Webhookのイベントタイプとフィールド
AdaptyはサブスクリプションイベントへのレスポンスとしてWebhookを送信します。このセクションでは、これらのイベントタイプと各Webhookに含まれるデータについて説明します。
Webhookイベントタイプ
すべてのイベントタイプをWebhookに送信するか、一部のみを選択して送信できます。受信データの内容やビジネスロジックの構築方法については、イベントフローを参照してください。不要なイベントタイプは、Webhook連携の設定時に無効化できます。また、必要に応じてAdaptyのデフォルトイベントIDを独自のIDに置き換えることも可能です。
| イベント名 | 説明 |
|---|---|
| subscription_started | トライアル期間なしで有料サブスクリプションを開始したとき(即時課金)にトリガーされます。 |
| subscription_active | subscription_started イベントの後、サブスクリプションがまだアクティブであることを確認します。サブスクリプション開始からこのチェックまでの日数を設定する必要があります。サブスクリプションがまだアクティブな場合(グレース期間中を含む)にイベントが届きます。その時点でサブスクリプションが終了していた場合や、ユーザーが自動更新をオフにしていた場合は、イベントは届かず、Adapty は再チェックしません。このイベントはトライアルなしで購入したサブスクリプションにのみ続きます。トライアルからの切り替えは trial_converted を送信するため、このチェックは開始されません。 |
| subscription_renewed | サブスクリプションが更新されてユーザーに課金されたときに発生します。トライアルあり・なしを問わず、2 回目以降の請求から発生します。 |
| subscription_renewal_cancelled | ユーザーがサブスクリプションの自動更新をオフにしました。ユーザーは有料サブスクリプション期間が終了するまでプレミアム機能にアクセスできます。 |
| subscription_renewal_reactivated | ユーザーがサブスクリプションの自動更新を再有効化したときにトリガーされます。 |
| subscription_expired | キャンセル後、サブスクリプションが完全に終了したときにトリガーされます。たとえば、ユーザーが 12 月 12 日にサブスクリプションをキャンセルしても 12 月 31 日まで有効な場合、イベントは 12 月 31 日に記録されます。 |
| subscription_paused | ユーザーがサブスクリプションの一時停止を有効にしたときに発生します(Android のみ)。 |
| subscription_deferred | 無償でユーザーのサブスクリプションを延長したときにトリガーされます。Google Play Developer API による延期、または App Store Server API による更新日の延長が対象です。ユーザーは延長された更新日までプレミアム機能にアクセスできます。 |
| non_subscription_purchase | 永続アクセスやゲーム内コインなどの消耗型アイテムといった、サブスクリプション以外のすべての購入。 |
| trial_started | ユーザーがトライアルサブスクリプションを開始したときにトリガーされます。 |
| trial_active | trial_started イベントの後、トライアルがまだアクティブであることを確認します。トライアル開始からこのチェックまでの日数を設定する必要があります。トライアルがまだ実行中の場合にイベントが届きます。その時点でトライアルが終了または切り替わっていた場合や、ユーザーが自動更新をオフにしていた場合は、イベントは届かず、Adapty は再チェックしません。 |
| trial_converted | トライアルが終了してユーザーに課金された(初回購入)ときに発生します。たとえば、ユーザーのトライアルが 1 月 14 日までだが 1 月 7 日に課金された場合、このイベントは 1 月 7 日に記録されます。 |
| trial_renewal_cancelled | ユーザーがトライアル期間中にサブスクリプションの自動更新をオフにしました。ユーザーはトライアルが終了するまでプレミアム機能にアクセスできますが、課金やサブスクリプションへの移行は行われません。 |
| trial_renewal_reactivated | ユーザーがトライアル期間中にサブスクリプションの自動更新を再有効化したときに発生します。 |
| trial_expired | サブスクリプションに切り替わらずにトライアルが終了したときにトリガーされます。 |
| entered_grace_period | 支払いの試行が失敗し、ユーザーがグレース期間に入ったとき(有効な場合)に発生します。この間、ユーザーはプレミアムアクセスを維持します。 |
| billing_issue_detected | 課金試行時に請求の問題が発生したとき(例:カード残高不足)にトリガーされます。 |
| subscription_refunded | サブスクリプションが返金されたとき(例:Apple サポートによる対応)にトリガーされます。 |
| non_subscription_purchase_refunded | サブスクリプション以外の購入が返金されたときにトリガーされます。 |
| access_level_updated | ユーザーのアクセスレベルが更新されたときに発生します。 |
subscription_renewal_reactivated は、ユーザーがキャンセルした時点でアクティブだったプロダクト ID(以前のプロダクト ID)を保持します。これは、ユーザーが別のプロダクトを購入して再アクティブ化した場合でも同様です。Apple はキャンセル → 再アクティブ化の一連の流れを通じて同じ original_transaction_id を維持するため、このイベントは元のプロダクトを反映します。新しいプロダクトは、新しいプロダクトの課金が開始される次の subscription_renewed イベントで確認できます。
Google Play では、Adapty が subscription_started イベントをすべての金額フィールドをゼロに設定した状態で送信することがあります。これは、たとえば Google が一つのサブスクリプションを別のものに切り替えた場合や、無料フェーズでサブスクリプションが開始された場合に発生します。このようなイベントを収益としてカウントしないでください。Google がサブスクリプションを切り替える際、新しい購入トークンが発行されるため、Adapty は異なる store_transaction_id で有料トランザクションを報告します。
Webhookイベントの構造
Adaptyは、Integrations -> WebhooksページのEvents namesセクションで選択したイベントのみを送信します。
Webhookイベントは JSON 形式でシリアライズされます。サーバーへの POST リクエストのボディには、以下の構造でラップされたシリアライズ済みイベントが含まれます。すべてのイベントは同じ構造に従いますが、フィールドの内容はイベントタイプ、ストア、および設定内容によって異なります。ユーザー属性は、設定したカスタムユーザー属性であるため、設定した内容が反映されます。アトリビューションデータのフィールドはすべてのイベントタイプで共通ですが、アトリビューションのリストはモバイルアプリで使用しているアトリビューションソースによって異なります。イベントの例を以下に示します:
{
"profile_id": "00000000-0000-0000-0000-000000000000",
"customer_user_id": "UserIdInYourSystem",
"idfv": "00000000-0000-0000-0000-000000000000",
"idfa": "00000000-0000-0000-0000-000000000000",
"advertising_id": "00000000-0000-0000-0000-000000000000",
"profile_install_datetime": "2000-01-31T00:00:00.000000+0000",
"user_agent": "ExampleUserAgent/1.0 (Device; OS Version) Browser/Engine",
"email": "john.doe@company.com",
"event_type": "subscription_started",
"event_datetime": "2000-01-31T00:00:00.000000+0000",
"event_properties": {
"store": "play_store",
"currency": "USD",
"price_usd": 4.99,
"profile_id": "00000000-0000-0000-0000-000000000000",
"cohort_name": "All Users",
"environment": "Production",
"price_local": 4.99,
"original_price_usd": 4.99,
"original_price_local": 4.99,
"discount_amount_usd": 0,
"discount_amount_local": 0,
"base_plan_id": "b1",
"developer_id": "onboarding_placement",
"ab_test_id": "00000000-0000-0000-0000-000000000000",
"ab_test_name": "onboarding_ab_test",
"ab_test_revision": 1,
"ab_test_variant_id": "00000000-0000-0000-0000-000000000000",
"ab_test_variant_name": "Variant B",
"paywall_name": "UsedPaywall",
"proceeds_usd": 4.2315,
"variation_id": "00000000-0000-0000-0000-000000000000",
"purchase_date": "2024-11-15T10:45:36.181000+0000",
"store_country": "AR",
"event_datetime": "2000-01-31T00:00:00.000000+0000",
"proceeds_local": 4.2415,
"tax_amount_usd": 0,
"transaction_id": "0000000000000000",
"net_revenue_usd": 4.2415,
"profile_country": "AR",
"paywall_revision": "1",
"profile_event_id": "00000000-0000-0000-0000-000000000000",
"tax_amount_local": 0,
"net_revenue_local": 4.2415,
"vendor_product_id": "onemonth_no_trial",
"profile_ip_address": "10.10.1.1",
"consecutive_payments": 1,
"rate_after_first_year": false,
"original_purchase_date": "2000-01-31T00:00:00.000000+0000",
"original_transaction_id": "0000000000000000",
"subscription_expires_at": "2000-01-31T00:00:00.000000+0000",
"profile_has_access_level": true,
"profile_total_revenue_usd": 4.99,
"promotional_offer_id": null,
"store_offer_category": null,
"store_offer_discount_type": null
},
"event_api_version": 1,
"profiles_sharing_access_level": [{"profile_id": "00000000-0000-0000-0000-000000000000", "customer_user_id": "UserIdInYourSystem"}],
"attributions": {
"appsflyer": {
"ad_set": "Keywords 1.12",
"status": "non_organic",
"channel": "Google Ads",
"ad_group": null,
"campaign": "Social media influencers - Rest of the world",
"creative": null,
"created_at": "2000-01-31T00:00:00.000000+0000"
}
},
"user_attributes": {"Favourite_color": "Violet", "Pet_name": "Fluffy"},
"integration_ids": {"firebase_app_instance_id": "val1", "branch_id": "val2", "one_signal_player_id": "val3"},
"play_store_purchase_token": {
"product_id": "product_123",
"purchase_token": "token_abc_123",
"is_subscription": true
}
}
イベントフィールド
イベントパラメーターはすべてのイベントタイプで共通です。
| フィールド | 型 | 説明 |
|---|---|---|
| advertising_id | UUID | 広告ID(Android のみ)。 |
| attributions | JSON | アトリビューションデータ。Webhook 設定で Send Attribution が有効な場合に含まれます。 |
| customer_user_id | String | ユーザーの識別時にアプリコードで設定したアプリ側のユーザー ID(UUID、メールアドレス、その他の ID)。アプリコードでユーザーを識別していない場合、または該当ユーザーが匿名(未ログイン)の場合は null になります。 |
| String | Adapty SDK の updateProfile メソッド、またはサーバーサイド API でプロファイルを作成・更新する際に設定したユーザーのメールアドレス。email の値を SDK や API メソッドに渡していない場合は null になります。 | |
| event_api_version | Integer | Adapty API のバージョン(現在: 1)。 |
| event_datetime | ISO 8601 | イベントのビジネス上の有効時刻。購入イベントなら購入日時、有効期限イベントなら有効期限など、Adapty がイベントを受信・送信した時刻ではありません。ISO 8601 形式(例: 2020-07-10T15:00:00.000000+0000)。順序については下記の注記を参照してください。 |
| event_properties | JSON | イベントプロパティ。 |
| event_type | String | Adapty 形式のイベント名。全リストはWebhook イベントタイプを参照してください。 |
| idfa | UUID | 広告識別子(Apple のみ)。Adapty ダッシュボードのプロファイルに表示される IDFA。トラッキング制限、キッズモード、プライバシー設定により利用できない場合は null になる場合があります。 |
| idfv | UUID | ベンダー識別子(IDFV)。開発者ごとに一意の値。Adapty ダッシュボードのプロファイルに表示される IDFV。 |
| integration_ids | JSON | Adapty SDK の setIntegrationIdentifier メソッド、またはサーバーサイド API でプロファイルを作成・更新する際に設定したユーザーのインテグレーション ID。利用できない場合またはインテグレーションが無効な場合は null。 |
| play_store_purchase_token | JSON | Play Store 購入トークン。Webhook 設定で Send Play Store purchase token が有効な場合に含まれます。 |
| profile_id | UUID | Adapty が各プロファイルに対して自動生成するプロファイル ID。ユーザーを識別しない場合やログイン前に購入を許可している場合、1 つの Apple/Google ID が異なるプロファイル ID と紐付く可能性があります。詳しくはAdapty の親プロファイルと継承プロファイルの仕組みを参照してください。 |
| profile_install_datetime | ISO 8601 | ISO 8601 形式のインストール日時(例: 2020-07-10T15:00:00.000000+0000)。 |
| profiles_sharing_access_level | JSON | 現在のユーザープロファイルを除く、アクセスレベルを共有しているユーザーの一覧。アプリでアクセスレベルの共有が有効になっている場合、同じ Apple/Google ID で使用されている他のプロファイルが含まれます。 形式:
|
| user_agent | String | デバイスのブラウザユーザーエージェント。 |
| user_attributes | JSON | アプリ固有の情報でユーザープロファイルを拡充するために設定できるカスタムデータ。ユーザーの設定(テーマ、言語など)や行動フラグ(オンボーディング完了、機能の使用状況)のトラッキングに主に使用します。 キーが文字列、値が文字列または数値のキーバリューペアで表されます(例: {"Favourite_color": "Violet", "Pet_name": "Fluffy"})。カスタム属性は、Adapty ダッシュボードで個別のプロファイルに対して手動で設定するか、Adapty SDK の updateProfile メソッドを使ってプログラムから設定するか、サーバーサイド API でプロファイルを作成・更新する際に設定できます。Webhook 設定で Send User Attributes が有効な場合に含まれます。 モバイルアプリコードではカスタム属性値を float または文字列として設定できますが、サーバーサイド API や過去データのインポートで受け取った属性は異なる形式で届く場合があります。その場合、boolean と integer の値は float に変換されます。 |
event_datetime はサブスクリプションのライフサイクルでイベントが発生した日時を表しており、Adapty が処理または配信した日時ではありません。そのため、複数のイベントが同じ event_datetime を持つ場合や、時系列順とは異なる順序で届く場合があります。たとえば、subscription_expired イベントの event_datetime が、それより前に配信された subscription_renewal_cancelled イベントの event_datetime より早い場合があります。イベントの順序付けに event_datetime を使用しないでください。代わりに、受信時刻を基準にイベントを並べ替え、profile_event_id またはトランザクション ID を使って重複を排除してください。
アトリビューション
アトリビューションデータを送信するには、Integrations -> Webhooks ページで Send Attribution オプションを有効にしてください。アトリビューションデータの送信を有効にしており、アトリビューション連携を設定済みの場合、以下のデータがすべてのソースのイベントに付与されて送信されます。同じアトリビューションデータはすべてのイベントタイプに送信されます。
{
"attributions": {
"appsflyer": {
"ad_set": "sample_ad_set_123",
"status": "non_organic",
"channel": "sample_channel",
"ad_group": "sample_ad_group_456",
"campaign": "sample_ios_campaign",
"creative": "sample_creative_789",
"created_at": "2000-01-31T00:00:00.000000+0000",
"network_user_id": "0000000000000-0000000"
}
}
}
| フィールド名 | フィールド型 | 説明 |
|---|---|---|
| ad_set | String | アトリビューションの広告セット。 |
| status | String | organic、non_organic,、または unknown のいずれか。 |
| channel | String | マーケティングチャネル名。 |
| ad_group | String | アトリビューションの広告グループ。 |
| campaign | String | マーケティングキャンペーン名。 |
| creative | String | アトリビューションのクリエイティブキーワード。 |
| created_at | ISO 8601 date | アトリビューションレコードの作成日時。 |
| network_user_id | String | アトリビューションソースがユーザーに割り当てたID。 |
インテグレーション ID
現在、イベントで使用されているインテグレーション ID は以下のとおりです:
adjust_device_idairbridge_device_idamplitude_device_idamplitude_user_idappmetrica_device_idappmetrica_profile_idappsflyer_idbranch_idfacebook_anonymous_idfirebase_app_instance_idmixpanel_user_idpushwoosh_hwidone_signal_player_idone_signal_subscription_idtenjin_analytics_installation_idposthog_distinct_user_idsingular_sdid
Play Store の購入トークン
このフィールドには、必要に応じて購入を再検証するために必要なすべてのデータが含まれています。Webhookインテグレーションの設定で Send Play Store purchase token オプションが有効になっている場合にのみ送信されます。
| Field | Type | Description |
|---|---|---|
| product_id | String | Play Store で購入したプロダクトの一意識別子(SKU)。 |
| purchase_token | String | この購入トランザクションを一意に識別するために Google Play が生成するトークン。 |
| is_subscription | Boolean | 購入したプロダクトがサブスクリプション(true)か買い切り購入(false)かを示します。 |
イベントプロパティ
イベントプロパティは、イベントの種類によって、また同じ種類のイベント間でも異なる場合があります。たとえば、App Store から発生したイベントには、base_plan_id のような Android 固有のプロパティは含まれません。
アクセスレベル更新イベントには固有のプロパティがあるため、専用セクションを設けています。同様に、追加の税・収益イベントプロパティも特定のイベントタイプのみに該当するため、別セクションに分けています。
ほとんどのイベントタイプに共通
ほとんどのイベントタイプのイベントプロパティは共通です(Access Level Updated イベントは除き、そちらは別セクションで説明しています)。以下の表は、各プロパティと、それが特定のイベントに属するかどうかをまとめたものです。
Adaptyは、currencylayer.comの為替レート(8時間ごとに更新)を使用して他の通貨をUSDに換算します。レートは取引時点で固定されるため、その後の変動は換算結果に影響しません。
| フィールド | タイプ | 説明 |
|---|---|---|
| ab_test_id | UUID | トランザクションが発生した Adapty A/B テスト の ID。クロスプレースメント A/B テストの場合は、クロスプレースメントテストの ID であり、すべてのプレースメントで同じ値になります。フローおよび A/B テストフィールドを参照してください。 |
| ab_test_name | String | トランザクションが発生した Adapty A/B テスト の名前。クロスプレースメント A/B テストの場合は、あるプレースメントにおけるテスト名が <テスト名> child-N の形式(N はバリアント番号ではなくプレースメント番号)で入ります。クロスプレースメントテストをプレースメント横断で集計する場合は ab_test_id を使用し、名前は ab_test_parent_name から取得してください。 |
| ab_test_parent_name | String | トランザクションが発生したクロスプレースメント A/B テストの名前。クロスプレースメント A/B テストにのみ存在します。 |
| ab_test_revision | Integer | トランザクションが発生した A/B テストのリビジョン。 |
| ab_test_variant_id | UUID | トランザクションが発生した A/B テストバリアントの ID。通常のペイウォール A/B テストでは variation_id と一致し、フロー A/B テストでは flow_variation_id と一致します。クロスプレースメント A/B テストでは、すべてのプレースメントで同じバリアントに対して同じ値になります。テストバリアントごとにトランザクションを分割する際に使用してください。 |
| ab_test_variant_name | String | A/B テストバリアントの名前。クロスプレースメント A/B テストの場合はテスト設定に基づくバリアント名。それ以外のテストの場合はバリアント名、またはバリアントに名前がない場合はペイウォール名もしくはフロー名。ab_test_variant_id と同時に存在します。 |
| base_plan_id | String | Google Play ストアの ベースプラン ID または Stripe の 価格 ID。 |
| cancellation_reason | String | キャンセル理由の候補: 以下のイベントタイプで存在します: subscription_cancelled、subscription_refunded、trial_cancelled。 |
| cohort_name | String | ユーザーに表示するペイウォールを決定したオーディエンスの名前。 |
| consecutive_payments | Integer | ユーザーが途切れなくサブスクリプションを継続している期間数(現在の期間を含む)。 |
| currency | String | ローカル通貨。Send trial price が有効でない限り、trial_started では null。追加税・収益イベントプロパティを参照してください。 |
| developer_id | String | トランザクションが発生したプレースメントの ID。 |
| discount_amount_local | Float | トランザクションに適用された割引額:標準価格から実際に請求された金額(Apple/Google の手数料控除前)をローカル通貨で引いた値。フルプライス購入の場合は 0。無料トライアルの場合は何も請求されないため、標準価格(original_price_local)と同額になります。オファーが適用されたが標準価格が不明な場合(original_price_local 参照)は null。App Store の pay-up-front オファーでは常に null:一括払いが複数の請求期間をカバーするため、1 期間あたりの標準価格と比較できないためです。 |
| discount_amount_usd | Float | discount_amount_local の USD 換算値。 |
| environment | String | 指定可能な値: Sandbox または Production。 |
| event_datetime | ISO 8601 date | イベントの日時。イベントのルートレベルと同じ値です。 |
| flow_id | UUID | トランザクションが発生したフローの ID。A/B テストの有無にかかわらず、フロー内で行われたすべてのトランザクションで存在します。 |
| flow_name | String | トランザクションが発生したフローの名前。flow_id と同時に存在します。 |
| flow_variation_id | UUID | このプレースメントにおけるフローバリアントの ID。SDK がアプリに flow.variationId として返す値と同じです。flow_id と同時に存在します。 |
| original_price_local | Float | Apple/Google の手数料控除前の、割引なし標準価格(ローカル通貨)。サブスクリプションの場合は更新価格。フルプライス購入の場合は price_local と同額で、買い切り購入の場合も常に price_local と同額(ストアが別途標準価格を報告しないため)。ストアが信頼できる標準価格を報告しない割引購入の場合(例:自動更新オフ、更新時にもオファーが適用中、プロダクト変更が保留中など)は null。 |
| original_price_usd | Float | original_price_local の USD 換算値。 |
| original_purchase_date | ISO 8601 date | 自動更新サブスクリプションの場合、最初のトランザクション(original transaction ID と呼ばれる ID が更新チェーンをリンクする)が元の購入であり、それ以降のトランザクションはその延長です。元の購入日は、この最初のトランザクションの日時です。 |
| original_transaction_id | String | 自動更新サブスクリプションの場合、更新チェーンをリンクする元のトランザクション ID。元のトランザクションはチェーンの最初のもので、それ以降のトランザクションはその延長です。 延長がない場合、 |
| paywall_name | String | トランザクションが発生したペイウォールの名前。フローの場合は、フロー内のペイウォール画面の ID(scr_...)であり、名前ではありません。フロー名は flow_name に入ります。 |
| paywall_revision | String | トランザクションが発生したペイウォールのリビジョン。デフォルト値は 1 です。 |
| price_local | Float | Apple/Google の手数料控除前にトランザクションで請求された金額(ローカル通貨)。Send trial price が有効でない限り、何も請求されない trial_started では null。 |
| price_usd | Float | Apple/Google の手数料控除前にトランザクションで請求された金額(USD)。Send trial price が有効でない限り、何も請求されない trial_started では null。 |
| profile_country | String | プロファイルの IP を元に Adapty が判定した国。 |
| profile_event_id | UUID | 重複排除に使用できる一意のイベント ID。 |
| profile_has_access_level | Boolean | プロファイルにアクティブなアクセスレベルがあるかどうかを示すブール値。 |
| profile_id | UUID | Adapty が生成したプロファイル ID。イベントのルートレベルと同じ値です。 |
| profile_ip_address | String | プロファイルの IP アドレス(IPv4 または IPv6。IPv4 が利用可能な場合は IPv4 が優先されます)。アプリ設定で Collect users’ IP addresses が無効の場合は null。 |
| profile_total_revenue_usd | Float | プロファイルの合計収益(返金分を差し引いた値)。 |
| promotional_offer_id | String | 使用されたプロモーションオファーの Adapty ID。ダッシュボードでオファーを作成する際にこの ID を設定します。 |
| purchase_date | ISO 8601 date | プロダクト購入の日時。 |
| rate_after_first_year | Boolean | サブスクリプションが 1 年間継続更新した後に手数料の優遇レート(通常 15%)の対象になるかどうかを示すブール値。手数料レートはプログラムの適用資格や国によって異なります。詳細はストア手数料と税金を参照してください。 |
| store | String | プロダクトが購入されたストア。標準値: app_store、play_store、stripe、paddle。 サーバーサイド API でカスタムストアトランザクションを設定した場合は、store パラメーターで指定した値が使用されます。 |
| store_country | String | アプリストアから提供された国情報。 |
| store_offer_category | String | 適用されたオファーのカテゴリー。指定可能な値: introductory、promotional、winback。 |
| store_offer_discount_type | String | 適用されたオファーの種類。指定可能な値: free_trial、pay_as_you_go、pay_up_front。 |
| store_offer_number_of_periods | Integer | オファーが割引する基本請求期間の数(1 以上)。オファーが適用されている場合のみ存在します。App Store の pay-up-front オファー、またはストアがオファー期間を報告しない場合は null。 |
| subscription_expires_at | ISO 8601 date | サブスクリプションの有効期限。 返金、請求エラー、グレース期間、アクセスレベルイベントでは、キャンセル日またはグレース期間終了日(該当する場合)が入ります。購入・更新イベントでは、通常のサブスクリプション有効期限が入ります。 |
| transaction_id | String | トランザクションの一意の識別子。 |
| trial_duration | String | トライアル期間の日数。"{} days" 形式(例: "7 days")で送信されます。trial_started、trial_converted、trial_cancelled のトライアル関連イベントタイプにのみ存在します。 |
| variation_id | UUID | 購入が行われたペイウォールの一意の ID。フローの場合は、A/B テストバリアントではなくフロー内のペイウォール画面の ID。フローバージョンが公開されるたびに新しい画面 ID が発行されるため、Adapty は時間の経過とともに異なる variation_id 値を持つ 1 つのバリアントを送信します。テストバリアントごとにトランザクションを分割するには ab_test_variant_id を使用してください。 |
| vendor_product_id | String | Apple App Store、Google Play ストア、または Stripe におけるプロダクト ID。 12 か月コミットメントプランの場合、値は 実際のストアトランザクションなしでアクセスが付与された場合、
|
フローとA/Bテストのフィールド
フローとA/Bテストのフィールドは、トランザクションがどのフロー、A/Bテスト、バリアントから発生したかを示します。通常のペイウォールおよびフローのA/Bテスト、ペイウォールやフローのクロスプレースメントA/Bテストなど、あらゆるA/Bテストタイプで機能します。
Adapty は、developer_id や variation_id を含むイベントと同様に、プレースメントでのトランザクションイベントにこれらのフィールドを送信します。更新、返金、キャンセル、その他のサブスクリプションイベントには、A/B テストが終了した後でも、元の購入と同じフロー、A/B テスト、バリアントが引き継がれます。フィールドに値がない場合、そのイベントにはフィールド自体が含まれません。これらのフィールドが空または null になることはありません。
| トランザクションソース | flow_id, flow_name, flow_variation_id | ab_test_id | ab_test_variant_id, ab_test_variant_name | ab_test_parent_name |
|---|---|---|---|---|
| 通常のペイウォール A/B テスト | — | A/B テスト ID | variation_id と一致 | — |
| A/B テスト外のペイウォール | — | — | — | — |
| フロー A/B テスト | ✅ | A/B テスト ID | flow_variation_id と一致 | — |
| A/B テスト外のフロー | ✅ | — | — | — |
| ペイウォールのクロスプレースメント A/B テスト | — | クロスプレースメントテスト ID | 全プレースメントで共通 | ✅ |
| フローのクロスプレースメント A/B テスト | ✅(このプレースメントのフローバリアント) | クロスプレースメントテスト ID | 全プレースメントで共通 | ✅ |
| プレースメント外 | — | — | — | — |
例えば、フローのクロスプレースメント A/B テストにおける2番目のプレースメントでのバリアント A での購入では、Adapty は以下を送信します:
{
"variation_id": "<paywall screen ID on this placement>",
"ab_test_name": "Onboarding test child-1",
"paywall_name": "scr_a1b2c3d4",
"flow_id": "<flow ID>",
"flow_name": "Onboarding X",
"flow_variation_id": "<variant A on this placement>",
"ab_test_id": "<crossplacement test ID>",
"ab_test_variant_id": "<variant A, shared by all placements>",
"ab_test_variant_name": "A",
"ab_test_parent_name": "Onboarding test"
}
これらのフィールドでレポートを作成するには、トランザクションを ID(ab_test_id、ab_test_variant_id、flow_id)でグループ化し、名前をラベルとして使用します。Adapty はイベント送信時点の名前を使用するため、テスト、バリアント、またはフローの名前を変更すると、それ以降のイベントには新しい名前が付きます。送信済みのイベントは再送信も更新もされません。
クロスプレースメント A/B テストの共有バリアント ID は、通常、最初のプレースメントのバリアント ID とのみ一致します。特定のプレースメントで SDK が返したバリアントとイベントを紐付けるには、flow_variation_id または variation_id を使用してください。
クロスプレースメント A/B テストで同じフローが複数のバリアントに含まれている場合、購入だけではユーザーがどのバリアントにいたかを特定できません。Adapty はユーザーのアサインメント記録からバリアントを取得します。その記録が利用できない場合、Adapty は flow_id、flow_name、ab_test_id を送信しますが、flow_variation_id、ab_test_variant_id、ab_test_variant_name は送信しません。これは、フローを見た直後(記録が保存される前)に購入した場合や、記録の有効期限が切れた後に更新が発生した場合に起こります。Adapty ダッシュボードはそのようなトランザクションを最初のバリアントとしてカウントするため、インテグレーションのデータとダッシュボードの値が異なる場合があります。
税金と収益に関する追加イベントプロパティ
以下の税金と収益に関するイベントプロパティは、特定のイベントタイプにのみ適用される追加フィールドです。つまり、ここに記載されているイベントタイプには、ほとんどのイベントタイプに共通するイベントプロパティに加えて、以下の追加フィールドが含まれます。
税金と収益に関するイベントプロパティを持つイベントタイプ:
subscription_renewedsubscription_initial_purchase(subscription_startedとも呼ばれる — 同じイベント)subscription_refundednon_subscription_purchasenon_subscription_purchase_refundedtrial_startedtrial_converted
| フィールド | 型 | 説明 |
|---|---|---|
| net_revenue_local | Float | ローカル通貨でのネット収益(Apple/Googleの手数料および税金を差し引いた収益)。 |
| net_revenue_usd | Float | USD でのネット収益(Apple/Googleの手数料および税金を差し引いた収益)。 |
| proceeds_local | Float | Apple/Googleの手数料を差し引いた price_local。 |
| proceeds_usd | Float | Apple/Googleの手数料を差し引いた price_usd。 |
| tax_amount_local | Float | price_local に含まれる推定税額。ユーザーが税金を支払った場合でも、Stripe および Paddle では 0。 |
| tax_amount_usd | Float | price_usd に含まれる推定税額。ユーザーが税金を支払った場合でも、Stripe および Paddle では 0。 |
純収益にはnet_revenue_*を直接使用してください。tax_amount_*が0でない限り、proceeds_*からtax_amount_*を引いた金額は小さくなります。例えば、価格が12、手数料30%、税率20%の場合、Adaptyは次のように計算します:
proceeds_*=price_*× (1 − 手数料) = 12 × 0.7 = 8.40tax_amount_*=price_*× 税率 ÷ (1 + 税率) = 12 × 0.2 ÷ 1.2 = 2.00net_revenue_*=proceeds_*÷ (1 + 税率) = 8.40 ÷ 1.2 = 7.00
無料トライアルは課金が発生しないため、trial_started では価格フィールド(price_*、proceeds_*、net_revenue_*、tax_amount_*)および currency はデフォルトで null になります。これらの値を受け取るには、Webhook設定で Send trial price を有効にしてください。有効にすると、Adapty はサブスクリプション価格に Trial price percentage を掛けて計算し、currency を送信します。これらの値はサブスクリプションの内容を表すものであり、実際の課金ではないため、trial_started を収益の合計に含めないでください。
non_subscription_purchase のペイロード例
non_subscription_purchaseはサブスクリプションイベントと同じ構造に従いますが、買い切り購入または消耗型アイテムの購入を反映します。サブスクリプション専用フィールドは適用されません:cancellation_reason、will_renew、is_in_grace_period、is_refund、is_lifetime、trial_durationは存在しません。subscription_expires_atは存在しますがnullです。税金と収益のフィールド(net_revenue_*、proceeds_*、tax_amount_*)は含まれます。
ペイロードの例(クリックして展開)
{
"profile_id": "00000000-0000-0000-0000-000000000000",
"customer_user_id": "UserIdInYourSystem",
"event_type": "non_subscription_purchase",
"event_datetime": "2000-01-31T00:00:00.000000+0000",
"event_properties": {
"store": "app_store",
"currency": "USD",
"price_usd": 4.99,
"price_local": 4.99,
"original_price_usd": 4.99,
"original_price_local": 4.99,
"discount_amount_usd": 0,
"discount_amount_local": 0,
"proceeds_usd": 4.2415,
"proceeds_local": 4.2415,
"net_revenue_usd": 4.2415,
"net_revenue_local": 4.2415,
"tax_amount_usd": 0,
"tax_amount_local": 0,
"profile_id": "00000000-0000-0000-0000-000000000000",
"environment": "Production",
"vendor_product_id": "100coins",
"transaction_id": "0000000000000000",
"original_transaction_id": "0000000000000000",
"purchase_date": "2024-11-15T10:45:36.181000+0000",
"original_purchase_date": "2024-11-15T10:45:36.181000+0000",
"subscription_expires_at": null,
"store_country": "US",
"profile_country": "US",
"profile_ip_address": "10.10.1.1",
"profile_has_access_level": false,
"profile_total_revenue_usd": 4.99,
"consecutive_payments": 1,
"rate_after_first_year": false,
"profile_event_id": "00000000-0000-0000-0000-000000000000"
},
"event_api_version": 1
} アクセスレベル更新イベントについて
Access Level Updated イベントは、Webhook インテグレーションが有効であり、このイベントタイプが有効になっている場合にのみ生成される特定の Webhook イベントです。有効になっている場合、設定済みの Webhook に送信され、Event Feed に表示されます。有効になっていない場合、イベントは作成されません。
アクセスレベルの共有を有効にしている場合、access level updated イベントはアクセスレベルを共有しているすべてのプロファイルに対して送信されます。
このイベントを使用して、データベース内のユーザーのアクセスレベルを更新し、バックエンドでプレミアム機能を付与または取り消し、デバイスやプラットフォーム間でアクセスを同期させましょう。
| プロパティ | タイプ | 説明 |
|---|---|---|
| ab_test_id | UUID | トランザクションが発生した A/B テストの ID。フローおよび A/B テストのフィールドを参照。 |
| ab_test_name | String | トランザクションが発生した A/B テストの名前。クロスプレースメント A/B テストの場合、1つのプレースメントにおけるテスト名(<テスト名> child-N)。 |
| ab_test_parent_name | String | クロスプレースメント A/B テストの名前。クロスプレースメント A/B テストにのみ存在します。 |
| ab_test_variant_id | UUID | トランザクションが発生した A/B テストのバリアント ID。 |
| ab_test_variant_name | String | A/B テストのバリアント名。 |
| access_level_id | String | アクセスレベルの ID。 |
| activated_at | ISO 8601 date | アクセスが最後にアクティベートされた日時。 |
| active_introductory_offer_type | String | 適用された初回オファーのタイプ。free_trial、pay_as_you_go、pay_up_front のいずれか。 |
| active_promotional_offer_id | String | Adapty ダッシュボードのプロダクトセクションに記載されているプロモーションオファーの ID。 |
| active_promotional_offer_type | String | 適用されたプロモーションオファーのタイプ。free_trial、pay_as_you_go、pay_up_front のいずれか。 |
| base_plan_id | String | Google Play ストアのベースプラン ID、または Stripe の価格 ID。 |
| billing_issue_detected_at | ISO 8601 date | 請求問題が発生した日時。 |
| cancellation_reason | String | キャンセル理由として考えられる値: voluntarily_cancelled、billing_error、price_increase、product_was_not_available、refund、cancelled_by_developer、new_subscription_replace、upgraded、unknown、adapty_revoked。 |
| cohort_name | String | プロファイルが属するオーディエンスの名前。 |
| currency | String | ローカル通貨(デフォルトは USD)。 |
| developer_id | String | トランザクションが発生したプレースメントの ID。 |
| environment | String | Sandbox または Production。 |
| event_datetime | ISO 8601 date | イベントの日時。 |
| expires_at | ISO 8601 date | アクセスが失効する日時。Adapty はこのフィールドから グレース期間中はグレース期間の終了日時が入り、返金またはキャンセル後はキャンセル日時が入ります。グレース期間終了用の専用フィールドはありません。 |
| flow_id | UUID | トランザクションが発生したフローの ID。 |
| flow_name | String | トランザクションが発生したフローの名前。 |
| flow_variation_id | UUID | このプレースメントにおけるフローバリアントの ID。SDK の flow.variationId と同じ値。 |
| is_active | Boolean | アクセスレベルがアクティブかどうかを示すブール値。イベント生成時に expires_at(starts_at および is_lifetime と組み合わせて)から算出されます。 |
| is_in_grace_period | Boolean | プロファイルがグレース期間中かどうかを示すブール値。true の間、expires_at にはグレース期間の終了日時が入ります。 |
| is_lifetime | Boolean | アクセスレベルが永続アクセスかどうかを示すブール値。 |
| is_refund | Boolean | トランザクションが返金かどうかを示すブール値。 |
| original_purchase_date | ISO 8601 date | 自動更新サブスクリプションにおいて、最初のトランザクション(オリジナルトランザクション)の日時。オリジナルトランザクション ID は更新チェーンをリンクし、以降のトランザクションはその延長です。 |
| original_transaction_id | String | 自動更新サブスクリプションにおいて、更新チェーンをリンクするオリジナルトランザクション ID。オリジナルトランザクションはチェーンの最初のものであり、以降のトランザクションはその延長です。 延長がない場合、 |
| paywall_name | String | トランザクションが発生したペイウォールの名前。フローの場合はペイウォール画面の ID(scr_...)。 |
| paywall_revision | String | トランザクションが発生したペイウォールのリビジョン。デフォルト値は 1。 |
| profile_country | String | プロファイルの IP をもとに Adapty が判定した国。 |
| profile_event_id | UUID | 重複排除に使用できる一意のイベント ID。 |
| profile_has_access_level | Boolean | プロファイルにアクティブなアクセスレベルがあるかどうかを示すブール値。 |
| profile_id | UUID | Adapty 内部のユーザープロファイル ID。 |
| profile_ip_address | String | プロファイルの IP アドレス(IPv4 または IPv6。IPv4 が優先されます)。アプリ設定で Collect users’ IP addresses が無効な場合は null。 |
| profile_total_revenue_usd | Float | プロファイルの累計収益(返金を含む)。 |
| purchase_date | ISO 8601 date | プロダクト購入の日時。 |
| renewed_at | ISO 8601 date | 有料アクセスの現在の期間が最後に開始された日時。最初の更新まではの activated_at と同じ値になります。 |
| starts_at | ISO 8601 date | アクセスレベルが開始する日時。 |
| store | String | プロダクトが購入されたストア。標準値: app_store、play_store、stripe、paddle。 サーバーサイド API でカスタムストアトランザクションを設定した場合は、store パラメータの値が使用されます。 |
| store_country | String | アプリストアから Adapty に送信された国。 |
| subscription_expires_at | ISO 8601 date | サブスクリプションの有効期限。このイベントでは expires_at と同じ値(グレース期間中はグレース期間の終了日時、返金またはキャンセル後はキャンセル日時)が入ります。 |
| transaction_id | String | トランザクションの一意の識別子。 |
| trial_duration | String | トライアル期間の日数(例:「7 days」)。 |
| variation_id | UUID | バリアションの識別子。購入をこのペイウォールに紐付けるために使用されます。フローの場合、A/B テストのバリアントではなく、フロー内のペイウォール画面の ID。 |
| vendor_product_id | String | ストア(Apple/Google/Stripe)のプロダクト ID。 12ヶ月コミットメントプランの場合、値は 実際のストアトランザクションなしでアクセスが付与された場合、
|
| will_renew | Boolean | 有料アクセスレベルが更新されるかどうかを示す値。 |
この構造は、私たちまたは連携するサードパーティによって新しいデータが追加されることで、今後拡張される可能性があります。この構造を処理するコードは、構造全体ではなく特定のフィールドに依存するよう、十分に堅牢に実装してください。