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

SDK 実装の代替手段として、server-to-server 連携を用いた Singular の REST API を通じて、ユーザーセッションを追跡し、アプリインストール、再エンゲージメント、リテンション指標のアトリビューションを有効化します。

概要

Server-to-Server ユースケース

Singular REST API は、アプリがデバイス固有のデータをバックエンドに転送し、そのバックエンドがアトリビューション処理と分析レポートのために Singular のサーバーへ送信する、直接的な server-to-server 連携を可能にします。

サポートされる機能:

インストールアトリビューション: マーケティングキャンペーンへのファーストタッチアトリビューション
再エンゲージメントアトリビューション: 復帰ユーザーに対するマルチタッチアトリビューション
リテンション指標: セッションベースのエンゲージメント追跡
イベント追跡: カスタムのアプリ内イベント計測

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

Server-to-server 連携は、4 ステップのデータ送信プロセスに従います。

クライアント側の収集: アプリが必要なデバイスおよびアプリケーションデータを収集します
サーバーへの送信: アプリが収集したデータをバックエンドサーバーに転送します
Singular API 呼び出し: サーバーがデータを Singular REST API エンドポイントに送信します
レスポンス処理: サーバーが Singular のレスポンスを受信して処理します

セッションデータフロー図

重要な考慮事項

必須要件:

リアルタイム処理: リクエストは個別に処理されます — バッチ処理はサポートされていません
順序性: イベントは時系列順に送信する必要があります
重複排除なし: Singular はデータの重複排除を行いません — サーバー側で重複排除を実装してください
データの永続性: デバイスレベルのデータは取り込み後に削除できません — 送信前に検証してください
セッションが先: イベント追跡の前にセッションを確立する必要があります

連携のメリット:

柔軟性: データ収集および送信タイミングを完全に制御できます
機能の同等性: 適切なデータが提供されれば、すべての SDK 機能をサポートします
カスタム実装: 特定のバックエンドアーキテクチャに合わせて連携を調整できます

セッション管理

SESSION エンドポイントは、アトリビューションと追跡のためにユーザーセッションを初期化するよう、アプリの起動イベントを Singular に通知します。

セッションを送信するタイミング

セッションのトリガー

次のアプリライフサイクルイベントで SESSION リクエストを送信します:

新規インストール: インストール後の初回アプリ起動
終了状態からの起動: 完全に閉じた状態からのアプリ起動
バックグラウンドからフォアグラウンドへの復帰: タイムアウト期間（推奨: 60 秒）を超えてバックグラウンドにあった後、アプリがフォアグラウンドに復帰したとき

セッションタイムアウトのロジック

アプリを短時間バックグラウンドにした際の過剰な SESSION リクエストを防ぐため、セッションタイムアウトを実装してください。

推奨される実装:

タイムアウト時間: 60 秒（1 分）
フォアグラウンド < タイムアウト: タイムアウト期間内にアプリがフォアグラウンドに復帰した場合は SESSION を送信しません
フォアグラウンド > タイムアウト: タイムアウト期間を超えてバックグラウンドにあった場合は SESSION を送信します
アプリライフサイクルの追跡: アプリのライフサイクルイベントとタイマーを使用してセッション状態を管理します

ディープリンクのサポート: ディープリンク、Universal Links、または App Links 経由でアプリが起動された場合は、タイムアウトの状態にかかわらず、 openuri パラメーターを設定して常に SESSION を送信してください。

アトリビューション処理

セッションベースのアトリビューション

Singular は SESSION リクエストを処理し、アトリビューションの種類を判定して、適切なワークフローをトリガーします。

セッションの種類	Singular の処理	アトリビューション結果
初回セッション（新規インストール）	インストールアトリビューション処理がトリガーされます	インストールをマーケティングキャンペーンにアトリビュートします
再エンゲージメント適格	再エンゲージメントアトリビューション処理がトリガーされます	ユーザーの復帰をキャンペーンまたはディープリンクにアトリビュートします
標準セッション	リテンション追跡のためにセッションが記録されます	ユーザーのアクティビティおよびエンゲージメント指標にカウントされます

詳細: 再エンゲージメントアトリビューション FAQ

イベント順序の要件

セッションとイベントのタイミングは、アトリビューションの精度とデータ品質に直接影響します。

重要な順序ルール:

イベントの前にセッション: 該当セッションのイベントを送信する前に、単一の SESSION を受信する必要があります
リアルタイムのイベント送信: アプリ内イベントは、それぞれのセッションの後にリアルタイムで送信する必要があります
順序どおりの処理: セッションの順序が不正だと、データの不整合やアトリビューションエラーが発生します

高度なオプション

拡張機能

Singular S2S 連携は、追加の SESSION パラメーターを必要とする高度な機能をサポートします。

高度な機能: ディープリンク、SKAdNetwork、およびクロスデバイス追跡の要件については、高度な S2S オプションをご確認ください。

API エンドポイント仕様

SESSION エンドポイントは、デバイス、アプリケーション、およびアトリビューションデータを含むクエリパラメーターを持つ GET リクエストを受け付けます。

エンドポイント URL

ベース URL とメソッド

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

リクエスト形式:

GET /api/v1/launch?param1=value1&param2=value2

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

必須パラメーター

すべての SESSION リクエストには、適切な値と形式でこれらの必須パラメーターを含める必要があります。

API 認証

SDK Key

これらは、 S2S Fundamentals で一度定義される共有 S2S パラメーターです。

デバイス識別子

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

これらは、 S2S Fundamentals で一度定義される共有 S2S パラメーターです。

デバイスパラメーター

デバイス情報

これらは、 S2S Fundamentals で一度定義される共有 S2S パラメーターです。

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

アプリ情報

アプリ識別子（ i ）、 app_v 、および att_authorization_status は共有パラメーターです。 S2S Fundamentals のアプリケーションパラメーターを参照してください。

パラメーター詳細


        install

boolean

セッションがインストールまたは再インストール後の初回セッションを表すかどうかを示します。

true - 新規インストール／再インストール後の初回セッション
false - 後続のセッション（アプリはすでにインストール済み）

必須の対象: 再インストール追跡機能

例: true


        install_time

iOS, Android

integer

初回アプリインストールの Unix タイムスタンプ。

例: 1510040127


        update_time

iOS, Android

integer

最後のアプリ更新の Unix タイムスタンプ。

例: 1510040127

不正防止パラメーター

インストール元の検証

パラメーター詳細


        install_source

Android, PC

string

インストール元のパッケージ名またはストア識別子。

Android: Install Source Package Name

Android の例: com.android.vending （Google Play Store）

PC でサポートされるストア:

steam
epic
microsoftstore
humblestore
gog
selfdistributed


        install_receipt

iOS

string

不正検証用の Base64 エンコードされた iOS インストールレシート。

例（一部省略）: MIJF9wYJKoZIhvcNAQcCoIJF6DCCReQCAQExCzAJBgUrDgMCGgUAMII1m...

ディープリンクパラメーター

ディープリンクのサポート

パラメーター詳細


        openuri

iOS, Android

string

アプリを起動した URL エンコード済みのディープリンク、Universal Link、または App Link。

元の URL: myapp://home/page?queryparam1=value1&queryparam2=value2

エンコードされた例: myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1%26queryparam2%3Dvalue2


        ddl_enabled

iOS, Android

boolean

アプリがレスポンスに deferred deep link URL を期待するかどうかを示します。

true - レスポンスに deferred deep link を期待する
false - deferred deep link を期待しない

レスポンス例:

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}


        singular_link_resolve_required

iOS, Android

boolean

Singular ショートリンクからロングリンクへの解決を要求します。Singular ショートリンクを含む openuri とともに使用する必要があります。

true - 展開されたロングリンクを返す
false - リンクを解決しない

レスポンス例:

{
  "status":"ok",
  "resolved_singular_link":"https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

高度なアトリビューションパラメーター

プラットフォームアトリビューションの強化

パラメーター詳細


        install_ref

Android (Google Play)
Native PC (Google Play Games)

JSON

JSON URL エンコードされた Google Install Referrer 情報。Android および Google Play Games PC インストールに対して最も正確なアトリビューションを提供します。

Android JSON 構造:

{
   "installBeginTimestampSeconds":"1568939453",
   "referrer":"utm_source=google-play&utm_medium=organic",
   "clickTimestampSeconds":"0",
   "referrer_source":"service",
   "current_device_time":"1568944524"
}

Native PC JSON 構造:

{
   "install_time_epoch_seconds":"1568939453",
   "install_referrer":"utm_source=google-play&utm_medium=organic"
}

必須の対象:

Facebook のユーザーレベルエクスポート
Data Destination の共有
ポストバックの精度

詳細情報:

URL エンコードの例: %7B%22installBeginTimestampSeconds%22%3A%221568939453%22...


        meta_ref

Android (Google Play)

JSON

2025 年 6 月 18 日以降: Meta Advanced Mobile Measurement (AMM) により、Meta Install Referrer 実装の必要性がなくなりました。AMM が有効な場合は推奨されません。

粒度の細かいユーザーレベルのアトリビューションデータのための、JSON URL エンコードされた Meta Install Referrer。

JSON 構造:

{
  "install_referrer": {
    "utm_source":"apps.facebook.com",
    "utm_campaign": "fb4a",
    "utm_content": {
      "source":{
        "data":"c7e6b890bf18a059c2185650bdb1af3dced7...",
        "nonce":"24859720343e2381daee9f39ae61"
        },
      "app":533744218636280,
      "t":1731181327
      },
    "is_ct":1,
    "actual_timestamp":1731181444
  }
}

詳細: Meta Referrer FAQ


        attribution_token

iOS

string

AdServices フレームワーク（iOS 14.3 以降）からの Apple Search Ads アトリビューショントークン。

取得方法: インストール／再インストール後の初回アプリ起動時に attributionToken() を使用します。

例（一部省略）: KztLg%2FIkNsWDMuBMOU%2BySnkPU5myJb4OFmeaMUE%2BTqQJP...

オプションパラメーター

オプションパラメーターは、追跡機能を強化し、高度な機能をサポートします。

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

パラメーター詳細


        utime

integer

セッションの 10 桁の Unix タイムスタンプ。

例: 1483228800


        umilisec

integer

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

例: 1483228800000

ネットワークおよび位置情報パラメーター

これらは、 S2S Fundamentals で一度定義される共有 S2S パラメーターです。

カスタムプロパティ

パラメーター詳細


        global_properties

JSON

カスタムのキーと値のペアを持つ URL エンコードされた JSON オブジェクト。

制限:

キーと値のペアは最大 5 個
キーおよび値ごとに最大 200 文字

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

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

アンインストール追跡のサポート

パラメーター詳細


        apns_token

iOS

string

16 進数エンコードされた Apple Push Notification Service (APNs) デバイストークン。

iOS アンインストール追跡に必須
16 進数エンコードされた文字列である必要があります
APNs トークンの取得

例: b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052

fcm

Android

string

Firebase Cloud Messaging デバイストークン。

Android アンインストール追跡に必須
FCM トークンの取得

例: bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvD...MExUdFQ3P1

データプライバシーパラメーター

これらは、 S2S Fundamentals で一度定義される共有 S2S パラメーターです。

クロスデバイスのサポート

これらは、 S2S Fundamentals で一度定義される共有 S2S パラメーターです。

SKAdNetwork のサポート

パラメーター詳細


        skan_conversion_value

iOS

integer

セッション時点での最新の SKAdNetwork コンバージョン値。

詳細: SKAdNetwork の実装

例: 7


        skan_first_call_timestamp

iOS

integer

SKAdNetwork API への初回呼び出しの Unix タイムスタンプ。

例: 1483228800


        skan_last_call_timestamp

iOS

integer

セッション時点での SKAdNetwork API への最新の呼び出しの Unix タイムスタンプ。

例: 1483228800

Google Ads ICM のサポート（ベータ）

パラメーター詳細


        odm_info

iOS

string

Google Ads Integrated Conversion Measurement（ベータ）に必須です。

Google Ads ICM Documentation


        odm_error

iOS

string

Google Ads Integrated Conversion Measurement（ベータ）に必須です。

Google Ads ICM Documentation

リクエスト例

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

例に関する免責事項: コードサンプルには、必須パラメーターがすべて含まれていない場合があります。本番実装の前に、完全なパラメーターリストを検証してください。開発／テストには一意の 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',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'install': 'true',
    'n': 'MyCoolAppName',
    'bd': 'Build/13D15',
    'app_v': '1.2.3',
    'openuri': 'myapp://home/page?queryparam1=value1',
    'ddl_enabled': 'true',
    'install_source': 'com.android.vending',
    'install_time': 1510040127,
    'update_time': 1510090877
}

response = requests.get('https://s2s.singular.net/api/v1/launch', params=params)
print(response.json())

cURL の例

curl -G "https://s2s.singular.net/api/v1/launch" \
  --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 "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "install=true" \
  --data-urlencode "n=MyCoolAppName" \
  --data-urlencode "bd=Build/13D15" \
  --data-urlencode "app_v=1.2.3" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1" \
  --data-urlencode "ddl_enabled=true" \
  --data-urlencode "install_source=com.android.vending" \
  --data-urlencode "install_time=1510040127" \
  --data-urlencode "update_time=1510090877"

HTTP の例

GET /api/v1/launch
    ?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
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &install=true
    &n=MyCoolAppName
    &bd=Build%2F13D15
    &app_v=1.2.3
    &openuri=myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1
    &ddl_enabled=true
    &install_source=com.android.vending
    &install_time=1510040127
    &update_time=1510090877 HTTP/1.1
Host: s2s.singular.net
Accept: application/json

Java の例

// Base URL
String baseUrl = "https://s2s.singular.net/api/v1/launch";

// 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("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("install", "true");
params.put("n", "MyCoolAppName");
params.put("bd", "Build/13D15");
params.put("app_v", "1.2.3");
params.put("openuri", "myapp://home/page?queryparam1=value1");
params.put("ddl_enabled", "true");
params.put("install_source", "com.android.vending");
params.put("install_time", "1510040127");
params.put("update_time", "1510090877");

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

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

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

エラーに関する完全なドキュメント: S2S Response Codes & Error Handling

テストと検証

リアルタイムのデータ検証には Singular SDK Console を使用し、本番デプロイの前に S2S 連携を検証してください。

テスト手順

エンドツーエンドの検証

テストデバイスの登録: デバイスの広告 ID を取得し、 Singular SDK Console に追加します
Console ロギングの有効化: テストデータを取得するために、SDK Console にデバイス識別子を追加します
開発用アプリ ID の使用: テストデータを本番データと分離するために、アプリ識別子を開発版（例: com.singular.app.dev ）で上書きします
アプリの起動: セッションをトリガーするために、終了状態からアプリを起動します
クライアントデータの検証: アプリが必要な Singular のデータポイントをすべてサーバーに送信していることを確認します
サーバーリクエストの確認: サーバーが必要なパラメーターをすべて含めて https://s2s.singular.net/api/v1/launch に SESSION リクエストを送信していることを確認します
SDK Console の確認: 数秒以内に、SESSION イベントが SDK Console に表示されるはずです
テストの繰り返し: アプリへの入場およびフォアグラウンド操作のたびに SESSION がトリガーされることを検証します

SDK Console のセッションイベント

重要な確認: いずれの EVENT リクエストよりも前に、アプリの起動／フォアグラウンド時に SESSION イベントが発生することを確認してください。順序が不正だとアトリビューションエラーが発生します。

成功の指標: SESSION が SDK Console に表示されれば、エンドツーエンドの連携テストが成功したことになります！

追加リソース

テストドキュメント

包括的なテストガイド: S2S Integration Testing Guide

Server-to-Server - SESSION エンドポイント API リファレンス

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

概要

Server-to-Server ユースケース

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

重要な考慮事項

セッション管理

セッションを送信するタイミング

セッションのトリガー

セッションタイムアウトのロジック

アトリビューション処理

セッションベースのアトリビューション

イベント順序の要件

高度なオプション

拡張機能

API エンドポイント仕様

エンドポイント URL

ベース URL とメソッド

必須パラメーター

API 認証

SDK Key

デバイス識別子

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

デバイスパラメーター

デバイス情報

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

アプリ情報

不正防止パラメーター

インストール元の検証

ディープリンクパラメーター

ディープリンクのサポート

高度なアトリビューションパラメーター

プラットフォームアトリビューションの強化

オプションパラメーター

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

ネットワークおよび位置情報パラメーター

カスタムプロパティ

アンインストール追跡のサポート

データプライバシーパラメーター

クロスデバイスのサポート

SKAdNetwork のサポート

Google Ads ICM のサポート（ベータ）

リクエスト例

Python の例

cURL の例

HTTP の例

Java の例

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

テストと検証

テスト手順

エンドツーエンドの検証

追加リソース

テストドキュメント