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

PBA向け Web Server-to-ServerイベントAPI(Web-S2S)

  • 更新

概要:Web Server-to-Server(Web-S2S)イベントAPIを使用すると、Web SDKでは送信されないイベントやコンバージョンをPBAへ送信できます。

5107_Infographic_Web_S2S_759x270_option1.jpg

PBA向け Web Server-to-ServerイベントAPI

People-Based Attribution(PBA)向けのWeb-S2S APIは、Web SDKを補完する仕組みであり、マーケターがWeb SDKの対象外となるウェブサイト上のイベントをレポートできるようにします。 For example, a visitor to the website (a web user), triggers an online payment event, processed by backend systems. たとえば、Webサイト訪問者(Webユーザー)がオンライン決済イベントを発生させ、その処理がバックエンドシステムで行われる場合、処理完了後にバックエンドはS2S APIを使用して、そのイベントをAppsFlyerへ送信します。

S2S APIで送信されたイベントは以下のように扱われます。

  • Web SDKから送信されたイベントと同様に記録される
  • コンバージョンイベントとして設定されている場合、PBAダッシュボードに表示される
  • PBA Raw Dataに記録され、event_sourceのフィールドには web S2S として設定される

API利用手順

以下のセクションを参考にAPIコールを作成してください。 

No. 項目 Remarks
1 ユニークユーザーID
  • 可能な限り最も適切なユーザーIDを送信してください。これはデータ分析に大きく影響します。
  • ベストプラクティスは customerUserId の送信です。利用できない場合は afUserId(Web SDKが設定するCookie ID) を送信してください。
  • 顧客ユーザーID(CUID)とafUserIdを関連付ける場合は、両方のIDを含めて setCuID() メッセージを送信します。
2 タイムスタンプ
  • AppsFlyerはイベントのタイムスタンプに対して厳格な検証を行います。
    • 遅れて到着したイベント:イベントは、本来の発生日から24時間以内に送信された場合、元のタイムスタンプで記録されます。たとえば、月曜日 23:59(UTC)のイベントは火曜日 23:59:59(UTC)までに送信すれば元の時間を保持しますが、火曜日 23:59:59 UTC 以降に送信された場合にはサーバー受信時間に上書きされます。
    • 未来のタイムスタンプ:実際の受信時間より未来のタイムスタンプは許可されません。この場合もサーバー受信時間に上書きされます。
  • Timestamps are UTC-based. ※タイムスタンプはUTCベースです。 必要に応じてローカル時間からUTCへ変換してからパラメータに記載してください。
3 収益金額と通貨設定 eventRevenueCurrency と eventRevenue は、eventValue 内に含まれている場合でも必ず送信してください。これらの情報が管理画面上で使用されます。

API基本情報

APIの実装には、管理画面から取得できる以下の認証情報が必要です。

  • Bundle ID(Brand Bundle ID)
  • Web Dev key

認証情報の取得方法: 

  1. AppsFlyerの上部メニューからマイアプリ > ブランドバンドルを表示を選択します。
    バンドルの一覧が表示されます。
  2. 適切な内容をコピーして記録します:
    • Brand bundle ID
    • Web dev key

Web S2S API 基本仕様

Path

https://webs2s.appsflyer.com/v1/bundleId/method

  • bundleId:ダッシュボードに表示されるアプリのBundle ID 
  • method 次のいずれかを実行してください:
    • event:バックエンドイベント送信用
    • setCuId: afUserIdとCUIDを関連付ける場合
HTTP method POST
Content Type application/json 
JSON payload 制限 

最大サイズ:1KB

レート制限

POST limitation volume: 60,000 POSTs per minute. To increase the limit, contact your CSM.

TLS

setCuId メソッド

メソッド名

setCuId

ユースケース 

CUIDをWeb訪問者に紐づける場合に使用します。 For example, any time you match the web afUserId with your customer user ID. Doing so enables PBA to match data from various sources. これはWebサイトで使用する setCustomerUserId と同様の仕組みです。

メソッドパス

https://webs2s.appsflyer.com/v1/bundleId/setcuid

Payload

JSON payloadはこちらに記載されたパラメータで構成され、すべてのパラメーターは必須です。 All parameters are mandatory.

 setCuIdの Curl サンプル


curl --location --request POST 'https://webs2s.appsflyer.com/v1/bundleId/setcuid' \ --header 'Accept-Encoding: application/json' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerUserId": "1234567890abcdef", "afUserId":"9999999-f848-4963-a091-568f0bf9a361", "webDevKey" : "99999999-9999-9999-9999-999999999999"}

Event メソッド

メソッド名

event

ユースケース 送信
メソッドパス

https://webs2s.appsflyer.com/v1/bundleId/event

 詳細情報 この記事のイベントメソッドの詳細セクションには、Payloadの詳細、Curlの例、Pythonの例、およびテストに関する推奨事項が含まれています。

Event メソッドの詳細

Payload パラメータ

Payload パラメーターは、ユーザー識別子とイベントパラメータに分かれています。 

  • User ID:少なくとも1つのユーザーIDパラメータを送信する必要があります。
  • Event:必須パラメータと、必要に応じてオプションのパラメータを送信してください。

ユーザーIDパラメータ(少なくとも1つのパラメータを送信)

ユーザーIDパラメータ  説明

customerUserId

顧客ユーザーID (CUID) はお客様が設定した一意の識別子です。

  • AppsFlyerに送信するすべてのイベントで同一IDを使用する必要があります。つまり、同じIDが Web SDK、モバイル SDK、および S2S API で使用されています。
  • Web SDKの顧客ユーザーID
  • 形式:文字列
  • 例:"customerUserId" : "663274"
  • ローデータで入力される項目:customer_user_id

afUserId

Web SDKがユーザーのサイト訪問時に付与するユーザーIDです。このCookie値をバックエンドサーバーへ送信する必要があります。

  •  Cookie の詳細:
    • 名称:afUserId
    • 値:afUserId をこの値に設定してください。
    • ドメイン:website-domain
  • 例: "afUserId" : "unique_cookie_uuid"
  • ローデータで入力される項目:af_web_id

イベントパラメーター

パラメータ名 必須 説明

webDevKey

Yes

管理画面から取得できる Web Dev Key を使用して入力してください。

  • 例:"webDevKey" : "ffffffff-ffff-ffff-ffff-ffffffffffff"
eventType Yes

AppsFlyerが内部で使用するイベント属性の識別子です。常に EVENT で設定してください。

  • 例:"eventType" : "EVENT"
eventName Yes
  • このパラメータは、PBA設定でマーケティング担当者が設定したイベントコンバージョンリストを使用して、コンバージョンとコンバージョンでないイベントを区別するために使用されます。 
  • マーケティング担当者のコンバージョンロジックと一致する値を入力してください。
  • 形式:文字列
  • 例:"eventName" : "web_purchase"
  • ローデータで入力される項目:event_name
timestamp No

イベントが発生した時間(ミリ秒単位)です。 13桁の Unix タイムスタンプとして送信してください。

  • タイムスタンプが送信されない場合は、サーバー時刻が使用・設定されます。 
  • 遅れて到着したイベントには、現在のサーバ時刻がタイムスタンプとしてが使用されます これは、イベントが発生した翌日の午前0時(UTC)よりも後にデータが届いた場合に適用されます。 Late means arrival after midnight UTC on the day following the event. 例えば、月曜日に発生したイベントは、UTCタイムゾーンで火曜日の深夜までに処理される必要があります。 
  • 未来のタイムスタンプ(現在のサーバー時刻との比較)を持つイベントはサーバー時刻でタイムスタンプが記録されます。
  • 形式:Int
  • 例:"timestamp" : 1584835200123
  • ローデータで入力される項目:event_time
eventValue No
イベントの詳細を説明する、イベントパラメータの一覧です。このパラメーターを使用して、製品、アイテム価格などの情報をアプリ内イベントで送信してください。
  • Note about revenue! You can populate this parameter with revenue details. In addition, you must populate eventRevenue, and eventRevenueCurrency.
  • 形式:JSON
  • 例: SKU ABC123を送信するために、青色で単価が$3.99のイベント値を設定する場合:
    {"Purchase": {"sku" : "ABC123", "color": "blue", "unit_price":3.99,"currency": "USD"}}
  • 制限: 1000文字を超えないようにしてください。 Do not exceed this; it will be truncated. 
  • ローデータで入力される項目:event_value
eventRevenueCurrency No

収益イベントの通貨コードです。 3文字で構成されている ISO 4217 通貨コードを設定してください。

  • デフォルト:USD
  • 形式:文字列
  • 例: "eventRevenueCurrency" : "EUR"
  • ローデータで入力される項目:event_revenue_currency
eventRevenue No 

Revenue (monetary value) assigned to an event.

収益に関する注意点:このパラメーターに収益の詳細データを入力してください。さらに、eventRevenue と eventRevenueCurrency を入力する必要があります。 

  • 負の値も入力できます。(例:ユーザーによる返金など)
  • 形式:Float 
  • 値の例:1 1.2 1234.20 -1234.20
  • ローデータで入力される項目:event_revenue
eventCategory No  このパラメーターは非推奨で、廃止日以降(今後発表予定)に削除されます。代わりに eventValue を使用してください。
eventLabel No 

このパラメーターは非推奨で、廃止日以降(今後発表予定)に削除されます。代わりに eventValue を使用してください。

referrer No

HTTP referrer

  • 形式:文字列
  • 例:"referrer" : "https://www.google.com/"
  • ローデータで入力される項目:http_referrer
userAgent No 

ブラウザからサーバーに送信される User-agent リクエスト です。

  • デバイスタイプを判断するのに役立ちますので、できる限りこの値を送信してください。 
  • 形式:文字列
  • 例:"userAgent" : "Chrome/80.0.3987"
  • ローデータで入力される項目:user_agent
ip No

ユーザーのIPアドレスです。

  • 可能な限り、この項目の値を送信してください。これは、ユーザーの地理情報 を決定するのに役立ちます。
  • 形式:文字列
  • 例: "ip": "192.0.2.1"
  • ローデータで入力される項目:ip
 

Curl サンプル

curl --location --request POST 'https://webs2s.appsflyer.com/v1/bundleId/event' \
--header 'Accept-Encoding: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
	"customerUserId": "1234567890abcdef",
	"afUserId":"9999999-f848-4963-a091-568f0bf9a361",
    "webDevKey" : "99999999-9999-9999-9999-999999999999",
    "ip" : "192.0.2.1",
	"eventType":"EVENT",
	"timestamp" : 1234567890123,
	"eventName":"my_web_event",
	"eventRevenueCurrency" : "EUR",
	"eventRevenue" : 1234.56,
	
		"eventValue": {
		"purchase":{
		 "shoes": "color",
		 "quantity" : "3",
		 "Revenue" : "1234.56",
		 "Currency" : "ZAR"
		}
	}

}'

Python サンプル

''' using the requests python package, install using pip install requests  '''
import requests
url = "https://webs2s.appsflyer.com/v1/bundleId/event"
payload = {
    "customerUserId": "1234567890abcdef",
    "afUserId": "9999999-f848-4963-a091-568f0bf9a361",
    "webDevKey": "99999999-9999-9999-9999-999999999999",
    "ip": "192.0.2.1",
    "eventType": "EVENT",
    "timestamp": 1234567890123,
    "eventName": "my_web_event",
    "eventRevenenuCurrency": "EUR",
    "eventRevenue": 1234.56,
    "eventValue":
        {
            "purchase":
            {
                "shoes": "color",
                "quantity": "3",
                "Revenue": "1234.56",
                "Currency": "ZAR"
            }
        }
    }
headers = {
    'Accept-Encoding': 'application/json',
    'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text.encode('utf8'))

テスト

テスト時は以下の手順でイベントを送信してください。

  1. イベントを送信する
  2. Ensure that you get a 200 OK return code. If not, take corrective action using the return codes and error messages.
  3. UTCタイムゾーンの午前0時のあと数時間待機し、PBA Raw Dataにイベントが表示されるまで待つ(PBAデータの処理は1日1回のみのため) You must wait because PBA data is processed once a day. 

追加情報

Web Dev Key の取得

 Web Dev Key の取得方法:

  1. AppsFlyerの管理画面内で、[ My Apps ]のタブに移動してください。
  2. Click View brand bundles.

    GetWebDevKeyPba_us-en.pn

  3. 必要な Web Dev Key をコピーしてください。 

Web SDKの afUserID の抽出

  • afUserIdは、ユーザーが最初にウェブサイトを訪問した際に Web SDK によって割り当てられる一意の識別子です。
  • afUserIdが必要な場合は、以下の方法のいずれかを使用してください。


HTTP CookieヘッダーからafUserIdを取得

  • afUserIdは、ユーザーがサイトへアクセスする際に訪問者のブラウザから送信されます。
  •  必要に応じてHTTP cookie ヘッダーから抽出してください。


訪問者のブラウザでafUserIdを確認

  •  [ブランドバンドルを表示]をクリックします。
  • afUserIdを確認するには、訪問者がWeb SDKが実装されたページを少なくとも一度訪問している必要があります。 
  • afUserIdを含むCookieは、自社ドメインに対するファーストパーティCookieです。
  • 以下の手順はChrome 81を使用して作成されています。ブラウザやOSによって手順が多少異なる場合があります。

訪問者のブラウザから afUserId を取得する方法:

  1. In your browser, go to your website.
  2. 右クリックし、Inspect(検証)を選択します。
    ブラウザの検査ウィンドウが開きます。

    S2S_inspect.jpg

  3. (A) Applicationタブを開きます。
  4. サイドメニューにて、(B) [Cookie] を展開します。
  5. 自社Webサイトを選択します。表示されない場合は、ブラウザをリフレッシュしてください。
  6. トラブルシューティングやデバッグの目的で、訪問者のブラウザ上でafUserIdを確認できます。 

レスポンスコード

レスポンスコード メッセージ How to Handle
200 OK  
404 Not found
  • エンドポイントを確認してください。 
  • 正しい Bundle ID が設定されているか確認してください。
400 Bad request
  • JSON にエラーがあります。詳細についてはエラーメッセージをご覧ください。 

トラブルシューティング

  • 症状:HTTPのリターンコードが返されない
    ソリューション: AppsFlyerサーバーを許可リストに追加してください

リリースノート


Web SDKリリースノート
日付  エンドポイントバージョン* Notes
2020-05-12 1  初期リリース
2020-05-24 1  
* バージョン番号は、エンドポイントのバージョン番号に紐づいています。 https://webs2s.appsflyer.com/v1/method