サーバー間 (S2S) イベントAPI for モバイル

概要 :サーバー間(S2S)イベントAPIを使用して、アプリの外部で発生したイベントをAppsFlyerへ送信します。S2SイベントはSDKイベントと同様にメディアソースへ紐付けられ、プラットフォーム全体で使用できます。 

S2S_us-en.png

サーバー間 (S2S) イベントAPI for モバイル

AppsFlyerのプラットフォームは、AppsFlyer SDKおよびAPIによって送信されたイベントをメディアソースに紐づけて記録します。S2S APIを使用して、アプリの外部で発生したイベントを計測可能です。(例:Webサイト上での定期購読登録の更新など)S2Sイベントが記録されると、通常のイベントデータと同様、管理画面、ローデータ、各種レポート画面など、プラットフォーム全体で利用できます。

AppsFlyerはS2Sイベントに以下情報を入力します。

  • S2Sメッセージで送信されたイベントの値
  • インストール時間やメディアソースなどのAppsFlyerのインストール計測の値に

APIの利用手順

以下のセクションに含まれる情報を使用して、APIコールを作成してください。

S2S API 仕様

API endpoint

https://api2.appsflyer.com/inappevent/app_id

  • app_id: AppsFlyerの管理画面上で使用されているアプリID。ダッシュボードに表示されているとおりに、正確に入力してください。
  • iOS apps:  idを冒頭に付与することを忘れないでください。  これが漏れると、有効 200(OK)のリターンコードは表示されますが、イベントは記録されません
  • Windows: app IDをMicrosoft App Storeから取得してください。
  • Example Android: https://api2.appsflyer.com/inappevent/com.appsflyer.myapp
    iOS:https://api2.appsflyer.com/inappevent/id123456789
    Windows:https://api2.appsflyer.com/inappevent/a1b2c3d4e5f6
HTTP method POST
Content Type application/json
認証

--header 'authentication: dev_key'

  • dev_key がヘッダーの認証トークンです。 
  • Dev keyを取得するには、AppsFlyerの管理画面内で アプリ設定 > Dev Key を確認してください。
サーバーのホワイトリスト登録

AWSのIPアドレスをホワイトリストに登録して、サーバーがファイアウォールの背後にある場合にもレスポンスメッセージを取得できるようにしてください。 

JSON ペイロード制限 

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

レート制限

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

コーディング仕様
URLのエンコード

メソッドURLを形成する前に、予約文字(Reserved Characters)をパーセントエンコードしてください。 (https://tools.ietf.org/html/rfc3986#section-2.1

TLS

TLS 1.2以上を使用してください。Ciphersもサポートしています。

S2S API 仕様

ペイロードパラメータ

ペイロードパラメータは次のもので構成されます。

  • 1つ以上の端末識別子(OSによって異なります)
    • ユーザーが広告追跡の制限をONにしている(LAT端末)の場合など、特定の理由により広告IDを送信できないことがあります。 
    • 広告ID / 端末識別子の送信失敗は計測不具合を引き起こす可能性があり、 AppsFlyerがイベントを紐付けることができなくなります。 
      • これは、たとえば、連携済みパートナー側のデータポリシーにより、インストールのローデータが存在しない場合などに発生します。
      • 端末識別子のパラメータは必須ではありません。端末識別子を送信しないことも選択可能ですが、その結果として起こり得る事象についてもご認識ください。 
OS 識別子名 説明

iOS

iconAFios.png

idfa 

利用可能な場合は、端末のIDFAを入力してください。

フォーマット:String

例: "idfa": "9876F1SS-2983-3855-27RR-2R626772VFNB"

Android

iconAFand.png

advertising_id

利用可能な場合は、端末のGAID(Google Advertising ID)を入力してください。

フォーマット:String

例: "advertising_id": "9c9a82fb-d5de-4cd1-90c3-527441c11828"

oaid

フォーマット:String

例: "oaid": "1fe9a970-efbb-29e0-0bdd-f5dbbf751ab5"

amazon_aid

フォーマット:String

imei

フォーマット:String

例: "imei": "AA-BBBBBB-CCCCCC-D"

端末識別子
パラメータ名 必須 説明
appsflyer_id はい

アプリの初回起動時に AppsFlyerによって生成されるユニークなID

  • フォーマット:String
  • 例: "appsflyer_id": "1415211453000-6513894"
customer_user_id いいえ

カスタマーユーザーID:  アプリの所有者が設定した一意のユーザーID。

  • フォーマット:文字列(String)
  • 例: "customer_user_id": "my_customer_number1234" 
IP いいえ

イベント発生時のモバイルデバイスのIPアドレス

  • 送信された場合、IPアドレスは他の地理的情報の入力にも使用されます。
  • 送信されない場合、AppsFlyerはインストール計測時の値を使用して、IPアドレスと地理的情報を入力します。
  • フォーマット:IPV4またはIPV6 addressを含む文字列(String)
  • 例: "ip": "192.0.2.1
af_events_api はい

常に true に設定してください。 

  • フォーマット:String
  • 例: "af_events_api" :"true"
eventName はい

イベント名を指定してください。イベント名がマーケティング担当者からの要件と一致していることを確認してください。

  • フォーマット:String
  • 例: "eventName": "af_purchase"
Event Value はい

値なしでイベントを送信する場合は、次のように送信します: "event_value":""

  • イベントの値は、追加の記号やフォーマットなしで送信する必要があります。 
  • af_revenue のパラメータには小数点のコンマが使用可能です。また、負の値の前には -を付与する必要があります。
  • フォーマット:JSONの文字列
  • 例: "eventValue": "{ \"af_revenue\": \"6\", \"af_content_type\": \"wallets\", \"af_content_id\": \"15854\", \"af_quantity\" :\"1\" }"
app_version_name いいえ

アプリのバージョンまたは識別子。

  • フォーマット:String
  • 例: "app_version_name": "my_app_version"
Event Time いいえ

UTCタイムゾーンでの、イベントの発生時刻。

  • デフォルト設定: eventTime を送信しない場合、eventTimeはHTTPメッセージの到着時刻で記録されます。
  • フォーマット:string形式のyyyy-mm-dd hh:mm:ss.sss
    (タイムゾーンはUTCである必要があります。)
  • 例: "eventTime":"2019-05-15 12:17:01.123" はUTC時間での12:17:01を意味します。 

イベント計測の締切

  •   eventTime  を実装する場合、イベントはイベント発火翌日の02:00(UTC)までにAppsFlyerで受信される必要があります。つまり、イベントが月曜日の17:00 UTCに発生した場合には、火曜日の02:00 UTCまでにAppsFlyerのサーバーに送信される必要があります。 
  • データの締切後に受け取ったイベントには、データの到着時刻がeventTimeとして付与されます。 
  • また、データの到着時刻よりも未来の時刻が付与されたイベントについても、未来の時刻ではなく、データの到着時刻でデータが記録されます。

  • タイムゾーンはUTCです。
  • イベントを eventTime =月曜日 21:00で送信するとします。
データ到着時間 AppsFlyerによって記録される時間 リマーク
火曜日
01:00 
月曜日
21:00 
データ受付の締切前に到着。
水曜日
09:00 
水曜日
09:00 
データ受付の締切後に到着。データの到着時間で記録されます。
eventCurrency いいえ

ISO 4217の3文字コード、もしくはBCN(ビットコイン)の通貨コード

デフォルト設定:USD

例: " eventCurrency ": " ZAR "

イベントパラメータ

Curl サンプル

curl --location --request POST 'https://api2.appsflyer.com/inappevent/<app_id_placeholder>' \
--header 'authentication: <dev_key_placeholder>
' \
--header 'Content-Type: application/json' \
--data-raw '{{
  "appsflyer_id": "9999999999999-9999999999999999999",
	"advertising_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
	"customer_user_id" : "example_customer_id_123",
	"ip": "199.0.2.1",
	"af_events_api" :"true",
	"app_version_name" : "example_version_name",
	"eventTime" : "2020-02-25 12:00.000",
	"eventName": "af_purchase",
	"eventCurrency": "ZAR",
	"eventValue": 
	"{
		\"af_revenue\": \"1006\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }"
}}
'

Response codes

応答コード  Message 処理方法
200 OK

メッセージを受信すると、最低限のデータ検証が実行されます。そのため、イベントがAppsFlyerに完全に記録されない場合でも、OKのレスポンスを受け取ることがあります。イベントをデバッグするには:

  • 1. この記事内にある、Curl サンプルを使用してください。
    • アプリIDとDev Keyを変更してください。
    • appsflyer_idとeventTimeのパラメーターを変更してください。現在の時刻と、最近非オーガニックインストールで記録されたappsflyer_idを使用してください。
  • 2. コールを送信してください。
    • 200 OKのメッセージが返されます。
    • 収益を含め、イベントが正しく記録されているかどうかを確認してください。
    • 必要に応じて追加の変更を行い、再度テストしてください。
400 Failed to Authenticate 認証キーが正しいことを確認してください。
400  appsflyer_id is a mandatory field
  •  JSONで正しいAppsFlyer IDを渡すようにしてください。
  • JSONが正しく文字列化(stringified())され、正しい形式で記述されていることを確認してください。
401 Unauthorized authentication headerで提供されたキーがこのアプリの<dev_key>ではない場合。
400 Bad request

リクエストに関して少なくとも1つの条件が検証できず失敗した場合

400  Payload is missing or failed to parse
  • JSONが文字列(String)化され、正しい形式で記述されていることを確認してください。
  • JSONペイロードに複数のイベントが含まれている場合にも、このエラーが返されます。リクエストごとに1つのイベントを送信してください。
500  Internal Server Error JSONが文字列(String)化され、正しい形式で記述されていることを確認してください。
 

テスト

特記事項:

  • テストには、非オーガニックインストールのAppsFlyer IDを使用してください。そうすればイベント計測はリアルタイムで行われますがオーガニックユーザーのイベント計測の場合、最長数時間の遅延を伴います。
  • 一部のイベントフィールドは、ユーザーのインストールアトリビューションイベントを使用して入力されます。たとえば、時間とメディアソースをインストールします。 

テスト端末を非オーガニックインストールとして紐付けるには:

  1. S2Sのメッセージをテストするために、カスタム計測リンク を準備して、メディアソース名には s2s_testと名付けてください。例: &pid=s2s_test 
  2. テスト端末をホワイトリストに登録してください。
  3. テスト端末からアプリをアンインストールしてください。
  4. テスト端末にリンクを送信してください。
  5. リンクをクリックしてください。
  6. アプリをインストールして起動してください。
  7. 管理画面のオーバービュー上で、インストールが計測されているか確認してください。
  8. S2Sメッセージ送信で使用するAppsFlyer IDを取得してください。

S2Sメッセージをテスト送信するには

  1. 先程の工程で取得したAppsFlyer IDを使用して、S2Sメッセージを準備してください。コード例については、以下を参照してください。
  2. S2Sメッセージを送信してください。
  3. 次のいずれかを実行して、S2SメッセージがどのようにAppsFlyerに記録されたかを確認してください。
  4. 以下を確認してください。
    • S2Sメッセージで送信された値が、レポートに正しく入力されているか特に、イベントの日付、イベントの通貨、イベントの収益、イベントの値に注意してください。
    • アトリビューションソースとインストールタイムはAppsFlyerによって入力されます。
    • SDKバージョンなどのSDK自体によって提供される値は入力されません。

S2Sメッセージを送信する際のコードサンプル

JavaPythonNode JSC#PHPGo
/* using the okhttp package 
install from maven https://mvnrepository.com/artifact/com.squareup.okhttp3/okhttp */
import okhttp3.*;
import java.io.IOException;

public class SendRequest {
  public static void main(String[] args) {

    OkHttpClient client = new OkHttpClient();
    MediaType mediaType = MediaType.parse("application/json");

    RequestBody body = RequestBody.create(mediaType, "" +
        "{\r\n\t\"appsflyer_id\": \"<APPS_FLYER_ID>\"," +
        "\r\n\t\"customer_user_id\": \"123456\",\r\n\t\"eventName\": \"af_purchase\",\r\n\t\"" +
        "eventValue\": \"{\\\"af_revenue\\\":\\\"6\\\" ,\\\"af_content_id\\\":\\\"15854\\\"}\",\r\n\t\"" +
        "eventCurrency\": \"USD\",\r\n\t\"" +
        "eventTime\": \"2018-08-10 4:17:00.000\",\r\n\t\"" +
        "af_events_api\" :\"true\"\r\n}");

    Request request = new Request.Builder()
        .url("https://api2.appsflyer.com/inappevent/<APP_ID>")
        .post(body)
        .addHeader("Content-Type", "application/json")
        .addHeader("authentication", "<YOUR_DEV_KEY>")
        .build();

    try {
      Response response = client.newCall(request).execute();
      System.out.println(response.code());
      System.out.println(response.body().string());
    } catch (IOException e) {
      e.printStackTrace();
    }
  }
}

パラメータについて

オーガニックと非オーガニックの違い

AppsFlyerがS2Sのアプリ内イベントを処理するとき、アトリビューションフィールドはAppsFlyer IDを使用して入力され、アプリ内イベントよりも前に発生していた関連するインストールイベントを識別します。

つまり、AppsFlyerが非オーガニックサーバー間アプリ内イベントに関連付けるデータは、オーガニックサーバー間アプリ内イベントに紐付けられないということです。

 例

たとえば、非オーガニックとオーガニックサーバー間アプリ内イベントのローデータレポートを比較する場合、非オーガニックイベントにはオーガニックアプリ内イベントにはないデータが含まれます。

非オーガニックのアプリ内イベントには、メディアソース、キャンペーン、アトリビューションタッチタイプ、アトリビューションタッチタイムに関するデータが含まれます。

一方、オーガニックのアプリ内イベントは、オーガニックのインストールに従います。オーガニックインストールには、キャンペーン、メディアソース、またはアトリビューションのタッチタイプと時間に関連するデータはありません。

AppsFlyer IDとカスタマーユーザーID(CUID)のマッピング

パラメーターに入力する特定の値を取得するには、バックエンドロジックが必要です。以下では、AppsFlyer IDの取得方法について説明しています。

  • AppsFlyer IDは必須であり、イベントの紐付けに使用されます。
  • このIDはユーザーが最初にアプリをインストールしたときに発行されます。
  • CUIDをAppsFlyer IDにマップできるようにするには、アプリでCUIDを設定する必要があります。

どのユーザーがどのイベントを実行したかを簡単に把握できるようにするには、以下のフローを実装してください。

  • ユーザーがアプリをインストールしたときにカスタマーユーザーID を付与(設定)してください。
  • AppsFlyerのローデータレポートにCUIDとAppsFlyer IDが記録されるので、AppsFlyerのPush APIなどのデータ提供機能を利用して取得してください。 
  • ローデータレポートを使って、CUIDとAppsFlyer IDを照合させてください。 
  • AppsFlyer IDは、実装したSDKからも取得することが可能です。(Android/iOS)
  • お客様自身のデータベース上でも、AppsFlyer IDをカスタマーユーザーIDにマッピングしてください。(将来的な使用においても重要です)。

AppsFlyer IDをお客様側のカスタマーユーザーIDにマッピングすると、どのユーザーがどのイベントを実行したかを簡単に知ることができます。その後、他の値(イベント値、イベント通貨、イベント時間など)を取得してサーバー間アプリ内イベントを送信できます。 

 Request bodyの例

{
  "appsflyer_id": "1415211453000-6513894",
	"advertising_id": "38412345-8cf0-aa78-b23e-10b96e40000d",
	"eventName": "af_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	"ip": "1.2.3.4",
	"eventTime": "2014-05-15 12:17:00.000",
	"af_events_api" :"true"
}


この例では、AppsFlyerはcontent typeなどの追加のプロパティと一緒に、収益を含む購入イベントであるS2Sのアプリ内イベントを受信します。

AppsFlyer IDの取得

appsflyer_id はサーバー間イベントメッセージの必須パラメータです。AppsFlyerでは、このパラメーターを使用して、オリジナルの端末とメディアソースにイベントを紐付けます。 次のいずれかの方法でIDを取得できます。

 ヒント

S2Sのメッセージをテストする時にローデータ、Push API、またはPull APIを使用している場合、メディアソースが"s2s_test"のレコードを確認してください。これはテスト対象のデバイスを指しており、そのAppsFlyerデバイスIDが必要なIDとなります。

マイナスの収益を送る

購入がキャンセルされた場合などには、マイナスの収益の値を持つイベントも送信可能です。 af_revenue のパラメータには、マイナスの値も使用することができます。 

af_quantity のパラメータも使用している場合には、利用されているシステム側のロジックによっては、マイナスの値を設定したいケースもあるかと思います。AppsFlyerでは af_quantity を収益の集計などには使用しませんのでご安心ください。

マイナスの収益を送る例

{{
	"eventName": "cancel_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"-6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	
}}

イベント値なしでのイベント送信

イベント値なしでイベントを送信する場合は、単に空の文字列をイベント値に渡します: "event_value":""

AppsFlyerは、広告主の設定に応じて、高度なターゲティングや最適化、オーディエンスの作成を目的に、このようなリッチアプリ内イベントをメディアソースに送信できます。

トラブルシューティング

イベントが管理画面に表示されない

  • エンドポイント:使用されているエンドポイントが正しいことを確認してください。
  • ペイロードに必須のパラメータが含まれていることを確認してください。詳細はこちらです。
  • イベント計測に使用しているAppsFlyerIDが、(このガイドで提示しているサンプルのIDでなく)そのアプリがインストールされている実際のappsflyer_idであることを確認してください。詳細はこちらです。
  • S2Sイベントは、イベントの一括送信をサポートしていません。各S2Sイベントは個別に送信する必要があります。 
  • オーバービューの画面で指定する日付は、イベントの発生日ではなく、アプリのインストール日(LTV)になります。
    • 正しい日付範囲を選択していることを確認してください。
    • 管理画面でイベントを確認するには、管理画面で選択した日付が、イベントの発生日ではなく、端末(appsflyer_id)のインストール日と一致していることを確認してください。

  • イベントローデータレポート:日付範囲は、インストール日ではなくイベントの発火日が関係します。 

イベントに収益が含まれない

S2Sイベントを送信しても、その収益が記録されない場合には、送信したJSONが文字列化されているかどうかを確認してください。最も重要な部分は、JSONのイベント値パラメーターです。次の例に示すように、文字列化する必要があります。

"{\"af_revenue\":\"6\" ,\"af_content_type\":\"wallets\"}"

文字列(String)化されていない場合、イベント値は正しく処理されず、収益は記録されません。

収益の値は書式化しないでください。小数点のコンマは使用可能ですが、必須ではありません。通貨記号や通貨コード、 , のような値の区切り文字も含めないでください。収益の値の冒頭には -(マイナス)を付与することも可能です。

  • 有効な値の例: 123, -123.45123.456 
  • 無効な値の例: 1,234.561,234

S2Sイベントのすべてのフィールドが入力されない

ローデータのフィールドはS2Sのコールで送信された値と、インストールイベントのデータを使用して入力されます。AppsFlyerのSDKを使って計測するアプリ内イベントと似たような挙動になりますが、まったく同一ではなくいくつかの違いがあります。具体的には、次のフィールドはS2Sイベントでは入力されません。

  • WIFI
  • Operator
  • Language
  • Device Type
  • Device Category
  • App Version:  app_version_nameを使用して設定します
  • App Name
この記事は役に立ちましたか?