PC and Console game attribution is an enterprise feature. To learn more about this feature, read our PC and Console Game Attribution FAQ or reach out to your Customer Success Manager.
Singular provides a REST API that can be used to report all your PC and Console game conversion data to Singular for analytics and attribution.
This guide explains how to build a PC & Console S2S integration with Singular and implement various optional features.
Integration Concepts
This section details important overarching concepts that are important to implementing a feature complete PC & Console S2S integration.
For a full list of the S2S API endpoints, their parameters, and sample calls, see the PC & Console S2S Endpoint Reference.
User Privacy
In order to preserve user privacy, Singular recommends that game developers offer an option for end-users to opt-in or opt-out to tracking. Depending on your businesses' requirements for handling user data, you may:
- Not send game event data to Singular on opt-out
- Send game event data to Singular, but include the opt-in and opt-out consent choices of the user. In these cases, implement and pass this consent flag through the "Limit Data Sharing" value in the data_sharing_options parameter.
Singular uses "Limit Data Sharing" in "User Privacy Postbacks" as well as passing this information on to partners who require it in order to comply with relevant regulations. See "User Privacy and Limit Data Sharing" for more information.
Authentication
All requests to Singular's PC & Console S2S API require an SDK key to be sent in the "a=" parameter. Your Singular SDK key can be found under "Developer Tools -> SDK Integration > SDK Keys" in your Singular dashboard.
Warning: Do not use the Singular "API key" found in "Developer Tools -> API Keys". The "API key" is separately used for Singular's Reporting API.
Supported Platforms, Game Systems, and Stores
The "Platform" in Singular is defined as the "platform" where the user plays the game, and must be passed in the "p=" parameter on all S2S API requests. A closed list of supported "platform" values is below:
- pc
- xbox
- playstation
- nintendo
- metaquest
In addition to "platform", the "operating/game system" and "store" should be passed in the "os=" and "install_source=" parameters, respectively. Custom values are supported, but Singular recommends the following values by platform:
| Platform (p=) |
Operating/Game System (os=) |
Store (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 |
Game Identifier
In order for Singular to associate game events with a game, a game identifier must be passed in the "i=" parameter on every request.
- Any value can be supported, but Singular recommends the value be passed in reverse DNS notation (i.e. com.singular.game)
- If your game is available on multiple platforms, it is required that the same game identifier be used for the same game across the supported platforms (i.e. p=pc&i=com.singular.game, p=xbox&i=com.singular.game, p=playstation&i=com.singular.game)
- In order for Singular to properly attribute game conversions to web campaigns driving through a website landing page, your Singular web integration's "product ID" must match the game identifier value as well.
Identifying Unique Game Installs
In order for Singular to associate game events throughout multiple game sessions for the same game install, an installation/device identifier must be passed in the "sdid=" parameter on every request.
- Recommended UUID (Version 4) format
- Value should be generated by the game/server at the moment of the first game launch (install), and persist throughout the life of the game installation.
Match ID (Optional)
If your game's web campaigns drive users to a web landing page and you can utilize "match ID" for website -> PC/Console game attribution, you can optionally pass the "match ID" in the "match_id=" parameter to improve attribution accuracy. Read more about PC & Console attribution in our FAQ on the topic.
- In order for install attribution to use the "match ID", it must be passed on the first game launch for the user.
- "Match ID" must match the same value user in your Singular web SDK implementation
Important: Utilizing the match ID for attribution is considered an advanced feature. Consult with your Singular Solution Engineer before implementing.
Reporting Game Launches
Reporting all game sessions to Singular is required in a PC & Console integration and expects that game sessions are sent each time the game is launched.
To notify Singular about a game session, call the Session Notification Endpoint.
Session notifications allow Singular to do several things:
- If it's the first game session after a unique install (see Identifying Unique Game Installs), Singular recognizes a new install and triggers the install attribution process.
- (Coming soon) If the game session qualifies as a re-engagement session, Singular triggers the re-engagement attribution process (learn more in the Re-engagement FAQ).
- Otherwise, Singular marks it as a game session, which is used to track user activity and retention.
Tip: When you collect the data to report a game session, be sure to wait for asynchronous functions to return and handle various functionality. For example:
- When using Match ID to improve attribution matching, it is important to report the first game session only after the Match ID is potentially available. See Match ID.
- If your game provides a way to opt-in to Singular's marketing and game analytics, it is important to wait until consent is collected before reporting the game session. See User Privacy.
Reporting In-Game Events
Events
Singular can collect data about in-game events to help analyze the performance of your marketing campaigns. Events can include any user interaction from logins and registrations to leveling up in the game.
Before you implement an S2S integration with Singular, you should have a list of the events your organization wants to track (see Defining In-Game Events).
To notify Singular when an event occurs in your game, call the Event Notification endpoint. The event name you include in the call is how the event will be identified in Singular reports, exports, and postbacks.
Notes:
- Singular recommends passing events using Singular's standard event and attribute naming convention. Using standard events streamlines mapping and compatibility with your partners standard events in integrations.
- Singular recommends passing custom event names and attributes in English for compatibility with any third-party partners and analytics solutions you may want to use.
- Event names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.
- Event attributes and values are limited to 500 ASCII characters.
Revenue
Singular can collect data about revenue gained through the game to help analyze the performance and ROI of your campaigns. Singular will make the data available to you in reports, log export, and postbacks.
To track revenue events, use the same Event Notification endpoint that you use for all events, but add the following information:
- is_revenue_event=true: This marks the event as a revenue event. You can skip this parameter if the event name is "__iap__" or the amount is larger than zero.
- Revenue amount (e.g., "amt=1.99").
- Currency (use the ISO 4217 currency code, e.g. "cur=USD").