EVENTエンドポイントAPIリファレンス
サーバー間の使用例
EVENT APIはお客様のアプリケーションでイベントトラッキングを可能にします。お客様のアプリがデバイス固有のデータをお客様のサーバーに転送し、サーバーからSingularのサーバーに転送されると、プラットフォームはこの情報を次のように処理します:イベントアトリビューション、アプリ収益メトリクス。この処理されたデータは、お客様のレポート、エクスポートログ、設定されたポストバックに自動的に入力され、お客様のマーケティングキャンペーンに包括的な分析を提供します。
Singular REST APIは、SDKの代わりにサーバー間の直接統合を可能にします。SDKは自動的にデバイスとアプリのデータを収集しますが、S2Sアプローチでは以下のことが必要です:
- アプリから必要なデータポイントを収集
- このデータをサーバーに転送する
- デバイスグラフからデバイスの詳細を更新/取得
- REST API経由でSingularにイベントを転送する。
キーポイント
- 柔軟性:データ収集と送信を完全にコントロール
- 機能の同等性:適切なデータが提供されれば、すべてのSDK機能をサポートします。
- 統合パス:クライアント → お客様のサーバー → Singular API
- リアルタイム処理:一度に1つのリクエスト、バッチ処理なし
- シーケンシャルなデータフロー:イベントは時系列に処理される
- データの重複排除: Singularは受信データを重複排除しない。成功したリクエストを1つ送信し、リクエストが再生される場合に備えてログを保存しておくことを推奨する。
- データの検証: デバイスレベルのデータは永続的であり、一度取り込まれると削除できません。データをSingularに送信する前に、正確性を確保するために徹底したデータ検証を実施してください。
前提条件
- イベントトラッキングを受信する前にセッションを確立する必要があります。
- セッションの順序が無効な場合、データに矛盾が生じます。
はじめに
EVENT エンドポイントのドキュメントを参照してください:
このサーバーサイドのアプローチは、すべてのSDK機能を維持しながら、統合をよりコントロールすることができます。
イベントのレポート
Singularはアプリ内イベントのデータを収集し、マーケティングキャンペーンのパフォーマンス分析に役立てることができます。イベントには、ログインや登録からゲームアプリのレベルアップまで、あらゆるユーザーインタラクションが含まれます。
SDK/S2SとSingularの統合を実装する前に、貴社がトラッキングしたいイベントのリストを用意してください(アプリ内イベントの定義参照)。
呼び出しに含めるイベント名は、Singularのレポート、エクスポート、ポストバックでイベントを識別する方法です。
注意事項
- Singularでは、Singularの標準イベントと属性の命名規則を使ってイベントを渡すことを推奨しています。標準イベントを使用することで、マッピングが効率化され、統合におけるパートナーの標準イベントとの互換性が向上します。
- サードパーティのパートナーや分析ソリューションとの互換性のために、イベント名やその他の属性を英語で渡すことを強くお勧めします。
重要
- イベント名は32 ASCII文字に制限されています。非ASCII文字の場合、UTF-8に変換されると32バイトに制限されます。
- イベントの属性と値は500 ASCII文字に制限されています。
イベントAPIエンドポイント
HTTPメソッドとイベント・エンドポイント
GET https://s2s.singular.net/api/v1/evt
必須パラメータ
以下の表は、このエンドポイントがサポートする必須パラメーターの一覧です。リストされているパラメータはすべてクエリ・パラメータです。
GET /api/v1/evt?param1=value1¶m2=value2
- すべての必須パラメータは、EVENT API リクエストに含める必要があります。
- パラメータは、指定されたフォーマットとデータ型に従う必要があります。
必須パラメータ | |
---|---|
API キー | |
パラメータ | 説明 |
|
aパラメータはSingular SDK Keyを指定する。 SDKキーはSingular UIのメインメニューのDeveloper Toolsから取得してください。 注意:データが拒否されるため、レポートAPIキーは使用しないでください。 値の例
|
デバイス識別子パラメータ | |
パラメータ | 説明 |
サポートされているプラットフォーム
|
idfaパラメータはIDFA(Identifier for Advertisers)を指定します。IDFAは広告主がユーザーのアクション(広告のクリックやアプリのインストールなど)を追跡し、特定のキャンペーンに関連付けるのに役立ち、正確な広告ターゲティングとキャンペーンの最適化を可能にします。 iOS 14.5以降、アプリがIDFAにアクセスする前に、ユーザーはApp Tracking Transparency(ATT)フレームワークを介してオプトインする必要があります。ユーザーがIDFAにオプトインしない場合、IDFAは利用できなくなり、トラッキング機能が制限されます。
値の例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
idfvパラメータはIdentifier for Vendors (IDFV)を指定します。IDFVはAppleがデバイスに割り当てる一意の識別子で、特定のベンダーまたはデベロッパーに固有のものです。これは、特定のベンダーまたはデベロッパーに固有のもので、特定のデバイス上の同じベンダーのすべてのアプリ間で一貫性を維持し、ベンダーがユーザーを個人的に識別することなく、そのアプリのエコシステム全体でユーザーの行動やインタラクションを追跡できるようにします。
値の例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
aifaパラメータはGoogle Advertising Identifier (GAID)を指定し、AIFA in SingularまたはAndroid Advertising ID (AAID)とも呼ばれる。この識別子は、Android端末に割り当てられた一意のユーザーリセット可能な識別子です。これにより、広告主やアプリ開発者は、アプリ全体のユーザーアクション(広告のクリックやアプリのインストールなど)を追跡して特定のキャンペーンに関連付けることができ、ユーザーのプライバシーを維持しながら、正確な広告ターゲティングとキャンペーンの最適化が可能になります。
値の例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
asidパラメータは、AndroidアプリセットIDを指定します。ASIDは、開発者がプライバシーに配慮した方法で自社のアプリ全体のユーザーを追跡する方法を提供します。特に分析や不正防止に役立ちますが、パーソナライズ広告や計測などの広告目的には使用できません。
値の例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
amidパラメータは、Advertising IDがユーザーのプライバシー保護に役立つユーザーリセット可能な一意の識別子であることを指定します。インタレストベースの広告を表示するため、または分析を生成するためにユーザーの行動に関する情報を収集する場合は、Advertising IDを使用する必要があります。ユーザーは、Advertising IDをリセットしたり、インタレストベース広告をオプトアウトすることができます。
値の例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
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)を使用してアクセスできる。
値の例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
andiパラメータは、Android IDを指定します。Android IDは、デバイスが最初にセットアップされたときにAndroidオペレーティングシステムによって生成される一意の64ビット識別子です。これは、デバイスのライフタイムを通じて永続的であるように設計されていますが、工場出荷時のリセットなどの特定の条件下でリセットすることができます。 Android IDは各デバイスに固有で、Android 8.0(Oreo)からはアプリごと、ユーザーごとにスコープされるようになった。つまり、同じデバイス上の異なるアプリは、同じ署名キーを共有しない限り、異なるAndroid IDを受け取ることになります。 Android IDは、デバイスがファクトリーリセットされない限り、またはOTA(無線)アップデート後にアプリがアンインストールされ再インストールされない限り、一定に保たれます。
値の例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
sdidパラメータはSingular Device IDを指定する。
値の例
|
パラメータ | 説明 |
サポートされるプラットフォーム:
|
singパラメータは、Enterprise カスタマに限定され、クライアント定義の識別子を指定します。他のすべての識別子が使用できない特別な用途でのみ使用されます。この識別子はSingular Solution Engineerがアプリごとに有効にする必要があります。 値の例
|
デバイスパラメータ | |
パラメータ | 説明 |
|
pパラメータはアプリのプラットフォームを指定する。 以下のリストには、大文字と小文字を区別する パラメータ値が含まれています:
値の例
|
パラメータ | 説明 |
|
ipパラメータは、デバイスのパブリック (IPV4) IP アドレスを指定する。IPV6 はサポートされていません。 値の例
|
パラメータ | 説明 |
|
veパラメータは、イベント時のデバイスの OS バージョンを指定する。 値の例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
maパラメータは、デバイスハードウェアのMakeを指定する。このパラメータはmodelパラメータと一緒に使用する必要があります。 例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
moパラメータは、デバイスハードウェアのモデルを指定します。このパラメータはmakeパラメータと一緒に使用する必要があります。 例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
lcパラメータは、アンダースコアで区切られた2文字の言語と国コードを使用して、デバイスのIETFロケールタグを指定します。 値の例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
bdパラメータは、URLエンコードされたデバイスのBuildを指定します。 値の例
|
アプリケーション・パラメータ | |
パラメータ | 説明 |
|
iパラメータはアプリケーション識別子を指定する。 大文字と小文字を区別します :
値の例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
att_authorization_statusパラメータは、App Tracking Transparency(ATT)ステータスコードを指定します。iOS 14.5以降、IDFA識別子にアクセスするにはApp Tracking Transparency (ATT)プロンプトが必要です。 注:ATTプロンプトを実装しない場合でも、ATT認可ステータスに「未定」を示す値「0」を渡す必要があります。 サポートされる値は以下のとおり:
例
|
イベント・パラメータ | |
パラメータ | 説明 |
|
nパラメータは追跡されるイベントの名前を指定する。
値の例
|
リクエストボディ
このメソッドを呼び出すときはリクエストボディを指定しないでください。リクエストはクエリパラメータ付きのGETメソッドを使用して送信する必要があります。
リクエストの例
以下のコードサンプルは、サポートされているすべてのパラメータを表しているわけではありません。リクエストを実装する際には、上記のように必要なパラメータをすべて含めるようにし、本番インスタンスからデータを送信する前に正しい値が渡されていることを確認してください。開発とテストのために、一意な `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 application-level status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());
// Disconnect
conn.disconnect();
オプションのパラメータ
次の表は、このエンドポイントがサポートするオプション・パラメーターの一覧です。リストされているパラメータはすべてクエリ・パラメータです。
オプション・パラメータ | |
---|---|
タイムスタンプ・パラメータ | |
パラメータ | 説明 |
|
utimeパラメータは、イベントの時間を10桁のUNIX時間で指定します。
値の例
|
パラメータ | 説明 |
|
umilisecパラメータは、イベントの Time をミリ秒 13 桁 UNIX 時間で指定する。
値の例
|
デバイスとネットワークパラメータ | |
パラメータ | 説明 |
|
global_propertiesパラメータには、最大 5 つのキーと値のペアを含む URL エンコードされた JSON オブジェクトを指定します。各キーと値の長さは最大200文字です。
JSONオブジェクトは次のようにする必要があります:
値の例
|
パラメータ | 説明 |
|
use_ipパラメータは、'ip' パラメータの代わりに HTTP リクエストから IP アドレスを抽出するように Singular に指示します。この機能を使うには'true' を渡します。
値の例
|
パラメータ | 説明 |
|
countryパラメータには、イベント実行時のユーザーのISO 3166-1 alpha-2 の 2 文字の国コードを含める必要がある。このパラメータは以下の場合にのみ必要である:
値の例
|
イベントパラメータ | |
パラメータ | 説明 |
|
eパラメータは、JSON 形式のカスタムイベント属性を指定します。
値の例
|
収益パラメータ | |
パラメータ | 説明 |
|
is_revenue_eventパラメータは、イベントが収益イベントであるかどうかを指定します。
値の例
|
パラメータ | 説明 |
|
amtパラメータは通貨量を指定します。
値の例
|
パラメータ | 説明 |
|
curパラメータでは、大文字のISO 42173 文字の通貨コードを指定します。
値の例
|
パラメータ | 説明 |
対応プラットフォーム
|
purchase_receiptパラメータは、購入時に受け取ったレシートを指定します。Android、iOSでの取得方法は以下をご参照ください。
例 (iOS):
例(Android):
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
receipt_signatureパラメータは、購入レシートの署名に使用する署名を指定します。
値の例
|
パラメータ | 説明 |
|
purchase_product_idパラメータは、商品のSKU識別子を指定します。
値の例
|
パラメータ | 説明 |
|
purchase_transaction_idパラメータはトランザクション識別子を指定します。
例 (iOS):
例(Android):
|
データプライバシー | |
パラメータ | 説明 |
|
data_sharing_optionsパラメータは、情報共有に対するエンドユーザーの同意を指定します。設定されている場合、この値は永続化され、そのユーザーのその後の 'SESSION' と 'EVENT' リクエストごとに渡される必要があります。
値はURLエンコードされたJSON文字列でなければならない。
値の例
|
クロスデバイスサポート | |
パラメータ | 説明 |
|
custom_user_idパラメータは、内部ユーザーIDを指定します。
例
|
iOSのSkAdNetworkサポート | |
パラメータ | 説明 |
対応プラットフォーム
|
skan_conversion_valueパラメータは、このイベント通知の時点における最新のSKAdNetwork変換値を指定します(SKAdNetworkの実装についての詳細はこちら)。
値の例
|
パラメータ | 説明 |
対応プラットフォーム
|
skan_first_call_timestampパラメータは、基礎となるSkAdNetwork APIへの最初のコールのUnixタイムスタンプを指定します(SKAdNetworkの実装についての詳細はこちら)。
値の例
|
パラメータ | 説明 |
サポートされているプラットフォーム
|
skan_last_call_timestampパラメータは、このイベント通知時に基礎となるSkAdNetwork APIへの最新のコールのUnixタイムスタンプを指定します(SKAdNetworkの実装について詳しくはこちら)。
値の例
|
イベントテスト
サーバー間の統合を行った後、本番インスタンスで稼動する前にSingularがデータを受信していることを確認することが重要です。詳細はテストガイドを参照してください。高レベルでは、以下のステップに従う必要があります:
- テストデバイスの Advertising ID を取得し、Singular SDK コンソールに ID を追加します。
- Singular SDK コンソールを開き、デバイス識別子を追加してデータのキャプチャを開始します。
- アプリ識別子を開発用アプリ識別子(com.singular.app.dev)でオーバーライドし、テストデータとイベントを本番データと分離します。
- 終了状態からアプリをビルドまたはオープンする
- App Openが必要なすべてのSingularデータポイントとともにサーバーに送信されることを検証します。
- サーバーが、Singular の'launch' エンドポイントに、必要なデータポイントをすべて含む Session Notification をトリガーすることを検証します。
- 数秒後、Singular SDKコンソールにSessionイベントが表示されます。
- アプリのイベントのトリガーに進みます。
- 必要なSingularデータポイントをすべて含むイベントがサーバーに送信されることを確認します。
- サーバがSingular'evt'エンドポイントに必要なデータポイントを含むイベント通知をトリガーすることを確認します。
- 数秒後、Singular SDKコンソールにイベントが表示されます。
- テストを繰り返し、すべてのイベントが期待通りに、期待通りの値で送信されていることを確認します。
- セッションイベントがアプリのオープン時またはフォアグラウンドで、イベントを受信する前に発生することを確認します。
- イベント要求データポイントがセッションデータポイントと一致することを確認します。
SDKコンソールにイベントが表示されれば、イベント処理のエンドツーエンドのテストは完了です!