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 설치:
pip install amplitude-analytics
SDK 초기화
어떤 이벤트든 계측하기 전에 SDK를 초기화하십시오. Amplitude 프로젝트 API 키가 필요합니다. 이 호출에서 구성 객체를 전달할 수도 있습니다. 초기화 후 요청 전반에 걸쳐 SDK 클라이언트 인스턴스를 재사용합니다.
from amplitude import Amplitude
client = Amplitude(AMPLITUDE_API_KEY)
SDK 구성
| 옵션 | 유형 | 설명 | 기본값 |
|---|---|---|---|
api_key | 문자열(필수) | Amplitude 프로젝트의 API 키입니다. 클라이언트 인스턴스는 이 프로젝트에 이벤트를 전송합니다. 클라이언트를 초기화할 때 이 값을 설정하십시오. | None |
flush_queue_size | 정수입니다. | 이벤트는 버퍼에서 대기하고 배치로 전송됩니다. SDK는 이벤트 수가 flush_queue_size에 도달하면 버퍼를 플러시합니다. | 200 |
flush_interval_millis | 정수입니다. | SDK는 flush_interval_millis 밀리초마다 버퍼를 플러시합니다. | 10000 (10초) |
flush_max_retries | 정수입니다. | 요청이 오류를 반환할 때 클라이언트가 이벤트를 재시도하는 회입니다. | 12 |
logger | 로거 | Amplitude 클라이언트가 사용하는 로거 인스턴스입니다. | python 내장 로깅: logging.getLogger(name) |
min_id_length | 정수입니다. | user_id 및 device_id의 최소 길이입니다. | 5 |
callback | 기능 | 클라이언트 수준의 콜백 함수. 세 가지 매개변수 event(Event 인스턴스), code(정수 HTTP 응답 코드), message(문자열 메시지)를 사용합니다. | None |
server_zone | 문자열 | 프로젝트의 서버 영역입니다. 지원 대상은 EU 및 US입니다. EU 데이터 상주국의 경우 EU로 설정하십시오. | US |
server_url | 문자열 | SDK가 이벤트를 전송하는 API 엔드포인트 URL입니다. SDK는 server_zone 및 use_batch를 기반으로 이를 자동으로 선택합니다. 필드를 None 대신 문자열 값으로 설정하면 SDK는 server_zone와 use_batch를 무시하고 문자열 값을 사용합니다. | https://api2.amplitude.com/2/httpapi |
use_batch | 부울입니다. | 배치 API를 사용할 것인지 여부입니다. 기본적으로 SDK는 기본 serverUrl을 사용합니다. | False |
storage_provider | 스토리지 공급자 | 스토리지 버퍼에 이벤트를 저장할 스토리지 인스턴스를 생성합니다. 스토리지 버퍼는 SDK가 이벤트를 전송할 때까지 이벤트를 보관합니다. | InMemoryStorageProvider |
opt_out | 부울입니다. | True인 경우 클라이언트는 이벤트를 처리하거나 전송하지 않습니다. | False |
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로 설정합니다. 일반 모드와 일괄 처리 모드는 동일한 플러시 대기열 크기와 플러시 간격을 사용합니다.
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
이벤트 추적
이벤트는 사용자가 애플리케이션과 상호 작용하는 방식을 나타냅니다. 예를 들어 '버튼 클릭됨'은 일반적인 이벤트입니다.
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 메서드를 호출한 다음 객체를 클라이언트에 전달하십시오.
from amplitude import Identify, EventOptions
identify_obj=Identify()
client.identify(identify_obj, EventOptions(user_id="USER_ID"))
Identify.set
사용자 속성의 값을 설정합니다. 예를 들어 사용자의 역할을 설정합니다.
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으로 초기화합니다. 예를 들어 사용자의 여행 횟수를 추적합니다.
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는 앞에 추가하기 전에 이를 빈 목록으로 초기화합니다.
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는 추가하기 전에 이를 빈 목록으로 초기화합니다.
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는 삽입하기 전에 해당 값을 빈 목록으로 초기화합니다. 사용자 속성에 이미 값이 있으면 작업은 아무런 동작도 하지 않습니다.
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는 삽입하기 전에 해당 값을 빈 목록으로 초기화합니다. 사용자 속성에 이미 값이 있으면 작업은 아무런 동작도 하지 않습니다.
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
사용자 속성 배열에서 하나 이상의 값을 제거합니다(존재하는 경우). 사용자 속성에 값이 존재하지 않는 경우 작업은 아무런 동작도 하지 않습니다.
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는 되돌릴 수 없는 작업이므로 주의해서 사용하십시오.
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]입니다.
# 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 속성을 사용하여 이벤트 수준 그룹을 설정합니다.
# 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 객체를 허용하여 그룹에 적용합니다.
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개 구매한다고 가정합니다.
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"))
수익 인터페이스
| 이름 | 유형 | 설명 | 기본값 |
|---|---|---|---|
product_id (선택 사항) | 문자열 | 제품의 식별자입니다. Amplitude는 Google Play 스토어 제품 ID와 같은 것을 권장합니다. | null |
| 수량 (필수) | int | 구매한 제품의 수량입니다. revenue = quantity * price | 1 |
| 가격 (필수) | 더블 | 구입한 제품의 가격이며, 이는 음수일 수 있습니다. revenue = quantity * price | null |
revenue_type (선택 사항, 매출 확인을 위해 필요함) | 문자열 | 수익 유형(예: 세금, 환급금, 소득)입니다. | null |
| 영수증(선택 사항) | 문자열 | 수익의 영수증 식별자입니다. | null |
receipt_sig (선택 사항, 매출 확인을 위해 필요함) | 문자열 | 수익의 영수증 서명입니다. | null |
| 속성(선택 사항) | JSONObject | 수익 이벤트에 포함시킬 이벤트 속성의 객체입니다. | null |
플러시
이 flush 메서드는 클라이언트가 버퍼링된 이벤트를 전송하도록 트리거합니다.
client.flush()
추가
이 add 메소드는 Amplitude 클라이언트 인스턴스에 플러그인을 추가합니다. 플러그인은 이벤트를 처리하고 전송하는 데 도움이 됩니다. 플러그인에 대해 자세히 알아보세요.
client.add(plugin_obj)
제거
이 remove 메서드는 지정된 플러그인이 있는 경우 클라이언트 인스턴스에서 해당 플러그인을 제거합니다.
client.remove(plugin_obj)
시스템 종료
shutdown 메서드를 사용하여 인스턴스를 닫습니다. 닫힌 인스턴스는 새 이벤트를 받아들이지 않으며 버퍼에 남아 있는 이벤트를 플러시하려고 시도합니다. 플러시 후 클라이언트 인스턴스는 실행 중인 스레드를 종료합니다.
버전 v1.1.1 이상에서는 SDK가 메인 스레드가 종료될 때 실행할 shutdown 메서드를 자동으로 등록합니다.
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 속성에 증분 정수를 추가하여 계측된 각 이벤트를 수정합니다.
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())
목적지 유형 플러그인
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())
이 내용이 도움이 되었나요?