どのようにお手伝いできますか?

Web Performance Measurement用サーバー間(S2S)API

  • 更新

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の呼び出しは自社サーバーから送信され、ブラウザを経由しないため、これらの制限の影響を受けません。

仕組み

  1. ユーザーがブラウザでWebサイトにアクセスするか、イベントを発生させます。
  2. 自社サーバーがイベントを受信します。
  3. 自社サーバーから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の計測と並行して、サイトでアドネットワークのピクセルを使用している。
  • 同じイベントをWeb SDKとこのAPIの両方で送信している。

送信する場合は、アドネットワーク自身のピクセルイベント(例:fbq()のeventID)にも同じ値を設定してください。これにより、アドネットワークがコンバージョンを二重計上せず、1件として数えられます。

省略すると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の計測と並行して、サイトでアドネットワークのピクセルを使用している。
  • 同じイベントをWeb SDKとこのAPIの両方で送信している。

送信する場合は、アドネットワーク自身のピクセルイベント(例:fbq()のeventID)にも同じ値を設定してください。これにより、アドネットワークがコンバージョンを二重計上せず、1件として数えられます。

省略すると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を付けることもでき、その場合はページのスクリプトや広告ブロッカーによる読み取り・削除を防げます。また、ページ上でスクリプトを実行する必要もありません。

設定と読み取りの手順:

  1. Cookieを持たない訪問者からの最初のリクエスト時に、自社サーバーで安定した一意のID(UUIDなど)を生成します。
  2. そのIDをファーストパーティCookieで返します。

    Set-Cookie: af_web_id=<generated-id>; Max-Age=34128000; Path=/; Secure; HttpOnly; SameSite=Lax
  3. 以降のすべてのリクエストでは、受信したCookieヘッダーから値を読み取り、再利用します。 IDを再生成しないでください。
  4. その値を、すべての呼び出しでリクエストの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を取得するには、以下の手順に従います。

  1. ブラウザでWebサイトを開きます。
  2. 右クリックし、[Inspect]を選択します。ブラウザの要素検証ウィンドウが開きます。
  3. (A)[Application]タブを開きます。
  4. サイドメニューで(B)[Cookies]を展開します。
  5. Webサイトを選択します。表示されない場合は、ブラウザを再読み込みしてください。
  6. (C)[filter]欄にafUserIdを入力します。 afUserIDの値が表示されます。

Segment(CDP)経由でのイベント送信

Segmentを使って、S2S APIにイベントを送信できます。 (Segmentは、顧客イベントを収集し、設定した送信先に送るためのカスタマーデータプラットフォームです。)

Web SDKとSegmentは、一方から他方にデータを渡すのではなく、AppsFlyerにデータを送る2つの独立した経路です。Web SDKはアトリビューションパラメータを含む訪問を送り、SegmentはSDKを実装していないプロパティのイベントを送ります。両方の経路は互いに独立しています。AppsFlyerが、両方で送信された識別子を使って訪問とイベントを紐付けます。

Web SDK:訪問を送信
Segment:イベントを送信
S2S API
紐付けに使用:appsflyer_idまたはcustomer_user_id
AppsFlyer:訪問とイベントを紐付け
Web SDKとSegmentは、共通の識別子で紐付けられる、AppsFlyerへの2つの独立したデータ送信経路です。

注意

ここでは、Segmentのカスタム送信先からS2S経由で送信するWebイベントを説明します。アプリのインストールやアプリ内イベントをAppsFlyerのモバイルSDKに連携する、SegmentのモバイルSDKラッパーについては、Segment連携を参照してください。対象プラットフォームも連携方法も異なります。

Segmentでの送信先の設定

AppsFlyerには、S2S API用の構築済みSegment送信先がまだありません。そのため、各イベントをS2Sエンドポイントに送信するカスタム送信先をSegmentで設定する必要があります。データ形式をどの程度制御する必要があるかに応じて、2つの方法があります。

方法1:Webhooks(Actions)送信先

まずはこの方法を推奨します。コードは不要で、すべてSegmentのUIで設定できます。

設定手順:

  1. Segmentの送信先カタログからWebhooks送信先を追加します。
  2. 送信したいイベントを収集しているソースに接続します。
  3. イベントの種類ごとにマッピングを作成します。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つのルール
  1. マーケティングサイトではWeb SDKを引き続き使用してください。訪問はWeb SDKが記録し、イベントはSegmentが送信します。このセクションの冒頭で説明したとおり、イベントの前にユーザーの訪問が必要です。訪問がない場合、イベントはオーガニックにアトリビューションされます。 Web SDKを一切使わず、すべてをサーバー側で実装する場合は、すべてをサーバー側で実装する方法に従ってください。
  2. 各呼び出しには適切な識別子も必要です。「各呼び出しで適切な識別子を送信」で説明したとおり、同じappsflyer_idまたはcustomer_user_idの組み合わせを送信してください。
設定の検証

送信先とペイロードの設定ができたら、以下の3段階で導入を進めます。

  1. Segmentで1〜2個のイベントをマッピングし(まずは新規登録イベントを推奨)、マッピングのテスト機能からテストイベントを送信します。
  2. ローデータレポートに正しく届き、マーケティングサイトの訪問と紐付いていることを確認します。
  3. 確認できたら、残りのイベントにもマッピングを広げます。
推奨する導入手順

送信先とペイロードの設定ができたら、以下の3段階で導入を進めます。

  1. Segmentで1〜2個のイベントをマッピングし(まずは新規登録イベントを推奨)、マッピングのテスト機能からテストイベントを送信します。
  2. ローデータレポートに正しく届き、マーケティングサイトの訪問と紐付いていることを確認します。
  3. 確認できたら、残りのイベントにもマッピングを広げます。