PC & Console API エンドポイントリファレンス
PC およびコンソール向けのサーバー間 (server-to-server) エンドポイントの完全な API リファレンスです。セッショントラッキングとイベントレポートに関する詳細なパラメータ仕様と実装例を提供します。
関連リファレンス: PC およびコンソールは、S2S スイートの他の部分と同じ S2S エンドポイントを使用します。モバイルおよびウェブの相当版については、SESSIONエンドポイントリファレンスおよびEVENTエンドポイントリファレンスをご覧ください。本リファレンスでは PC およびコンソールのセッションおよびイベントエンドポイントを扱います。
エンタープライズ機能: PC およびコンソールのゲームアトリビューションはエンタープライズ機能です。詳細については、 PC およびコンソールゲームアトリビューション FAQ をお読みいただくか、担当のカスタマーサクセスマネージャーにお問い合わせください。
連携ガイド: 実装手順とベストプラクティスの詳細については、 PC & Console S2S 連携ガイド をご覧ください。
セッション通知エンドポイント
インストールアトリビューション、リエンゲージメントトラッキング、ユーザーリテンション分析のために、ゲームの起動とセッションを Singular にレポートします。
エンドポイント仕様
| メソッド | URL |
|---|---|
POST
|
https://s2s.singular.net/api/v1/launch
|
パラメータは
application/x-www-form-urlencoded
リクエストボディとして送信します。以下の必須ヘッダーを含めてください:
Content-Type: application/x-www-form-urlencoded
目的
セッション通知エンドポイントを使用して、すべてのゲーム起動 (初回セッションおよび再セッション) をほぼリアルタイムでレポートします。Singular Device ID で識別されるインストールについて Singular が最初に受け取ったゲーム起動が、アトリビューションプロセスをトリガーします。
アトリビューションワークフロー:
- 初回セッション: Web キャンペーンのクリックとの照合によるインストールアトリビューションをトリガーします
- 以降のセッション: ユーザーアクティビティ、リテンション、リエンゲージメント分析のためにトラッキングされます
- リアルタイムレポート: セッション通知は実際のゲーム起動にできる限り近いタイミングで送信します
セッションパラメータ
必須パラメータ
| パラメータ | 詳細 |
|---|---|
a |
タイプ: String
重要: Reporting API Key は使用しないでください。リクエストが拒否されます。
例:
|
p
|
タイプ: String
|
i
|
タイプ: String
重要: アトリビューションを機能させるには、Web SDK の Product ID と完全に一致している必要があります。同じゲームのすべてのプラットフォームで同じ値を使用してください。
例:
|
sdid
|
タイプ: UUIDv4
|
os
|
タイプ: String
|
install_source
|
タイプ: String
|
ip
|
タイプ: String
代替方法: 明示的に渡す代わりに、
例:
|
任意パラメータ
以下のオプションパラメータがサポートされています。
| パラメータ | 詳細 |
|---|---|
install_ref
|
タイプ: String
要件:
実装の詳細については、
Google Play for Native PC Install Referrer ドキュメント
を参照してください。
|
match_id
|
タイプ: String
要件:
実装の詳細については、
Match ID アトリビューション
を参照してください。
|
av
|
タイプ: String
|
global_properties
|
タイプ: JSON
|
install
|
タイプ: Boolean
|
utime
|
タイプ: Integer
|
umilisec
|
タイプ: Integer
|
ve |
タイプ: String
|
ua |
タイプ: String
|
use_ip |
タイプ: Boolean
制限事項:
例:
|
data_sharing_options |
タイプ: JSON
|
custom_user_id |
タイプ: String
PII は使用不可: 個人を特定できる情報は渡さないでください。生のメールアドレス、電話番号、氏名ではなく、ハッシュ化またはその他の方法で匿名化した内部識別子を使用してください。
例:
|
リクエスト例
実装サンプル
基本的なセッションリクエスト
curl -X POST "https://s2s.singular.net/api/v1/launch" \
-H "Content-Type: application/x-www-form-urlencoded" \
--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"
Match ID を含む初回起動
curl -X POST "https://s2s.singular.net/api/v1/launch" \
-H "Content-Type: application/x-www-form-urlencoded" \
--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.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
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'
})
Match 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.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
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, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: 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'
});
Match 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, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: params.toString()
});
return await response.json();
}
イベント通知エンドポイント
パートナー Conversion API サポート:
これらのイベントを Singular の Conversion API 連携を通じて広告ネットワークパートナーに転送するには、標準の任意イベント属性 (
eventId
や
ehash
などのハッシュ化されたファーストパーティデータ) を含めます。
Conversion API 連携向けの標準イベント属性
を参照してください。
分析、キャンペーン最適化、パートナー転送のために、ゲーム内イベントを Singular にレポートします。
2026年7月15日よりV2が必須。 2026年7月15日以降に作成されたアカウントは、Event Endpoint V2(SDIDベース)を使用する必要があります。新規アカウントではV1は利用できません。すでにV1で連携済みの既存のお客様は影響を受けません。V2への移行をご希望の場合は、担当のSingular Customer Success Managerにお問い合わせください。
エンドポイント仕様
| メソッド | URL |
|---|---|
POST
|
https://s2s.singular.net/api/v2/evt
|
パラメータは
application/x-www-form-urlencoded
リクエストボディとして送信します。以下の必須ヘッダーを含めてください:
Content-Type: application/x-www-form-urlencoded
目的
イベント通知エンドポイントを使用して、必要なすべてのゲーム内イベントをほぼリアルタイムでレポートします。イベントデータは、分析、レポート、パートナー最適化、キャンペーンパフォーマンス測定に使用されます。
イベントのベストプラクティス:
- 標準イベント: 自動的なパートナーマッピングのために Singular の標準イベント名 を使用します
- リアルタイムレポート: イベントは実際の発生にできる限り近いタイミングで送信します
- 収益イベント: 購入トラッキングと ROI 分析のために収益パラメータを含めます
イベントパラメータ
必須パラメータ
| パラメータ | 詳細 |
|---|---|
a |
タイプ: String
重要: Reporting API Key は使用しないでください。リクエストが拒否されます。
例:
|
p
|
タイプ: String
|
i
|
タイプ: String
|
sdid
|
タイプ: UUIDv4
|
n
|
タイプ: String
推奨: 自動的なパートナー連携のために Singular の標準イベント名 を使用します。
例:
|
os
|
タイプ: String
|
install_source
|
タイプ: String
|
ip
|
タイプ: String
|
任意パラメータ
以下のオプションパラメータがサポートされています。
| パラメータ | 詳細 |
|---|---|
e
|
タイプ: JSON
推奨: パートナー互換性のために Singular の標準属性名 を使用します。
例:
|
is_revenue_event
|
タイプ: Boolean
|
amt
|
タイプ: Number
|
cur
|
タイプ: String
|
av
|
タイプ: String
|
global_properties
|
タイプ: JSON
|
utime
|
タイプ: Integer
|
umilisec
|
タイプ: Integer
|
ve |
タイプ: String
|
ua |
タイプ: String
|
use_ip |
タイプ: Boolean
制限事項:
例:
|
data_sharing_options |
タイプ: JSON
|
custom_user_id |
タイプ: String
PII は使用不可: 個人を特定できる情報は渡さないでください。生のメールアドレス、電話番号、氏名ではなく、ハッシュ化またはその他の方法で匿名化した内部識別子を使用してください。
例:
|
リクエスト例
実装サンプル
標準イベント
curl -X POST "https://s2s.singular.net/api/v2/evt" \
-H "Content-Type: application/x-www-form-urlencoded" \
--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 -X POST "https://s2s.singular.net/api/v2/evt" \
-H "Content-Type: application/x-www-form-urlencoded" \
--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/v2/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.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
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/v2/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.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
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/v2/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, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: 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/v2/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, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: 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 レスポンスを返します。成功またはエラーを判定するために、status フィールドの検証が必要です。
レスポンス形式
重要:
すべてのレスポンスは HTTP 200 ステータスコードを返します。成功 (
ok
) または失敗 (
error
) を判定するために、常にレスポンスボディの
status
フィールドを検証してください。
レスポンスコードの完全なドキュメントとエラーハンドリング戦略については、 S2S レスポンスコードとエラーハンドリング を参照してください。
追加リソース
- 連携ガイド: PC & Console S2S 連携ガイド
- Web SDK: Web SDK の概要と使い方
- アトリビューション FAQ: PC およびコンソールゲームアトリビューション FAQ
- 標準イベント: Singular 標準イベントリファレンス