PBA向けWebサーバー間イベントAPI (Web-S2S)

概要:PBA向けのWebサーバー間(Web-S2S)イベントAPIを使用すると、Web SDKでレポートされないイベントやコンバージョンをレポートすることができます。

5107_Infographic_Web_S2S_759x270_option1.jpg

PBA向けWebサーバー間イベントAPI

ピープル ベースド アトリビューション向けのWeb-S2S APIは、Web SDK を補完するもので、ウェブサイト上で発生するにもかかわらず Web SDKの範囲外のイベントをレポートすることができます。例えば、ウェブサイトへの訪問者(ウェブユーザー)が、オンラインでの支払いイベントを実行するものの、これはバックエンドシステムで処理される場合です。処理が完了後、バックエンドはS2S APIを使用してイベントをAppsFlyerに報告します。

S2S APIで送信されたイベントは、次のような特徴があります。

  • Web SDKによってレポートされたイベントと同様に記録されます。
  • コンバージョンイベントとして設定されている場合、PBA管理画面に含まれます。
  • PBAローデータ内の event_source の項目は web S2S と入力されます。

APIの利用手順

以下のセクションを使用して、APIコールを作成してください。 

記事に対するフィードバックをお願いします

開発者の皆様へ、

開発者としてAPI ガイドの重要な詳細をスキップしてしまったり、見逃してしまうことはありませんか。次の表では、こうしたミスを防ぐためのヒントをご紹介しています。 また、この記事についてのご意見をぜひお聞かせください。フィードバックを送信するには、このページ下にある、 この記事は役に立ちましたか?をクリックしてください。

よくあるミスを防ぐためのチェックリスト
No. ポイント 備考
1 ユニークユーザーID
  • 利用できるIDのうち最も最適な一意のユーザー識別子を提供してください。このIDの設定はデータ分析に大きな影響を与えます。
  • ベストプラクティスは「customerUserId」を送信することです。これが利用できない場合は、Web SDKによって設定されたWebサイトのcookie IDである「afUserId」を送信してください。
  • 顧客ユーザーID(CUID)を「afUserId」に紐づける際は、常に「setCuID() 」メッセージを両方のIDと共に送信してください。
2 タイムスタンプ
  • イベントが遅れて到着した場合、タイムスタンプは抑制されます。つまり、月曜日のタイムスタンプを持つイベントは、火曜日の午前 0 時 (UTC) より前に到着する必要があります。
  • タイムスタンプはUTCベースです。必要に応じて、パラメータに格納する前にローカル時間からUTC時間に変換してください。
3 収益と通貨 eventRevenueCurrencyeventRevenue は、それらが「eventValue」に含まれている場合でも、入力する必要があります。管理画面でこれらのデータを使用するため、必ず実行してください。

APIの基本

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

  • バンドルID(ブランドバンドルID)
  • Web Dev key

認証情報の取得方法:

  1. AppsFlyerにて、[My Apps] > [ブランドバンドルを表示] を開きます。
    バンドルの一覧が表示されます。
  2. 適切な内容をコピーして記録します:
    • ブランドバンドルID
    • Web dev key 
パス

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

  • バンドルID:管理画面から取得できるアプリのバンドルIDです。 
  • method は次のいずれかです:
    • event: レポートしたいバックエンドのイベントを送信してください。
    • setCuId: afUserId を CUID と紐づける際に送信します。
HTTP メソッド POST
Content Type application/json 
JSON ペイロード制限 

JSON ペイロードサイズ:最大1KB

レート制限

POSTのボリューム制限:60,000 POST /分この上限を増やしたい場合には、CSMまでご連絡ください。

TLS
Web S2S API の基本

setCuId メソッド

メソッド名

setCuid

ユースケース 

CUIDをウェブサイト訪問者に紐づける場合に使用します。例えば、ウェブの afUserId を顧客ユーザーIDと照合する度に使用します。これにより、PBAはさまざまなソースからデータを照合できるようになります。これは、ウェブサイトの setCustomerUserId と同様です。  

メソッドのパス

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

ペイロード

JSONペイロードはこちらにリストされているパラメータで構成されています。全てのパラメータは必須です。

 Curl の setCuid の例

ccurl --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"}

アプリ内イベントメソッド

アプリ内イベントメソッド
メソッド名

イベント

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

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

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

イベントメソッドの詳細

ペイロードパラメータ

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

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

customerUserID

顧客ユーザーID (CUID) はアプリ所有者が設定した一意の識別子です。

  • AppsFlyerにいかなる手段でレポートされているイベントと同一の識別子を使用してください。つまり、同じ識別子が Web SDK、モバイル SDK、および S2S API で使用されています。
  • Web SDKの顧客ユーザーID
  • フォーマット:String
  • 例:"customerUserId" : "663274"
  • ローデータで入力される項目:customer_usesr_id

afUserId

Web SDKによって、ウェブサイトを訪問するすべてのユーザーに割り当てられた一意のユーザーIDです。cookie の値をバックエンドサーバーに渡す必要があります。

  •  Cookie の詳細:
    • 名前: afUserId
    • 値:afUserId をこの値に設定します。
    • ドメイン: website-domain
  • 例:"afUserId" : "unique_cookie_uuid"
  • ローデータで入力される項目:af_web_id
ユーザー識別子パラメータ(少なくとも1つのパラメータを送信)
パラメータ名 必須 説明

webDevKey

はい

管理画面から取得できる Web Dev Key を使用して入力します。

  • 例:"webDevKey" : "ffffffff-ffff-ffff-ffff-ffffffffffff"
eventType はい

AppsFlyerが内部で使用するイベント属性識別子です。常に EVENT と設定されます。

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

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

  • タイムスタンプが送信されない場合は、サーバー時刻を使用して設定されます。
  • 遅れて到着したイベントには、現在のサーバ時刻を使用してタイムスタンプが付きます。これは、イベントが発生した翌日の午前0時(UTC)よりも後にデータが届いた場合を指します。例えば、月曜日に発生したイベントは、UTCタイムゾーンの火曜日深夜までに処理される必要があります
  • 未来のタイムスタンプ(現在のサーバー時刻との比較)を持つイベントはサーバー時刻でタイムスタンプが記録されます。
  • フォーマット:Int
  • 例: "timestamp" : 1584835200123
  • ローデータで入力される項目:event_time
eventValue いいえ
イベントを説明する、イベントパラメータの一覧。このパラメーターを使用して、製品、アイテム価格などの情報をリッチアプリ内イベントで送信してください。
  • 収益に関する注意点!このパラメーターには収益の詳細データを入力してください。さらに、eventRevenue と eventRevenueCurrency を入力する必要があります。
  • フォーマット:JSON
  • 例: 青色で単価が3.99ドルである商品「ABC123」を送信するには、EventValueを次のように設定します
    {{"Purcahse": {{"sku" : "ABC123", "color": "blue", "unit_price":3.99,"currency": "USD"}}}}
  • 制限最大1000文字まで。これを超えないようにしてください。超過したものは切り捨てられます。
  • ローデータで入力される項目:event_value
eventRevenueCurrency いいえ

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

  • デフォルト設定:USD
  • フォーマット:String
  • 例: "eventRevenueCurrency" : "EUR"
  • ローデータで入力される項目:event_revenue_currency
eventRevenue いいえ 

イベントに紐づく収益額(通貨値)。

注!収益が eventValue でレポートされている場合は、eventRevenue でも値を送信し、eventRevenueCurrency に入力します。

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

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

referrer いいえ

HTTPリファラ

  • フォーマット:String
  • 例:"referer" : "https://www.google.com/"
  • ローデータで入力される項目:http_referrer
userAgent いいえ 

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

  • デバイスタイプを判断するのに役立ちますので、できる限りこの値を送信してください。
  • フォーマット:String
  • 例:"userAgent" : "Chrome/80.0.3987"
  • ローデータで入力される項目:user_agent
ip いいえ

ユーザーのIPアドレス

  • 可能であれば、この項目の値を送信します。これは、ユーザーの地理的位置 を決定するのに役立ちます。
  • フォーマット:String
  • 例:"ip": "192.0.2.1"
  • ローデータで入力される項目:ip
イベントパラメータ

Curl の例

ccurl --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_wev_event",
	"eventRevenenuCurrency" : "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_wev_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. 200 OKのリターンコードが受信できていることを確認します。できない場合は、リターンコードとエラーメッセージをもとに修正を行います。
  3. UTCタイムゾーンの午前0時のあと数時間待機し、PBAローデータレポートにイベントが記録されていることを確認します。PBAデータは1日1回処理されるため、このように待つ必要があります。

追加情報

Web Dev Key の取得

 Web Dev Key の取得方法:

  1. AppsFlyerの管理画面内で、[ My Apps ]のタブに移動してください。
  2. [ブランドバンドルを表示]をクリックします。

    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 を使用して作成されました。さまざまなブラウザとオペレーティングシステムにより、手順に多少違いがある可能性があります。

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

  1. ブラウザにてウェブサイトに移動します。
  2. 右クリックして、[検証] を選択します。

    ブラウザ検証の画面が開きます。

    S2S_inspect.jpg

  3. (A) [Application] タブへ移動します。
  4. サイドメニューにて、(B) [Cookie] を展開します。
  5. ウェブサイトを選択します。表示されない場合は、ブラウザを更新します。
  6. (C) [Filter] 項目にて、afUserIdを入力します。
    afUserID の値が表示されます。 

レスポンスステイタスコード

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

トラブルシューティング

  • 症状:HTTPリターンコードが返されない
    解決策:AppsFlyer サーバーを許可リストに追加します。

リリースノート


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