ドキュメント

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

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

エンタープライズ機能:PCおよびコンソールゲームの属性追跡はエンタープライズ機能です。詳細については、 PCおよびコンソールゲーム属性追跡FAQ を参照するか、カスタマーサクセスマネージャーにお問い合わせください。

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

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

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

エンドポイント仕様

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

目的

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

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

初回セッション:インストールアトリビューションをトリガーウェブキャンペーンクリックとのマッチングを実施
以降のセッション：ユーザー活動、継続率、再エンゲージメント分析を追跡
リアルタイムレポート: 実際のゲーム起動に可能な限り近いタイミングでセッション通知を送信

セッションパラメータ

必須パラメータ

パラメータ	説明	制約	例
`a`	API認証用のSingular SDKキー。場所:ダッシュボード → 開発者ツール → SDK 統合 → SDK キー重要:SDKキーを使用し、レポート用APIキーは使用しないでください	必須文字列	`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 PlayStation:playstation_3, playstation_4, playstation_5 Nintendo:nintendo_switch Meta Quest:metaquest, metaquest_2, metaquest_pro	必須カスタム値をサポート	`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`

オプションパラメータ

パラメータ	説明	制約	例
`install_ref`	JSON URLエンコードされたGoogleインストールリファラー情報。Google Play Gamesストア経由で配信されるネイティブPCゲームに対して最も正確なアトリビューションを提供します。要件: Play Games PC SDKの実装が必要初回起動時に送信される初回ゲーム起動時のみ送信必須実装の詳細については、 Google Play for Native PC Install Referrer のドキュメントを参照してください。	オプション文字列初回起動時のみ	`%7B%22install_time_epoch_seconds%22%3A%221568939453%22` `%2C%22install_referrer%22%3A%22utm_source%3Dgoogle-play%26utm_medium%3Dorganic%22%7D`
`match_id`	ウェブクリックとゲームインストールを決定論的に紐付ける識別子要件: 初回ゲーム起動時のみ送信必須 Web SDK実装からの値と一致すること個人識別情報(PII)の場合はSHA-256でハッシュ化必須実装の詳細については Match IDAttribution を参照。	オプション文字列初回起動時のみ	`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` - ユーザーがオプトアウト（拒否）実装ガイダンスについてはユーザープライバシーを参照のこと。	オプション URLエンコードされたJSON	`%7B%22limit_data_sharing%22%3Atrue%7D`
`install`	ゲームインストール後の初回セッションを示すインストールフラグ。再インストール追跡機能に必須。	オプションブール値	`true`
`utime`	ゲーム起動のタイムスタンプ（UNIX タイム（秒））。	オプション整数（UNIX タイムスタンプ）	`1483228800`
`umilisec`	ゲーム起動の UNIX タイムスタンプ (ミリ秒)。	オプション整数（UNIXタイムスタンプ（ミリ秒））	`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`

目的

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

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

標準イベント:自動パートナーマッピングのため単一の標準イベント名を使用
リアルタイムレポート:イベントは可能な限り発生直後に送信してください
収益イベント：購入追跡とROI分析のため、収益パラメータを含める

イベントパラメータ

必須パラメータ

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

オプションパラメータ

パラメータ	説明	制約	例
`e`	イベントに関する豊富な情報を提供するカスタムイベント属性。推奨:パートナー互換性のため単数形の標準属性名を使用。	オプション URLエンコードされたJSON 属性ごとに最大500 ASCII文字	`%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	イベントを収益イベントとしてマークします。イベント名が`__iap__`または非ゼロの`amt`が指定されている場合は省略可。	収益イベントでは必須ブール値	`true`
`amt`	収益イベントの通貨金額。 `cur` パラメータと併用。	収益イベントに必須小数点以下の桁数	`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タイムスタンプ（ミリ秒））	`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ステータスコードを返します。レスポンス本体のstatus フィールドを常に検証し、成功(ok) または失敗(error)を判定してください。

完全なレスポンスコードのドキュメントとエラー処理戦略については、 S2Sレスポンスコードとエラー処理を参照してください。

追加リソース

統合ガイド:PC & コンソール向けS2S統合ガイド
Web SDK:Web SDK概要とはじめに
アトリビューションFAQ：PCおよびコンソールゲームアトリビューションFAQ
標準イベント：Singular標準イベントリファレンス

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

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

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

エンドポイント仕様

目的

セッションパラメータ

必須パラメータ

オプションパラメータ

リクエストの例

実装例

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

マッチID付き初回起動

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

マッチID付き初回起動

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

マッチID付き初回起動

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

エンドポイント仕様

目的

イベントパラメータ

必須パラメータ

オプションパラメータ

リクエストの例

実装例

標準イベント

収益イベント

標準イベント

収益イベント

標準イベント

収益イベント

レスポンス処理

レスポンス形式

追加リソース

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