ドキュメント

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

SingularのREST APIを使用してインプレッションレベルの広告収益をトラッキングし、アトリビューション分析やキャンペーン最適化を行います。

概要

サーバー間の使用例

広告収益APIはインプレッションレベルの広告収益トラッキングを可能にし、アプリは収益データをメディエーションプラットフォームからお客様のバックエンドに転送し、バックエンドは広告収益分析とレポーティングのためにSingularのサーバーに転送します。

サポートされる機能

広告収益：メディエーションプラットフォームからのインプレッションレベルの収益をトラッキング
プラットフォームのアトリビューション：広告収益をユーザー獲得キャンペーンにつなげる
メディエーションの統合：主要な広告仲介プラットフォームをすべてサポート
通貨変換：組織設定に合わせた自動通貨変換

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

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

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

重要な要件

前提条件

イベントの前のセッション：広告収益をトラッキングする前にセッションを確立する必要があります。
順序：セッションの順序が無効な場合、データに矛盾が生じ、アトリビューションエラーが発生する。
Mediation Platformのデータ：Mediation SDKから必要な属性を直接収集する。

統合の制約

リアルタイム処理：リクエストは個別に処理される。
時系列イベント：イベントは発生順に送信されなければならない。
重複排除なし：Singularはデータを重複排除しません。重複を防ぐためにサーバーサイドで重複排除を実装します。
データの永続性：デバイスレベルのデータはインジェスト後に削除できない。

APIエンドポイントの選択

Singularは異なる統合アーキテクチャに最適化された2つのEVENTエンドポイントバージョンを提供します。

エンドポイントの選択：統合アーキテクチャとデバイス識別子戦略に基づいてエンドポイントを選択します。ユースケースが正しいエンドポイントを決定します。

イベントエンドポイント V1

V1 の使用例

プラットフォーム固有のデバイス識別子（IDFA、IDFV、AIFA、ASID など）に依存する統合には、イベント・エンドポイント V1 を使用します。

推奨用途

純粋なサーバーサイド：Singular SDKを実装していないサーバーサイドの統合
ハイブリッド（非SDID）：Singular SDKがSingularデバイスID（SDID）を使用しないハイブリッド統合

エンドポイントURL

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

イベントエンドポイント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

アカウントの有効化：V2エンドポイントでは、SDIDを使用するためにSingularアカウントの設定が必要です。有効化については、ソリューションエンジニアまたはCSMにお問い合わせください。

必要なデバイス識別子

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

V1 エンドポイント識別子

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

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

パラメータ	プラットフォーム	説明
`idfa`	iOS	広告主識別子（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の有無にかかわらず、必ず含める必要があります。 IDFVの取得例：`21DB6612-09B3-4ECC-84AC-B353B0AF1334`
`aifa`	アンドロイド (グーグルプレイ)	Google Advertising ID (GAID) は、ユーザーリセット可能な広告トラッキングを可能にします。 Google Play端末では必須 Google Play以外の端末では省略可 NULLまたは空文字列を渡さない AIFAの取得例: `8ecd7512-2864-440c-93f3-a3cabe62525b`
`asid`	アンドロイド (グーグルプレイ)	Android のアプリセット ID は、同じ開発者のアプリを横断的に追跡するプライバシーに配慮したものです。常に必須：GAIDの有無にかかわらず、Google Playデバイスに含める必要があります。 ASIDの取得例：`edee92a2-7b2f-45f4-a509-840f170fc6d9`
`amid`	アンドロイド (アマゾン)	Google Playサービスを利用していないAmazon Fire端末用のAmazon Advertising ID。 Amazonデバイスに必要です。 AMIDの取得例：`df07c7dc-cea7-4a89-b328-810ff5acb15d`
`oaid`	アンドロイド (中国OEM)	Google Playサービスを利用していない中国製端末用のオープン広告識別子（OAID）。 GooglePlayを利用していないHuawei、Xiaomi、OPPO、Vivoの端末に必要です。 OAIDの取得例：`01234567-89abc-defe-dcba-987654321012`
`andi`	アンドロイド (非Google Play）	Android IDは、デバイスが生成した64ビットの識別子です。使用は制限されています：他の識別子が利用できず、Google Play経由でアプリが配布されていない場合にのみ使用。 ANDIの取得例 `fc8d449516de0dfb`

V2エンドポイント識別子

SDIDのみの要件

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

パラメータ説明

sdid

プラットフォーム：iOS、Android

Singular SDKから取得した、またはクライアントサイドで生成されたSingularデバイスID。

iOS/Android：SDID使用にはアカウントの有効化が必要-SDKコールバックメソッドは初期化後にSDIDを提供
識別子の簡素化：AIFA、ASID、IDFA、IDFVパラメータの必要性を排除
SDIDの取得

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

必須パラメータ

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

パラメータの形式：すべてのパラメータは、GETメソッドを使用してURLクエリパラメータとして渡す必要があります。JSONリクエストボディにパラメータを送信しないでください。

API認証

パラメータタイプ説明

a

string

API 認証用の単一 SDK キー。

取得元Singular UI → メインメニュー →開発者ツール

重要：リクエストは拒否されます。

例 sdkKey_afdadsf7asf56

デバイスパラメータ

パラメータ説明

p

アプリケーションのプラットフォーム（大文字と小文字は区別されます）。

許可される値：Android、iOS

例 Android

ip

デバイスのパブリックIPv4 IPアドレス。IPv6をサポートするが、属性互換性のためにIPv4を推奨。

例 172.58.29.235

ve

イベント発生時のデバイスのOSバージョン。

例 9.2

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

パラメータ説明

i

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

Android：パッケージ名 (例:com.singular.app)
iOS：バンドルID (例:com.singular.app)

例 com.singular.app

att_authorization_status
iOS

App Tracking Transparency（ATT）ステータスコード（iOS 14.5+）。

ステータスの値

0 - 未決定（プロンプトが表示されない）
1 - 制限あり（デバイスレベルのトラッキングは無効
2 - 拒否（ユーザが承認を拒否）
3 - Authorized（ユーザーによる承認）

常に必要：ATTが実装されていない場合でも、0 （未確定）をパスする。

例 3

イベントパラメータ

パラメータ	説明
`n`	追跡するイベントの名前。広告収入には必須のイベント名： `__ADMON_USER_LEVEL_REVENUE__` イベント名はアンダースコア付きのすべて大文字でなければなりません。最大32 ASCII文字
`e`	メディエーション・プラットフォームからのカスタム・イベント属性を指定するJSON URLエンコード文字列。必須属性： `ad_platform` - 必須）広告ネットワーク名オプションの属性： `ad_mediation_platform` `ad_type` `ad_group_type` `ad_impression_id` `ad_placement_name` `ad_unit_id` `ad_unit_name` `ad_group_id` `ad_group_name` `ad_group_priority` `ad_placement_id` JSON構造： `{ "ad_platform": "AdMob", "ad_mediation_platform": "admob.AdMobAdapter", "ad_unit_id": "ca-app-pub-6325336052/44923540" }` URLエンコード例： `%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` 注：値のない属性は省略する。
`is_admon_revenue`	イベントが広告収益メトリクスの広告収益イベントであるかどうかを指定します。このイベントに`true` を渡します。例 `true`
`is_revenue_event`	イベントが収益メトリクスの収益イベントであるかどうかを指定します。このイベントに`true` を渡します。例 `true`
`amt`	インプレッション収益の通貨金額。 `cur` パラメータと組み合わせて使用する。例 `0.00782`
`cur`	ISO 4217の3文字の大文字の通貨コード。 `amt` パラメータと組み合わせて使用する。例 `USD`

オプションパラメータ

オプションのパラメータは、追加のコンテキストと機能で広告収益のトラッキングを強化します。

ネットワークパラメータ

パラメータ説明

use_ip

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

制限事項

Singular による IP ベースのジオロケーションを防ぎます。
country パラメータで二文字の国コードを指定
ip パラメータと排他的
ip またはuse_ipのどちらかを指定する必要があります。

例 true

country

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

必須IPアドレスが利用できないか、use_ip=true

例 US

データプライバシー

パラメータ説明

data_sharing_options

JSON URLエンコードされた、データ共有に対するエンドユーザーの同意。その後のすべてのEVENTリクエストで永続化され、渡されなければならない。

ユーザー同意（オプトイン）：

{"limit_data_sharing":false}

ユーザー拒否（オプトアウト）：

{"limit_data_sharing":true}

URLエンコード例：%7B%22limit_data_sharing%22%3Atrue%7D

クロスデバイス対応

パラメータ説明

custom_user_id

クロスデバイス追跡用の内部ユーザーID。

例 123456789abcd

リクエスト例

サンプル・コードは、複数のプログラミング言語にわたるAd Revenue EVENTエンドポイントの統合を示します。

例に関する免責事項：コードサンプルは、すべての必要なパラメータを含まない場合があります。本番実装の前に、完全なパラメータ・リストを検証してください。開発/テストには、一意のi （アプリ識別子）を使用してください。

Pythonの例

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の例

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"

HTTPの例

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

Javaの例

// 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 レスポンスコードとエラー処理

テストと検証

リアルタイムのデータ検証のために、Singular SDK Consoleを使用して、本番デプロイ前にS2S広告収益統合を検証します。

テスト手順

エンドツーエンドの検証

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

SDK Console Session Event

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

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

SDK Console Ad Revenue Event

重要な検証

SESSIONイベントがアプリのオープン/フォアグラウンドで発生し、EVENTが受信される前に発生すること。
EVENTに必要なデータポイントがSESSIONのデータポイントと一致すること
イベント引数で渡されるMediation Platformの詳細が正しいことを確認する。
正しい収益額と通貨を確認する

成功指標：SDKコンソールに広告収益イベントが表示されれば、エンドツーエンドの広告収益統合テストは成功です！

その他のリソース

テスト資料

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

サーバー間 - 広告収入のトラッキング API リファレンス

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

概要

サーバー間の使用例

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

重要な要件

APIエンドポイントの選択

イベントエンドポイント V1

V1 の使用例

イベントエンドポイントV2

V2の使用例

必要なデバイス識別子

V1 エンドポイント識別子

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

V2エンドポイント識別子

SDIDのみの要件

必須パラメータ

API認証

デバイスパラメータ

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

イベントパラメータ

オプションパラメータ

ネットワークパラメータ

データプライバシー

クロスデバイス対応

リクエスト例

Pythonの例

cURLの例

HTTPの例

Javaの例

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

テストと検証

テスト手順

エンドツーエンドの検証

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

その他のリソース

テスト資料