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

Singular の REST API を使用してサーバー間連携でアプリ内イベントと収益を追跡し、 SDK 実装の代替手段としてアトリビューション分析とキャンペーン最適化に活用します。

概要

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

EVENT API はアプリ内イベントの追跡を可能にします。アプリはユーザーの操作データを バックエンドに転送し、バックエンドがそれを Singular のサーバーに送信することで、 イベントアトリビューションと収益分析のレポーティングを実現します。

サポートされる機能:

• イベントアトリビューション: ユーザーのアクションをマーケティング キャンペーンに関連付けます
• 収益追跡: アプリ内課金やトランザクションを測定し、アトリビューションします
• カスタムイベント: 登録からレベルクリアまで、あらゆるユーザー操作を 追跡します
• イベントプロパティ: より詳細な分析のために、イベントにコンテキスト データを付加します

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

サーバー間連携によるイベント追跡は、4 ステップのデータ送信プロセスに従います。

1. クライアントでの収集: アプリがイベントデータとデバイス識別子を 収集します
2. サーバーへの送信: アプリがイベントデータを自社のバックエンド サーバーに転送します
3. デバイスグラフの照会: サーバーが Singular のデバイスグラフから デバイス詳細を取得または更新します
4. Event API 呼び出し: サーバーが Singular の REST API エンドポイントにイベントを送信します

重要な要件

イベント追跡のガイドライン

命名規則とデータ構造に関する Singular のベストプラクティスに従って、イベント追跡を 実装します。

イベントの定義

イベントの定義

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

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

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

標準イベントの命名

文字数の制限

API エンドポイントの選択

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

Event エンドポイント V1

V1 のユースケース

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

推奨される用途:

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

エンドポイント URL:

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

Event エンドポイント V2

V2 のユースケース

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

推奨される用途:

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

エンドポイント URL:

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

Web (p=Web) バリアント

Web 連携では、この同じ EVENT エンドポイントを p=Web と共に使用します。Web の SESSION 呼び出しはありません。 conversion_event=true を伴う最初の __PAGE_VISIT__ イベントが、起動の代わりにアトリビューションの タッチポイントを確立します。

Web 固有のパラメーター

これらのパラメーターは p=Web の場合に適用されます。共有パラメーター ( a , i , ip , sdid , custom_user_id ) は S2S の基礎 で定義されています。

Web クリック ID: パートナーのクリック ID ( ScCid , ttclid , gclid / gbraid / wbraid , dclid , fbclid , rdt_uuid ) を、イベントの e パラメーター内で渡します。

必須のデバイス識別子

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

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

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

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

これらは S2S の基礎 で一度だけ定義されている共有 S2S パラメーターです。

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

SDID のみの要件

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

必須パラメーター

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

API 認証

これらは S2S の基礎 で一度だけ定義されている共有 S2S パラメーターです。

デバイスパラメーター

これらは S2S の基礎 で一度だけ定義されている共有 S2S パラメーターです。

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

これらは S2S の基礎 で一度だけ定義されている共有 S2S パラメーターです。

イベントパラメーター

オプションパラメーター

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

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

イベント属性

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

%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

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

これらは S2S の基礎 で一度だけ定義されている共有 S2S パラメーターです。

データプライバシー

これらは S2S の基礎 で一度だけ定義されている共有 S2S パラメーターです。

クロスデバイスサポート

これらは S2S の基礎 で一度だけ定義されている共有 S2S パラメーターです。

SKAdNetwork サポート

収益追跡

適切な検証と通貨処理により、アプリ内課金と収益イベントを追跡します。

必須の収益パラメーター

基本的な収益追跡

自社で収益の検証を行う場合の、収益イベント追跡に最低限必要なパラメーター。

収益検証パラメーター

Singular による収益検証

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

MIISqwYJKoZI...cNqts0jvcNvPcK7yuj0KhJ9nTTQ54kDKfReihzc6aw==

%7B%22orderId%22%3A%22GPA.1234%22%2C%22packageName%22%3A%22com.example%22%2C%22productId%22%3A%22com.example.product%22...

TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==

リクエストの例

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

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

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

// 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 コンソールを使用してリアルタイムでの データ検証を行い、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 コンソールの確認（セッション）: 数秒以内に、SESSION イベントが SDK コンソールに表示されるはずです

イベントのテスト

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

追加リソース

テストに関するドキュメント

包括的なテストガイド: S2S 連携テストガイド