ドキュメント

EVENTエンドポイントAPIリファレンス

SingularのREST APIを使用して、アトリビューション分析とキャンペーン最適化のためにアプリ内イベントと収益をトラッキングします。

概要

サーバー間の使用例

EVENT APIはアプリ内イベントトラッキングを可能にし、アプリはユーザーインタラクションデータをお客様のバックエンドに転送し、バックエンドはイベントアトリビューションと収益分析レポートのためにSingularのサーバーに送信します。

サポートされる機能

イベントアトリビューションユーザーアクションをマーケティングキャンペーンに接続
収益トラッキング：アプリ内課金やトランザクションの測定とアトリビューション
カスタムイベント：登録からレベル完了まで、あらゆるユーザーインタラクションをトラッキング
イベントプロパティ：より詳細な分析のためにイベントにコンテキストデータを添付

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

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

クライアント収集：アプリがイベントデータとデバイス識別子を収集
サーバー送信：アプリがイベントデータをバックエンドサーバーに転送
デバイスグラフ照会：サーバーはSingularデバイスグラフからデバイスの詳細を取得または更新します。
イベントAPIコール：サーバーがSingular REST APIエンドポイントにイベントを送信

Event Data Flow Diagram

重要な要件

前提条件

イベントの前のセッション：イベントトラッキングの前にセッションが確立されていること。
順序：セッションの順序が無効な場合、データの不整合やアトリビューションエラーが発生します。

統合の制約

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

イベントトラッキングのガイドライン

イベントトラッキングはSingularの命名規則とデータ構造のベストプラクティスに従って実装してください。

イベントの定義

S2S統合を実施する前に、キャンペーンパフォーマンス分析のために追跡したいイベントの完全なリストを定義してください。

イベント計画ガイド：アプリ内イベントの定義

イベント名の影響：Singularに渡されるイベント名は、レポート、エクスポート、ポストバックでのイベントの表示方法を直接決定します。

標準的なイベント名

ベストプラクティス

標準イベント：パートナーとの統合マッピングを合理化するために、Singularの標準イベント命名規則を使用してください。
英語：サードパーティのパートナーや分析ソリューションとの互換性を保つために、イベント名を英語で渡します。
標準属性：イベントプロパティに標準イベント属性名を使用

文字数の制限

長さの制限：

イベント名：最大 32 ASCII 文字（非 ASCII の場合、UTF-8 に変換すると 32 バイト）。
イベント属性：属性のキーと値ごとに最大500 ASCII文字

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端末では使用禁止。他に利用可能な識別子がなく、アプリがGoogle Play経由で配布されていない場合にのみ使用します。 ANDIの取得例 `fc8d449516de0dfb`
`sdid`	ウェブ、PC、コンソール、CTV	ネイティブ広告識別子のないプラットフォーム用の単一デバイスID。ウェブ：Singular Web SDKから取得 PC/コンソール：固有のアプリインストールを表すクライアント生成UUIDv4 SDIDを取得例：`40009df0-d618-4d81-9da1-cbb3337b8dec`
`sing`	エンタープライズのみ	標準的な識別子が利用できない特殊なユースケースのためのクライアント定義の識別子。制限あり：アプリケーションごとにSingular Solution Engineerが有効にする必要があります。例：`da534a95-1b1b-47d4-94b6-07955ec85177`

V2エンドポイント識別子

SDIDのみの要件

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

パラメータ説明

sdid

プラットフォーム：iOS、Android、Web、PC、Xbox、PlayStation、任天堂、MetaQuest、CTV

Singular SDKから取得したSingular Device ID、またはPC/コンソール/CTV用にクライアントサイドで生成したSingular Device ID。

iOS/Android：SDIDの使用にはアカウントの有効化が必要-SDKのコールバックメソッドが初期化後にSDIDを提供
識別子の簡素化：AIFA、ASID、IDFA、IDFVパラメータが不要。
ウェブ：Singular Web SDKから取得
PC/コンソール/CTV：クライアントが生成したUUIDv4で一意のアプリをインストール
SDIDの取得

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

必須パラメータ

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

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

API認証

パラメータタイプ説明

a

string

API 認証用の単一 SDK キー。

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

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

例 sdkKey_afdadsf7asf56

デバイスパラメータ

パラメータ	説明
`p`	アプリケーションのプラットフォーム（大文字と小文字は区別されます）。許可される値：Android、iOS、ウェブ、PC、Xbox、プレイステーション、任天堂、メタクエスト、CTV 例 `Android`
`ip`	デバイスのパブリックIPv4 IPアドレス。IPv6がサポートされていますが、属性互換性のためにIPv4を推奨します。例 `172.58.29.235`
`ve`	イベント発生時のデバイスのOSバージョン。例 `9.2`
`ma` iOS、Android	デバイスのメーカー名。`mo`(モデル) と共に使用する必要があります。デバイスメーカーを取得例 `Samsung` `LG`,`Apple`
`mo` iOS、Android	デバイスモデル。`ma` (make)と一緒に使用する必要があります。デバイスモデルの取得例 `iPhone 4S` `Galaxy SIII`
`lc` iOS、Android	IETFロケールタグ-アンダースコアで区切られた2文字の言語と国コード。デバイスロケールの取得例 `en_US`
`bd` iOS、Android	URLエンコードされたデバイスビルド識別子。デバイスビルドの取得例 `Build%2F13D15`

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

パラメータ説明

i

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

Android：パッケージ名 (例:com.singular.app)
iOS：バンドルID (例:com.singular.app)
ウェブ：プロダクトID
PC/コンソール/CTV：お客様指定の識別子

例 com.singular.app

att_authorization_status
iOS

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

ステータスの値

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

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

例 3

イベントパラメータ

パラメータ	説明
`n`	追跡されるイベントの名前。最大32 ASCII文字（UTF-8の場合は32バイト）推奨標準のイベント命名規則を使用する。例 `sng_add_to_cart`

オプションのパラメータ

オプショナルパラメータは、イベントトラッキングに追加のコンテキストと機能を追加します。

タイムスタンプパラメータ

パラメータタイプ説明

utime

int

イベントの10桁のUnixタイムスタンプ。

例 1483228800

umilisec

int

ミリ秒を含む13桁のUnixタイムスタンプ。

例 1483228800000

イベント属性

パラメータ説明

e

カスタムイベント属性を指定するJSON URLエンコード文字列。

JSON構造：

{
  "sng_attr_content_id": 5581,
  "sng_attr_content": "XBox",
  "sng_attr_content_type": "electronics"
}

推奨：標準的な属性の命名規則を使用
属性のキーと値ごとに最大500 ASCII文字

URLエンコード例：

%7B%22sng_attr_content_id%22%3A5581%2C%22sng_attr_content%22%3A%22XBox%22%2C%22sng_attr_content_type%22%3A%22electronics%22%7D

global_properties

イベントにグローバルに適用されるカスタムキーと値のペアを含むJSON URLエンコードオブジェクト。

制限：

最大5つのキーと値のペア
1つのキーと値につき最大200文字

JSON: {"key1":"value1","key2":"value2"}

URLエンコード： %7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D

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

パラメータ説明

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

SKAdNetworkサポート

パラメータ説明

skan_conversion_value
iOS

イベント時の最新のSKAdNetwork変換値。

詳細:SKAdNetworkの実装

例 7

skan_first_call_timestamp
iOS

SKAdNetwork APIを最初にコールしたUnixタイムスタンプ。

例 1483228800

skan_last_call_timestamp
iOS

イベント発生時にSKAdNetwork APIを呼び出した直近のUnixタイムスタンプ。

例 1483228800

収益トラッキング

アプリ内課金と収益イベントをトラッキングし、適切なバリデーションと通貨処理を行います。

必要な収益パラメータ

基本的な収益トラッキング

独自の収益検証を行う際の収益イベントトラッキングに最低限必要なパラメータです。

ベストプラクティスイベントリクエストをSingularに送信する前に、サーバー側でApp Storeの収益イベントを検証してください。独自の検証を行う場合は、これらのパラメータのみが必要です。

パラメータタイプ説明

is_revenue_event

string

イベントが収益イベントであるかどうかを指定します。

イベント名が__iap__またはamt の場合は省略可能。

例 true

amt

double

トランザクションの通貨金額。

cur パラメータと組み合わせて使用する。

例 2.51

cur

string

ISO 4217 の3 文字大文字の通貨コード。

amt パラメータと組み合わせて使用します。

例 USD

収益検証パラメータ

Singularで検証された収益

SingularがApp Storeでサーバーサイドの収益検証を行うためのオプションのパラメータです。

バリデーションの要件：

App Storeでの収益検証をSingularに依存する場合は必須です。
購入レシートと署名の値が正しい構文であることを確認します。
フォーマットが正しくない場合、Singularは収益をブロックし、__iapinvalid__ イベントを生成します。

パラメータ	説明
`purchase_receipt` iOS、Android	購入トランザクションから受け取った領収書。 Android: Google Play Billing Library Purchaseオブジェクト iOS: StoreKitアプリのレシート例（iOS）： `MIISqwYJKoZI...cNqts0jvcNvPcK7yuj0KhJ9nTTQ54kDKfReihzc6aw==` 例（Android、URLエンコード）： `%7B%22orderId%22%3A%22GPA.1234%22%2C%22packageName%22%3A%22com.example%22%2C%22productId%22%3A%22com.example.product%22...`
`receipt_signature` Android	購入レシートの署名に使用される署名（Androidのみ）。例 `TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==`
`purchase_product_id`	商品のSKU識別子。例 `com.example.product`
`purchase_transaction_id`	取引識別子。例（iOS）： `380000123004321` 例 (Android): `GPA.1234-1234-1234-12345`

リクエスト例

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

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

Pythonの例

import requests

params = {
    'a': 'sdk_key_here',
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'ma': 'samsung',
    'mo': 'SM-G935F',
    'lc': 'en_US',
    'bd': 'Build/13D15',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'n': 'sng_add_to_cart'
}

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 "ma=samsung" \
  --data-urlencode "mo=SM-G935F" \
  --data-urlencode "lc=en_US" \
  --data-urlencode "bd=Build/13D15" \
  --data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "n=sng_add_to_cart"

HTTPの例

GET /api/v1/evt
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &ma=samsung
    &mo=SM-G935F
    &lc=en_US
    &bd=Build%2F13D15
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &n=sng_add_to_cart 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("ma", "samsung");
params.put("mo", "SM-G935F");
params.put("lc", "en_US");
params.put("bd", "Build/13D15");
params.put("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "sng_add_to_cart");

// 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

イベントテスト

イベントをトリガーします：アプリでイベントをトリガーします。
イベントデータの検証：必要なすべてのSingularデータポイントを含むイベントがサーバーに送信されたことを確認します。
サーバー・リクエストを検証する：サーバーが必要なパラメータをすべて含むEVENTリクエストをhttps://s2s.singular.net/api/v1/evt。
SDKコンソール（イベント）を確認します：数秒以内にSDKコンソールにEVENTが表示されます。
テストを繰り返します：期待される値で送信されたすべてのイベントを検証します。

SDK Console Event

重要な検証：

EVENTを受信する前に、アプリのオープン/フォアグラウンドでSESSIONイベントが発生することを確認する。
EVENTの必要データポイントがSESSIONのデータポイントと一致することを確認する。

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

その他のリソース

テストドキュメント

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

サーバー間 - EVENT エンドポイント API リファレンス

EVENTエンドポイントAPIリファレンス

概要

サーバー間の使用例

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

重要な要件

イベントトラッキングのガイドライン

イベントの定義

イベントの定義

標準的なイベント名

文字数の制限

APIエンドポイントの選択

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

V1 の使用例

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

V2の使用例

必要なデバイス識別子

V1 エンドポイント識別子

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

V2エンドポイント識別子

SDIDのみの要件

必須パラメータ

API認証

デバイスパラメータ

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

イベントパラメータ

オプションのパラメータ

タイムスタンプパラメータ

イベント属性

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

データプライバシー

クロスデバイス対応

SKAdNetworkサポート

収益トラッキング

必要な収益パラメータ

基本的な収益トラッキング

収益検証パラメータ

Singularで検証された収益

リクエスト例

Pythonの例

cURLの例

HTTPの例

Javaの例

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

テストと検証

テスト手順

エンドツーエンドの検証

イベントテスト

その他のリソース

テストドキュメント