サーバー間 - 統合ガイド

SingularのREST APIを導入することで、SDK統合に代わる完全なサーバーサイドトラッキングを実現し、データ収集、送信、アトリビューションワークフローを完全にコントロールすることができます。

概要

サーバー間の使用例

サーバー間（S2S）統合は、クライアントアプリケーションにSingular SDKを組み込むことなく、バックエンドインフラから完全なアトリビューションと分析ソリューションを構築するためのREST APIエンドポイントを提供します。

統合のアプローチ

• 純粋なS2S：100%サーバーサイドでセッションとイベントのトラッキングを行います。
• ハイブリッド：Singular SDKがセッションを管理し、サーバーサイドがイベントトラッキングを処理します。

ハイブリッド統合パターン

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

デバイス・データ取得方法：

1. クライアント管理フロー：クライアントで必要なデータポイントをキャプチャし、Singular EVENT エンドポイントを使用するために内部 API を介してサーバーに転送します。
2. 内部 BI ポストバック：インストール後、再エンゲージメント後、またはイベント後にデバイス識別子を含むリアルタイムのJSONペイロードを受信するように、Singular内部BIポストバックを設定します（セットアップガイド）。

実装リソース：

• EVENTエンドポイント必須パラメータ
• デバイスデータの取得ガイド（iOS/Androidコードサンプル

主な統合原則

統合要件

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

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

REST API エンドポイント

Singular はサーバー間のセッションとイベントのトラッキングのために二つの主要な REST API エンドポイントを提供します。

セッションエンドポイント

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

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

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

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

イベントエンドポイント

イベントトラッキング API

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

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

参考資料：EVENTエンドポイントAPIリファレンス

実装フェーズ

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

フェーズ1：データ収集

必要なデータポイント

Singularプラットフォームの機能に必要な全パラメータを収集する強固なデータ収集戦略を確立する。

実装リソース：

• SESSIONエンドポイント必須パラメータ
• EVENTエンドポイント必須パラメータ
• デバイスデータの取得ガイド（iOS/Android コードサンプル
• SKAdNetwork 4実装ガイド（iOS特有のデータポイント

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

重要なタイミング要件

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

ベストプラクティス

• アプリのセッション開始のためにサーバー側のイベントリスナーを実装する
• すべての必要なパラメータを使用してセッションデータを直ちに転送する
• アプリ内イベント用にサーバーサイドイベントリスナーを実装する
• すべての必要なパラメータを使用してイベントデータを即座に転送
• 信頼性の高いデータ転送のためにWebhookアーキテクチャを使用する
• 失敗したリクエストに対するリトライ・メカニズムの実装
• 品質保証のためにデータフローを監視する

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

双方向通信

レスポンス・ハンドリングは、サーバーサイドのAPIインタラクションとクライアントサイドの機能の橋渡しをし、ディファード・ディープ・リンクとコンバージョン値の更新を可能にする。

主なレスポンス・タイプ

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

ベストプラクティス

• サーバーインフラでのレスポンス処理の実装
• Singular API レスポンスの解析と検証
• 関連するレスポンスデータをクライアントアプリに転送（iOS SKAdNetworkでは必須）
• クライアント側のレスポンス処理の実装
• 適切なHTTPステータスコードで優雅にエラーを処理する
• リトライメカニズムのために失敗したレスポンスを記録する

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

データフローの検証

テスト・フェーズでは、本番展開の前に、完全なデータ・パイプラインの機能と属性の正確性を検証します。

セッション帰属プロセス

• 最初のセッション（新規インストール）：Singularが新規インストールを認識し、インストールアトリビューションプロセスをトリガーします。
• リエンゲージメント認定：Singularがリエンゲージメントアトリビューションプロセスをトリガーします（リエンゲージメントFAQ
• 標準セッション：Singularはユーザーアクティビティとリテンションメトリクスのためにセッションを記録します。

検証チェックリスト：

• セッション・データ・フローをテストし、最初のセッションとその後のセッションに正しいデータ・ポイントと値があることを確認する。
• セッションがSingularに報告された後にのみイベントを受信することを確認する（セッション前のイベントはオーガニックなアトリビューションを作成する
• セッションレスポンスが処理され、クライアントアプリに渡されることを確認する（ディファードディープリンクには重要

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

高度な機能

高度なアトリビューション処理、ディープリンク、クロスデバイストラッキング、プラットフォーム固有の機能により、S2S統合を強化します。

Apple検索広告アトリビューション

iOS検索広告統合

Apple Search AdsはSelf-Attributing Network (SAN)であり、Appleフレームワークによるプラットフォーム固有のアトリビューション実装が必要です。

フレームワークのサポート

• iOS 14.2以下： iAdフレームワーク
• iOS 14.3以上： AdServicesフレームワーク（推奨

完全ガイド：Apple Search Ads Integration ドキュメント

iAdフレームワークの実装

iOS14.2以下のiAdフレームワークを使用して、Apple Search Adsのアトリビューションデータを取得および送信します。

ステップ 1: アトリビューションデータの取得

#import <iAd/iAd.h>

Class ADClientClass = NSClassFromString(@"ADClient");

if (ADClientClass) {
    id sharedClient = [ADClientClass performSelector:@selector(sharedClient)];
    
    if ([sharedClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) {
        [sharedClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
            if (attributionDetails && attributionDetails.count  0) {
                // REPORT attributionDetails FROM YOUR APP TO YOUR SERVER
            }
        }];
    }
}

ステップ2：Singularへの送信

e パラメータとしてアトリビューション JSON を渡し、EVENT エンドポイントを介して予約名__iAd_Attribution__ でイベントを報告する。

AdServicesフレームワークの実装

iOS14.3以上の場合、AdServicesフレームワークを使用してアトリビューショントークンを取得および送信します。

ステップ1：アトリビューショントークンの取得

#import <AdServices/AdServices.h>

NSError *error = nil;
Class AAAttributionClass = NSClassFromString(@"AAAttribution");
if (AAAttributionClass) {
    NSString *attributionToken = [AAAttributionClass attributionTokenWithError:&error];
    if (!error && attributionToken) {
        // Handle attributionToken
    }
}

ステップ2：Singularに送信

トークンをURLエンコードし、SESSIONエンドポイントに attribution_token パラメータとして追加します。

Google Play インストールリファラー

Android インストールのアトリビューション

Google Play Install Referrer は、Play ストアに到着する前のユーザーに関する情報を含む、最も正確な Android インストール帰属情報を提供します。

詳細:Google Install Referrer ドキュメント

実装ステップ

1. Play Install Referrer API を使用して、アプリを最初に開いたときにインストールリファラーを取得する。
2. 必要な属性を含むinstall_ref JSON パラメータを含むSESSION エンドポイント経由でセッションを報告します。

install_ref 属性：

メタインストールリファラー

Facebookアトリビューションの強化

Meta Referrerは、Google Play Install ReferrerとMeta Install Referrerのテクノロジーを組み合わせた、アプリインストールの詳細なユーザーレベルのアトリビューションデータを提供するAndroid専用の測定ソリューションです。

詳細：Meta Referrer FAQ

実装ステップ

1. Metaのドキュメントに従って、最初のアプリ開封時にMetaインストールリファラーを取得する。
2. meta_ref JSON パラメータに必要な属性を含むSESSION エンドポイント経由でセッションを報告します。

meta_ref 属性：

Singularリンクとディープリンク

キャンペーンから特定のアプリ内コンテンツへのシームレスなユーザー体験を可能にするために、シンギュラートラッキングリンクのディープリンクとディファードディープリンクのサポートを実装します。

ディープリンクは、ユーザーをアプリ内の特定のコンテンツに導くクリック可能なリンクです。アプリがインストールされたデバイスでユーザーがディープリンクをクリックすると、アプリが開き、特定の商品や体験が表示されます。

リソース：ディープリンクFAQ｜シンギュラーリンクFAQ

前提条件

プラットフォーム設定

クライアントアプリがSingular LinksをiOSユニバーサルリンクまたはAndroidアプリリンクとして認識する必要があります。

設定ガイド:シンギュラーリンクの前提条件

ディープリンクの実装

ディープリンクのキャプチャ

ディープリンク経由でアプリが開くと、openuri パラメータに URL 値を追加することで、openURL をキャプチャし、SESSION リクエストに追加します。 シンギュラーリンクを使用する場合は必須です。

シンギュラーリンクのパラメータ：

• _ios_dl および_android_dl: プラットフォームごとに異なるディープリンク値でリンクが生成された場合に存在します。
• _dl iOSとAndroidでディープリンクの値が同じ場合に存在。
• _p パススルーパラメータが含まれている場合に必要。

ディープリンクハンドラコード

アプリには、openURL を解析し、シンギュラーリンクパラメータを適切に処理するハンドラコードが必要です。

class DeepLinkHandler {
    func handleURL(_ url: URL) {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else {
            return
        }

        var params: [String: String] = [:]

        // Parse query parameters
        if let queryItems = components.queryItems {
            for item in queryItems {
                switch item.name {
                case "_dl":
                    params["deeplink"] = item.value
                case "_ios_dl":
                    params["ios_deeplink"] = item.value
                case "_p":
                    params["passthrough"] = item.value
                default:
                    break
                }
            }
        }

        // Handle the parsed parameters
        processDeepLinkParameters(params)
    }

    private func processDeepLinkParameters(_ params: [String: String]) {
        // Process the parameters as needed
        print("Processed parameters: \(params)")
    }
}

// In SceneDelegate or AppDelegate
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    let handler = DeepLinkHandler()
    handler.handleURL(url)
}

class DeepLinkHandler {
    fun handleDeepLink(intent: Intent) {
        val data: Uri? = intent.data

        data?.let { uri ->
            val params = mutableMapOf<String, String>()

            // Parse query parameters
            uri.queryParameterNames?.forEach { name ->
                when (name) {
                    "_dl" -> params["deeplink"] = uri.getQueryParameter(name) ?: ""
                    "_android_dl" -> params["android_deeplink"] = uri.getQueryParameter(name) ?: ""
                    "_p" -> params["passthrough"] = uri.getQueryParameter(name) ?: ""
                }
            }

            processDeepLinkParameters(params)
        }
    }

    private fun processDeepLinkParameters(params: Map<String, String>) {
        // Process the parameters as needed
        println("Processed parameters: $params")
    }
}

// In your Activity
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Handle deep link if activity was launched from a deep link
        intent?.let { DeepLinkHandler().handleDeepLink(it) }
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        // Handle deep link if app was already running
        intent?.let { DeepLinkHandler().handleDeepLink(it) }
    }
}

遅延ディープリンク

初回インストール時のディープリンク

インストール後初めてアプリを開いたとき、Singularにセッションを報告するときにパラメータを追加することで、遅延ディープリンクを有効にします。

必須パラメータ：

• install=true
• ddl_enabled=true

Singularはアプリが遅延ディープリンクのトラッキングリンクを通してインストールされたかどうかをチェックします。もしそうなら、SESSIONリクエストが返されます：

• deferred_deeplink ユーザーに正しい製品/体験を表示するためのディープリンクのアドレスパース
• deferred_passthrough ディープリンクに追加されたパススルーパラメータ

サンプルレスポンス：

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}

動的パススルーパラメータ

Singular的なトラッキングリンクには、ユーザー体験をカスタマイズするための動的パススルー・パラメータを含めることができます。

組織がリンクに動的パススルーを設定した場合、ディープリンクの URL には、コンテンツ/エクスペリエンスのルーティング用に URL エンコードされた JSON 文字列値または構造化されていない文字列を持つ_p パラメータが含まれます。

詳細:動的パススルー・パラメータ

ショートリンクの解決

短縮されたSingularリンクからアプリを開く場合、SESSIONリクエストにパラメータを含めて、短いリンクを長いリンクに解決します。

必須パラメータ: singular_link_resolve_required=true

リンクハンドラでディープリンクとパススルーパラメータを解析するために、Singularは短縮されていないロングリンクを返します。

サンプルレスポンス：

{
  "status": "ok",
  "resolved_singular_link": "https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

その他の機能

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

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

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

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

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

詳細：カスタムユーザIDパラメータ

収益トラッキング

アプリ内課金レポート

ROI分析、キャンペーンパフォーマンス測定、エクスポート/ポストバックの充実のために、アプリ内購入からの収益を追跡します。

収益パラメータで EVENTエンドポイントを使用します：

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

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

アンインストール追跡

サイレントプッシュ通知のセットアップ

セッション通知ごとにプッシュトークンを送信することで、デバイスのサイレントプッシュ通知を使用してアンインストールを追跡します。

セットアップ要件：

1. プラットフォーム固有のアンインストール追跡セットアップに従ってください：
   • iOS アンインストール追跡セットアップ
   • Android アンインストール追跡セットアップ
2. SESSION リクエストにプラットフォーム固有のトークンを追加します：
   • iOS： apns_token (APNsデバイストークン)
   • Androidの場合 fcm (FCMデバイストークン）

iOSインストールレシート

レシートの検証

iOSセッションを報告するときに install_receipt パラメータを渡す。

import Foundation
import StoreKit

class ReceiptManager {
    static func getInstallReceipt() - String? {
        if #available(iOS 18.0, *) {
            let semaphore = DispatchSemaphore(value: 0)
            var result: String?
            
            Task {
                do {
                    let transaction = try await AppTransaction.shared
                    result = transaction.jwsRepresentation
                    semaphore.signal()
                } catch {
                    debugPrint("Failed to get app transaction: \(error.localizedDescription)")
                    semaphore.signal()
                }
            }
            
            semaphore.wait()
            return result
            
        } else {
            guard let receiptURL = Bundle.main.appStoreReceiptURL else {
                debugPrint("Receipt URL not found")
                return nil
            }
            
            do {
                let receiptData = try Data(contentsOf: receiptURL, options: .uncached)
                return receiptData.base64EncodedString(options: [])
            } catch {
                debugPrint("Failed to read receipt: \(error.localizedDescription)")
                return nil
            }
        }
    }
}

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

ユーザーの同意処理

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

次のパラメータを使用します。 data_sharing_options パラメータを使用します：

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

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

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