Skip to main content

Telemetry Events

🔹 Tools to use: Big Fish Telemetry Services, BFG SDK

What is Telemetry?​

Telemetry is the process of collecting and transmitting data from one source to another. In the gaming industry, telemetry data is used to monitor and track how players interact with various parts of the game, such as clicking on ads or reading messages. In addition, you can collect data about the player's mobile device, operating system, and more.

By integrating the BFG SDK, your game will automatically collect game-specific data such as install events, purchases, and session times. In addition, you can create custom events directly from the SDK.

If you need more customization than the BFG SDK methods offer, the Game Telemetry Service (GTS) API is available so that you can configure the telemetry events you capture with REST API calls.

Both methods transmit data to AppsFlyer, GoGame, and any other data collection tools you have integrated into your game. This data can be used to analyze:

  • Campaigns and advertisements for the user
  • Tracking install/uninstall rates
  • A/B testing
  • Collecting sales data

In addition, Big Fish's telemetry services help developers debug technical issues and track key performance indicators (KPIs).

Understanding Telemetry Events​

Big Fish's telemetry services collect and transmit data in the form of telemetry events. Telemetry events are actions that are performed at a specific moment in time. Together, all the events create a comprehensive history of a player's actions, providing valuable insights for analyzing their behavior and play patterns.

By default, every game will automatically collect the following telemetry events:

Telemetry EventDescription
InstallThis event fires automatically only on the application's first launch and after the SDK has finished initializing.

NOTE: AppsFlyer has its own install event that is sent on the first launch of the application. This is not the same as the default install event in the Big Fish Telemetry Services. AppsFlyer's install event is gated behind both the General Data Policy Regulation (GDPR) and App Tracking Transparency (ATT) selection.
Session StartThis event fires every time the app returns to foreground.
Session EndThis event fires every time the app goes to background.
PurchaseThis event fires whenever a successful purchase or restore is made.
warning

The expected order of events is: Install, Session Start, Purchase, Session End. This order can differ from expected in the following edge cases:

  • Disabled internet connection which causes the Install event to be queued.
  • A general timeout of 60 seconds before the Install event can be fired.

Creating Custom Events with the BFG SDK​

Custom telemetry events let you record data that is not included in the default events described above. Examples of custom events include when a user levels up, collects an item, or completes an in-game event. Work with your Big Fish producer to identify which custom events are relevant for your game.

To create a custom event with the BFG SDK, use the bfgGameReporting.logCustomEvent method (Unity | Android | iOS). The following code sample demonstrates how to set up a custom telemetry event using the BFG SDK:

{
    Dictionary<string, string> additionalDetails = new Dictionary<string, string> ();
    additionalDetails.Add ("customKey", "customValue");
    bfgGameReporting.logCustomEvent("eventName", additionalDetails);
}

Custom events contain several key-value pairs that help sort and filter your data. These keys include:

  • event_name (e.g. details1 in the logCustomEventSerialized method)
  • name
  • details2
  • details3
  • result
  • value

Depending on what the event pertains to, the key values can differ. The following table shows some examples of data that might be sent:

Triggerevent_namenamedetails2details3resultvalue
Player completes a FTUE stepFTUENUXswipe_bomb300end
Player completes level 3 and winsprogresslevelworld_13win
Player completes level 3 and losesprogresslevelworld_13fail
Player unlocks a new characterprogresscharacterpaul_bunyanunlock
Player spends coins on a boostereconomy*storebooster

Economy events contain a collect and/or spend JSON that details all the items sunk and sourced in that transaction.

We recommend that you attach a variety of data points to your custom events, such as:

  • User stats at the time of the event
  • Wallet balances
  • In-game location and details about the location (for example, the designed win rate of the level the player just completed)
  • Player flags
  • End-of-content flags

Using the Game Telemetry Service API​

Getting started with the GTS API​

As you begin working with the GTS API, complete the following steps to get started:

  1. Obtain an API key to allow telemetry data to be successfully sent. You can obtain an API key by reaching out to your Big Fish producer or engineering partner.
  2. Implement the OpenAPI Spec by either:
    • Downloading the OpenAPI Spec ↗️ into your server either programmatically or manually. You can find the OpenAPI spec by clicking /gts/v3/api-docs under the GTS Events API ↗️
    • Implementing your own REST API calls to interface directly with the endpoints that the GTS API provides

Once you have your API key and the OpenAPI Specification implemented, you are ready to create your custom events using the GTS API.

Creating a custom schema​

info

Creating a custom schema is not required, but we highly recommend this process to ensure data consistencies. Custom schemas will be created and implemented during the onboarding of your game with the GTS API.

When using the GTS API, you need to create a new JSON schema for every custom event you'll use. The schema will serve as a validator, checking the fields of the payload to ensure they meet the correct format and constraints.

Your custom schema should match the latest JSON Schema Specification ↗️. Additionally, your schema must define a payload p object and optionally, an additive a object.

In your custom schema, any code to track additional data that is not captured by the payload (d) or additive data (a) will replace the # INSERT CUSTOM SCHEMA DEFINITION HERE in d.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://storage.googleapis.com/gts-json-schema-sandbox/events/sampleGame/sampleEvent/2.0.0/schema",
  "type": "object",
  "properties": {
    "p": {
      "description": "Payload",
      "type": "object",
      "$ref": "https://storage.googleapis.com/gts-json-schema-sandbox/events/standard/common/2.0.0/payload.json"
    },
    "a": {
      "description": "Additive data",
      "type": "object",
      "$ref": "https://storage.googleapis.com/gts-json-schema-sandbox/events/standard/common/2.0.0/additive.json"
    },
    "d": {
      # INSERT CUSTOM SCHEMA DEFINITION HERE
    }
  },
  "required": [
    "p"
  ],
  "additionalProperties": false
}

For examples of a payload and additive JSON, see payload.json ↗️ and additive.json ↗️ schemas.

Once the custom schema is created, it is added to the telemetry service. This schema will be referenced by game and event type.

Creating a custom event with the GTS API​

When creating a custom event with the GTS API, you will make REST API calls to the endpoints created during onboarding. Making these REST API calls require you to have the eventType, appName, and version to construct the URL endpoint. The follow code sample demonstrates what an endpoint would look like:

/events/{eventType}/{appName}/{version}

You can make a REST API calls with the following sample JSON and/or curl commands:

{
  "p": {
    "aupid": "41a16190651d4179be277133fe48f116",
    "aupn": "rave",
    "aus": "authenticated",
    "apn": "sampleGame",
    "et": "sampleEvent",
    "tsc": 1440455083,
    "bfgudid": "8b3fe1e989711b783de00f43c81e6bd4214ae115",
    "apuid": "827367477",
    "plt": "ios",
    "apv": "1.1",
    "apbv": "78676",
    "sid": "d839ac578a674d04b9ae989ba9467f29",
    "psid": "c42a78f0d0d74dcca4e7856ea5eef664",
    "lc": "en-US",
    "bfsv": "06000100",
    "ceid": "222C2020-3AEA-4069-A2DD-08002B30309D",
    "aps": "itunes",
    "apsid": "123456789",
    "bid": "com.sampleGame.myGame",
    "dvi": {
      "ios": {
        "gcid": "e000e8b1494fc74dcd6135323fcc191a99233394",
        "ifa": "ABBBB3A0-13F8-4B68-AC0E-3B657CF7317E",
        "ifae": 1,
        "idfv": "CCCCC3A0-13F8-4B68-AC0E-3B657CF7317E",
        "aptts": 1,
        "tpte": 1,
        "pe": 0
      },
      "dvattr": {
        "pt": "mobile",
        "sr": "768x1024",
        "osi": "iPhone OS",
        "osv": "7.1.1",
        "dvc": "Verizon",
        "dvm": "iPhone6,1",
        "dvb": "iPhone",
        "dvidm": "phone"
      }
    }
  },
  "d": {
    "name": "John",
    "level": 27
  }
}

If the request is successful, you will receive a response code of 200. For all other response codes, see GTS Events API ↗️.

{
  "code": 200,
  "message": "accepted",
  "requestId": "1595b8efccfb049a1dd587dd6beec99a"
}

You can test your schemas and requests, and view all possible response codes with the GTS Events API ↗️.

To look up data and events that are sent to the telemetry service, use the Event Viewer in the Publisher Portal ↗️.

info

Access to the Publisher Portal requires an OKTA account. Contact your Big Fish producer after the game has been onboarded into the Big Fish Games platform.

Connecting the GTS API with GoGame​

By design, the GTS API and GoGame are not connected and require GoGame provisioning for your game. Contact the User Acquisition team to be onboarded to GoGame and be provisioned with the appropriate GoGame codes needed for your game. The telemetry service requires the GoGame ID and codes provisioned to your game in order to send REST API calls to GoGame. All GoGame calls from the telemetry service are done through Custom Events, one for every GoGame code provisioned or needed by your game.

Working with the Analytics Team​

The analytics team are experts in the standard taxonomy, the data pipeline, and the Looker dashboards. When you are ready to implement custom events, contact the analyst(s) assigned to your project or reach out to your Big Fish producer to make that connection.

The analyst will need a playable build of the app to understand the game and ensure they are tracking all the important features. While Big Fish Games has a lot of standardized code, each game has unique aspects that should be captured.

The analyst, product team, and other key stakeholders will collaborate to document the questions that need answering as the game develops. With these questions in hand, the analyst will create a telemetry document that serves as the definitive guide for data implementation. Developers should follow this document precisely. If any issues or questions arise, they should be discussed with the analyst to reach a satisfactory resolution.

The analyst will work with a QA team (yours or Big Fish Games) to verify that the events trigger when expected and the data is formatted correctly. Note any issues and confirm the implementation in the taxonomy document.

Standardizing Taxonomy​

Standardized telemetry allows the engineering and analytics teams to quickly onboard new games, avoiding the need to write custom code for each game. By sending data via our telemetry services in the format described here, more time can be spent helping uncover insights and less time troubleshooting code to build the pipeline.

Common asks from the Big Fish team may include changing all the keys to snake_case, changing the key “arena” to the more generic term “world”, or pluralizing a specific key.

Examining Telemetry Data​

Big Fish Games uses three tools to display, analyze, and respond to incoming telemetry data:

  • Snowflake is a data warehouse tool that helps organizations store, manage, and analyze large volumes of data from various sources.
  • New Relic is an infrastructure monitoring tool, providing real-time visibility into the system's performance and operations.
  • Looker is a business intelligence tool that lets analysts explore data sets and share insights from the data.

Big Fish Games uses a Data Build Tool Cloud (dbt) service to manage the process of extracting data and transferring it to our data warehouse (Snowflake). Once the data is transferred, Snowflake displays a standard set of tables related to economy measures, progression, user stats, FTUE, and more. If your data is not part of one of the standard tables, Big Fish will build additional tables to display your data.

Many of the Snowflake tables can be viewed in various Looker Explores, which allow an analyst to investigate the data themselves. Additionally, the Big Fish data engineering team will create a series of Looker dashboards to help you monitor your game activity and understand your game's overall health.

Big Fish Games sends metrics to New Relic, which allows our Incident Response Team to monitor game KPIs in near real-time. This setup is used to trigger alerts for game health metrics. If an alert is activated, an escalation process will be initiated to address any game outages.