On this page

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.

Ampli for Python SDK

Amplitudeデータは、Pythonアプリ（Python 3.6以上）からのアナリティクスイベントの追跡をサポートしています。Ampliは生成されたトラッキングライブラリをPythonパッケージとしてパッケージ化します。

  1. Amplitude SDKをインストールする

    shell
    pip install amplitude-analytics

  2. Ampli CLIをインストールする

    shell
    npm install -g @amplitude/ampli

  3. Ampliラッパーをプロジェクトに組み込む

    shell
    ampli pull [--path ./ampli]

  4. Ampliラッパーを初期化する

    python
    from .ampli import *
ampli.load(LoadOptions(
  client=LoadClientOptions(AMPLITUDE_API_KEY)
))

  5. ユーザーを識別し、ユーザープロパティを設定する

    python
    ampli.identify("user_id", Identify(userProp="A trait associated with this user"))

  6. 強力に型付けされたメソッドとクラスを使用してイベントを追跡する

    python
    ampli.song_played('user_id', SongPlayed(song_id="song-1"))
ampli.track('user-id', new SongFavorited(song_id="song-2"));

  7. アプリケーション終了前のイベントのフラッシュ

    python
    ampli.flush();

  8. CLIを使用して実装ステータスを確認する

    shell
    ampli status [--update]

Amplitude SDKをインストールする

まだインストールしていない場合は、コアとなるAmplitude SDKの依存関係をインストールしてください。

bash
pip install amplitude-analytics

Ampliをインストールする

Ampli CLIは、HomebrewまたはNPMからインストールできます。

npm install -g @amplitude/ampli

Ampli ラッパーをプロジェクトに組み込む

プロジェクトのルートディレクトリからAmpli CLIpullコマンドを実行してAmplitudeデータにログインし、トラッキングプラン用の強く型付けされたAmpliラッパーをダウンロードしてください。

bash
ampli pull

Ampliは、ワークスペースにログインしてソースを選択するよう求めます。

bash
➜ ampli pull
Ampli project is not initialized. No existing `ampli.json` configuration found.
? Create a new Ampli project here? Yes
? Organization: Amplitude
? Workspace: My Workspace
? Source: My Source

Ampliの初期化

コードでAmpliを初期化します。load()メソッドには、Ampliラッパーの設定オプションを指定するLoadOptionsインスタンスが必要です。

python
from .ampli import *
ampli.load(LoadOptions(
   client=LoadClientOptions(AMPLITUDE_API_KEY)
))

LoadOptionsは次の引数を受け入れます：

引数必須デフォルト概要
disabledいいえFalseTrueの場合、Ampliラッパーのすべての呼び出しはno-opになります。ローカル環境や開発環境で役立ちます。
clientいいえNoneAmplitudeコアSDKクライアントの設定オプションを指定するLoadClientOptionsインスタンス。

LoadClientOptionsは次の引数を受け入れます：

引数必須デフォルト概要
instanceapi_keyが設定されていない場合は必須です。None使用するAmplitudeインスタンス。 デフォルトでは、Ampliはインスタンスを作成します。
api_keyinstanceが設定されていない場合は必須です。None使用するAPIキーです。トラッキングプランで設定されたAPIキーを上書きします。
configurationいいえNone使用するAmplitudeの設定。 デフォルト設定を上書きします。

Identify

アプリ内のユーザーを識別したり、今後のすべてのイベントをそのユーザーのIDに関連付けたり、ユーザープロパティを設定したりするには、identify()を呼び出します。Ampliは、トラッキングプランからユーザープロパティのタイプを生成します。

identify()関数は文字列user_id、Identifyイベントインスタンス、およびオプションのEventOptionsを受け入れます。

たとえば、トラッキングプランに次のような文字列型のroleと呼ばれるユーザープロパティが含まれている場合：

python
ampli.identify("user_id", Identify(role="admin"))

オプション引数は、device_idなど、この呼び出しのAmplitudeフィールドを受け入れます。

python
ampli.identify("user_id", Identify(role="admin"), EventOptions(device_id="device_id"))

グループ識別

アプリ内のグループを識別し、グループのプロパティを設定または更新するためにgroup_identify()呼び出します。 Ampliは、トラッキングプランからグループプロパティのタイプを生成します。

group_identify()関数は文字列group_type、文字列group_name、Groupイベントインスタンス、およびオプションのEventOptionsを受け取ります。

例えば、トラッキングプランに整数型のtotal_memberというプロパティを持つグループsport:footballが含まれている場合は次のようになります：

python
ampli.group_identify("sport", "football", Group(total_member=23))

グループの設定

ユーザーをグループ（部署や会社など）に関連付けるには、set_group()を呼び出します。set_group()関数は、user_id、group_type、group_name、およびオプションのEventOptionsを受け入れます。

python
ampli.set_group("user_id", "sport", "football")

group_name は、単一のグループ名文字列または複数のグループ名のリストを受け入れます。

python
ampli.set_group("user_id", "sport", ["football", "basketball"])

追跡

イベントを追跡するには、そのイベントに対応する関数を呼び出します。 トラッキングプラン内のすべてのイベントには、Ampliラッパー内にそれぞれ専用の関数が生成されます。コールを次のように構造化します。

python
ampli.event_name("user_id", EventName(...), EventOptions(...))

オプションのEventOptions引数は、device_idなどのAmplitudeフィールドを受け入れます。

たとえば、トラッキングプランに、songId（文字列）とsongFavorited（ブール値）という2つの必須プロパティを持つsongPlayedイベントが含まれる場合：

python
ampli.song_played('user_id', SongPlayed(
  song_id = 'songId', # str,
  song_favorited = True, # bool
))

また、Ampli はイベントごとにクラスを生成します。 汎用トラックメソッドを使用してイベントオブジェクトを送信します。

python
my_event = SongPlayed(
  song_id = 'songId', # str,
  song_favorited = True, # bool
)
ampli.track('user_id', SongPlayed(
  song_id = 'songId', # str,
  song_favorited = True, # bool
), EventOptions(device_id="device_id"))

フラッシュ

Ampliラッパーはイベントをキューに入れ、flushQueueSizeおよびflushIntervalの設定値に基づいて自動的に送信します。

保留中のイベントをすぐに送信するには、flush()を呼び出します。flush()メソッドは、Promiseを返します。このPromiseは、Ampliが処理を続行する前にすべての保留中のイベントを確実に送信するために使用できます。アプリケーションが終了する前にflush()を呼び出します。

python
ampli.flush();

プラグイン

プラグインはAmplitudeの動作を拡張します。 たとえば、エンリッチメントプラグインがイベントプロパティを変更し、送信先プラグインがデータをサードパーティ製 API に送信します。

まずはプラグインを定義します。 次の例は、送信先プラグインを示しています。

python
from amplitude import DestinationPlugin, PluginType, BaseEvent, IdentifyEvent
from analytics import Client as SegmentClient
class SegmentPlugin(DestinationPlugin):
  def __init__(self, write_key):
      self.plugin_type = PluginType.DESTINATION
      self.configuration = None
      self.segment = SegmentClient(write_key)
  def setup(self, client):
      self.configuration = client.configuration
  def execute(self, event: BaseEvent) -> None:
      if isinstance(event, IdentifyEvent):
          self.segment.identify(event.user_id, event.user_properties)
      elif isinstance(event, BaseEvent):
          self.segment.track(event.user_id, event.event_type, event.event_properties)

Ampli を初期化した後にプラグインを追加してください。

python
ampli.client.add(SegmentPlugin("write_key"))

ステータス

statusコマンドを使用して、コードがイベントを実装していることを確認します。

bash
ampli status [--update]

出力にはステータスと、欠落しているイベントが示されます。

bash
➜ ampli status
✘ Verifying event tracking implementation in source code
 ✔ Song Played (1 location)
 ✘ Song Stopped Called when a user stops playing a song.
Events Tracked: 1 missed, 2 total

トラブルシューティング

ImportError：既知の親パッケージがない場合に相対インポートを試みました

このエラーは、python3 main.py でスクリプトを直接実行し、from .ampli import * などの相対インポートを使用した場合に発生します。 スクリプトを直接実行する場合、Pythonはモジュール構造を認識しません。

解決策は2つあります。

オプション1：絶対インポートを使用する

パッケージ構造に基づいて絶対インポートを使用してください：

python
from ampli import *

または、Ampliラッパーがパッケージに含まれている場合：

python
from your_package.ampli import *

オプション2：モジュールとして実行する

スクリプトをモジュールとして実行します：

bash
python3 -m your_package.main

Was this helpful?