ドキュメント

PC & コンソール API エンドポイント・リファレンス

PCとコンソールのサーバー間エンドポイントの完全なAPIリファレンスで、セッション追跡とイベントレポート用の詳細なパラメータ仕様と実装例を提供します。

エンタープライズ機能：PC およびコンソールのゲーム帰属は企業向け機能です。詳細については、PC およびコンソールゲームの帰属に関する FAQをお読みいただくか、カスタマーサクセスマネージャーまでお問い合わせください。

統合ガイド：完全な実装手順とベストプラクティスについては、PC & Console S2S 統合ガイドを参照してください。

セッション通知エンドポイント

ゲームの起動とセッションをSingularに報告して、インストールアトリビューション、リエンゲージメント追跡、ユーザー維持分析を行います。

エンドポイント仕様

方法	URL
`GET`	`https://s2s.singular.net/api/v1/launch`

目的

セッション通知エンドポイントを使用して、すべてのゲーム起動（初回セッションとリピートセッション）をほぼリアルタイムで報告します。Singular Device IDで識別されるインストールに対してSingularが受信した最初のゲーム起動が、アトリビューションプロセスのトリガーとなります。

アトリビューションワークフロー：

最初のセッション：ウェブキャンペーンのクリックに対するインストールアトリビューションマッチングをトリガーします。
後続セッション：ユーザーアクティビティ、リテンション、リエンゲージメント分析のために追跡されます。
リアルタイムレポート：実際のゲーム起動にできるだけ近いタイミングでセッション通知を送信

セッションパラメータ

必須パラメータ

パラメータ	説明	制約	例
`a`	API認証用の単一SDKキー。場所ダッシュボード → 開発者ツール → SDK統合 → SDKキー重要：レポートAPIキーではなく、SDKキーを使用してください。	必須文字列	`your_org_name_sh868sdjv`
`p`	ユーザーがゲームをプレイするプラットフォーム。サポートされる値： `pc` `xbox` `playstation` `nintendo` `metaquest`	必須文字列大文字と小文字を区別	`pc`
`i`	ゲームに固有のゲーム識別子。重要です：アトリビューションが機能するためには、Web SDK Product ID と正確に一致する必要があります。同じゲームのすべてのプラットフォームで同じ値を使用してください。	必須逆DNS表記を推奨大文字と小文字を区別	`com.singular.game`
`sdid`	固有のゲームインストールおよびユーザーアクティビティを識別する単一デバイス ID。生成：初回起動時にゲーム/サーバーによって作成され、ゲームのインストール寿命を通じて持続する。	必須 UUID バージョン 4 形式を推奨。	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	オペレーティングシステムまたはゲームシステム。カスタム値もサポートするが、プラットフォーム別の推奨値： PC:windows、linux、macos、steamos Xbox:xbox_one、xbox_360、xbox_series_s、xbox_series_x プレイステーション：プレイステーション3、プレイステーション4、プレイステーション5 任天堂：ニンテンドースイッチメタクエスト：メタクエスト、メタクエスト2、メタクエストプロ	必須サポートされるカスタム値	`windows`
`install_source`	ゲームストアまたは配信方法。推奨値 `steam` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed` カスタム値対応	必須カスタム値対応	`steam`
`ip`	ゲーム起動時のデバイスのIPアドレス。別の方法明示的に渡す代わりに、`use_ip=true`を使用して HTTP リクエストヘッダから IP を抽出します。	必須 IPv4またはIPv6形式 `use_ip=true` の場合は不要	`172.58.29.235`

オプションのパラメータ

パラメータ	説明	制約	例
`match_id`	ウェブクリックとゲームインストールをマッチさせる決定論的アトリビューション用の識別子。要件：最初のゲーム起動時にのみ送信されること Web SDK 実装の値と一致すること。 PII の場合は、SHA-256 を使用してハッシュ化する必要があります。実装の詳細については、「Match ID Attribution」を参照してください。	オプション文字列初回起動時のみ	`matchid_12345`
`ve`	オペレーティング・システムのバージョン。	オプション文字列	`22H2`
`av`	アプリケーションのバージョンまたはゲームのビルド識別子。	任意文字列	`1.1.5.581823a`
`use_ip`	明示的な`ip` パラメータを要求する代わりに、HTTP リクエストヘッダーから IP アドレスを抽出します。 `true` に設定すると、`ip`パラメータを提供しません。	オプションブール値デフォルト：false	`true`
`ua`	デバイスのユーザーエージェント文字列。	任意文字列	`Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`
`global_properties`	ユーザー用に保存され、その後のすべてのリクエストに渡って持続されるキーと値のペア。以前に設定された値を送信しない場合、この値は解除されます。フォーマットURLエンコードされたJSONオブジェクト	オプション最大5つのプロパティそれぞれ最大200文字 URLエンコードされたJSON	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	プライバシーコンプライアンスのための情報共有に対するユーザーの同意。設定されている場合、永続化され、後続のリクエストごとに渡される必要があります。値： `"limit_data_sharing":false` - ユーザーのオプトイン（同意 `"limit_data_sharing":true` - ユーザのオプトアウト（拒否実装ガイダンスについては、User Privacyを参照してください。	オプション URLエンコードされたJSON	`%7B%22limit_data_sharing%22%3Atrue%7D`
`install`	ゲームインストール後の最初のセッションを示すインストールフラグ。再インストール追跡機能には必須。	オプションブール値	`true`
`utime`	UNIX時間（秒）でのゲーム起動のタイムスタンプ。	任意整数（UNIXタイムスタンプ）	`1483228800`
`umilisec`	UNIX時間でのゲーム起動のタイムスタンプ（ミリ秒）。	任意整数（UNIXタイムスタンプ ms）	`1483228800000`
`custom_user_id`	システムからのカスタムユーザー識別子。	任意文字列	`123456789abcd`

リクエスト例

実装例

基本セッションリクエスト

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235"

マッチIDによる初回起動

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235" \
  --data-urlencode "match_id=abc123def456" \
  --data-urlencode "install=true"

基本セッションリクエスト

import requests

def report_session(config):
    url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'ip': config['ip_address']
    }
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_session({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'ip_address': '172.58.29.235'
})

マッチID付き初回起動

def report_first_launch(config):
    url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'ip': config['ip_address'],
        'match_id': config['match_id'],
        'install': 'true'
    }
    
    response = requests.get(url, params=params)
    return response.json()

基本セッションリクエスト

async function reportSession(config) {
    const url = 'https://s2s.singular.net/api/v1/launch';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'ip': config.ipAddress
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportSession({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    ipAddress: '172.58.29.235'
});

マッチIDによる初回起動

async function reportFirstLaunch(config) {
    const url = 'https://s2s.singular.net/api/v1/launch';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'ip': config.ipAddress,
        'match_id': config.matchId,
        'install': 'true'
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

イベント通知エンドポイント

分析、キャンペーンの最適化、パートナーへの転送のために、ゲーム内のイベントをSingularに報告します。

エンドポイント仕様

メソッド	URL
`GET`	`https://s2s.singular.net/api/v1/evt`

目的

イベント通知エンドポイントを使用して、希望するすべてのゲーム内イベントをほぼリアルタイムで報告します。イベントデータは、分析、レポート、パートナーの最適化、キャンペーンのパフォーマンス測定に使用されます。

イベントのベストプラクティス

標準イベント：自動パートナーマッピングのためにSingular標準イベント名を使用する。
リアルタイムレポート：可能な限り実際の発生に近いイベントを送信
収益イベント：購入追跡とROI分析のための収益パラメータを含む

イベントパラメータ

必須パラメータ

パラメータ	説明	制約	例
`a`	API認証用の単一SDKキー。場所ダッシュボード → 開発者ツール → SDK統合 → SDKキー	必須文字列	`your_org_name_sh868sdjv`
`p`	ユーザーがゲームをプレイするプラットフォーム。サポートされる値：PC、Xbox、プレイステーション、任天堂、メタクエスト	必須文字列大文字と小文字を区別	`pc`
`i`	ゲームに固有のゲーム識別子。セッション通知およびWeb SDK Product IDで使用される値と一致する必要があります。	必須逆DNS表記を推奨大文字と小文字を区別	`com.singular.game`
`sdid`	固有のゲームインストールを識別する単数形のデバイスID。セッション通知で使用されるSDIDと一致する必要があります。	必須 UUID形式	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`n`	ゲーム内のアクションやマイルストーンを特定するイベント名。推奨：パートナーとの自動統合のため、Singular標準のイベント名を使用すること。	必須文字列 32ASCII文字以内	`sng_achievement_unlocked`
`os`	オペレーティングシステムまたはゲームシステム。セッション通知で使用される値と一致する必要があります。	必須カスタム値をサポート	`windows`
`install_source`	ゲームストアまたは配信方法。セッション通知で使用される値と一致する必要があります。	必須サポートされているカスタム値	`steam`
`ip`	イベント発生時のデバイスのIPアドレス。	必須 IPv4またはIPv6形式 `use_ip=true` の場合は不要	`172.58.29.235`

オプションのパラメータ

パラメータ	説明	制約	例
`e`	イベントに関する豊富な情報を提供するカスタムイベント属性。推奨：パートナーとの互換性のためにSingular標準属性名を使用する。	オプション URLエンコードされたJSON 属性ごとに最大500 ASCII文字	`%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	イベントを収益イベントとしてマークする。イベント名が`__iap__`、またはゼロ以外の`amt`。	収益イベントの場合は必須ブール値	`true`
`amt`	収益イベントの通貨金額。 `cur` 。	収益イベントには必須 10進数	`2.51`
`cur`	収益イベントのISO-4217 3文字通貨コード。 `amt` パラメータで使用する。参照：ISO-4217 通貨コード	収益イベントに必要 ISO-4217コード	`EUR`
`ve`	オペレーティングシステムのバージョン。	オプション文字列	`22H2`
`av`	アプリケーションのバージョンまたはゲームのビルド識別子。	任意文字列	`1.1.5.581823a`
`use_ip`	HTTP リクエストヘッダから IP アドレスを抽出します。	任意ブール値デフォルト：false	`true`
`ua`	デバイスのユーザーエージェント文字列。	任意文字列	`Mozilla/5.0 (Windows NT 10.0; Win64; x64)`
`global_properties`	ユーザー用に保存されたキーと値のペア。設定された場合、その後のすべてのリクエストに渡って持続しなければならない。	オプション最大5つのプロパティそれぞれ最大200文字 URLエンコードされたJSON	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	情報共有に対するユーザーの同意。設定されている場合、後続のすべてのリクエストで永続する必要があります。	オプション URLエンコードされたJSON	`%7B%22limit_data_sharing%22%3Atrue%7D`
`utime`	UNIX時間（秒）でのイベントのタイムスタンプ。	任意整数（UNIXタイムスタンプ）	`1483228800`
`umilisec`	UNIX時間（ミリ秒）でのイベントのタイムスタンプ。	任意整数（UNIXタイムスタンプ ms）	`1483228800000`
`custom_user_id`	システムからのカスタムユーザー識別子。	任意文字列	`123456789abcd`

リクエスト例

サンプル実装

標準イベント

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "n=sng_level_achieved" \
  --data-urlencode 'e={"sng_attr_level":"5","sng_attr_score":"1250"}' \
  --data-urlencode "ip=172.58.29.235"

収益イベント

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "n=__iap__" \
  --data-urlencode "is_revenue_event=true" \
  --data-urlencode "amt=9.99" \
  --data-urlencode "cur=USD" \
  --data-urlencode "ip=172.58.29.235"

標準イベント

import requests
import json

def report_event(config):
    url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'n': config['event_name'],
        'ip': config['ip_address']
    }
    
    if 'attributes' in config:
        params['e'] = json.dumps(config['attributes'])
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_event({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'event_name': 'sng_level_achieved',
    'attributes': {
        'sng_attr_level': '5',
        'sng_attr_score': '1250'
    },
    'ip_address': '172.58.29.235'
})

収益イベント

def report_revenue(config):
    url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': config['amount'],
        'cur': config['currency'],
        'ip': config['ip_address']
    }
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_revenue({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'amount': 9.99,
    'currency': 'USD',
    'ip_address': '172.58.29.235'
})

標準イベント

async function reportEvent(config) {
    const url = 'https://s2s.singular.net/api/v1/evt';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'n': config.eventName,
        'ip': config.ipAddress
    });
    
    if (config.attributes) {
        params.append('e', JSON.stringify(config.attributes));
    }
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportEvent({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    eventName: 'sng_level_achieved',
    attributes: {
        'sng_attr_level': '5',
        'sng_attr_score': '1250'
    },
    ipAddress: '172.58.29.235'
});

収益イベント

async function reportRevenue(config) {
    const url = 'https://s2s.singular.net/api/v1/evt';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': config.amount,
        'cur': config.currency,
        'ip': config.ipAddress
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportRevenue({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    amount: 9.99,
    currency: 'USD',
    ipAddress: '172.58.29.235'
});

レスポンス処理

どちらのエンドポイントも、成功またはエラーの判定のためにステータス・フィールドの検証を必要とする一貫した JSON レスポンスを返します。

レスポンス・フォーマット

重要：すべてのレスポンスは HTTP 200 ステータス・コードを返します。成功 (ok) または失敗 (error) を判断するには、常にレスポンス・ボディのstatus フィールドを検証します。

完全なレスポンスコードとエラー処理方法については、S2S レスポンスコードとエラー処理をご参照ください。

PC＆コンソール - APIエンドポイントリファレンス

PC & コンソール API エンドポイント・リファレンス

セッション通知エンドポイント

エンドポイント仕様

目的

セッションパラメータ

必須パラメータ

オプションのパラメータ

リクエスト例

実装例

基本セッションリクエスト

マッチIDによる初回起動

基本セッションリクエスト

マッチID付き初回起動

基本セッションリクエスト

マッチIDによる初回起動

イベント通知エンドポイント

エンドポイント仕様

目的

イベントパラメータ

必須パラメータ

オプションのパラメータ

リクエスト例

サンプル実装

標準イベント

収益イベント

標準イベント

収益イベント

標準イベント

収益イベント

レスポンス処理

レスポンス・フォーマット

その他のリソース

PC＆コンソール - APIエンドポイントリファレンス

PC & コンソール API エンドポイント・リファレンス

セッション通知エンドポイント

エンドポイント仕様

目的

セッション パラメータ

必須パラメータ

オプションのパラメータ

リクエスト例

実装例

基本セッションリクエスト

マッチIDによる初回起動

基本セッションリクエスト

マッチID付き初回起動

基本セッションリクエスト

マッチIDによる初回起動

イベント通知エンドポイント

エンドポイント仕様

目的

イベントパラメータ

必須パラメータ

オプションのパラメータ

リクエスト例

サンプル実装

標準イベント

収益イベント

標準イベント

収益イベント

標準イベント

収益イベント

レスポンス処理

レスポンス・フォーマット

その他のリソース

セッションパラメータ