Server-to-Server - 連携ガイド

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

概要

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

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

連携アプローチ:

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

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

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

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

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

実装リソース:

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

主な連携の原則

連携の要件

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

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

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リファレンス

実装フェーズ

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 Search Adsアトリビューション

iOS Search Adsの連携

Apple Search Adsは自己アトリビューションネットワーク（SAN）であり、Appleのフレームワークを介したプラットフォーム固有のアトリビューション実装が必要です。

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

• iOS 14.2以下: iADフレームワーク
• iOS 14.3以上: AdServicesフレームワーク （推奨）

詳細なガイド: Apple Search Ads連携ドキュメント

iADフレームワークの実装

iOS 14.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への送信

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

AdServicesフレームワークの実装

iOS 14.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 Install Referrer

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

Google Play Install Referrerは、Play Storeに到達する前のユーザーの発生元に関する情報を含み、Androidのインストールアトリビューションにおいて最も正確な手段を提供します。

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

実装手順:

1. Play Install Referrer API を使用して、初回のアプリ起動時にインストールリファラーを取得します
2. 必須属性を持つ install_ref JSONパラメータを含めて、 SESSIONエンドポイント 経由でセッションを報告します

install_refの属性:

Meta Install Referrer

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

Meta ReferrerはAndroid固有の計測ソリューションで、Google Play Install ReferrerとMeta Install Referrerの技術を組み合わせることで、アプリインストールに対する詳細なユーザーレベルのアトリビューションデータを提供します。

詳細: Meta Referrer FAQ

実装手順:

1. Metaのドキュメント に従って、初回のアプリ起動時にMetaのインストールリファラーを取得します
2. 必須属性を持つ meta_ref JSONパラメータを含めて、 SESSIONエンドポイント 経由でセッションを報告します

meta_refの属性:

Singular Linksとディープリンク

Singularのトラッキングリンクに対してディープリンクとディファードディープリンクを実装することで、ユーザーがキャンペーンからアプリ内の特定の画面までシームレスに移動できるようにします。

ディープリンクは、アプリ内の特定のコンテンツを開くクリック可能なリンクです。サポートすべきシナリオは2つあります:

• ディープリンク（ダイレクト）: ユーザーがすでにアプリをインストールしている場合。Singular Linkをタップすると、アプリが直接適切なコンテンツを開きます。
• ディファードディープリンク（DDL）: ユーザーがまだアプリを持っていない場合。リンクをタップし、ストアからインストールすると、初回起動時にアプリは意図したコンテンツへユーザーをルーティングします。

SDK連携では、Singularがこのほとんどを自動的に処理します。Server-to-Server（S2S）連携ではデバイス上にSDKが存在しないため、お客様のチームは2つの追加作業を担当します。アプリが受け取ったディープリンクをSingularに渡すことと、Singularが返すディファードディープリンクを読み取ってユーザーをルーティングすることです。どちらもSESSIONエンドポイントを経由します:

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

リソース: ディープリンクFAQ | Singular Links FAQ

3つの設定の概要

ステップ1: アプリレベルの設定

ディープリンクが機能する前に、Singular LinksがOSによってiOS Universal LinksおよびAndroid App Linksとして認識され、リンクをタップするとブラウザではなくアプリが開くようにする必要があります。従来のURIアプリスキームはフォールバックとしてサポートされています。

詳細なプラットフォームの手順については、標準的なセットアップガイドに従い、その後で以下の各項目が完了していることを確認してください。詳細な手順はSingular Linksの前提条件とディープリンクの設定方法に記載されています。ここでのチェックリストは、必要な順序とチームが最も見落としやすいポイントを示します。

設定チェックリスト:

1. リンクのサブドメインを追加します（Attribution > Manage Links > Manage Link Domains、例: yourbrand.sng.link）。これはSingular Linksが使用するホストです。
2. iOS — Universal Links: applinks:yourbrand.sng.linkに対してAssociated Domains機能を有効にし、Apple Developer PortalからApp Prefix / Team IDをコピーしてSettings > Apps > [iOSアプリ] > Show Advanced Settingsに貼り付けます。オプションで、XcodeでアプリスキームのフォールバックをURL Typeとして登録します。
3. Android — App Links: SHA-256署名フィンガープリントを生成し（本番環境はPlay Console、デバッグはkeytool）、Singularドメインに対するautoVerifyインテントフィルターをAndroidManifest.xmlに追加し、フィンガープリントをSettings > Apps > [Androidアプリ] > Show Advanced Settings > App Links SHA256 fingerprintsに貼り付けます。
4. ディープリンクを定義します（Attribution > Manage Links > Create Link、以下のフィールドのマッピングを参照）。

Manage Linksのリダイレクトフィールドのマッピング

リンクを作成する際、3つのリダイレクトフィールドが、後でAPIで使用される3つのディープリンクの概念に直接対応します:

開発者への引き継ぎ: エンジニアリングは、プラットフォームごとのディープリンクスキームと遷移先URLのリスト（例: myapp://autumnfashion）を提供する必要があります。

ステップ2: SESSION（インバウンド）— ディープリンクをSingularに送信する

アプリがSingular Linkから開かれたら、開いた完全なURLを取得し、SESSIONリクエストのopenuriパラメータ（URLエンコード済み）でSingularに送信します。これにより、Singularはセッションをリンクにアトリビューションし、ディープリンクの結果を報告します。Singular Linksを使用する場合は必須です。

URLに含まれるSingular Linkのパラメータ

アプリ内で開いたURLを取得する

アプリには、開いたURLを受け取り、SESSIONリクエストに含めるためにサーバーへ転送するハンドラーコードが必要です。

iOS（Swift）:

// Custom scheme / direct opens
func scene(_ scene: UIScene,
           openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    SessionReporter.report(openURL: url.absoluteString)
}

// Universal Links arrive via:
func scene(_ scene: UIScene,
           continue userActivity: NSUserActivity) {
    if let url = userActivity.webpageURL {
        SessionReporter.report(openURL: url.absoluteString)
    }
}

Android（Kotlin）:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent?.data?.let { uri ->
        SessionReporter.report(uri.toString())
    }
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { SessionReporter.report(it.toString()) }
}

openuriを使ってSESSIONリクエストを送信する

サーバーから、取得したURL（URLエンコード済み）をopenuriとして含めます:

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1"

短縮リンクの解決

ユーザーが短縮されたSingular Linkを開いた場合は、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"
}

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

組織でリンクに対する動的パススルーを設定している場合、ディープリンクURLには、コンテンツルーティング用のURLエンコードされたJSON文字列または非構造化文字列を含む_pパラメータが含まれます。動的パススルーパラメータを参照してください。

リファレンス: SESSIONエンドポイントAPIリファレンス（ディープリンクパラメータ）。

ステップ3: SESSION（アウトバウンド）— ディファードディープリンクをアプリに中継する

リンクをタップした後にアプリをインストールしたユーザーの場合、ディファードディープリンクは、インストール後の初回セッションでSingularがSESSIONレスポンスとして返します。お客様のサーバーは、その値をアプリに中継して、ユーザーをルーティングできるようにする必要があります。

初回セッションでDDLをリクエストする

インストール後の初回SESSIONリクエストで、次の2つのパラメータを追加します:

SESSIONリクエストのサンプル（install + DDL有効）:

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "install=true" \
  --data-urlencode "ddl_enabled=true"

レスポンスを読み取ってアプリに中継する

インストールがディファードディープリンクを含むトラッキングリンクから発生した場合、Singularは次を返します:

SESSIONレスポンスのサンプル:

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

テストと検証

• ディファードディープリンク: アプリが入っていないデバイスでリンクをタップし、ストアに着地することを確認します。インストールして開くと、アプリは意図したコンテンツを表示するはずです。
• ダイレクトディープリンク: アプリがインストールされた状態でリンクをタップし、アプリが直接、意図したコンテンツを開くことを確認します。
• SESSIONの順序: いかなるイベントよりも前に単一のSESSIONが受信されること、およびSESSIONレスポンスが解析されてクライアントに渡されること（ディファードディープリンクに必須）を確認します。
• openuriの設定: ディープリンクでの起動時に、タイムアウトウィンドウに関係なく、openuriを設定したSESSIONが送信されることを確認します。

テストガイド: 連携のテスト | トラッキングリンクのテスト

追加の機能

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

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

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

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

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

詳細情報: カスタムユーザー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"）

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

アンインストールトラッキング

サイレントプッシュ通知の設定

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

設定の要件:

1. プラットフォーム固有のアンインストールトラッキングの設定に従ってください:
   • iOSアンインストールトラッキングの設定
   • Androidアンインストールトラッキングの設定
2. プラットフォーム固有のトークンをSESSIONリクエストに付加します:
   • iOS: apns_token （APNsデバイストークン）
   • Android: fcm （FCMデバイストークン）

iOSインストールレシート

レシートの検証

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 を ユーザープライバシーポストバック で使用し、コンプライアンスを必要とするパートナーに情報を渡します。

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