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

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

共通のS2Sパラメーター: エンドポイント、認証、および共通のリクエストパラメーターは、 S2S基礎ハブで一度だけ定義されています。このリファレンスでは、PC & コンソール固有の内容のみを扱います。

エンタープライズ機能: PCおよびコンソールゲームのアトリビューションはエンタープライズ機能です。詳細については、 PCおよびコンソールゲームアトリビューションFAQ をお読みいただくか、カスタマーサクセスマネージャーにお問い合わせください。

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

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

インストールアトリビューション、再エンゲージメントトラッキング、ユーザーリテンション分析のために、ゲームの起動とセッションをSingularにレポートします。

エンドポイント仕様

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

目的

セッション通知エンドポイントを使用して、すべてのゲーム起動（初回セッションおよび以降のセッション）をほぼリアルタイムでレポートします。Singular Device IDで識別されるインストールについてSingularが受信した最初のゲーム起動が、アトリビューションプロセスをトリガーします。

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

初回セッション: Webキャンペーンのクリックとのインストールアトリビューションマッチングをトリガーします
以降のセッション: ユーザーアクティビティ、リテンション、再エンゲージメント分析のためにトラッキングされます
リアルタイムレポート: セッション通知は、実際のゲーム起動にできるだけ近いタイミングで送信してください

セッションパラメーター

必須パラメーター

認証には共通の a パラメーター（SDK Key）を使用します。S2S基礎ハブの認証をご覧ください。

パラメーター	詳細
`p`	`string` 必須。大文字と小文字を区別します。ユーザーがゲームをプレイするプラットフォーム。サポートされる値: `pc` `xbox` `playstation` `nintendo` `metaquest` 例: `pc`
`i`	`string` 必須。大文字と小文字を区別します。逆DNS表記を推奨します。ゲームごとに固有のゲーム識別子。重要: アトリビューションを機能させるには、Web SDKのProduct IDと完全に一致させる必要があります。同一ゲームについては、すべてのプラットフォームで同じ値を使用してください。例: `com.singular.game`
`sdid`	`UUID` 必須。 UUIDバージョン4形式を推奨します。固有のゲームインストールおよびユーザーアクティビティを識別するSingular Device ID。生成: 初回起動時にゲーム/サーバーによって作成され、ゲームインストールのライフタイム全体を通じて保持されます。例: `49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	`string` 必須。カスタム値をサポートします。オペレーティングシステムまたはゲームシステム。プラットフォーム別の推奨値: 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`	`string` 必須。カスタム値をサポートします。ゲームストアまたは配信方法。推奨値: `steam` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed` カスタム値をサポートします。例: `steam`
`ip`	`string` 必須。 IPv4またはIPv6形式。 `use_ip=true` の場合は不要です。ゲーム起動時のデバイスのIPアドレス。代替方法: 明示的に渡す代わりに `use_ip=true` を使用して、HTTPリクエストヘッダーから IPを抽出できます。S2S基礎ハブのネットワークと位置情報をご覧ください。例: `172.58.29.235`

オプションパラメーター

汎用デバイスプロパティ（ ve 、 ua ）、ネットワークパラメーター（ use_ip ）、データプライバシー（ data_sharing_options ）、クロスデバイス（ custom_user_id ）は、すべてのS2Sエンドポイントで共通です。S2S基礎ハブのデバイスパラメーター、ネットワークと位置情報、データプライバシー、クロスデバイスをご覧ください。以下のパラメーターはPC & コンソール固有のものです。

パラメーター	詳細
`install_ref`	`string` オプション。初回起動時のみ。JSON URLエンコードされたGoogle Install Referrer情報。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`	`string` オプション。初回起動時のみ。Webクリックとゲームインストールを決定論的にマッチングしてアトリビューションを行うための識別子。要件: 初回のゲーム起動時のみ送信する必要があります Web SDK実装で使用した値と一致する必要があります PIIの場合は、SHA-256でハッシュ化する必要があります実装の詳細については、 Match IDアトリビューションをご覧ください。例: `matchid_12345`
`av`	`string` オプション。アプリケーションバージョンまたはゲームビルド識別子。例: `1.1.5.581823a`
`global_properties`	`JSON` オプション。 URLエンコードされたJSON。最大5プロパティ、各200文字まで。ユーザーに対して保存され、以降のすべてのリクエストにわたって保持されるキーと値のペア。以前に設定した値を送信しないと、その値は解除されます。例: `%7B%22key1%22%3A%22value1%22%7D`
`install`	`boolean` オプション。ゲームインストール後の最初のセッションであることを示すインストールフラグ。再インストールトラッキング機能に必要です。例: `true`
`utime`	`integer` オプション。 UNIXタイムスタンプ（秒）。UNIX時間でのゲーム起動のタイムスタンプ。例: `1483228800`
`umilisec`	`integer` オプション。 UNIXタイムスタンプ（ミリ秒）。UNIX時間でのゲーム起動のタイムスタンプ。例: `1483228800000`

リクエスト例

実装サンプル

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

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"

Match 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'
})

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.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'
});

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}?${params.toString()}`);
    return await response.json();
}

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

パートナー Conversion API のサポート: SingularのConversion API連携を通じてこれらのイベントを広告ネットワークパートナーに転送するには、標準のオプションイベント属性（eventIdやehashなどのハッシュ化されたファーストパーティデータ）を含めてください。Conversion API連携のための標準イベント属性を参照してください。

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

エンドポイント仕様

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

目的

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

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

標準イベント: 自動的なパートナーマッピングのために、 Singularの標準イベント名を使用してください
リアルタイムレポート: イベントは実際の発生にできるだけ近いタイミングで送信してください
収益イベント: 購入トラッキングとROI分析のために、収益パラメーターを含めてください

イベントパラメーター

必須パラメーター

認証には共通の a パラメーター（SDK Key）を使用します。S2S基礎ハブの認証をご覧ください。

パラメーター	詳細
`p`	`string` 必須。大文字と小文字を区別します。ユーザーがゲームをプレイするプラットフォーム。サポートされる値: pc, xbox, playstation, nintendo, metaquest 例: `pc`
`i`	`string` 必須。大文字と小文字を区別します。逆DNS表記を推奨します。ゲームごとに固有のゲーム識別子。セッション通知およびWeb SDKのProduct IDで使用した値と一致する必要があります。例: `com.singular.game`
`sdid`	`UUID` 必須。固有のゲームインストールを識別するSingular Device ID。セッション通知で使用したSDIDと一致する必要があります。例: `49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`n`	`string` 必須。最大32 ASCII文字。ゲーム内アクションまたはマイルストーンを識別するイベント名。推奨: 自動的なパートナー統合のために、 Singularの標準イベント名を使用してください。例: `sng_achievement_unlocked`
`os`	`string` 必須。カスタム値をサポートします。オペレーティングシステムまたはゲームシステム。セッション通知で使用した値と一致する必要があります。例: `windows`
`install_source`	`string` 必須。カスタム値をサポートします。ゲームストアまたは配信方法。セッション通知で使用した値と一致する必要があります。例: `steam`
`ip`	`string` 必須。 IPv4またはIPv6形式。 `use_ip=true` の場合は不要です。イベント発生時のデバイスのIPアドレス。例: `172.58.29.235`

オプションパラメーター

パラメーター	詳細
`e`	`JSON` オプション。 URLエンコードされたJSON、属性ごとに最大500 ASCII文字。イベントに関する詳細な情報を提供するカスタムイベント属性。推奨: パートナーとの互換性のために、 Singularの標準属性名を使用してください。例: `%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	`boolean` 収益イベントには必須。イベントを収益イベントとしてマークします。イベント名が `__iap__` である場合、または0以外の `amt` が指定されている場合は省略できます。例: `true`
`amt`	`number` 収益イベントには必須。収益イベントの通貨金額。 `cur` パラメーターと併用してください。例: `2.51`
`cur`	`string` 収益イベントには必須。収益イベントのISO-4217 3文字通貨コード。 `amt` パラメーターと併用してください。参照: ISO-4217通貨コード例: `EUR`
`av`	`string` オプション。アプリケーションバージョンまたはゲームビルド識別子。例: `1.1.5.581823a`
`global_properties`	`JSON` オプション。 URLエンコードされたJSON。最大5プロパティ、各200文字まで。ユーザーに対して保存されるキーと値のペア。設定されている場合、以降のすべてのリクエストにわたって保持する必要があります。例: `%7B%22key1%22%3A%22value1%22%7D`
`utime`	`integer` オプション。 UNIXタイムスタンプ（秒）。UNIX時間でのイベントのタイムスタンプ。例: `1483228800`
`umilisec`	`integer` オプション。 UNIXタイムスタンプ（ミリ秒）。UNIX時間でのイベントのタイムスタンプ。例: `1483228800000`

リクエスト例

実装サンプル

標準イベント

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レスポンスを返し、成功またはエラーを判定するために statusフィールドの検証が必要です。

レスポンス形式

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

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

追加リソース

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