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

フォローする
Avatar
Jared Ornstead
Updated
ドキュメント

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

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

概要

サーバー間の使用例

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

サポートされる機能

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

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

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

  1. クライアント収集：アプリがイベントデータとデバイス識別子を収集
  2. サーバー送信：アプリがイベントデータをバックエンドサーバーに転送
  3. デバイスグラフ照会：サーバーはSingularデバイスグラフからデバイスの詳細を取得または更新します。
  4. イベント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の有無にかかわらず、必ず含める必要があります。

例：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デバイスに含める必要があります。

例：edee92a2-7b2f-45f4-a509-840f170fc6d9
amid アンドロイド
(アマゾン)

Google Playサービスを利用していないAmazon Fire端末用のAmazon Advertising ID。

例：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経由で配布されていない場合にのみ使用します。

例 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

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

パラメータ 説明
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

追跡されるイベントの名前。

例 sng_add_to_cart

オプション・パラメータ

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

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

パラメータ タイプ 説明
utime int

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

例 1483228800

umilisec int

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

例 1483228800000

ma
iOS、Android 		string

デバイスのメーカー名。mo(モデル) と共に使用する必要があります。

デバイスメーカーを取得

例 Samsung LG,Apple
mo
iOS、Android 		string

デバイスモデル。ma (make)と一緒に使用する必要があります。

デバイスモデルの取得

例 iPhone 4S Galaxy SIII
lc
iOS、Android 		string

IETFロケールタグ-アンダースコアで区切られた2文字の言語と国コード。

デバイスロケールの取得

例 en_US

bd
iOS、Android 		string

URLエンコードされたデバイスビルド識別子。

デバイスビルドの取得

例 Build%2F13D15

イベント属性

パラメータ 説明
e

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

JSON構造： 

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

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

購入トランザクションから受け取った領収書。

例（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 （アプリ識別子）を使用してください。

PYTHONCURLHTTPJAVA

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())

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

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

完全なエラードキュメント:S2S レスポンスコードとエラー処理

テストと検証

リアルタイムのデータ検証のために、Singular SDK Consoleを使用して、本番展開前にS2Sイベント統合を検証します。

テスト手順

エンドツーエンドの検証

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

SDK Console Session Event

イベントテスト

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

SDK Console Event

重要な検証：

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

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

その他のリソース

テストドキュメント

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