Web Performance MeasurementのS2S APIでは、Webへの訪問やイベントを、自社サーバーからAppsFlyerに直接送信できます。広告ブロッカーやCookieの制限など、ブラウザによる制約を回避できます。 Web SDKと併用することも、単独で使用することもでき、より網羅的で質の高いアトリビューションデータを取得できます。
Webアトリビューション用S2S APIについて
AppsFlyerは、Webデータをアトリビューション用に送信する方法として、Web SDK(クライアント側)とS2S API(サーバー間通信)の2つに対応しています。構成やニーズに応じて、それぞれを単独で使用することも、併用することもできます。
Web SDKはブラウザ上で動作します。 S2S APIを使うと、同じデータを自社のバックエンドから送信できます。この違いが重要なのは、SafariのITP、FirefoxのETP、Braveなど、プライバシーを重視するブラウザや広告ブロッカーによって、クライアント側の計測がブロック・制限される場合があるためです。業界の推計では、Webユーザーの25〜40%がブラウザレベルでのブロックの対象とされています。 S2Sの呼び出しは自社サーバーから送信され、ブラウザを経由しないため、これらの制限の影響を受けません。
仕組み
- ユーザーがブラウザでWebサイトにアクセスするか、イベントを発生させます。
- 自社サーバーがイベントを受信します。
- 自社サーバーからAppsFlyerのサーバーにイベントを直接送信し、アトリビューションを行います。
S2Sを使用するメリット
S2S APIを使用する主なメリットは、以下のとおりです。
- サーバー側のイベントを計測:バックエンドで処理するサブスクリプションの更新や、CRMシステムで発生するイベントなど、ブラウザを一切経由しないコンバージョンもあります。これらをAppsFlyerに取り込み、適切なキャンペーンに紐付けるには、S2Sを使用する必要があります。
- 計測範囲の拡大:S2Sの呼び出しはブラウザではなく自社サーバーから送信するため、広告ブロッカー、Safari ITPのCookie制限、その他のブラウザレベルの制約を受けません。クライアント側の計測だけでは把握できない訪問やコンバージョンを記録できます。
- バックエンドの情報によるデータの補完:S2Sでは、カスタマーユーザーID、ハッシュ化したメールアドレスや電話番号、CRMの属性、サブスクリプションのステータス、その他の内部識別子などを、サーバー上でイベントに追加してから送信できます。これにより、ユーザーの識別精度とシグナルの品質が向上します。
- セキュリティ:Dev Key、ユーザー識別子、追加データは自社サーバーで管理され、安全な接続で送信されます。自社のインフラから外部に送信する情報を完全に制御できます。
API仕様
ベースURL:https://events.appsflyer.com
認証
すべてのリクエストで、リクエストヘッダーに有効なS2S APIトークンと正しいコンテンツタイプを含める必要があります。
| ヘッダー | 型 | 説明 |
|---|---|---|
Authorization |
APIトークン |
S2S APIトークンは、以下の形式でヘッダーに含めます。 Authorization: Bearer {s2s-token} |
Content-Type |
文字列 |
application/jsonである必要があります。すべてのリクエストで必須です。 |
注意
S2S APIトークンを作成するには、AppsFlyerトークンの管理の手順を参照してください。
イベントの計測
POST /v2.0/s2s/inapps/app/web/{appId}
指定したアプリのWebイベント(購入、新規登録、カスタム操作など)を計測します。
パスパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
appId |
必須 | AppsFlyerで定義したunified_app_id。例:website-www.example.com
|
リクエスト本文
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
user_id |
オブジェクト | 必須 | ユーザー識別子。 customer_user_idまたはappsflyer_idの少なくとも一方を含める必要があります。 |
event_name |
文字列 | 必須 | イベント名。 1〜64文字。 @ = + -は使用できません。例:af_purchase
|
event_revenue |
数値(double) | 任意 | 購入や収益化イベントの収益額。 |
event_revenue_currency |
文字列(ISO-4217) | 任意 | 収益額の通貨コード。例:USD、EUR。 |
event_value |
オブジェクト | 任意 | 自由形式のイベントパラメータ。 custom_parametersサブオブジェクトに対応します。 |
event_url |
文字列 | 任意 | イベントが発生したページのURL。有効なHTTP URL。最大4,096文字。 |
timestamp |
整数(int64) | 任意 | Unix時間。単位はミリ秒(UTC)。省略した場合、AppsFlyerは受信時刻を使用します。遅延データの受付期限:イベントは、アプリのタイムゾーンで翌日の00:30までに届く必要があります。 |
ip |
文字列 | 任意 | デバイスのIPアドレス(IPv4またはIPv6)。最大46文字。 |
user_agent |
文字列 | 任意 | ブラウザのユーザーエージェント文字列全体。最大1,024文字。 |
http_referrer |
文字列 | 任意 | 現在のページのリファラURL。 |
af_customer_event_id |
文字列 | 任意 |
アドネットワークのプラットフォームでコンバージョンの重複を排除するために使用する、自社で発行したイベントごとの一意のID。 AppsFlyerは、この値をイベントIDとしてアドネットワークに転送します。 以下のいずれかに該当する場合に送信してください。
送信する場合は、アドネットワーク自身のピクセルイベント(例: 省略するとAppsFlyerが独自のIDを生成するため、アドネットワークはピクセルイベントと照合できません。 制限:最大256文字。照合は完全一致で、大文字と小文字を区別します。 |
email_hashed |
文字列 | 任意 | 正規化したメールアドレス(小文字に変換し、前後の空白を削除)のSHA256ハッシュ。 64文字の16進数文字列である必要があります。 |
phone_number_hashed |
文字列 | 任意 | 電話番号のSHA256ハッシュ。 64文字の16進数文字列である必要があります。 |
phone_number_e164_hashed |
文字列 | 任意 | E.164形式の電話番号(例:+14155552671)のSHA256ハッシュ。 64文字の16進数文字列である必要があります。 |
first_name_hashed |
文字列 | 任意 | 正規化した名のSHA256ハッシュ。 64文字の16進数文字列である必要があります。 |
last_name_hashed |
文字列 | 任意 | 正規化した姓のSHA256ハッシュ。 64文字の16進数文字列である必要があります。 |
リクエスト例
{"user_id":{"customer_user_id":"15667737-366d-4994-ac8b-653fe6b2be4a"},"event_name":"af_purchase","event_revenue":49.99,"event_revenue_currency":"USD","af_customer_event_id": "550e8400-e29b-41d4-a716-446655440000","event_value":{"af_content_id":"SKU-001","af_quantity":2,"custom_parameters":{"promo_code":"SUMMER10"}},"event_url":"https://example.com/checkout/success","timestamp":1712000000000,"ip":"35.244.183.10","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...","email_hashed":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"}レスポンス
| ステータス | 説明 |
|---|---|
| 202 Accepted | リクエストを受け付けました。ステータス、メッセージ、および任意のmessageIdを返します。 |
| 400 Bad Request | フィールドが無効または不足しています。 |
| 401 Unauthorized | アプリが存在しないか、認証に失敗しました。 |
| 403 Forbidden | アプリのトラフィックがブロックされています。 |
| 415 Unsupported Media Type |
Content-Typeはapplication/jsonである必要があります。 |
訪問の計測
POST /v2.0/s2s/visits/app/web/{appId}
指定したWebアプリのページ訪問を計測します。このエンドポイントの基本フィールドはイベント用エンドポイントと共通ですが、重要な違いが2つあります。event_urlは必須で、イベント名と収益のフィールドは使用しません。
パスパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
appId |
必須 | AppsFlyerで定義したunified_app_id。例:website-www.example.com
|
リクエスト本文
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
user_id |
オブジェクト | 必須 | ユーザー識別子。 customer_user_idまたはappsflyer_idの少なくとも一方を含める必要があります。 |
event_url |
文字列 | 必須 | 訪問したページのURL。有効なHTTP URL。最大4,096文字。 |
timestamp |
整数(int64) | 任意 | Unix時間。単位はミリ秒(UTC)。省略した場合、AppsFlyerは受信時刻を使用します。遅延データの受付期限:訪問は、アプリのタイムゾーンで翌日の00:30までに届く必要があります。 |
ip |
文字列 | 任意 | デバイスのIPアドレス(IPv4またはIPv6)。最大46文字。 |
user_agent |
文字列 | 任意 | ブラウザのユーザーエージェント文字列全体。最大1,024文字。 |
http_referrer |
文字列 | 任意 | 現在のページのリファラURL。 |
event_value |
オブジェクト | 任意 |
custom_parametersサブオブジェクトを含む、自由形式のイベントパラメータ。 |
af_customer_event_id |
文字列 | 任意 |
アドネットワークのプラットフォームでコンバージョンの重複を排除するために使用する、自社で発行したイベントごとの一意のID。 AppsFlyerは、この値をイベントIDとしてアドネットワークに転送します。 以下のいずれかに該当する場合に送信してください。
送信する場合は、アドネットワーク自身のピクセルイベント(例: 省略するとAppsFlyerが独自のIDを生成するため、アドネットワークはピクセルイベントと照合できません。 制限:最大256文字。照合は完全一致で、大文字と小文字を区別します。 |
email_hashed |
文字列 | 任意 | 正規化したメールアドレスのSHA256ハッシュ。 64文字の16進数文字列である必要があります。 |
phone_number_hashed |
文字列 | 任意 | 電話番号のSHA256ハッシュ。 64文字の16進数文字列である必要があります。 |
phone_number_e164_hashed |
文字列 | 任意 | E.164形式の電話番号のSHA256ハッシュ。 64文字の16進数文字列である必要があります。 |
first_name_hashed |
文字列 | 任意 | 正規化した名のSHA256ハッシュ。 64文字の16進数文字列である必要があります。 |
last_name_hashed |
文字列 | 任意 | 正規化した姓のSHA256ハッシュ。 64文字の16進数文字列である必要があります。 |
リクエスト例
{"user_id":{"appsflyer_id":"1234567890abcdef","customer_user_id":"15667737-366d-4994-ac8b-653fe6b2be4a"},"af_customer_event_id": "550e8400-e29b-41d4-a716-446655440000","event_url":"https://example.com/products/sneakers","timestamp":1712000000000,"ip":"35.244.183.10","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...","http_referrer":"https://www.google.com/","email_hashed":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"}レスポンス
| ステータス | 説明 |
|---|---|
| 202 Accepted | リクエストを受け付けました。ステータス、メッセージ、および任意のmessageIdを返します。 |
| 400 Bad Request | フィールドが無効または不足しています。 |
| 401 Unauthorized | アプリが存在しないか、認証に失敗しました。 |
| 403 Forbidden | アプリのトラフィックがブロックされています。 |
| 415 Unsupported Media Type |
Content-Typeはapplication/jsonである必要があります。 |
すべてをサーバー側で実装する方法
Web SDKとS2Sを併用する場合は、代わりにWeb SDKのafUserIDの取得を参照してください。このセクションは、SDKを使用しない実装のみを対象としています。
サイトでWeb SDKを使用しない場合は、通常SDKが行うすべての処理を自社で担う必要があります。ユーザーのCookieの発行、適切な識別子の送信、各イベントのペイロードに必要な情報をすべて含めることが求められます。これらを正しく実装すると、S2Sを使用するメリットで説明した利点をすべて得られます。
イベントだけでなく訪問も送信
訪問には、後続のすべてのイベントの基準となるアトリビューションパラメータが含まれます。このシステムは、ユーザーのイベントに先立って訪問があることを前提としています。訪問より先にイベントを送信すると、オーガニックに分類されます。
HTTP経由でファーストパーティCookieを発行
Web SDKがafUserId Cookieを設定しないため、自社で発行・管理する必要があります。JavaScriptで書き込むクライアント側のCookieではなく、レスポンスのSet-Cookieヘッダーで設定するHTTP Cookieとして発行してください。
クライアント側でdocument.cookieを使って設定したCookieは、有効期間が短く、Safariでは最短7日、ITPの対象ドメインでは24時間で失効します。失効すると識別子がリセットされ、再訪問者が新規ユーザーとして扱われます。サーバーが設定するCookieは、この制限の対象外で、ブラウザの上限まで保持できます(Chromeでは最大400日)。 HttpOnlyを付けることもでき、その場合はページのスクリプトや広告ブロッカーによる読み取り・削除を防げます。また、ページ上でスクリプトを実行する必要もありません。
設定と読み取りの手順:
- Cookieを持たない訪問者からの最初のリクエスト時に、自社サーバーで安定した一意のID(UUIDなど)を生成します。
-
そのIDをファーストパーティCookieで返します。
Set-Cookie: af_web_id=<generated-id>; Max-Age=34128000; Path=/; Secure; HttpOnly; SameSite=Lax - 以降のすべてのリクエストでは、受信したCookieヘッダーから値を読み取り、再利用します。 IDを再生成しないでください。
- その値を、すべての呼び出しでリクエストの
user_idオブジェクト内のappsflyer_idとしてAppsFlyerに送信します。
Cookie名は任意です。AppsFlyerが読み取るのは送信された値であり、Cookie名ではありません。必ず自社のファーストパーティドメインから設定してください。
各呼び出しで適切な識別子を送信
すべての呼び出しで、user_idオブジェクトにappsflyer_id(Cookieの値)またはcustomer_user_id(自社の内部ユーザーID)の少なくとも一方を含める必要があります。両方の値がある場合は、両方を送信するとユーザーの識別精度が向上します。
訪問時のユーザーはほとんどが匿名のため、Cookieの値は常に送信してください。サイト内のイベントでは、ユーザーを識別できた時点でcustomer_user_idを追加し、Cookieの値も引き続き送信します。ブラウザ以外で発生したイベントでは、過去の識別済みセッションでAppsFlyerがすでにそのユーザーを認識していれば、customer_user_idだけで十分です。
考慮事項
ユーザーの識別
user_idオブジェクトは、すべてのリクエストで必須です。以下の識別子の少なくとも一方を指定する必要があります。
| フィールド | 型 | 説明 |
|---|---|---|
customer_user_id |
文字列(1〜64文字) | 自社システムで設定した内部ユーザー識別子。 |
appsflyer_id |
文字列(1文字以上) | Webユーザーに対するAppsFlyerの内部識別子。 AppsFlyer Web SDKを使用する場合は、Web SDKのCookieからappsflyer_idの値を取得します。 afUserIdから抽出してください。 Web SDKのafUserIdの取得を参照してください。
|
遅延データの受付期限
イベントと訪問は、アプリのタイムゾーンで翌日の00:30までに受信される必要があります。遅れたイベントは、サーバーの受信時刻を使用します。
ハッシュ化する個人情報(PII)のフィールド
すべての個人情報フィールドは、送信前にSHA256でハッシュ化する必要があります。ハッシュ化する前に、テキストを正規化してください(小文字に変換し、前後の空白を削除)。各ハッシュ値は、ちょうど64文字の16進数である必要があります(大文字と小文字は区別しません)。
- すべてのハッシュ化フィールドのパターン:
^[a-fA-F0-9]{64}$ -
phone_number_e164_hashedフィールドの電話番号は、ハッシュ化前にE.164形式(例:+14155552671)に揃える必要があります。
Web SDKのafUserIDの取得
-
afUserIdパラメータは、ユーザーのサイトへの初回訪問時にWeb SDKが設定する一意の識別子です。 -
afUserIdが必要な場合は、以下のいずれかの方法で取得してください。
HTTP CookieヘッダーからのafUserIdの取得
-
afUserIdは、訪問者のブラウザからサイトへのリクエストで送信されます。 - 必要に応じて、HTTP Cookieヘッダーから抽出してください。
訪問者のブラウザでのafUserIdの表示
- トラブルシューティングやデバッグのために、訪問者のブラウザで
afUserIdを確認します。 - 表示するには、訪問者がWeb SDKを実装したページに1回以上アクセスしている必要があります。
-
afUserIdを含むCookieは、自社ドメインに対するファーストパーティCookieです。 - 以下の手順はChrome 81で作成したものです。ブラウザやOSによって異なる場合があります。
訪問者のブラウザからafUserIdを取得するには、以下の手順に従います。
- ブラウザでWebサイトを開きます。
- 右クリックし、[Inspect]を選択します。ブラウザの要素検証ウィンドウが開きます。
- (A)[Application]タブを開きます。
- サイドメニューで(B)[Cookies]を展開します。
- Webサイトを選択します。表示されない場合は、ブラウザを再読み込みしてください。
- (C)[filter]欄に
afUserIdを入力します。 afUserIDの値が表示されます。
Segment(CDP)経由でのイベント送信
Segmentを使って、S2S APIにイベントを送信できます。 (Segmentは、顧客イベントを収集し、設定した送信先に送るためのカスタマーデータプラットフォームです。)
Web SDKとSegmentは、一方から他方にデータを渡すのではなく、AppsFlyerにデータを送る2つの独立した経路です。Web SDKはアトリビューションパラメータを含む訪問を送り、SegmentはSDKを実装していないプロパティのイベントを送ります。両方の経路は互いに独立しています。AppsFlyerが、両方で送信された識別子を使って訪問とイベントを紐付けます。
注意
ここでは、Segmentのカスタム送信先からS2S経由で送信するWebイベントを説明します。アプリのインストールやアプリ内イベントをAppsFlyerのモバイルSDKに連携する、SegmentのモバイルSDKラッパーについては、Segment連携を参照してください。対象プラットフォームも連携方法も異なります。
Segmentでの送信先の設定
AppsFlyerには、S2S API用の構築済みSegment送信先がまだありません。そのため、各イベントをS2Sエンドポイントに送信するカスタム送信先をSegmentで設定する必要があります。データ形式をどの程度制御する必要があるかに応じて、2つの方法があります。
方法1:Webhooks(Actions)送信先
まずはこの方法を推奨します。コードは不要で、すべてSegmentのUIで設定できます。
設定手順:
- Segmentの送信先カタログからWebhooks送信先を追加します。
- 送信したいイベントを収集しているソースに接続します。
- イベントの種類ごとにマッピングを作成します。AppsFlyerのURLを指定し、メソッドをPOSTに設定して、必要なヘッダーを追加し、イベントのフィールドからJSONペイロードを構築します。
方法2:Destination Function
WebhooksのマッピングでAppsFlyerに必要なペイロード形式を作成できない場合にのみ、この方法を使用してください。 Destination Functionは、Segment内で実行される小規模なJavaScript関数です。各イベントを受信し、fetchを使ってAppsFlyerのエンドポイントに送信します。
以下の場合に使用します。
-
userオブジェクト内にuser_idを入れるなど、WebhooksのマッピングUIでは作成できないネスト構造がペイロードに必要な場合。 - タイムスタンプの形式変換など、送信前にイベントデータの変換が必要な場合。
AppsFlyerのエンドポイント
どちらの設定でも、以下のエンドポイントに送信してください。
POST https://events.appsflyer.com/v2.0/s2s/inapps/app/web/website-{your_domain}
Authorization: Bearer {s2s-token}
Content-Type: application/json
AppsFlyerのトークン管理ページからS2S APIキーを取得します(認証を参照)。パスには、アプリ設定ページにある[Web SDK ID]のUUIDではなく、WebアプリID(例:website-www.your_domain)を使用してください。
イベントごとのペイロード
マッピングしたイベントごとに、以下のフィールドを含むJSON本文を作成します。
{
"user_id": {
"customer_user_id": "<your internal user ID>",
"appsflyer_id": "<afUserId cookie value, when available>"
},
"event_name": "signup",
"event_url": "<page URL where the event happened>",
"ip": "<end-user IP>",
"user_agent": "<end-user user agent>",
"af_customer_event_id": "<Segment messageId>"
}
アトリビューションを行うための2つのルール
- マーケティングサイトではWeb SDKを引き続き使用してください。訪問はWeb SDKが記録し、イベントはSegmentが送信します。このセクションの冒頭で説明したとおり、イベントの前にユーザーの訪問が必要です。訪問がない場合、イベントはオーガニックにアトリビューションされます。 Web SDKを一切使わず、すべてをサーバー側で実装する場合は、すべてをサーバー側で実装する方法に従ってください。
- 各呼び出しには適切な識別子も必要です。「各呼び出しで適切な識別子を送信」で説明したとおり、同じ
appsflyer_idまたはcustomer_user_idの組み合わせを送信してください。
設定の検証
送信先とペイロードの設定ができたら、以下の3段階で導入を進めます。
- Segmentで1〜2個のイベントをマッピングし(まずは新規登録イベントを推奨)、マッピングのテスト機能からテストイベントを送信します。
- ローデータレポートに正しく届き、マーケティングサイトの訪問と紐付いていることを確認します。
- 確認できたら、残りのイベントにもマッピングを広げます。
推奨する導入手順
送信先とペイロードの設定ができたら、以下の3段階で導入を進めます。
- Segmentで1〜2個のイベントをマッピングし(まずは新規登録イベントを推奨)、マッピングのテスト機能からテストイベントを送信します。
- ローデータレポートに正しく届き、マーケティングサイトの訪問と紐付いていることを確認します。
- 確認できたら、残りのイベントにもマッピングを広げます。