adjust-icon

サーバー間(S2S)開発者ガイド

Adjustは、モバイルアプリ、コンソールアプリ、コネクテッドTV(CTV)アプリ向けのサーバー間(S2S)インターフェイスを提供しています。サーバー間でAdjustを実装する場合は、Adjust SDKの機能を複製できるようにアプリを変更する必要があります。このガイドでは、以下の手順について説明します。

  • 必要なアップデートをアプリに実装する方法
  • Adjustへサーバー間リクエストを送信する方法

事前準備

事前準備として、以下を実行してください。

サーバー間セッション計測 を有効化する

モバイルアプリ向けにサーバー間インターフェイスを使用している場合、Adjustはアプリのサーバー間セッション計測を有効にする必要があります。ご希望の場合は、Adjustの担当者またはsupport@adjust.comにお問い合わせください。

プラットフォームを選択すると、コネクテッドTV計測PCおよびコンソール計測のサーバー間セッション計測が自動的に有効になります。

S2Sセキュリティを設定する

サーバー間(S2S)セキュリティを実装してサーバー間のアクティビティを保護し、スプーフィングされたリクエストを防止します。Adjustダッシュボードでトークンを生成し、受信する各リクエストにそのトークンを含めます。

ローカルでイベントキューを保持する

ユーザーは、アプリのインストールやセッションなどの重要なイベントをオフラインのデバイスで実行することがあります。アトリビューションの正確性を維持するには、デバイスがオンラインになり、Adjustのサーバーに正常に送信できるようになるまで、これらのイベントを取得してローカルに格納しておく必要があります。

永続的なローカルイベントキューを可能にするには、以下の手順を実行します。

  1. アクティビティが発生した際に格納するためのキューを作成します。
  2. 各アクティビティには、デバイスでイベントが発生した時間を秒単位で示すcreated_at_unixタイムスタンプが付与されます。例えば、いつイベントが発生したのかを「1484085154」のように表します。
  3. このキューをSQLiteデータベースやファイルなどのローカルストレージに保存して、アプリを再起動しても保持できるようにします。
  4. キューが空ではなく、デバイスがオンラインのときに、Adjustのサーバーにアクティビティの送信を試みます。
  5. アクティビティの送信が成功した場合のみ、キューからアクティビティを削除します。

このアプローチは、以下のような場合にデータ損失を最小に抑制します。

  • 短時間のネットワーク中断(例:5GからWiFiへの切り替え時など)
  • 長時間オンラインに復帰できない
  • 送信前にアプリがクラッシュまたは強制終了

ローカルキューがない場合、インストールデータの10%~20%が失われる危険があり、アトリビューションの正確性に大きな影響が及ぶことがあります。このキューシステムを実装することで、Adjustはユーザーアクティビティを完全かつ正確に受信し、オフラインで発生したイベントであっても正確にアトリビューションできるようになります。

iOSフレームワークを追加する

特定のiOS機能をサポートするには、フレームワークをプロジェクトにリンクする必要があります。フレームワークをプロジェクトに追加するには、次の手順を実行します。

  1. Xcodeでプロジェクトを開きます。
  2. プロジェクトナビゲータで、ターゲットを選択します。
  3. General タブに移動します。
  4. Frameworks, Libraries, Embedded Content のセクションまでスクロールします。
  5. + 」ボタンを選択します。
  6. 以下のリストを参考に、アプリに必要なフレームワークを検索して追加します。
Framework説明
AdSupport.frameworkIDFAの収集と、AppTrackingTransparency(ATT)以前のiOSバージョンで「Limit Ad Tracking(追跡型広告を制限)」ステータスを収集する場合に必要です。
AppTrackingTransparency.frameworkAppTrackingTransparencyのポップアップを表示し、iOS 14.5以降を実行するデバイスでIDFAを収集する場合に必要です。
AdServices.frameworkAdjustがApple Search Adsキャンペーンをアトリビュートするのに必要です。
StoreKit.frameworkSKAdNetworkキャンペーンの実行に必要です。

必須パラメーター

各サーバー間リクエストには、以下のパラメーターが必要です。

パラメーター説明
s2sリクエストが「サーバー間リクエスト」であることを示します。「1」にハードコーディングする必要があります。
app_tokenAdjustのアプリトークン。
os_nameモバイルOS名。以下のオプションを参照してください。
  • android
  • android-tv
  • apple-tv
  • bada
  • blackberry
  • fire-tv
  • ios
  • linux
  • macos
  • nintendo
  • playstation
  • roku-os
  • server
  • smart-cast
  • steamos
  • symbian
  • tizen
  • unknown
  • webos
  • windows
  • windows-phone
  • xbox

これらのパラメーターをサーバー上に作成します。これらはデバイスの種類に関係なく、Adjustへ送信される全てのサーバー間リクエストに使用されます。デバイス固有のパラメーターは、必要に応じて追加されます。このガイドではクライアント側の全てのパラメーターの処理方法について説明しますが、実際は、その多くがサーバー側で発生します。

デバイスIDとトラッキングのステータス

全てのサーバー間リクエストには、 少なくとも1つ のデバイスIDを含める必要があります。モバイルのオペレーティングシステムがプライバシー対策を実装していることから、広告IDを常に利用できるとは限りません。そのため、可能な場合は広告IDを含めますが、常にバックアップのIDを含める必要があります。

PCおよびコンソール/コネクテッドTV(CTV)のデバイスID

PC、コンソールおよびコネクテッドTVを計測する場合、それぞれの呼び出しに一意のexternal_device_idパラメーターを含めることで、デバイスIDとして使用できます。デバイスを識別する一意の値には、任意の文字列を指定できます。

iOSデバイスID

IDFAと計測ステータス

広告主ID(IDFA)は、ユーザーが共有することに同意したiOSデバイスでのみ利用可能です。IDFAを収集するアプリもあれば、そうでないアプリもありますが、アプリがIDFAを収集するかどうかに関係なく、Adjustは各リクエストのトラッキングステータスを要求します。以下から、実装環境に対応するコードを選んで使用してください。

IDFAを収集するアプリ

  1. XcodeでATTの説明を追加します。

    1. プロジェクトのInfo.plistファイルを開きます。
    2. エディターで、 Information Property List を右クリックし、 Add Row を選択すると、ルートにキーを追加できます。
    3. NSUserTrackingUsageDescriptionにキーを設定します。
    4. トラッキングの許可を求める理由を文字列で設定します。例えば、「このIDは、パーソナライズされた広告を配信するために使用されます」のように入力します。このテキストについては、Appleのガイドラインを確認してください。
  2. ATTポップアップの実装とIDFAの取得

ATTには以下の要件があります。

  • ATTのサポートはiOS 14で開始されましたが、IDFAの取得にユーザーの同意が必要となるのはiOS 14.5以降のみです。このためAdjustは、iOS 14.5以降のバージョンを使用するユーザーに対してATTポップアップを表示することを推奨しています。
  • ATTポップアップを表示するには、アプリをアクティブな状態にする必要があります。他のシステムポップアップの直後だと表示に失敗する可能性があるため、アプリの状態が再びアクティブになるまで待機しなければなりません。
  • ポップアップを最も早く表示できるのは、 applicationDidBecomeActive(App Delegate)またはsceneDidBecomeActive(Scene Delegate)です。didFinishLaunchingWithOptions(App Delegate)でATTポップアップを表示することはできません。

以下のコード例は、これらの要件を全て満たしています。

正確なアトリビューションを行うため、最初のセッションリクエストと、その後の全てのリクエストにIDFAを含めてください。

IDFAを収集しないアプリ

以下のコードを使用して、トラッキングステータスを取得します。

idfv

ベンダーID(DFV)は、最新のiOSデバイスの全てで利用可能なバックアップIDです。

メインの重複排除トークン

アンインストールと再インストールのアプリアクティビティを一貫して計測するには、バージョン4のUUID(メインの重複排除トークン)をランダムに生成し、iOSキーチェーンに保存します。メインの重複排除トークンは、全てのデバイスに対して生成する必要があるバックアップIDです。

Google PlayデバイスID(Android)

Google広告ID

Google Play開発者サービスの広告ID(GPS ADID)は、ユーザーが広告IDの削除を選択していない場合、Google Play開発サービスを搭載したAndroidデバイスで利用可能です。

  1. アプリのbuild.gradleファイルに、dependencyとしてplay-services-ads-identifierを追加します。
  1. 以下のパーミッションをAndroidManifest.xmlファイルに追加します。

    AndroidManifest.xml
    <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
  2. アプリでR8またはProGuardを使用している場合は、proguard-rules.proファイルに以下のルールを追加して、コード最適化中にGoogle広告IDを取得するためのクラスとメソッドを保持します。ファイルが存在しない場合は、アプリモジュールのディレクトリ内でファイルを作成してください。

    proguard-rules.pro
    -keep class com.google.android.gms.common.ConnectionResult {
    int SUCCESS;
    }
    -keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
    com.google.android.gms.ads.identifier.
    AdvertisingIdClient$Info getAdvertisingIdInfo(
    android.content.Context);
    }
    -keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
    java.lang.String getId();
    boolean isLimitAdTrackingEnabled();
    }
  3. Google広告IDとトラッキングステータスを収集するためのコードを実装します。

App Set ID

App Set IDは、Google Play開発者サービスがインストールされており、APIレベル30(Android 11)以降を実行する全てのAndroidデバイスで利用可能なバックアップIDです。

  1. アプリのbuild.gradleファイルに、必要なdependencyを追加します。
  1. App Set IDを収集するためのコードを実装します。

追加パラメーター

これらのパラメーターは必須ではありませんが、いずれかを使用する場合は、全てのリクエストに含める必要があります。

Unixタイムスタンプ

各サーバー間リクエストにUnixのタイムスタンプを含めると、デバイスでアクティビティが発生した時刻が提供されるため、アトリビューションの正確性が向上します。

確率的モデリングのデータポイント

確率的モデリングをアトリビューションメソッドとして使用するには、全てのサーバー間リクエストに以下のパラメーターを含める必要があります。

パラメーター説明
device_nameデバイス名。
device_typeデバイスのタイプまたはモデル。
os_versionデバイス上で動作するオペレーティングシステムのバージョン。
ip_addressデバイスのIPアドレス。

特にiOSの場合により包括的なアトリビューションが可能になるため、Adjustはこれらのパラメーターを追加することを強くお勧めしています。

環境

environment パラメーターを渡すことで、リクエストが送信される環境を指定できます。テストを可能にするために、Adjustでは異なる環境からのリクエストを分離して管理します。利用可能な値は以下のとおりです。

  • sandbox: テスト用のリクエストを本番用データと分けるため、テスト時に使用します。
  • production: アプリをリリースする際に使用する本番用環境です。

このパラメーターを指定しない場合、デフォルト値はproductionとなります。

グローバルコールバックパラメーター

ローデータのエクスポートを使用する場合、全てのサーバー間リクエストに「グローバルコールバック」を含めることで、ローデータにカスタムパラメーターを追加できます。これは通常、エクスポートされたローデータに内部ユーザーIDを含めるために使用します。

グローバルコールバックパラメーターは、文字列のキーと値のペアを含むJSONオブジェクトとして表されます。

グローバルパートナーパラメーター

特定のパートナーと連携する際、全てのサーバー間リクエストに「グローバルパートナーパラメーター」を含める場合があります。Adjustのサーバーは、パートナーへの全てのコールバックで、これらのパラメーターを渡します。これは通常、受信するコールバックに独自のユーザーIDを要求するアナリティクスパートナー向けに使用されます。

グローバルパートナーは、文字列のキーと値のペアを含むJSONオブジェクトとして表されます。

リクエスト

セッション

セッションは、Adjust実装の基盤として必要となる唯一のアクティビティです。セッションとは一般的に、アプリが開かれることを指します。Adjustのサーバーは、正常なセッションリクエストを次のようにログに記録します。

  • デバイスの最初のセッションを「インストール」アクティビティとして記録します。
  • 以降のセッションを「セッション」アクティビティとして記録します。
  • リアトリビューションの基準が満たされている場合は、「リアトリビューション」または「リアトリビューション再インストール」のアクティビティを記録します。

送信するサーバー間セッションリクエストにcreated_at_unixパラメーターが含まれる場合、Adjustのサーバーはこのパラメーター値が、ログに記録された最後のセッションのcreated_at_unix時間から20分以上経過していることを確認します。

リクエスト - cURL
curl -X POST "https://app.adjust.com/session" \ -H "Authorization: Bearer ADD_YOUR_AUTH_TOKEN_HERE" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "s2s=1\
&os_name=ios\
&app_token=i9dukg8o5slc\
&idfa=29DDE430-CE81-4F00-A50C-689595AAD142\
&att_status=3\
&idfv=59E27F41-A86B-4560-B585-63161F871C4B\
&primary_dedupe_token=3b35fcfb-6115-4cff-830f-e32a248c487d\
&created_at_unix=1484085154\
&device_name=iPhone16%2C2\
&device_type=iPhone\
&os_version=17.5.1\
&ip_address=192.0.0.1\
&environment=sandbox\
&callback_params=%7B%22user_id%22%3A%20%222696775149%22%2C%20%22user_category%22%3A%20%22high%20value%22%7D\
&partner_params=%7B%22analytics_user_id%22%3A%20%223913132433%22%2C%20%22analytics_session_id%22%3A%20%22nzFC9LKSqM%22%7D"\
-w "\n\nHTTP Status Code: %{http_code}\n"\
-s

これは、Adjustでデバイスの最初のセッションを正常にログに記録するためのレスポンスフォーマットです。Adjustのテストコンソールを使用すれば、実際のデバイスを利用せずに、必要に応じて何度でもテストできます。

レスポンス
{
"app_token": "4w565xzmb54d",
"adid": "df6c5653080670612cd2f9766ddc0814",
"timestamp": "2024-07-09T01:31:14.373Z+0000",
"message": "Install tracked",
"ask_in": 2000
}
HTTP Status Code: 200

これは、Adjustでデバイスの以降のセッションを正常にログに記録するためのレスポンスフォーマットです。

レスポンス
{
"app_token": "4w565xzmb54d",
"adid": "df6c5653080670612cd2f9766ddc0814",
"timestamp": "2024-07-09T02:31:14.373Z+0000",
"message": "Session tracked",
"ask_in": 5000
}
HTTP Status Code: 200

インストール後のイベント

デバイスのセッションリクエストを少なくとも1つ正常に送信すると、インストール後のイベントを送信できるようになります。これらは通常、マーケティング目標を表すイベントであり、ネットワークはこれをキャンペーンの最適化に使用できます。

コールバックパラメーター

ローデータエクスポートを使用する場合、特定のイベントリクエストにカスタムの「コールバックパラメーター」を含めることで、イベントレベルのカスタムデータを追加できます。たとえば、購入イベントのローデータに内部のトランザクションIDを含めることが可能です。

コールバックパラメーターは、文字列のキーと値のペアを含むJSONオブジェクトとして表されます。

パートナーパラメーター

特定のパートナーと連携する場合は、イベントリクエストにカスタムの「パートナーパラメーター」を含める必要があります。その後、Adjustのサーバーは、パートナーに送信する関連イベントのコールバックにこれらのパラメーターを追加するようになります。これは、view_itemadd_to_cart、購入などのイベントの動的なリマーケティングキャンペーンを可能にする、最も一般的な方法です。

パートナーパラメーターは、文字列のキーと値のペアを含むJSONオブジェクトとして表されます。

イベントリクエストを送信します。

リクエスト - cURL
curl -X POST "https://app.adjust.com/event" \
-H "Authorization:Bearer ADD_YOUR_AUTH_TOKEN_HERE" \
-H "Content-Type:application/x-www-form-urlencoded" \
-d "s2s=1\
&os_name=ios\
&app_token=4w565xzmb54d\
&idfa=29DDE430-CE81-4F00-A50C-689595AAD142\
&att_status=3\
&idfv=59E27F41-A86B-4560-B585-63161F871C4B\
&primary_dedupe_token=3b35fcfb-6115-4cff-830f-e32a248c487d\
&created_at_unix=1484085154\
&device_name=iPhone16%2C2\
&device_type=iPhone\
&os_version=17.5.1\
&ip_address=192.0.0.1\
&environment=sandbox\
&callback_params=%7B%22user_id%22%3A%20%222696775149%22%2C%20%22user_category%22%3A%20%22high%20value%22%2C%20%22txn_id%22%3A%20%228837853376%22%7D\
&partner_params=%7B%22analytics_user_id%22%3A%20%223913132433%22%2C%20%22analytics_session_id%22%3A%20%22nzFC9LKSqM%22%2C%20%22item_id%22%3A%20%22%5B%5C%2276524%5C%22%2C%5C%2262599%5C%22%5D%22%7D"\
&event_token=2y7e81\
&revenue=19.99\
&currency=USD\
-w "\n\nHTTP Status Code: %{http_code}\n"\
-s
レスポンス
{
"status": "OK"
}
HTTP Status Code: 200