Server-to-Server - 基礎

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

連携方法の選択: SDK と S2S のどちらを選ぶか? クライアント SDK を組み込める場合は、まず SDK 連携ドキュメントから始めてください。サーバーサイドでのイベント送信が必要な場合、SDK が提供されていないプラットフォームを使用している場合、またはデータ収集を完全に制御したい場合は Server-to-Server を使用します。本スイートは S2S の実装方法を扱い、モバイル、Web、PC/コンソール向けの各 S2S ガイドの共通リファレンスとなります。

概要

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

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

連携アプローチ:

Pure S2S: セッションとイベントの両方のトラッキングを扱う 100% サーバーサイド実装
ハイブリッド: Singular SDK がセッションを管理し、サーバーサイドがイベントトラッキングを処理

Pure S2S 連携

Pure S2S は完全なサーバーサイド実装です。バックエンドが必要なデータを収集し、デバイスグラフを維持し、セッションとイベントの両方を Singular に送信します。ステップごとのパイプラインについては、後述の「実装フェーズ」を参照してください。

ハイブリッド連携パターン

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

ハイブリッドの利点:

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

ハイブリッド S2S データフロー

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

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

デバイスグラフの維持: どちらの方法でも、デバイスグラフを維持するためのサーバーサイドロジックが必要です。SDK がデバイス識別子の変更を検出した場合は、正確なトラッキングを保証するためにサーバーを適宜更新してください。

関連リソース:

デバイスデータの取得ガイド (iOS/Android コードサンプル)

連携の主要原則

これらの原則は、プラットフォームやアプローチを問わず、すべての S2S 連携に適用されます:

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

実装フェーズ

完全な S2S 連携は 4 つのフェーズを順番に進め、各フェーズが前のフェーズの上に積み重なっていきます。

フェーズ 1: データ収集

必須データポイント

Singular が正確にアトリビューションとレポートを行うために必要なすべてのパラメーターを取得するデータ収集を設定します。

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

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

実装リソース:

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

重要なタイミング要件

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

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

セッションの遅延: アトリビューションの精度に深刻な影響を与えます — システムはキャンペーンとの紐付けに正確な時間データを必要とします
SKAdNetwork タイマー: コンバージョン値に対する厳格なオンデバイスのタイマーウィンドウにより、リアルタイムストリーミングが不可欠です。遅延はコンバージョン値の更新漏れやキャンペーンデータの不完全さを引き起こします

ベストプラクティス:

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

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

双方向通信

レスポンス処理は、サーバーサイドの API 呼び出しをクライアントアプリに接続し直すもので、これにより遅延ディープリンクとコンバージョン値の更新が可能になります。

主なレスポンスの種類:

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

ベストプラクティス:

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

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

データフローの検証

本番環境にデプロイする前に、データパイプライン全体をエンドツーエンドで検証し、アトリビューションが正確であることを確認してください。

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

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

重要なタイミング要件:

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

検証チェックリスト:

セッションデータフローをテスト — 初回およびそれ以降のセッションで正しいデータポイントと値があることを検証
Singular にセッションが報告された後にのみイベントが受信されることを確認 (セッション前のイベントは自然流入のアトリビューションを生成します)
セッションのレスポンスが処理され、クライアントアプリに渡されることを確認 (遅延ディープリンクに不可欠)

連携完了:

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

テストガイド: S2S 連携テストガイド

追加機能

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

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

カスタムユーザー ID の実装

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

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

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

詳細情報: Custom User ID パラメーター

収益トラッキング

アプリ内課金のレポート

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

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

is_revenue_event: 収益イベントの場合は true、それ以外の場合は false に設定します。
purchase_receipt : Android/iOS のアプリ内課金オブジェクト — トランザクションの詳細とレポートのエンリッチメントのために強く推奨されます
receipt_signature (Android): トランザクションの検証と不正防止のために強く推奨されます
amt : Double 型の収益額 (例: "amt=1.99")
cur : ISO 4217 の通貨コード (例: "cur=USD")

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

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

ユーザー同意の処理

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

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

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

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

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

詳細情報: ユーザープライバシーとデータ共有の制限

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

各エンドポイントリファレンスには、完全な必須および任意のパラメーターがインラインで記載されています。パラメーターの完全な一覧については、以下を参照してください:

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

プラットフォームガイド

機能ガイド