ドキュメント

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

サーバー間の使用例

SingularはEVENT APIを使って広告収入をトラッキングすることができます。お客様のメディエーションプラットフォームから、有料イベントハンドラを使用してお客様のサーバーにインプレッションレベルの収益詳細を転送することで、Singularはこのデータを処理し、レポート、エクスポートログ、ポストバックへのシームレスな統合を実現します。このプラットフォームはまた、お客様の組織のお好みの設定に合わせた自動通貨変換もサポートします。

Singular REST APIは、SDKの代わりにサーバー間の直接統合を可能にします。SDKは自動的にデバイスとアプリのデータを収集しますが、S2Sアプローチでは以下の作業が必要です：

アプリから必要なEVENT APIデータポイントを収集する。
関連するメディエーション・プラットフォームのデータポイントを収集する
このデータをサーバーに転送する。
REST API経由で'__ADMON_USER_LEVEL_REVENUE__'イベントをSingularに送信する。

キーポイント

柔軟性：データの収集と送信を完全にコントロール
機能の同等性：適切なデータが提供されれば、すべてのSDK機能をサポートします。
統合パス：クライアント → お客様のサーバー → Singular API
リアルタイム処理：一度に1つのリクエスト、バッチ処理なし
シーケンシャルなデータフロー：イベントは時系列に処理される
データの重複排除： Singularは受信データを重複排除しない。成功したリクエストを1つ送信し、リクエストが再生される場合に備えてログを保存しておくことを推奨する。
データの検証： デバイスレベルのデータは永続的であり、一度取り込まれると削除できません。データをSingularに送信する前に、正確性を確保するために徹底したデータ検証を実施してください。

前提条件

イベントトラッキングを受信する前にセッションを確立する必要があります。
セッションの順序が無効な場合、データに矛盾が生じます。
Mediation SDKからMediation Platformのデータ属性を直接収集します。実装の詳細と必要なデータポイントについては、SDKガイドとプラットフォーム固有のMediationドキュメントを参照してください。

はじめに

EVENTエンドポイントのドキュメントを参照してください：

必須パラメータ
オプションのパラメータ
リクエスト例
レスポンスコードとエラー
イベントのテスト

このサーバーサイドのアプローチは、すべてのSDK機能を維持しながら、統合をよりコントロールすることができます。

イベント API エンドポイント

HTTPメソッドとイベントエンドポイント

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

必須パラメータ

以下の表は、Event API 経由で広告収益イベントを送信するために必要なパラメータの一覧です。これらのパラメータは、クエリパラメータとして含める必要があります。

GET /api/v1/evt?param1=value1&param2=value2

すべての必須パラメータは、EVENT API リクエストに含める必要があります。
パラメータは、指定された形式とデータ型に従う必要があります。

必須パラメータ
APIキー
パラメータ	説明
`a`	`string` aパラメータはSingular SDK Keyを指定する。 SDKキーはSingular UIのメインメニューのDeveloper Toolsから取得してください。注意：データが拒否されるため、レポートAPIキーは使用しないでください。値の例 `sdkKey_afdadsf7asf56`
デバイス識別子パラメータ
パラメータ	説明
`idfa` サポートされているプラットフォーム iOS	`string` idfaパラメータはIDFA（Identifier for Advertisers）を指定します。IDFAは広告主がユーザーのアクション（広告のクリックやアプリのインストールなど）を追跡し、特定のキャンペーンに関連付けるのに役立ち、正確な広告ターゲティングとキャンペーンの最適化を可能にします。 iOS 14.5からは、アプリがIDFAにアクセスする前に、App Tracking Transparency（ATT）フレームワークを介してユーザーがオプトインする必要があります。ユーザーがIDFAにオプトインしない場合、IDFAは利用できなくなり、トラッキング機能が制限されます。 IDFAが利用できない場合は、リクエストからパラメータを省略してください。リクエストにNULLや空文字列を渡さないでください。 IDFA 識別子の取得方法値の例 `DFC5A647-9043-4699-B2A5-76F03A97064B`
パラメータ	説明
`idfv` サポートされているプラットフォーム iOS	`string` idfvパラメータはIdentifier for Vendors (IDFV)を指定します。IDFVはAppleがデバイスに割り当てる一意の識別子で、特定のベンダーまたはデベロッパーに固有のものです。これは、特定のベンダーまたはデベロッパーに固有のもので、特定のデバイス上の同じベンダーのすべてのアプリ間で一貫性を保ち、ベンダーがユーザーを個人的に特定することなく、そのアプリのエコシステム全体でユーザーの行動やインタラクションを追跡できるようにします。 IDFVは、ATTステータスやIDFAの有無にかかわらず、すべてのリクエストで要求されます。 IDFV識別子の取得方法値の例 `21DB6612-09B3-4ECC-84AC-B353B0AF1334`
パラメータ	説明
`aifa` サポートされているプラットフォームアンドロイド (グーグルプレイデバイス)	`string` aifaパラメータはGoogle Advertising Identifier (GAID)を指定し、AIFA in SingularまたはAndroid Advertising ID (AAID)とも呼ばれる。この識別子は、Android端末に割り当てられた一意のユーザーリセット可能な識別子です。これにより、広告主やアプリ開発者は、アプリ全体のユーザーアクション（広告のクリックやアプリのインストールなど）を追跡して特定のキャンペーンに関連付けることができ、ユーザーのプライバシーを維持しながら、正確な広告ターゲティングとキャンペーンの最適化が可能になります。 AIFAが利用できない場合は、リクエストからパラメータを省略します。 Google Playデバイスでのみ必要です。 Google Play以外の端末ではパラメータを省略してください。リクエストにNULLまたは空文字列を渡さないでください。 AIFA識別子の取得方法値の例 `8ecd7512-2864-440c-93f3-a3cabe62525b`
パラメータ	説明
`asid` サポートされているプラットフォームアンドロイド (グーグルプレイデバイス)	`string` asidパラメータは、AndroidアプリセットIDを指定します。ASIDは、開発者がプライバシーに配慮した方法で自社のアプリ全体のユーザーを追跡する方法を提供します。特に分析や不正防止に役立ちますが、パーソナライズ広告や計測などの広告目的には使用できません。 ASIDは、GAID/AIFAの有無にかかわらず、Google Playデバイスに対するすべてのリクエストで必要です。 Google Play以外の端末ではパラメータを省略してください。リクエストにNULLまたは空文字列を渡さないでください。 ASID識別子の取得方法値の例 `edee92a2-7b2f-45f4-a509-840f170fc6d9`
パラメータ	説明
`amid` サポートされているプラットフォームアンドロイド (グーグルプレイサービスなしのアマゾンデバイス)	`string` amidパラメータは、Advertising IDがユーザーのプライバシー保護に役立つユーザーリセット可能な一意の識別子であることを指定します。インタレストベースの広告を表示するため、または分析を生成するためにユーザーの行動に関する情報を収集する場合は、Advertising IDを使用する必要があります。ユーザーは、Advertising IDをリセットしたり、インタレストベース広告をオプトアウトすることができます。 AMIDは、Google PlayサービスのないAmazonデバイスのすべてのリクエストで必須です。 AMIDを使用できない場合は、パラメータを省略します。リクエストにNULLまたは空の文字列を渡さないでください。 AMID識別子の取得方法値の例 `df07c7dc-cea7-4a89-b328-810ff5acb15d`
パラメータ	説明
`oaid` サポートされているプラットフォームアンドロイド (グーグルプレイサービスのない中国製デバイス)	`string` oaidパラメータは、Open Advertising Identifier（OAID）を指定します。OAIDは、特に中国で製造されたAndroidデバイスの広告目的で使用される一意の匿名識別子です。中国市場など、Google Playサービスが利用できない、またはサポートされていない端末のために、Googleの広告ID（GAID）の代替としてMobile Security Alliance（MSA）によって導入されました。 OAIDは主に、Google Playサービスが制限されている環境における広告のアトリビューションやユーザー追跡のために使用され、広告主や開発者は匿名性を維持しながらユーザーの行動を追跡することができます。 OAIDは、ファーウェイやシャオミなどのブランドを含む、ほとんどの中国製アンドロイド端末で利用できる。MSA SDKまたはHuawei Mobile Services（HMS）を使用してアクセスできる。 OAID は、Google Play Services を使用していない中国製の Android デバイスで必要です。 OAIDが利用できない場合は、パラメータを省略してください。リクエストにNULLまたは空文字列を渡さないでください。 OAID識別子の取得方法値の例 `01234567-89abc-defe-dcba-987654321012`
パラメータ	説明
`andi` サポートされているプラットフォームアンドロイド (非Google Playデバイス）	`string` andiパラメータは、Android IDを指定します。Android IDは、デバイスが最初にセットアップされたときにAndroidオペレーティングシステムによって生成される一意の64ビット識別子です。これは、デバイスのライフタイムを通じて永続的であるように設計されていますが、工場出荷時のリセットなどの特定の条件下でリセットすることができます。 Android IDは各デバイスに固有で、Android 8.0（Oreo）からはアプリごと、ユーザーごとにスコープされるようになった。つまり、同じデバイス上の異なるアプリは、同じ署名キーを共有しない限り、異なるAndroid IDを受け取ることになります。 Android IDは、デバイスがファクトリーリセットされない限り、またはOTA（無線）アップデート後にアプリがアンインストールされ再インストールされない限り、一定に保たれます。 ANDIは、Google Playデバイスでの使用が禁止されています。上記のAIFAおよびASID識別子を使用してください。他の識別子が使用できず、アプリがGoogle Playストアでホストされていない場合に限り、ANDIをSingularに送信できます。他の識別子が使用可能な場合は、パラメータを省略してください。リクエストにNULLまたは空文字列を渡さないでください。 ANDI識別子の取得方法値の例 `fc8d449516de0dfb`
デバイスパラメータ
パラメータ	説明
`p`	`string` pパラメータはアプリのプラットフォームを指定する。以下のリストには、大文字と小文字を区別するパラメータ値が含まれています： Android iOS 値の例 `Android`
パラメータ	説明
`ip`	`string` ipパラメータは、デバイスのパブリック (IPV4) IP アドレスを指定する。IPV6 はサポートされていません。値の例 `172.58.29.235`
パラメータ	説明
`ve`	`string` veパラメータは、イベント時のデバイスの OS バージョンを指定する。値の例 `9.2`
アプリケーションパラメータ
パラメータ	説明
`i`	`string` iパラメータはアプリ識別子を指定する。大文字と小文字は区別されます： Androidの場合はパッケージ名 iOSのバンドルID 値の例 `com.singular.app`
パラメータ	説明
`att_authorization_status` サポートされているプラットフォーム iOS	`int` att_authorization_statusパラメータは、App Tracking Transparency(ATT)ステータスコードを指定する。iOS 14.5以降、IDFA識別子にアクセスするにはApp Tracking Transparency（ATT）プロンプトが必要です。注：ATTプロンプトを実装しない場合でも、ATT認可ステータスに「未定」を示す値「0」を渡す必要があります。サポートされる値は以下のとおり： 0 - 未決定。 1 - 制限、ユーザーはアプリのトラッキングを無効にしています。 2 - 拒否、ユーザーが認可を拒否。 3 - 認証済み: ユーザーが認証を許可した。例 `3`
イベントパラメータ
パラメータ	説明
`n`	`string` nパラメータは追跡されるイベントの名前を指定する。 AdMon Revenueをサポートするには、Event Nameが特定の値である必要があります。イベント名は、アンダースコア付きのすべて大文字である必要があります。以下のイベント名を使用してください： `__ADMON_USER_LEVEL_REVENUE__`
パラメータ	説明
`e`	`JSON URL-encoded string` eパラメータは、JSON形式のカスタム・イベント属性を指定します。必須属性は「ad_platform」のみです。その他の属性はオプションです。指定できる属性は以下のとおりです： ad_platform・・・必須広告プラットフォーム広告タイプ広告グループタイプ広告インプレッションID プレースメント名広告ユニット名広告ユニット名広告グループID グループ名広告グループ優先度 ad_placement_id（プレースメントID 注：値のない属性は省略する。 `{ "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`
パラメータ	説明
`is_admon_revenue`	`string` is_admon_revenueパラメータは、イベントが広告収益イベントであり、広告収益メトリクスに使用されるべきかどうかを指定する。このイベントには'true'を渡す。値の例 `true`
パラメータ	説明
`is_revenue_event`	`string` is_revenue_eventパラメータは、イベントが収益イベントかどうかを指定し、Revenue Metrics に使用する。このイベントには 'true' を渡す。値の例 `true`
パラメータ	説明
`amt`	`double` amtパラメータは通貨金額を指定する。これは 'cur' パラメータと組み合わせて使用します。値の例 `0.00782`
パラメータ	説明
`cur`	`string` curパラメータでは、大文字のISO 42173 文字の通貨コードを指定します。これは、'amt' パラメータと組み合わせて使用します。値の例 `USD`

リクエスト本文

このメソッドをコールする際には、リクエスト本文を指定しないでください。リクエストは、クエリパラメータを指定して GET メソッドを使用して送信する必要があります。

リクエストの例

以下のコードサンプルは、サポートされているすべてのパラメータを表しているわけではありません。リクエストを実装する際には、上記のように必要なパラメータをすべて含めるようにし、本番インスタンスからデータを送信する前に正しい値が渡されていることを検証してください。開発およびテストには、一意のアプリケーション識別子を使用することをお勧めします。

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 application-level status

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

// Disconnect

conn.disconnect();

オプション・パラメーター

次の表は、このエンドポイントがサポートするオプション・パラメーターの一覧です。リストされているパラメータはすべてクエリ・パラメータです。

オプション・パラメータ
デバイス＆ネットワーク・パラメータ
パラメータ	説明
`use_ip`	`string` use_ipパラメータはSingularに'ip'パラメータの代わりにHTTPリクエストからIPアドレスを抽出するように指示します。この機能を使うには'true' を渡します。このパラメータを使うと、SingularがIPアドレスに基づいてデバイスをジオロケーションするのを防ぎます。オプションの 'country' パラメータには、ユーザの国コードを2文字で指定できます。このパラメータは'ip'パラメータと排他的です。ip' パラメータと一緒に使用しないでください。データ拒否を避けるためには、リクエスト時に 'ip' パラメータか 'use_ip' パラメータを指定する必要があります。値の例 `true`
パラメータ	説明
`country`	`string` countryパラメータには、イベント実行時のユーザのISO 3166-1 alpha-2 の 2 文字の国コードを含める必要がある。このパラメータは以下の場合にのみ必要である： ip' パラメータが使用できない。 ip' パラメータが使用可能な場合、国は IP アドレスから自動的に決定され、 'country' パラメータは不要である。値の例 `US`
データプライバシー
パラメータ	説明
`data_sharing_options`	`JSON URL-encoded string` data_sharing_optionsパラメータは、情報共有に対するエンドユーザの同意を指定する。設定されている場合、この値は永続化され、そのユーザのその後の 'SESSION' および 'EVENT' リクエストごとに渡される必要があります。ユーザが情報を共有することに同意した(opted-in)ことを示すには、'false'を渡す： `{"limit_data_sharing":false}` ユーザが拒否した場合は 'true' を渡す： `{"limit_data_sharing":true}` 値はURLエンコードされたJSON文字列でなければなりません。値の例 `%7B%22limit_data_sharing%22%3Atrue%7D`
クロスデバイスサポート
パラメータ	説明
`custom_user_id`	`string` custom_user_idパラメータは、内部ユーザーIDを指定します。値の例 `123456789abcd`

イベントテスト

サーバー間の統合を行った後、本番インスタンスで稼働する前にSingularがデータを受信することを確認することが重要です。詳細はテストガイドを参照してください。高レベルでは以下のステップに従う必要があります：

テストデバイスの Advertising ID を取得し、Singular SDK コンソールに ID を追加します。
Singular SDK コンソールを開き、デバイス識別子を追加してデータのキャプチャを開始します。
アプリ識別子を開発用アプリ識別子（com.singular.app.dev）でオーバーライドし、テストデータとイベントを本番データと分離します。
終了状態からアプリをビルドまたはオープンする
App Openが必要なすべてのSingularデータポイントとともにサーバーに送信されることを検証します。
サーバーが、必要なすべてのデータポイントとともに、Singular の'launch' エンドポイントに Session Notification をトリガーすることを検証します。
数秒後、Singular SDK コンソールにセッションイベントが表示されます。
アプリのイベントのトリガーに進みます。
必要なSingularデータポイントをすべて含むイベントがサーバーに送信されることを確認します。
サーバがSingular'evt'エンドポイントに必要なデータポイントを含むイベント通知をトリガーすることを確認します。
数秒後、Singular SDKコンソールにイベントが表示されます。
テストを繰り返し、すべてのイベントが期待通りに、期待通りの値で送信されていることを確認します。

重要な検証

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

SDKコンソールにイベントが表示されれば、イベント処理のエンドツーエンドのテストは完了です！

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

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

サーバー間の使用例

キーポイント

前提条件

はじめに

イベント API エンドポイント

必須パラメータ

リクエスト本文

リクエストの例

PYTHON

CURL

HTTP

JAVA 例

オプション・パラメーター

イベントテスト