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

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
必須。 API 認証用の Singular SDK Key。
取得場所: Singular UI → メインメニュー → Developer Tools

重要: Reporting API Key は使用しないでください。リクエストが拒否されます。

例: sdkKey_afdadsf7asf56

p

タイプ: String
必須。 大文字と小文字を区別します。ユーザーがゲームをプレイするプラットフォームです。
サポートされる値:
例: PC

  • PC
  • Xbox
  • Playstation
  • Nintendo
  • MetaQuest
i

タイプ: String
必須。 大文字と小文字を区別します。逆 DNS 表記を推奨します。ゲームごとに一意のゲーム識別子です。

重要: アトリビューションを機能させるには、Web SDK の Product ID と完全に一致している必要があります。同じゲームのすべてのプラットフォームで同じ値を使用してください。

例: com.singular.game

sdid

タイプ: UUIDv4
必須。 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

  • steam
  • epicgamestore
  • microsoftstore
  • gog
  • humblestore
  • xbox
  • playstation
  • nintendo
  • metaquest
  • selfdistributed
ip

タイプ: String
必須。 IPv4 または IPv6 形式。 use_ip=true の場合は不要です。ゲーム起動時のデバイスの IP アドレスです。

代替方法: 明示的に渡す代わりに、use_ip=trueを使用して HTTP リクエストヘッダーから IP を抽出できます。

例: 172.58.29.235


任意パラメータ

以下のオプションパラメータがサポートされています。

パラメータ 詳細
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

ve

タイプ: String
任意。 例: 9.2

セッション時のデバイスの OS バージョン。
ua

タイプ: String
任意。 URL エンコードされた User Agent 文字列。
生の値: Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15...
例: Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0...

use_ip

タイプ: Boolean
任意。 ip パラメータの代わりに、HTTP リクエストから IP アドレスを抽出するよう Singular に指示します。

制限事項:

  • Singular による IP ベースの位置情報推定を妨げます。
  • country パラメータで 2 文字の国コードを指定してください。
  • ip パラメータとは相互排他的です。両方を使用しないでください。
  • データの拒否を避けるため、 ip または use_ip のいずれかを必ず指定してください。

例: true

data_sharing_options

タイプ: JSON
任意。 データ共有に関するエンドユーザーの同意を表す JSON(URL エンコード済み)。永続化し、以降のすべての SESSION および EVENT リクエストで渡す必要があります。
ユーザーが同意した場合(オプトイン):
ユーザーが拒否した場合(オプトアウト):
例: %7B%22limit_data_sharing%22%3Atrue%7D

{"limit_data_sharing":false}
{"limit_data_sharing":true}
custom_user_id

タイプ: String
任意。 クロスデバイストラッキング用の自社内部ユーザー ID。

PII は使用不可: 個人を特定できる情報は渡さないでください。生のメールアドレス、電話番号、氏名ではなく、ハッシュ化またはその他の方法で匿名化した内部識別子を使用してください。

例: 123456789abcd


リクエスト例

実装サンプル

CURL PYTHON JAVASCRIPT

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

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"

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

パートナー Conversion API サポート: これらのイベントを Singular の Conversion API 連携を通じて広告ネットワークパートナーに転送するには、標準の任意イベント属性 ( eventIdehash などのハッシュ化されたファーストパーティデータ) を含めます。 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
必須。 API 認証用の Singular SDK Key。
取得場所: Singular UI → メインメニュー → Developer Tools

重要: Reporting API Key は使用しないでください。リクエストが拒否されます。

例: sdkKey_afdadsf7asf56

p

タイプ: String
必須。 大文字と小文字を区別します。ユーザーがゲームをプレイするプラットフォームです。
サポートされる値: PC, Xbox, Playstation, Nintendo, MetaQuest
例: PC

i

タイプ: String
必須。 大文字と小文字を区別します。逆 DNS 表記を推奨します。ゲームごとに一意のゲーム識別子です。
セッション通知および Web SDK の Product ID で使用した値と一致している必要があります。
例: com.singular.game

sdid

タイプ: UUIDv4
必須。 一意のゲームインストールを識別する 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__ である場合、またはゼロ以外の 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

ve

タイプ: String
任意。 例: 9.2

セッション時のデバイスの OS バージョン。
ua

タイプ: String
任意。 URL エンコードされた User Agent 文字列。
生の値: Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15...
例: Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0...

use_ip

タイプ: Boolean
任意。 ip パラメータの代わりに、HTTP リクエストから IP アドレスを抽出するよう Singular に指示します。

制限事項:

  • Singular による IP ベースの位置情報推定を妨げます。
  • country パラメータで 2 文字の国コードを指定してください。
  • ip パラメータとは相互排他的です。両方を使用しないでください。
  • データの拒否を避けるため、 ip または use_ip のいずれかを必ず指定してください。

例: true

data_sharing_options

タイプ: JSON
任意。 データ共有に関するエンドユーザーの同意を表す JSON(URL エンコード済み)。永続化し、以降のすべての SESSION および EVENT リクエストで渡す必要があります。
ユーザーが同意した場合(オプトイン):
ユーザーが拒否した場合(オプトアウト):
例: %7B%22limit_data_sharing%22%3Atrue%7D

{"limit_data_sharing":false}
{"limit_data_sharing":true}
custom_user_id

タイプ: String
任意。 クロスデバイストラッキング用の自社内部ユーザー ID。

PII は使用不可: 個人を特定できる情報は渡さないでください。生のメールアドレス、電話番号、氏名ではなく、ハッシュ化またはその他の方法で匿名化した内部識別子を使用してください。

例: 123456789abcd


リクエスト例

実装サンプル

CURL PYTHON JAVASCRIPT

標準イベント

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"

レスポンス処理

両方のエンドポイントは一貫した JSON レスポンスを返します。成功またはエラーを判定するために、status フィールドの検証が必要です。

レスポンス形式

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

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


追加リソース