PCおよびコンソールゲームのアトリビューションは、エンタープライズ機能です。 この機能の詳細については、PCおよびコンソールゲームのアトリビューションに関するFAQをお読みいただくか、カスタマーサクセスマネージャーまでお問い合わせください。
Singularは、分析およびアトリビューションのために、PCおよびコンソールゲームのコンバージョンデータをSingularに報告するためのREST APIを提供しています。
このガイドでは、SingularでPC＆コンソールS2S統合を構築し、様々なオプション機能を実装する方法を説明します。
統合の概念
このセクションでは、完全なPC＆コンソールS2S統合を実装するために重要な包括的コンセプトについて詳しく説明します。
S2S APIエンドポイントの全リスト、パラメータ、サンプルコールについては、 PC & Console S2Sエンドポイントリファレンスを参照してください。
ユーザーのプライバシー
ユーザーのプライバシーを保護するため、Singularはゲーム開発者に対し、エンドユーザーがゲームイベントデータをSingularに送信することをオプトインまたはオプトアウトできるオプションを提供することを推奨します。
認証
SingularのPC & Console S2S APIへの全てのリクエストは、"a="パラメータでSDKキーを送信する必要があります。SingularのSDKキーはSingularダッシュボードの "Developer Tools -> SDK Integration > SDK Keys "にあります。
警告デベロッパーツール -> APIキー」にあるSingularの「APIキー」は使用しないでください。 APIキー」はSingularのレポーティングAPIに別途使用されます。
対応プラットフォーム、ゲームシステム、ストア
Singularの "Platform "は、ユーザーがゲームをプレイする "プラットフォーム "として定義され、全てのS2S APIリクエストの"p="パラメータに渡す必要があります。 サポートされる "Platform "値のリストは以下の通りです：
- pc
- xbox
- playstation
- nintendo
- metaquest
platform "に加えて、"operating/game system "と "store "は、それぞれ"os="と "install_source="パラメータで渡される必要がある。カスタム値もサポートされていますが、Singular ではプラットフォーム別に以下の値を推奨しています：
| プラットフォーム (p=) |
オペレーティングシステム/ゲームシステム (os=) |
ストア (install_source=) |
| pc |
windows linux macos steamos |
steam epicgamestore microsoftstore gog humblestore selfdistributed |
| xbox | xbox_one xbox_360 xbox_series_s xbox_series_x |
xbox |
| playstation | playstation_3 playstation_4 playstation_5 |
playstation |
| nintendo | nintendo_switch | nintendo |
| metaquest | metaquest metaquest_2 metaquest_pro |
metaquest |
ゲーム識別子
Singularがゲームイベントをゲームに関連付けるには、リクエストごとにゲーム識別子を"i="パラメータに渡す必要があります。
- どのような値でもかまいませんが、Singularでは逆DNS表記（com.singular.gameなど）で渡すことを推奨しています。
- お客様のゲームが複数のプラットフォームで提供されている場合、サポートされているプラットフォーム間で同じゲーム識別子を使用する必要があります（例：p=pc&i=com.singular.game、p=xbox&i=com.singular.game、p=playstation&i=com.singular.game）。
- Singularがゲームのコンバージョンをウェブサイトのランディングページを経由したウェブキャンペーンに正しく帰属させるためには、Singularウェブインテグレーションの「プロダクトID」がゲーム識別子の値とも一致する必要があります。
ユニークなゲームのインストールを識別する
Singularが複数のゲームセッションを通じて、同じゲームのインストールにゲームイベントを関連付けるには、すべてのリクエストの「sdid=」パラメータにインストール/デバイス識別子を渡す必要があります。
- 推奨UUID（バージョン4）フォーマット
- この値は、ゲームが最初に起動（インストール）されたときにゲーム/サーバーによって生成され、ゲームのインストール中ずっと持続する必要があります。
マッチID（オプション）
ゲームのウェブキャンペーンでウェブランディングページにユーザーを誘導し、ウェブサイト→PC/コンソールゲームのアトリビューションに「マッチ ID」を利用できる場合、オプションで「match_id=」パラメーターに「マッチ ID」を渡すことで、アトリビューションの精度を向上させることができます。PCおよびコンソールのアトリビューションについての詳細は、このトピックに関するFAQをご覧ください。
- インストールアトリビューションで "match ID" を使用するには、ユーザーの最初のゲーム起動時に "match ID" を渡す必要があります。
- "Match ID "は、Singular web SDKの実装にあるユーザーと同じ値である必要があります。
重要：マッチ ID をアトリビューションに利用することは高度な機能です。実装する前にSingularソリューションエンジニアにご相談ください。
試合開始の報告
PCとコンソールの統合では、すべてのゲームセッションをSingularに報告する必要があり、ゲームが起動するたびにゲームセッションが送信されることを想定しています。
ゲームセッションをSingularに通知するには、セッション通知エンドポイントを呼び出します。
セッション通知によって、Singularはいくつかのことができるようになります：
- 固有のインストール（固有のゲームインストールを識別するを参照）後の最初のゲームセッションの場合、Singularは新規インストールを認識し、インストール帰属プロセスをトリガーします。
- (ゲームセッションがリエンゲージメントセッションに該当する場合、Singularはリエンゲージメントアトリビューションプロセスを開始します（詳細はリエンゲージメントFAQをご覧ください）。
- そうでない場合、Singularはゲームセッションとしてマークし、ユーザーのアクティビティとリテンションのトラッキングに使用します。
ヒント ゲームセッションを報告するためにデータを収集するときは、非同期関数が戻ってくるのを待って、さまざまな機能を処理するようにしてください。 たとえば、次のような場合です：
- Match ID を使用してアトリビューション マッチングを向上させる場合、最初のゲーム セッションを報告するのは、Match ID が利用できる可能性が出てからにすることが重要です。Match IDを参照してください。
- あなたのゲームがSingularのマーケティングやゲーム分析にオプトインする方法を提供している場合、ゲームセッションを報告する前に同意が収集されるまで待つことが重要です。ユーザープライバシーをご覧ください。
ゲーム内イベントの報告
イベント
Singularはゲーム内イベントのデータを収集し、マーケティングキャンペーンのパフォーマンス分析に役立てることができます。イベントには、ログインや登録からゲームのレベルアップまで、あらゆるユーザーインタラクションが含まれます。
SingularとのS2S統合を実施する前に、貴社が追跡したいイベントのリストを用意してください（ゲーム内イベントの定義参照）。
ゲーム内でイベントが発生した時にSingularに通知するには、Event Notificationエンドポイントを呼び出します。 呼び出しに含めるイベント名は、Singularのレポート、エクスポート、ポストバックでイベントを識別する方法です。
注意事項
- Singularは、Singularの標準イベントと属性の命名規則を使用してイベントを渡すことを推奨します。 標準イベントを使用することで、マッピングが合理化され、統合におけるパートナーの標準イベントとの互換性が向上します。
- サードパーティのパートナーや分析ソリューションとの互換性を保つために、Singularはカスタムイベント名と属性を英語で渡すことを推奨します。
- イベント名は32 ASCII文字までに制限されています。非ASCII文字の場合、UTF-8に変換すると32バイトになります。
- イベントの属性と値は500 ASCII文字に制限されています。
収益
Singularはゲームを通して得た収益に関するデータを収集し、キャンペーンのパフォーマンスやROIの分析に役立てることができます。Singularはレポート、ログエクスポート、ポストバックでデータを利用できるようにします。
収益イベントをトラッキングするには、すべてのイベントに使用するのと同じイベント通知エンドポイントを使用しますが、以下の情報を追加します：
- is_revenue_event=true：イベントを収益イベントとしてマークします。イベント名が"__iap__"であるか、金額がゼロより大きい場合は、このパラメータを省略できます。
- 収益金額（例："amt=1.99"）。
- 通貨（ISO 4217の通貨コードを使用、例："cur=USD"）。