Server-to-Server - 基礎

フォローする
Avatar
Jared Ornstead
Updated

Server-to-Server - 基礎

SDK 統合の代替手段として、Singular の REST API を実装して完全なサーバーサイドトラッキングを行い、データの収集、送信、アトリビューションのワークフローを完全に制御できます。

統合方法の選択: SDK と S2S のどちらを使うか クライアント SDK を組み込めるのであれば、まず SDK 統合ドキュメント から始めてください。サーバーサイドでのイベント送信が必要な場合、SDK が用意されていないプラットフォームを使用している場合、またはデータ収集を完全に制御したい場合は、Server-to-Server を利用してください。このドキュメント群は S2S の経路を扱っており、Mobile、Web、PC/Console の各 S2S ガイドの共通リファレンスとなります。

概要

Server-to-Server のユースケース

Server-to-Server（S2S）統合は、Singular SDK をクライアントアプリケーションに組み込むことなく、バックエンドインフラストラクチャ上で完全なアトリビューションおよび分析ソリューションを構築するための REST API エンドポイントを提供します。

統合のアプローチ:

  • Pure S2S: セッションとイベントの両方のトラッキングを処理する 100% サーバーサイドの実装
  • Hybrid: Singular SDK がセッションを管理し、サーバーサイドがイベントトラッキングを処理する方式

Hybrid 統合パターン

Hybrid 統合は、セッション管理に Singular SDK を、バックエンドのイベントトラッキングにサーバーサイドの EVENT API を組み合わせ、実装の容易さとサーバーサイドの柔軟性のバランスを取ります。

Hybrid の利点:

  • SDK が複雑なセッションロジック、ディープリンク、デバイスデータの収集を自動的に処理します
  • サーバーはバックエンドシステムで処理されたトランザクションのイベントを送信します
  • クライアントサイドの実装の複雑さを軽減します
  • SESSION エンドポイントは不要です。SDK がセッションのライフサイクルを管理します

Hybrid S2S のデータフロー

デバイスデータの取得方法:

  1. クライアント管理フロー: 必要なデータポイントをクライアントで取得し、内部 API 経由でサーバーに転送して Singular の EVENT エンドポイントで使用します
  2. Internal BI ポストバック: Singular の Internal BI ポストバックを設定し、インストール、再エンゲージメント、またはイベントの後にデバイス識別子を含むリアルタイムの JSON ペイロードを受信します（ 設定ガイド ）

デバイスグラフのメンテナンス: いずれの方法でも、デバイスグラフを維持するためのサーバーサイドのロジックが必要です。SDK がデバイス識別子の変更を検知した場合は、正確なトラッキングを確保するために、それに応じてサーバーを更新してください。

実装リソース:

主要な統合原則

原則 説明
柔軟性 データの収集と送信タイミングを完全に制御できます
機能の同等性 適切なデータが提供されれば、SDK のすべての機能をサポートします
統合の経路 クライアント → 自社サーバー → Singular API
リアルタイム処理 一度に 1 リクエストずつ処理します。バッチ処理はサポートされません
順次フロー イベントは時系列順に処理する必要があります
重複排除なし Singular は重複排除を行いません。サーバーサイドで重複排除を実装してください
データの永続性 デバイスレベルのデータは取り込み後に削除できません。送信前に検証してください

統合要件

Pure S2S 統合では、セッションとイベントのトラッキングのために包括的なデータパイプラインの実装が必要です。

  1. データ収集: クライアントアプリケーションから必要なデータポイントを収集します
  2. デバイスグラフ: データをサーバーに転送し、デバイス識別子のストレージを維持します
  3. セッションリクエスト: SESSION API 経由でセッション通知を送信します
  4. レスポンス処理: Singular のレスポンスを処理してクライアントアプリに中継します
  5. イベントリクエスト: EVENT API 経由でイベントを転送します

関連する S2S ガイド

この記事は S2S ドキュメント群の共通リファレンスです。ご利用のプラットフォームに合ったガイドと、パラメータの詳細についてはエンドポイントリファレンスをご利用ください。

プラットフォームガイド

エンドポイントリファレンス

機能ガイド

REST API エンドポイント

Singular は、Server-to-Server のセッションおよびイベントトラッキング用に 2 つの主要な REST API エンドポイントを提供しています。

Session エンドポイント

セッショントラッキング API

SESSION エンドポイントは、アプリの起動イベントを Singular に通知し、アトリビューションおよびリテンショントラッキングのためにユーザーセッションを初期化します。 

GET https://s2s.singular.net/api/v1/launch

完全なリファレンス: SESSION エンドポイント API リファレンス

Event エンドポイント

イベントトラッキング API

EVENT エンドポイントは、アトリビューション分析とキャンペーン最適化のために、アプリ内イベントと収益をトラッキングします。 

GET https://s2s.singular.net/api/v1/evt

完全なリファレンス: EVENT エンドポイント API リファレンス

共通パラメータ

これらのパラメータは、Singular の S2S REST API の SESSION および EVENT エンドポイントで共有されます。このセクションはそれらの正式な定義を保持しており、他の S2S 記事は再定義するのではなくここへリンクします。

認証

パラメータ 詳細
a

string

API 認証用の Singular SDK Key。

取得場所: Singular UI → メインメニュー → Developer Tools 。

重要: Reporting API Key は使用しないでください。リクエストが拒否されます。

例: sdkKey_afdadsf7asf56

デバイス識別子

デバイス識別子はプラットフォームや利用可否によって異なります。ご利用のプラットフォームで該当するすべての識別子を含めてください。利用できない識別子は省略し、NULL や空文字列は絶対に渡さないでください。

パラメータ 詳細
idfa

プラットフォーム: iOS

Identifier for Advertisers (IDFA) は広告トラッキングとキャンペーンアトリビューションを可能にします。

ATT の要件: iOS 14.5 以降では、App Tracking Transparency フレームワークによるユーザーのオプトインが必要です。

  • IDFA が利用できない場合（ユーザーが ATT プロンプトを拒否した場合）はパラメータを省略してください。
  • NULL や空文字列は絶対に渡さないでください。
  • IDFA を取得する

例: DFC5A647-9043-4699-B2A5-76F03A97064B

idfv

プラットフォーム: iOS

Identifier for Vendors (IDFV) は、同一ベンダーのすべてのアプリで一貫して維持されます。

常に必須: ATT のステータスや IDFA の利用可否にかかわらず、必ず含める必要があります。

例: 21DB6612-09B3-4ECC-84AC-B353B0AF1334

aifa

プラットフォーム: Android
(Google Play)

Google Advertising ID (GAID) は、Android でユーザーがリセット可能な広告トラッキングを可能にします。

  • Google Play デバイスでは必須です。
  • Google Play 以外のデバイスでは省略してください。
  • 利用できない場合は省略してください。NULL や空文字列は絶対に渡さないでください。
  • AIFA を取得する

例: 8ecd7512-2864-440c-93f3-a3cabe62525b

asid

プラットフォーム: Android
(Google Play)

Android App Set ID は、同一開発者のアプリ間でプライバシーに配慮したトラッキングを提供します。

常に必須: GAID の利用可否にかかわらず、Google Play デバイスでは必ず含める必要があります。

例: edee92a2-7b2f-45f4-a509-840f170fc6d9

amid

プラットフォーム: Android
(Amazon)

Amazon Advertising ID は、Google Play サービスを持たない Amazon デバイス向けです。

  • Amazon Fire デバイスでは必須です。
  • 利用できない場合は省略してください。
  • AMID を取得する

例: df07c7dc-cea7-4a89-b328-810ff5acb15d

oaid

プラットフォーム: Android
(中国系 OEM)

Open Advertising Identifier (OAID) は、Google Play サービスを持たない中国製デバイス（Huawei、Xiaomi、OPPO など）向けです。

  • Google Play を持たない中国系 OEM デバイスでは必須です。
  • 利用できない場合は省略してください。
  • OAID を取得する

例: 01234567-89abc-defe-dcba-987654321012

andi

プラットフォーム: Android
(Google Play 以外)

Android ID はデバイスが生成する 64 ビットの識別子です。

使用制限: Google Play デバイスでは禁止されています。代わりに AIFA と ASID を使用してください。他に利用可能な識別子がなく、かつアプリが Google Play 経由で配布されていない場合にのみ送信してください。

例: fc8d449516de0dfb

sdid

プラットフォーム: iOS, Android, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV

Singular Device ID は、一意のアプリインストールを表す、クライアント生成の匿名化された UUIDv4 です。

主要識別子: PC およびコンソールアプリケーションで唯一関連するデバイス識別子です。

例: 40009df0-d618-4d81-9da1-cbb3337b8dec

デバイスパラメータ

パラメータ 詳細
p

string

アプリケーションのプラットフォーム。

許可される値（大文字・小文字を区別）:

  • Android
  • iOS
  • PC
  • Xbox
  • Playstation
  • Nintendo
  • MetaQuest
  • CTV

例: Android

ip

string

デバイスのパブリック IPv4 アドレス。IPv6 もサポートされていますが、広告ネットワークとのアトリビューション互換性のため IPv4 を推奨します。

例: 172.58.29.235

ve

string

セッション時のデバイスの OS バージョン。

例: 9.2

ma
iOS, Android

string

デバイスのメーカー（製造元名）。 mo （モデル）と併用する必要があります。

デバイスメーカーを取得する

例: Samsung , LG , Apple

mo
iOS, Android

string

デバイスのモデル。 ma （メーカー）と併用する必要があります。

デバイスモデルを取得する

例: iPhone 4S , Galaxy SIII

lc
iOS, Android

string

IETF ロケールタグ。アンダースコアで区切られた 2 文字の言語コードと国コード。

デバイスロケールを取得する

例: en_US

bd
iOS, Android

string

デバイスのビルド識別子（URL エンコード済み）。

デバイスビルドを取得する

例: Build%2F13D15

アプリケーションパラメータ

パラメータ 詳細
i

string

アプリ識別子（大文字・小文字を区別）。

  • Android: パッケージ名（例: com.singular.app ）
  • iOS: Bundle ID（例: com.singular.app ）
  • PC/Console: 指定された識別子

例: com.singular.app

app_v

string

アプリケーションのバージョン。

例: 1.2.3

att_authorization_status
iOS

integer

App Tracking Transparency (ATT) のステータスコード（iOS 14.5 以降）。

ステータス値:

  • 0 - 未確定（プロンプト未表示）
  • 1 - 制限あり（デバイスレベルのトラッキングが無効）
  • 2 - 拒否（ユーザーが許可を拒否）
  • 3 - 許可（ユーザーが許可を付与）

常に必須: ATT を実装していない場合でも、 0 （未確定）を渡してください。

例: 3

ネットワークおよび位置情報パラメータ

パラメータ 詳細
use_ip

boolean

ip パラメータの代わりに、HTTP リクエストから IP アドレスを抽出するよう Singular に指示します。

制限事項:

  • Singular による IP ベースの位置情報推定を妨げます。
  • country パラメータで 2 文字の国コードを指定してください。
  • ip パラメータとは相互排他的です。両方を使用しないでください。
  • データの拒否を避けるため、 ip または use_ip のいずれかを必ず指定してください。

例: true

country

string

ISO 3166-1 alpha-2 の 2 文字の国コード。

必須となる場合: IP アドレスが利用できない場合、または use_ip=true の場合。

例: US

ua

string

URL エンコードされた User Agent 文字列。

生の値: Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15...

例: Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0...

c
iOS, Android

string

ネットワーク接続の種類。

許可される値: wifi , carrier

例: wifi

cn
iOS, Android

string

インターネットプロバイダーのキャリア名。

例: Comcast

データプライバシーパラメータ

パラメータ 詳細
data_sharing_options

JSON

データ共有に関するエンドユーザーの同意を表す JSON（URL エンコード済み）。永続化し、以降のすべての SESSION および EVENT リクエストで渡す必要があります。

ユーザーが同意した場合（オプトイン）: 

{"limit_data_sharing":false}

ユーザーが拒否した場合（オプトアウト）: 

{"limit_data_sharing":true}

例: %7B%22limit_data_sharing%22%3Atrue%7D

dnt
iOS, Android

integer

Do Not Track のステータス。

  • 1 - Do Not Track 有効
  • 0 - Do Not Track 無効

例: 0

dntoff
iOS, Android

integer

Do Not Track が OFF かどうかを示します。

  • 0 - Do Not Track 有効（OFF=false）
  • 1 - Do Not Track 無効（OFF=true）

例: 1

クロスデバイスサポート

パラメータ 詳細
custom_user_id

string

クロスデバイストラッキング用の自社内部ユーザー ID。

PII は使用不可: 個人を特定できる情報は渡さないでください。生のメールアドレス、電話番号、氏名ではなく、ハッシュ化またはその他の方法で匿名化した内部識別子を使用してください。

例: 123456789abcd

実装フェーズ

S2S 統合を成功させるには、最適なデータ品質とアトリビューションの精度を得るために、4 つの主要な実装フェーズを順番に実行する必要があります。

フェーズ 1: データ収集

必要なデータポイント

Singular プラットフォームの機能に必要なすべてのパラメータを取得する、堅牢なデータ収集戦略を確立します。

すべての必須パラメータは必須: 必須パラメータを省略すると、データの不一致やアトリビューションエラーが発生します。任意のパラメータはありません。

非同期関数の処理: サーバー送信用にクライアントサイドのデータを収集する際は、非同期関数の完了を待ち、エッジケースを処理してください。データの欠落や部分的なアトリビューションを引き起こす一般的な問題です。

実装リソース:

フェーズ 2: リアルタイムストリーミング

重要なタイミング要件

リアルタイムのデータストリーミングは、アトリビューションの精度を維持し、SKAdNetwork のコンバージョン値の更新などの時間的制約のある機能を可能にします。

アトリビューションへの影響:

  • 遅延したセッション: アトリビューションの精度に深刻な影響を及ぼします。システムはキャンペーンとの関連付けに正確な時間データを必要とします
  • SKAdNetwork タイマー: コンバージョン値に対するデバイス上の厳格なタイマーウィンドウにより、リアルタイムストリーミングが不可欠です。遅延はコンバージョン値の更新の見逃しや不完全なキャンペーンデータの原因となります

ベストプラクティス:

  • アプリのセッション開始を検知するサーバーサイドのイベントリスナーを実装します
  • すべての必須パラメータとともに セッションデータ を即座に転送します
  • アプリ内イベントを検知するサーバーサイドのイベントリスナーを実装します
  • すべての必須パラメータとともに イベントデータ を即座に転送します
  • 信頼性の高いデータ送信のために webhook アーキテクチャを使用します
  • 失敗したリクエストに対するリトライ機構を実装します
  • 品質保証のためにデータフローを監視します

フェーズ 3: レスポンス処理

双方向通信

レスポンス処理は、サーバーサイドの API とのやり取りとクライアントサイドの機能を橋渡しし、遅延ディープリンクとコンバージョン値の更新を可能にします。

主要なレスポンスの種類:

  • 遅延ディープリンク: API レスポンスには保留中のディープリンクデータが含まれ、ユーザーのルーティングとパーソナライゼーションのために即座にアプリへ中継する必要があります
  • コンバージョン値: 正確なキャンペーン測定のため、iOS SKAdNetwork のコンバージョン値を速やかにアプリへ転送する必要があります

ベストプラクティス:

  • サーバーインフラストラクチャ上にレスポンス処理を実装します
  • Singular API のレスポンスを解析して検証します
  • 関連するレスポンスデータをクライアントアプリへ転送します（iOS SKAdNetwork には不可欠）
  • クライアントサイドのレスポンス処理を実装します
  • 適切な HTTP ステータスコードでエラーを適切に処理します
  • リトライ機構のために失敗したレスポンスをログに記録します

フェーズ 4: テストと検証

データフローの確認

テストフェーズでは、本番環境へのデプロイ前に、データパイプライン全体の機能とアトリビューションの精度を検証します。

セッションのアトリビューションプロセス:

  • 初回セッション（新規インストール）: Singular は新規インストールを認識し、インストールアトリビューションプロセスをトリガーします
  • 再エンゲージメントの条件を満たす場合: Singular は再エンゲージメントのアトリビューションプロセスをトリガーします（ 再エンゲージメント FAQ ）
  • 標準セッション: Singular はユーザーのアクティビティとリテンション指標のためにセッションを記録します

重要なタイミング要件:

  1. イベントの前にセッション: いかなるイベントよりも前に単一の SESSION を受信する必要があります。SDK はアプリ起動時にセッションをトリガーし、その後アプリ内イベントを送信します。1 分以上バックグラウンドにあると、セッションはタイムアウトします。アプリがフォアグラウンドに戻ると新しいセッションが送信されます。セッション管理にはアプリのライフサイクルイベントとタイマーを使用してください
  2. リアルタイムイベント: アプリ内で発生したイベントは、対応するセッションの後にリアルタイムで送信する必要があります

検証チェックリスト:

  • セッションのデータフローをテストします。初回および以降のセッションが正しいデータポイントと値を持つことを検証します
  • セッションが Singular に報告された後にのみイベントが受信されることを確認します（セッションより前のイベントはオーガニックアトリビューションを生成します）
  • セッションのレスポンスが処理され、クライアントアプリに渡されることを確認します（遅延ディープリンクには不可欠）

統合完了:

  • ✓ データ収集とストレージが検証済み
  • ✓ Singular へのリアルタイムストリーミングが検証済み
  • ✓ レスポンス処理とログ記録が検証済み
  • ✓ すべてのテストデータフローが検証済み

テストガイド: S2S 統合テストガイド

追加機能

包括的な分析のために、クロスデバイストラッキング、収益トラッキング、アンインストールの監視、データプライバシーコンプライアンスを実装します。

クロスデバイストラッキング

Custom User ID の実装

custom_user_id パラメータを活用して、クロスデバイスレポートとユーザーレベルの分析のために、ユーザーをデバイスレベルのセッションに関連付けます。

プライバシーコンプライアンス: custom_user_id に個人を特定できる情報（PII）を含めないようにして、データプライバシーポリシーを遵守してください。一意のユーザー識別子として、ハッシュ化したユーザー名、メール、またはランダムに生成した文字列を使用してください。

ユーザーのプライバシーを維持しながら、包括的なクロスデバイスレポート、ユーザーレベルのデータエクスポート、Internal BI ポストバックを可能にします。

詳細: Custom User ID パラメータ

収益トラッキング

アプリ内課金のレポート

ROI 分析、キャンペーンパフォーマンスの測定、エクスポート/ポストバックのエンリッチメントのために、アプリ内課金からの収益をトラッキングします。

EVENT エンドポイント を 収益パラメータ とともに使用します:

  • is_revenue_event : イベントを収益イベントとしてマークします（イベント名が __iap__ の場合、または金額 > 0 の場合はスキップ）
  • purchase_receipt : Android/iOS のアプリ内課金オブジェクト。トランザクションの詳細とレポートのエンリッチメントのために強く推奨されます
  • receipt_signature （Android）: トランザクションの検証と不正防止のために強く推奨されます
  • amt : Double 型の収益額（例: "amt=1.99"）
  • cur : ISO 4217 の通貨コード（例: "cur=USD"）

実装ガイド: サブスクリプション状態管理

データプライバシーコンプライアンス

ユーザー同意の処理

GDPR、CCPA、その他のプライバシー規制を遵守するため、データ共有に関するエンドユーザーの同意を Singular に通知します。

data_sharing_options パラメータを使用して、ユーザーの選択を伝えます:

  • {"limit_data_sharing":false} : ユーザーが情報の共有に同意（オプトイン）した場合
  • {"limit_data_sharing":true} : ユーザーが情報の共有を拒否した場合

Singular は limit_data_sharing を User Privacy ポストバック で使用し、コンプライアンスを必要とするパートナーに情報を渡します。

任意だが推奨: このパラメータは任意ですが、一部のアトリビューション情報は、ユーザーが明示的にオプトインした場合にのみパートナーによって共有されます。

詳細: ユーザープライバシーと Limit Data Sharing