Python SDK

pypiv1.2.3

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 を設定する

オプション	タイプ	概要	デフォルト
`api_key`	文字列 (必須)	AmplitudeプロジェクトのAPIキーです。クライアントインスタンスは、このプロジェクトにイベントを送信します。クライアントを初期化するときにこの値を設定してください。	`None`
`flush_queue_size`	整数です。	イベントはバッファ内で待機し、バッチで送信されます。イベント数が`flush_queue_size`に達すると、SDKはバッファをフラッシュします。	`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`（イベントインスタンス）、`code`（整数のHTTP応答コード）、および`message`（文字列メッセージ）の3つのパラメータを取ります。	`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`

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

イベントを追跡する

イベントは、ユーザーがアプリケーションとどのように対話するかを表します。たとえば、「Button Clicked」は一般的なイベントです。

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

ユーザープロパティ配列の前に1つ以上の値を付加します。ユーザープロパティに値がまだない場合、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

ユーザープロパティ配列に1つ以上の値を追加します。ユーザープロパティに値がまだない場合、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

ユーザープロパティ配列の先頭に1つ以上の値を挿入します。ただし、これらの値が配列にまだ存在しない場合に限られます。ユーザープロパティに値がまだない場合、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

ユーザープロパティ配列の末尾に1つ以上の値を挿入します。ただし、これらの値が配列にまだ存在しない場合に限られます。ユーザープロパティに値がまだない場合、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

ユーザープロパティ配列に1つ以上の値が存在する場合、それらを削除します。値がユーザープロパティに存在しない場合、操作は何も行われません。

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に割り当てます。イベントセグメンテーションチャートで「..performed by」orgIdを選択すると、特定のイベントを実行した組織の数を照会できます。Amplitudeは、少なくとも1人のメンバーがイベントを実行した場合に、そのグループをカウントに含めます。

グループを設定する際には、group_typeとgroup_nameを定義してください。前の例ではorgIdがgroup_typeであり、10と15がそれぞれgroup_nameになります。別の例では、sportをgroup_typeとして使用しており、tennisやbaseballのようなgroup_name値を持ちます。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)

グループプロパティ

Group Identify 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()を使用してください。収益インスタンスは各トランザクションを保存し、revenue_typeやproduct_idなどの特別な収益プロパティを定義できます。AmplitudeのイベントセグメンテーションとレベニューLTVチャートはこれらのプロパティを使用しています。収益インスタンスオブジェクトをrevenueに渡して、収益イベントとしてAmplitudeに送信します。その後、Amplitudeは収益データを自動的に表示します。このアプローチを使用して、アプリ内購入とアプリ内以外の購入の両方を追跡できます。

ユーザーからの収益を追跡するには、revenueユーザーが収益を上げるたびに電話をかけます。たとえば、あるユーザーがプロダクトを3ユニットずつ3.99で購入したとします。

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"))

収益インターフェイス

名前	タイプ	概要	デフォルト
`product_id`（オプション）	文字列	プロダクトの識別子です。 AmplitudeはGoogle PlayストアのプロダクトIDのようなものを推奨しています。	null
数量 (必須)	int	購入された製品の数量。 `revenue = quantity * price`	1
価格 (必須)	Double	購入した製品の価格です。これは負の値になる可能性があります。 `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()を持つオブジェクトです。

プラグインのセットアップ

プラグインを使用できるように準備します。 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())

送信先タイプのプラグイン

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())

Was this helpful?