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

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

サーバー間の使用例

EVENT APIはお客様のアプリケーションでイベントトラッキングを可能にします。お客様のアプリがデバイス固有のデータをお客様のサーバーに転送し、サーバーからSingularのサーバーに転送されると、プラットフォームはこの情報を次のように処理します:イベントアトリビューション、アプリ収益メトリクス。この処理されたデータは、お客様のレポート、エクスポートログ、設定されたポストバックに自動的に入力され、お客様のマーケティングキャンペーンに包括的な分析を提供します。

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

  1. アプリから必要なデータポイントを収集
  2. このデータをサーバーに転送する
  3. デバイスグラフからデバイスの詳細を更新/取得
  4. REST API経由でSingularにイベントを転送する。

event-data-flow.png

キーポイント

  • 柔軟性:データ収集と送信を完全にコントロール
  • 機能の同等性:適切なデータが提供されれば、すべての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&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識別子を使用してください。
  • ANDIは、他の識別子が使用できず、アプリがGoogle Playストアでホストされていない場合にのみ、Singularに送信できます。
  • 他の識別子が使用可能な場合は、パラメータを省略してください。
  • リクエストにNULLまたは空文字列を渡さないでください。
  • ANDI識別子の取得方法

 

値の例
fc8d449516de0dfb
パラメータ 説明
sdid

サポートされているプラットフォーム

  • ウェブ
  • PC
  • Xbox
  • プレイステーション
  • 任天堂
  • メタクエスト
  • CTV
string

sdidパラメータはSingular Device IDを指定する。

  • ウェブイベントの場合、この値はSingularウェブSDKから取得されます。
    ウェブSDID識別子の取得方法
  • PC およびコンソールアプリケーションの場合、この値はクライアント側で生成された UUIDv4 で、一意のアプリインストールを表します。

 

値の例
40009df0-d618-4d81-9da1-cbb3337b8dec
パラメータ 説明
sing

サポートされるプラットフォーム:

  • 特別なユースケースのために制限されています。
  • 詳細については、ソリューション・エンジニアまたはCSMにお問い合わせください。
string

singパラメータは、Enterprise カスタマに限定され、クライアント定義の識別子を指定します。他のすべての識別子が使用できない特別な用途でのみ使用されます。この識別子はSingular Solution Engineerがアプリごとに有効にする必要があります。

 

値の例
da534a95-1b1b-47d4-94b6-07955ec85177
デバイスパラメータ
パラメータ 説明
p
string

pパラメータはアプリのプラットフォームを指定する。

以下のリストには、大文字と小文字を区別する パラメータ値が含まれています:

  • Android
  • iOS
  • ウェブ
  • PC
  • Xbox
  • プレイステーション
  • 任天堂
  • メタクエスト
  • CTV

 

値の例
Android
パラメータ 説明
ip
string

ipパラメータは、デバイスのパブリック (IPV4) IP アドレスを指定する。IPV6 はサポートされていません。

 

値の例
172.58.29.235
パラメータ 説明
ve
string

veパラメータは、イベント時のデバイスの OS バージョンを指定する。

 

値の例
9.2
パラメータ 説明
ma

サポートされているプラットフォーム

  • アンドロイド
  • iOS
string

maパラメータは、デバイスハードウェアのMakeを指定する。このパラメータはmodelパラメータと一緒に使用する必要があります。

デバイスMakeの取得方法

 

Samsung, LG, Apple
パラメータ 説明
mo

サポートされているプラットフォーム

  • アンドロイド
  • iOS
string

moパラメータは、デバイスハードウェアのモデルを指定します。このパラメータはmakeパラメータと一緒に使用する必要があります。

デバイスモデルの取得方法

 

iPhone 4S, Galaxy SIII
パラメータ 説明
lc

サポートされているプラットフォーム

  • アンドロイド
  • iOS
string

lcパラメータは、アンダースコアで区切られた2文字の言語と国コードを使用して、デバイスのIETFロケールタグを指定します。

デバイスロケールの取得方法

 

値の例
en_US
パラメータ 説明
bd

サポートされているプラットフォーム

  • アンドロイド
  • iOS
string

bdパラメータは、URLエンコードされたデバイスのBuildを指定します。

デバイスのビルドを取得する方法

 

値の例
Build%2F13D15
アプリケーション・パラメータ
パラメータ 説明
i
string

iパラメータはアプリケーション識別子を指定する。

大文字と小文字を区別します

  • Android用パッケージ名
  • iOS用バンドルID
  • ウェブ用プロダクトID
  • PC、Xbox、Playstation、Nintendo、MetaQuest、またはCTV用の指定識別子です。

 

値の例
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パラメータは追跡されるイベントの名前を指定する。

 

値の例
sng_add_to_cart

リクエストボディ

このメソッドを呼び出すときはリクエストボディを指定しないでください。リクエストはクエリパラメータ付きのGETメソッドを使用して送信する必要があります。

 

リクエストの例

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

 

PYTHON CURL HTTP JAVA

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

 

オプションのパラメータ

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

オプション・パラメータ
タイムスタンプ・パラメータ
パラメータ 説明
utime
int

utimeパラメータは、イベントの時間を10桁のUNIX時間で指定します。

 

値の例

1483228800
パラメータ 説明
umilisec
int

umilisecパラメータは、イベントの Time をミリ秒 13 桁 UNIX 時間で指定する。

 

値の例

1483228800000
デバイスとネットワークパラメータ
パラメータ 説明
global_properties
JSON URL-encoded string

global_propertiesパラメータには、最大 5 つのキーと値のペアを含む URL エンコードされた JSON オブジェクトを指定します。各キーと値の長さは最大200文字です。

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

JSONオブジェクトは次のようにする必要があります:

  • JSON文字列に変換され、URLエンコードされていること。

 

値の例

%7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D
パラメータ 説明
use_ip
string

use_ipパラメータは、'ip' パラメータの代わりに HTTP リクエストから IP アドレスを抽出するように Singular に指示します。この機能を使うには'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
イベントパラメータ
パラメータ 説明
e
JSON URL-encoded string

eパラメータは、JSON 形式のカスタムイベント属性を指定します。

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

 

値の例

%7B%22sng_attr_content_id%22%3A5581%2C
sng_attr_content%22%3A%22XBox%22%2C%22
sng_attr_content_type%22%3A%22electronics%22%7D
収益パラメータ
パラメータ 説明
is_revenue_event
string

is_revenue_eventパラメータは、イベントが収益イベントであるかどうかを指定します。

  • イベント名が__iap__の場合、またはamtが0以外の場合は省略可能です。

 

値の例

true
パラメータ 説明
amt
double

amtパラメータは通貨量を指定します。

  • これは 'cur' パラメータと組み合わせて使用する。

 

値の例

2.51
パラメータ 説明
cur
string

curパラメータでは、大文字のISO 42173 文字の通貨コードを指定します。

  • これは、'amt' パラメータと組み合わせて使用します。

 

値の例

USD
パラメータ 説明
purchase_receipt

対応プラットフォーム

  • アンドロイド
  • iOS
string

purchase_receiptパラメータは、購入時に受け取ったレシートを指定します。Android、iOSでの取得方法は以下をご参照ください。

 

例 (iOS):

MIISqwYJKoZI...cNqts0jvcNvPcK7y
uj0KhJ9nTTQ54kDKfReihzc6aw==

例(Android):

%7B%22orderId%22%3A%22GPA.1234%22%2C%22packageName%22%3A%22com.example%22%2C%22productId%22%3A%22com.example.product%22%2C%22purchaseTime%22%3A1417113074914%2C%22purchaseState%22%3A0%2C%22purchaseToken%22%3A%22hakfcimbk...%20pM%22%7D
パラメータ 説明
receipt_signature

サポートされているプラットフォーム

  • Android
string

receipt_signatureパラメータは、購入レシートの署名に使用する署名を指定します。

 

値の例

TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==
パラメータ 説明
purchase_product_id
string

purchase_product_idパラメータは、商品のSKU識別子を指定します。

 

値の例

com.example.product
パラメータ 説明
purchase_transaction_id
string

purchase_transaction_idパラメータはトランザクション識別子を指定します。

 

例 (iOS):

380000123004321

例(Android):

GPA.1234-1234-1234-12345
データプライバシー
パラメータ 説明
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
iOSのSkAdNetworkサポート
パラメータ 説明
skan_conversion_value

対応プラットフォーム

  • iOS
int

skan_conversion_valueパラメータは、このイベント通知の時点における最新のSKAdNetwork変換値を指定します(SKAdNetworkの実装についての詳細はこちら)。

 

値の例

7
パラメータ 説明
skan_first_call_timestamp

対応プラットフォーム

  • iOS
int

skan_first_call_timestampパラメータは、基礎となるSkAdNetwork APIへの最初のコールのUnixタイムスタンプを指定します(SKAdNetworkの実装についての詳細はこちら)。

 

値の例

1483228800
パラメータ 説明
skan_last_call_timestamp

サポートされているプラットフォーム

  • iOS
int

skan_last_call_timestampパラメータは、このイベント通知時に基礎となるSkAdNetwork APIへの最新のコールのUnixタイムスタンプを指定します(SKAdNetworkの実装について詳しくはこちら)。

 

値の例

1483228800

イベントテスト

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

  1. テストデバイスの Advertising ID を取得し、Singular SDK コンソールに ID を追加します。
  2. Singular SDK コンソールを開き、デバイス識別子を追加してデータのキャプチャを開始します。
  3. アプリ識別子を開発用アプリ識別子(com.singular.app.dev)でオーバーライドし、テストデータとイベントを本番データと分離します。
  4. 終了状態からアプリをビルドまたはオープンする
  5. App Openが必要なすべてのSingularデータポイントとともにサーバーに送信されることを検証します。
  6. サーバーが、Singular の'launch' エンドポイントに、必要なデータポイントをすべて含む Session Notification をトリガーすることを検証します。
  7. 数秒後、Singular SDKコンソールにSessionイベントが表示されます。
    s2s_session.png
  8. アプリのイベントのトリガーに進みます。
  9. 必要なSingularデータポイントをすべて含むイベントがサーバーに送信されることを確認します。
  10. サーバがSingular'evt'エンドポイントに必要なデータポイントを含むイベント通知をトリガーすることを確認します。
  11. 数秒後、Singular SDKコンソールにイベントが表示されます。
    s2s_event.png
  12. テストを繰り返し、すべてのイベントが期待通りに、期待通りの値で送信されていることを確認します。
重要な検証
  • セッションイベントがアプリのオープン時またはフォアグラウンドで、イベントを受信する前に発生することを確認します。
  • イベント要求データポイントがセッションデータポイントと一致することを確認します。

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