이 페이지에서

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

Python SDK

Python SDK를 사용하면 Amplitude로 이벤트를 전송할 수 있습니다.

SDK 설치

pip를 사용하여 amplitude-analytics 설치:

bash
pip install amplitude-analytics

SDK 초기화

어떤 이벤트든 계측하기 전에 SDK를 초기화하십시오. Amplitude 프로젝트 API 키가 필요합니다. 이 호출에서 구성 객체를 전달할 수도 있습니다. 초기화 후 요청 전반에 걸쳐 SDK 클라이언트 인스턴스를 재사용합니다.

python
from amplitude import Amplitude
client = Amplitude(AMPLITUDE_API_KEY)

SDK 구성

Python
def callback_func(event, code, message=None):
  # callback function that takes three input parameters
  # event: the event that triggered this callback
  # code: status code of request response
  # message: a optional string message for more detailed information
client.configuration.api_key = "new api key"
client.configuration.flush_max_retries = 5
client.configuration.logger = logging.getLogger(__name__)
client.configuration.min_id_length = 7
client.configuration.callback = callback_func
client.configuration.server_zone = "EU"
client.configuration.use_batch = True
client.configuration.server_url = "proxy url that forwarding the requests"
client.configuration.opt_out = False

일괄 처리 동작 구성

SDK는 track 메서드의 이벤트를 메모리 대기열에 추가하고 백그라운드에서 일괄적으로 플러시합니다.flush_queue_size 및 flush_interval_millis을 사용하여 일괄 처리 동작을 사용자 지정할 수 있습니다. 기본적으로 SDK는 serverUrl가 https://api2.amplitude.com/2/httpapi로 설정된 일반 모드에서 실행됩니다. 한 번에 대량의 데이터를 전송하려면 use_batch로 설정하십시오true. 그런 다음 SDK는 serverUrl를 https://api2.amplitude.com/batch의 배치 이벤트 업로드 API로 설정합니다. 일반 모드와 일괄 처리 모드는 동일한 플러시 대기열 크기와 플러시 간격을 사용합니다.

Python
from amplitude import Amplitude
client = Amplitude(AMPLITUDE_API_KEY)
# Events queued in memory flush when the number of events exceeds the upload threshold
# Default value is 200
client.configuration.flush_queue_size = 100
# Events queue flushes every set number of milliseconds
# Default value is 10 milliseconds
client.configuration.flush_interval_millis = 20000 # 20 seconds

이벤트 추적

이벤트는 사용자가 애플리케이션과 상호 작용하는 방식을 나타냅니다. 예를 들어 '버튼 클릭됨'은 일반적인 이벤트입니다.

python
from amplitude import Amplitude, BaseEvent
client = Amplitude(AMPLITUDE_API_KEY)
# Track a basic event
# One of user_id and device_id is required
event = BaseEvent(event_type="Button Clicked", user_id="User Id")
client.track(event)
# Track events with optional properties
client.track(
    BaseEvent(
        event_type="type of event",
        user_id="USER_ID",
        device_id="DEVICE_ID",
        event_properties={
            "source": "notification"
        }
))

사용자 속성

사용자 속성은 장치 세부 정보, 기본 설정, 언어 등과 같은 사용자를 설명합니다. 앱에서 작업을 수행하는 사람을 이해하도록 설정하세요.

Identify 호출은 이벤트를 전송하지 않고 사용자의 속성을 설정합니다. SDK는 개별 사용자 속성에 대해 set, set_once, unset, add, append, prepend, pre_insert, post_insert, remove 및 clear_all 작업을 지원합니다. Identify 인터페이스를 통해 작업을 선언합니다. 여러 작업을 하나의 Identify 객체로 묶은 다음 이를 Amplitude 클라이언트에 전달하여 서버로 전송합니다.

이벤트 이후에 Identify 호출을 전송하면 작업 결과가 대시보드 사용자의 프로필 영역에 즉시 나타납니다. 이 결과는 Identify 호출 후에 다른 이벤트가 전송될 때까지 차트 결과에 나타나지 않습니다. Identify 호출은 앞으로 진행되는 이벤트에만 영향을 줍니다. 자세한 내용은 사용자 속성 및 이벤트를 참조하십시오.

사용자 속성 설정

사용자 속성을 설정하려면 Identify 객체를 인스턴스화하고 해당 객체에 대해 Identify 메서드를 호출한 다음 객체를 클라이언트에 전달하십시오.

Python
from amplitude import Identify, EventOptions
identify_obj=Identify()
client.identify(identify_obj, EventOptions(user_id="USER_ID"))

Identify.set

사용자 속성의 값을 설정합니다. 예를 들어 사용자의 역할을 설정합니다.

Python
from amplitude import Identify, EventOptions
identify_obj=Identify()
identify_obj.set("location", "LAX")
client.identify(identify_obj, EventOptions(user_id="USER_ID"))

Identify.set_once

사용자 속성을 숫자 값만큼 증가시킵니다. 사용자 속성에 아직 값이 없으면 SDK는 값을 증가시키기 전에 0으로 초기화합니다. 예를 들어 사용자의 여행 횟수를 추적합니다.

Python
from amplitude import Identify, EventOptions
identify_obj=Identify()
identify_obj.add("travel-count", 1)
client.identify(identify_obj, EventOptions(user_id="USER_ID"))

사용자 속성의 배열

배열을 사용자 속성으로 사용합니다. 배열을 직접 설정하거나 prepend, append, pre_insert 및 post_insert를 사용하여 배열을 구축할 수 있습니다.

Identify.prepend

사용자 속성 배열 앞에 하나 이상의 값을 추가합니다. 사용자 속성에 아직 값이 없으면 SDK는 앞에 추가하기 전에 이를 빈 목록으로 초기화합니다.

Python
from amplitude import Identify, EventOptions
identify_obj=Identify()
identify_obj.prepend("visited-locations", "LAX")
client.identify(identify_obj, EventOptions(user_id="USER_ID"))

Identify.append

하나 이상의 값을 사용자 속성 배열에 추가합니다. 사용자 속성에 아직 값이 없는 경우 SDK는 추가하기 전에 이를 빈 목록으로 초기화합니다.

Python
from amplitude import Identify, EventOptions
identify_obj=Identify()
identify_obj.append("visited-locations", "SFO")
client.identify(identify_obj, EventOptions(user_id="USER_ID"))

Identify.pre_insert

사용자 속성 배열의 시작 부분에 하나 이상의 값을 삽입합니다. 해당 값이 아직 배열에 존재하지 않는 경우에만 해당 값을 삽입합니다. 사용자 속성에 아직 값이 없는 경우 SDK는 삽입하기 전에 해당 값을 빈 목록으로 초기화합니다. 사용자 속성에 이미 값이 있으면 작업은 아무런 동작도 하지 않습니다.

Python
from amplitude import Identify, EventOptions
identify_obj=Identify()
identify_obj.pre_insert("unique-locations", "LAX")
client.identify(identify_obj, EventOptions(user_id="USER_ID"))

Identify.post_insert

사용자 속성 배열의 끝에 하나 이상의 값을 삽입합니다. 해당 값이 아직 배열에 존재하지 않는 경우에만 해당 값을 삽입합니다. 사용자 속성에 아직 값이 없는 경우 SDK는 삽입하기 전에 해당 값을 빈 목록으로 초기화합니다. 사용자 속성에 이미 값이 있으면 작업은 아무런 동작도 하지 않습니다.

Python
from amplitude import Identify, EventOptions
identify_obj=Identify()
identify_obj.post_insert("unique-locations", "SFO")
client.identify(identify_obj, EventOptions(user_id="USER_ID"))

Identify.remove

사용자 속성 배열에서 하나 이상의 값을 제거합니다(존재하는 경우). 사용자 속성에 값이 존재하지 않는 경우 작업은 아무런 동작도 하지 않습니다.

Python
from amplitude import Identify, EventOptions
identify_obj=Identify()
identify_obj.remove("unique-locations", "JFK")
client.identify(identify_obj, EventOptions(user_id="USER_ID"))

Identify.clear_all

사용자로부터 모든 사용자 속성을 제거합니다. clear_all는 되돌릴 수 없는 작업이므로 주의해서 사용하십시오.

Python
from amplitude import Identify, EventOptions
identify_obj=Identify()
identify_obj.clear_all()
client.identify(identify_obj, EventOptions(user_id="USER_ID"))

사용자 그룹

Amplitude는 사용자를 그룹에 할당하고 해당 그룹에 대해 고유 사용자별 수행 회수가와 같은 쿼리를 실행할 수 있도록 지원합니다. 예를 들어 orgId을(를) 사용하여 조직별로 사용자를 그룹화합니다. Joe를 orgId 10에 할당하고 Sue를 orgId 15에 할당합니다. 이벤트 세분화 차트에서 특정 이벤트를 수행한 조직의 수를 쿼리하려면 "..수행자" orgId를 선택합니다. Amplitude는 적어도 한 명의 멤버가 이벤트를 수행했을 때 해당 그룹을 카운트에 포함합니다.

그룹을 설정할 때 group_type 및 group_name를 정의하십시오. 이전 예제에서 orgId는 group_type이며, 10와 15는 각각 group_name입니다. 또 다른 예제에서는 tennis 및 baseball와 같은 group_name 값을 가진 sport를 group_type로 사용합니다. 사용자가 속한 그룹을 지정하는 데 set_group()를 사용합니다. 이 값은 group_type:group_name를 사용자 속성으로 설정하기도 합니다. 이 호출은 해당 사용자의 group_type에 대한 기존 group_name 값을 해당 사용자 속성 값과 함께 덮어씁니다. group_type는 문자열입니다. group_name는 사용자가 여러 그룹에 속해 있음을 나타내는 문자열 또는 문자열 배열일 수 있습니다. 예를 들어 Joe가 orgId 10 및 16에 속해 있다면, group_name는 [10, 16]입니다.

Python
# set group with single group name
client.set_group(group_type="org_id", group_name="15",
                 event_options=EventOptions(user_id="USER_ID"))
# set group with multiple group names
client.set_group(group_type="org_id", group_name=["15", "21"],
                 event_options=EventOptions(user_id="USER_ID"))

이벤트의 groups 속성을 사용하여 이벤트 수준 그룹을 설정합니다.

Python
# set groups when initial a event instance
event = BaseEvent("event_type", "user_id", groups={"org_id": ["15", "21"]})
# set groups for an existing instance
event["groups"] = {"sport": "soccer"}
client.track(event)

그룹 속성

그룹 식별 API를 사용하여 특정 그룹의 속성을 설정하거나 업데이트할 수 있습니다. 이러한 업데이트는 앞으로 진행되는 이벤트에만 영향을 줍니다.

이 group_identify() 메서드는 그룹 유형 문자열, 그룹 이름 문자열 및 Identify 객체를 허용하여 그룹에 적용합니다.

Python
identify_obj=Identify()
identify_obj.set("locale", "en-us")
client.group_identify(group_type="org-id", group_name="15", identify_obj=identify_obj)

매출 추적

사용자의 수익을 추적하려면 수익 인터페이스와 함께 revenue() 사용하십시오. 수익 인스턴스는 각 거래를 저장하며 revenue_type 및 product_id과 같은 특별한 수익 속성을 정의할 수 있도록 합니다. Amplitude의 이벤트 세분화 및 수익 LTV (Lifetime Value) 차트는 이러한 속성을 사용합니다. Revenue 인스턴스 객체를 revenue에 전달하여 Amplitude에 수익 이벤트로 전송합니다. 그러면 Amplitude는 수익 데이터를 자동으로 표시합니다. 이 방법을 사용하여 인앱 구매와 인앱 외 구매를 모두 추적하세요.

사용자의 수익을 추적하려면 사용자가 수익을 창출할 때마다 전화하십시오. revenue예를 들어 사용자가 한 제품을 개당 3.99에 3개 구매한다고 가정합니다.

Python
from amplitude import Revenue
revenue_obj = Revenue(price=3.99,
                      quantity=3,
                      product_id="com.company.productId")
client.revenue(revenue_obj, EventOptions(user_id="USER_ID"))

수익 인터페이스

플러시

이 flush 메서드는 클라이언트가 버퍼링된 이벤트를 전송하도록 트리거합니다.

py
client.flush()

추가

이 add 메소드는 Amplitude 클라이언트 인스턴스에 플러그인을 추가합니다. 플러그인은 이벤트를 처리하고 전송하는 데 도움이 됩니다. 플러그인에 대해 자세히 알아보세요.

py
client.add(plugin_obj)

제거

이 remove 메서드는 지정된 플러그인이 있는 경우 클라이언트 인스턴스에서 해당 플러그인을 제거합니다.

py
client.remove(plugin_obj)

시스템 종료

shutdown 메서드를 사용하여 인스턴스를 닫습니다. 닫힌 인스턴스는 새 이벤트를 받아들이지 않으며 버퍼에 남아 있는 이벤트를 플러시하려고 시도합니다. 플러시 후 클라이언트 인스턴스는 실행 중인 스레드를 종료합니다.

버전 v1.1.1 이상에서는 SDK가 메인 스레드가 종료될 때 실행할 shutdown 메서드를 자동으로 등록합니다.

py
client.shutdown()

플러그인

플러그인은 Amplitude SDK의 동작을 확장합니다. 예를 들어 이벤트 속성을 수정하거나(보강 유형) 타사 API로 데이터(목적지 유형)를 전송합니다. 플러그인은 setup() 및 execute() 메서드를 가진 객체입니다.

Plugin.setup

플러그인을 사용할 준비를 합니다. client 인스턴스를 매개변수로 취하고 None를 반환합니다. 일반적인 용도: client.configuration에서 구성을 복사하거나 플러그인 종속성을 인스턴스화합니다. SDK는 client.add()를 통해 플러그인을 등록할 때 이 메서드를 호출합니다.

Plugin.execute

이벤트를 처리합니다. event 인스턴스를 매개변수로 받습니다. 보강 플러그인의 경우 수정되거나 보강된 이벤트를 반환합니다. 목적지 플러그인의 경우 event(BaseEvent), code(숫자) 및 message(문자열) 키가 포함된 맵을 반환합니다. SDK는 Identify, GroupIdentify 및 Revenue 이벤트를 비롯하여 클라이언트 인터페이스를 통해 계측되는 각 이벤트에 대해 이 메서드를 호출합니다.

플러그인 예제

보강 유형 플러그인

이 예제 플러그인은 이벤트의 event_id 속성에 증분 정수를 추가하여 계측된 각 이벤트를 수정합니다.

py
from threading import Lock
from amplitude import Amplitude, EventPlugin, PluginType
class AddEventIdPlugin(EventPlugin):
    def __init__(self, start=0):
        super().__init__(PluginType.ENRICHMENT)
        self.current_id = start
        self.configuration = None
        self.lock = Lock()
    def setup(self, client):
        self.configuration = client.configuration
    def execute(self, event):
        with self.lock:
            event.event_id = self.current_id
            self.current_id += 1
        return event
client = Amplitude(AMPLITUDE_API_KEY)
client.add(AddInsertIdPlugin())

목적지 유형 플러그인

Python
from amplitude import Amplitude, EventPlugin, DestinationPlugin, PluginType
import requests
class MyDestinationPlugin(DestinationPlugin):
    def __init__(self):
        super().__init__()
        # other init operations
        self.url = "api endpoint url"
        self.configuration = None
    def setup(self, client):
        # setup plugin using client instance
        # triggered by client.add() method
        super().setup(client)
        self.configuration = client.configuration
    def execute(self, event):
        # process event using plugins in this destination plugin instance
        event = self.timeline.process(event)
        # send event to customized destination
        payload = '{"key":"secret", "event": ' + str(event) + '}'
        requests.post(self.url, data=payload)
        self.configuration.logger.info("Event sent")
client = Amplitude(AMPLITUDE_API_KEY)
client.add(MyDestinationPlugin())

이 내용이 도움이 되었나요?