Web Measurement SDK (Self-Distribution)

This document will walk you through integrating the Gamesight Web SDK into your website/storefront for your self-distributed games which enables full funnel visibility and insights.

1. Generate Web SDK API Key

The first step in the Web SDK integration is generating your Web SDK API Key. Each game will use its own, individual/unique, API Key. This is different from the Measurement API Key, but it is generated the same way. You can find your Web SDK API Key in your Gamesight console dashboard under Settings > In-Game Integration.

2. Initialize the Web SDK

The below JavaScript Snippet will need to be inserted onto your website/storefront landing page for your self-distributed game(s). Initializing the Web SDK on your landing page helps Gamesight stitch together marketing touchpoint interactions with events that occur on your website.

You can access your Web SDK snippet from the Settings page in Gamesight, under Game > In-Game Integrations as shown below.

If you do not have access to this page, please contact an Admin for your Game so they can grant you the "Game Integrator" permissions.

If you do not have access to this page please contact an Admin for you Game so they can grant you the "Game Integrator" permissions.

3. Send Web Events

It is important to consider sending events for relevant data points during the user flow. For example, if you distribute on multiple storefronts (including self-distribution), you can send an event each time a user clicks on a specific storefront link. This will enable you to collect aggregate "click-outs to storefront" data by storefront (Steam, self-distributed, etc.). The send method below can be utilized in this scenario:

gsght('send', 'click_storefront_steam');

Login/Account Creation (Optional)

📘

Company-wide Player Accounts

When self-distributing games, it is common to have a company-wide account system that shares an ID between multiple games. If you have such an ID, please reach out to support and we can whitelist your account to use shared IDs. Attaching the shared ID to your events will improve the accuracy of attribution for all of your games.

Many self-distributed games feature account systems. Users typically register for in-game accounts on your webpage. If you have this feature implemented for your game and website, you can capture details of user account systems in Gamesight. This allows for deterministic values to be provided to Gamesight for increased attribution accuracy.

gsght('set', 'user_id', [
  // REQUIRED for Events: use this id type for your in-game user id
  {type: 'user_id', id: 'in_game_user_id'},

  // Optional: Link external game ids for things like company-wide accounts
  {type: 'MY_ID_TYPE', id: 'my_own_network_id', scope_type:'company', scope_id:'My Company'},
])

Generic User IDs

If no account system exists for your title, you should provide Gamesight with a generic user ID. By providing Gamesight with a unique User ID for each player, we can provide:

• More accurate reporting by preventing "double counting" of game sales
• Enable your BI team to tag users in your data warehouse based on their attributed referral source
• Advanced reports on user journeys and flows from web to game client and back
• Improved debugging experiences and visibility into the event stream.

Requirements for User IDs

Here are some important considerations when selecting your User ID value:

• Unique - Each user must get a unique User ID
• Consistent - The User ID must be consistent between game sessions
• Meaningful - The ID should be a value related to other metrics your BI team is already recording internally.
• Private - To protect users, the User ID value mustn't be personally identifiable to people outside of your company. This means avoiding public identifiers like email addresses or usernames.

To meet these requirements, we recommend using some internal Account ID. In the past, we have seen success with values such as uniquely hashed Steam IDs, game-specific account ids, or UUIDs that are associated with in-game accounts through a lookup table.

Purchase Events

For premium games, you will want to record purchase events that occur on your domain. You can send purchase events using the Gamesight web SDK. Revenue data can be passed with the event or, optionally, set up within the Goals menu on the Gamesight console. You can read more about configuring goal revenue inside the Gamesight platform here.

gsght('send', {
  // A name for this type of event.
  type: 'purchase',
  
  // All parameters below are optional
 
  // Unique transaction ID that is used for deduplicating events, commonly used to ensure idempotency with purchase events. Gamesight enforces that only 1 event will be processed per transaction_id.
  transaction_id: '123456-12345-234234-234234',
  
  // Revenue related info about this event
  revenue_amount: '1.23',
  // the type of currency used when calling this event
  revenue_currency: 'usd',
  
  // specify the platform type
  platform: 'web',

})

Downloads on Self-Distributed Platforms

You can measure the download event using the Gamesight web SDK for free-to-play games that don't include an initial purchase event. This will give you down-funnel visibility into how many users that interact with a marketing touchpoint are downloading the game.

gsght('send', 'download');

Session ID Matching (Optional)

Deterministic attribution can be achieved through a user account system or session ID matching. By ensuring that the Session ID used throughout the user flow is passed to the launcher during the download process, Gamesight can perform session ID matching.

📘

Attribution Methods for Self-Distribution Platforms

You have several advantages for attribution when using the self-distributed model. Account systems and Session IDs offer the possibility of deterministic matching. If there is no account system in place and session ID matching isn't feasible, Gamesight will fall back to fingerprinting methods to attribute your customers to your marketing touchpoints. You can read more about our available Attribution Methods here.

When a user is downloading your game using your self-distributed model, you can pull the Session ID and push this value into the download package to be provided with the executable. This can be called by using the gsid identifier. You can set the session ID in Gamesight with:

const session_id = gsght('get','gsid')

The Session ID should then be included as an additional identifier for the in-game event sent to Gamesight via an S2S API call using the measurement API. You can see an example of this in the section below.

4. In-Game Integration

Now you can start sending in-game events to the Gamesight platform. Gamesight requires an event payload with relevant device identifiers for attribution. You can read more about our Measurement API here for the in-game integration and event handling.

curl --request POST \
     --url https://api.ingest.marketing.gamesight.io/events \
     --header 'Accept: application/json' \
     --header 'Authorization: 893XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
     --header 'Content-Type: application/json' \
     --header 'X-Api-Version: 1.1.0' \
     --data '
{
     "type": "game_launch",
     "user_id": "user123",
     "identifiers": {
          "os": "Windows 7",
          "resolution": "1920x1080",
          "language": "en",
          "platform": "self-distributed",
          // Optional data point used for Session ID Matching
          "gsid": "session_id"
     },
     "ip": "172.123.245.14",
     "revenue_currency": "USD",
     "revenue_amount": 0
}
'

The platform identifier should be set to something that makes sense for your team.

In this case, as a self-distributed platform, this field can be considered an open input. Use a consistent identifier (such as self-distributed) that most clearly identifies the platform.

For more information or help planning your Gamesight integration, contact us through live chat or email us at [email protected]