広告収益トラッキング API リファレンス

SDK 実装の代替手段として、サーバー間連携を通じて Singular の REST API を使用し、インプレッションレベルの広告マネタイズ収益をトラッキングすることで、アトリビューション分析とキャンペーン最適化に活用できます。

概要

サーバー間連携のユースケース

広告収益 API は、インプレッションレベルの広告マネタイズトラッキングを可能にします。アプリはメディエーションプラットフォームからの収益データをバックエンドに転送し、バックエンドがそれを Singular のサーバーに送信することで、広告収益の分析とレポーティングを実現します。

サポートされる機能:

• 広告マネタイズ収益: メディエーションプラットフォームからのインプレッションレベルの収益をトラッキング
• プラットフォームアトリビューション: 広告収益をユーザー獲得キャンペーンに紐付け
• メディエーション連携: 主要なすべての広告メディエーションプラットフォームをサポート
• 通貨換算: 組織設定に合わせた自動通貨換算

データフローアーキテクチャ

サーバー間連携による広告収益トラッキングは、4 ステップのデータ送信プロセスに従います。

1. クライアント収集: アプリがメディエーションプラットフォームの SDK からインプレッションレベルの収益データを収集
2. サーバー送信: アプリが広告収益データをバックエンドサーバーに転送
3. デバイスグラフクエリ: サーバーが Singular デバイスグラフからデバイス詳細を取得または更新
4. Event API 呼び出し: サーバーが __ADMON_USER_LEVEL_REVENUE__ イベントを Singular REST API エンドポイントに送信

重要な要件

API エンドポイントの選択

Singular は、さまざまな連携アーキテクチャに最適化された 2 つの EVENT エンドポイントバージョンを提供しています。

Event Endpoint V1

V1 のユースケース

プラットフォーム固有のデバイス識別子（IDFA、IDFV、AIFA、ASID など）に依存する連携には、Event Endpoint V1 を使用してください。

推奨対象:

• 完全なサーバーサイド: Singular SDK を実装しないサーバーサイド連携
• ハイブリッド（非 SDID）: Singular SDK が Singular Device ID（SDID）を使用しないハイブリッド連携

エンドポイント URL:

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

Event Endpoint V2

V2 のユースケース

Singular SDK が SDID を使用してセッションをトラッキングし、サーバーが同じ SDID を使用してイベントを送信するハイブリッド連携には、Event Endpoint V2 を使用してください。

推奨対象:

• ハイブリッド（SDID ベース）: Singular SDK が SDID でセッションをトラッキングし、サーバーサイドのイベントが同じ SDID を使用する場合
• 識別子の簡素化: プラットフォーム固有のデバイス識別子（IDFA、AIFA など）を使用しない実装

エンドポイント URL:

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

必須のデバイス識別子

デバイス識別子の要件は、エンドポイントのバージョンとプラットフォームによって異なります。以下のプラットフォーム固有の要件をご確認ください。

V1 エンドポイントの識別子

プラットフォーム固有の識別子

Event Endpoint V1 では、デバイスのオペレーティングシステムとアプリの配信方法に基づいた、プラットフォーム固有の広告識別子が必要です。

これらは共有される S2S パラメーターであり、 S2S Fundamentals で一度だけ定義されています。

V2 エンドポイントの識別子

SDID のみの要件

Event Endpoint V2 では、すべてのプラットフォームで Singular Device ID（SDID）のみが必要となり、デバイス識別が簡素化されます。

必須パラメーター

すべての EVENT リクエストには、デバイス識別子に加えて、これらの必須パラメーターを含める必要があります。

API 認証

これらは共有される S2S パラメーターであり、 S2S Fundamentals で一度だけ定義されています。

デバイスパラメーター

これらは共有される S2S パラメーターであり、 S2S Fundamentals で一度だけ定義されています。

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

これらは共有される S2S パラメーターであり、 S2S Fundamentals で一度だけ定義されています。

イベントパラメーター

__ADMON_USER_LEVEL_REVENUE__

{
  "ad_platform": "AdMob",
  "ad_mediation_platform": "admob.AdMobAdapter",
  "ad_unit_id": "ca-app-pub-6325336052/44923540"
}

%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%5C%2F44923540%22%7D

任意パラメーター

任意パラメーターは、追加のコンテキストと機能によって広告収益トラッキングを強化します。

ネットワークパラメーター

これらは共有される S2S パラメーターであり、 S2S Fundamentals で一度だけ定義されています。

データプライバシー

これらは共有される S2S パラメーターであり、 S2S Fundamentals で一度だけ定義されています。

クロスデバイスサポート

これらは共有される S2S パラメーターであり、 S2S Fundamentals で一度だけ定義されています。

リクエスト例

サンプルコードは、複数のプログラミング言語にわたる広告収益 EVENT エンドポイント連携を示しています。

import requests

params = {
    'a': 'sdk_key_here',
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'n': '__ADMON_USER_LEVEL_REVENUE__',
    'e': '{"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}',
    'is_admon_revenue': 'true',
    'is_revenue_event': 'true',
    'amt': 0.00782,
    'cur': 'USD'
}

response = requests.get('https://s2s.singular.net/api/v1/evt', params=params)
print(response.json())

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=sdk_key_here" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.singular.app" \
  --data-urlencode "ip=10.1.2.3" \
  --data-urlencode "ve=9.2" \
  --data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "n=__ADMON_USER_LEVEL_REVENUE__" \
  --data-urlencode 'e={"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}' \
  --data-urlencode "is_admon_revenue=true" \
  --data-urlencode "is_revenue_event=true" \
  --data-urlencode "amt=0.00782" \
  --data-urlencode "cur=USD"

GET /api/v1/evt
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &n=__ADMON_USER_LEVEL_REVENUE__
    &e=%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%2F44923540%22%7D
    &is_admon_revenue=true
    &is_revenue_event=true
    &amt=0.00782
    &cur=USD HTTP/1.1
Host: s2s.singular.net
Accept: application/json

// Base URL
String baseUrl = "https://s2s.singular.net/api/v1/evt";

// Parameters
Map<String, String> params = new HashMap<>();
params.put("a", "sdk_key_here");
params.put("p", "Android");
params.put("i", "com.singular.app");
params.put("ip", "10.1.2.3");
params.put("ve", "9.2");
params.put("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "__ADMON_USER_LEVEL_REVENUE__");
params.put("e", "{\"ad_platform\":\"AdMob\",\"ad_mediation_platform\":\"admob.AdMobAdapter\",\"ad_unit_id\":\"ca-app-pub-6325336052/44923540\"}");
params.put("is_admon_revenue", "true");
params.put("is_revenue_event", "true");
params.put("amt", "0.00782");
params.put("cur", "USD");

// Build URL with encoded parameters
StringBuilder urlBuilder = new StringBuilder(baseUrl);
urlBuilder.append('?');

for (Map.Entry<String, String> entry : params.entrySet()) {
    if (urlBuilder.length() > baseUrl.length() + 1) {
        urlBuilder.append('&');
    }
    urlBuilder.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
        .append('=')
        .append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}

// Create connection
URL url = new URL(urlBuilder.toString());
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Accept", "application/json");

// Get response
int responseCode = conn.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(conn.getInputStream())
);

String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();

// Check status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());

// Disconnect
conn.disconnect();

レスポンスコードとエラー

EVENT エンドポイントは、リクエストの成功または失敗を示す HTTP ステータスコードと JSON レスポンスを返します。

エラーに関する完全なドキュメント: S2S Response Codes & Error Handling

テストと検証

本番デプロイの前に、Singular SDK Console を使用してリアルタイムのデータ検証を行い、S2S 広告収益連携を確認してください。

テスト手順

エンドツーエンド検証

1. テストデバイスの登録: デバイスの広告 ID を取得し、 Singular SDK Console に追加します
2. コンソールロギングの有効化: SDK Console にデバイス識別子を追加してテストデータをキャプチャします
3. 開発用アプリ ID の使用: アプリ識別子を開発版（例: com.singular.app.dev ）で上書きし、テストデータを本番データと分離します
4. ビルドと起動: 終了状態からアプリをビルドまたは起動します
5. クライアントデータの検証: アプリが必要なすべての Singular データポイントをサーバーに送信していることを確認します
6. セッションの確認: サーバーが必要なすべてのパラメーターとともに SESSION リクエストを https://s2s.singular.net/api/v1/launch に送信していることを確認します
7. SDK Console の確認（セッション）: 数秒以内に SESSION イベントが SDK Console に表示されるはずです

広告収益イベントのテスト

1. 広告インプレッションのトリガー: アプリ内で広告インプレッションを生成し、メディエーションプラットフォームのコールバックを発火させます
2. メディエーションデータの検証: インプレッションデータが、必要なすべてのメディエーションプラットフォーム属性とともにサーバーに送信されていることを確認します
3. サーバーリクエストの確認: サーバーが必要なすべてのパラメーターとともに EVENT リクエストを https://s2s.singular.net/api/v1/evt に送信していることを確認します
4. SDK Console の確認（イベント）: 数秒以内に __ADMON_USER_LEVEL_REVENUE__ イベントが SDK Console に表示されるはずです
5. テストの繰り返し: すべての広告インプレッションが、期待される値と正しい収益金額で送信されていることを検証します

その他のリソース

テストドキュメント

包括的なテストガイド: S2S Integration Testing Guide