Skip to main content


Download & Installation

You can download the latest version from the Github Repository.

Static Files

These 2 files are placed inside the Library folder. Add them to your Xcode project and select to ‘copy the files’ into your project.

  • GameAnalytics.h -> Required header file containing methods for GameAnalytics.
  • libGameAnalyticsTVOS.a -> Required static library for GameAnalytics.


The framework is called GameAnalytic.framework. Add this to your project. When using the Framework it is needed to use the following when importing GameAnalytics:

#import <GameAnalyticsTVOS/GameAnalytics.h>;

CocoaPods Installation

You can install GameAnalytics via CocoaPod


The CocoaPod will install the Framework version of the SDK.

Update your Podfile (in your project directory) with this information using your project name and the current SDK version released.


Run this command from the terminal in the Podfile folder:

pod install

In Xcode open the .workspace file generated by the pod installation and use that going forward.


When installing through CocoaPods you should not have to add dependency Frameworks/libraries manually.


tvOS does not have a persistent reliable local storage like on iOS devices. This affects how the SDK will behave compared to iOS.

Key/Value Storage

The iOS SDK will store certain key/values across sessions using a local database. As this cannot be done on tvOS the SDK is using the NSUserDefaults. The following fields are used when needed.

  • ga_tvos_dimension01
  • ga_tvos_dimension02
  • ga_tvos_dimension03
  • ga_tvos_gender
  • ga_tvos_fb
  • ga_tvos_birthyear
  • ga_tvos_session_num
  • ga_tvos_transaction_num

Event Queue

The SDK will queue events in a memory database (instead of a file on iOS) and send these periodically in a low priority thread.

If the device is offline it will gather these events in memory until a connection is established. If the device does not come online before the app is stopped then these events will be lost.

As most AppleTVs will be fixed at either being offline or online it should work fine.

Progression event attempt counts

It is not possible to count unique progression attempts on tvOS due to the limitations on local storage and the nature of NSUserDefaults. This will result in Level Attempts metrics being displayed inaccurately in our tool.

XCode Configuration

To use the SDK in Xcode it is needed to add both the SDK library and it’s dependencies. In the “Build Phases” section add the following to “Link Binary With Libraries”.

  • `AdSupport.framework
  • `SystemConfiguration.framework
  • `libsqlite3.tbd
  • libz.tbd
  • libGameAnalyticsTVOS.a

In the “Build Settings” section add the following to “Other Linker Flags”:

  • -lC++

Swift Setup

To use the SDK in a Swift project it is needed to add a bridging header. But don’t worry – this is very easy.

Create a header file called GameAnalytics-Bridging-Header.h and add this line:

#import "GameAnalytics.h"

In the Build Settings for the Xcode Swift project locate the section called “Swift Compiler – code generation” and the field “Objective-C Bridging Header“.

Add a link to the GameAnalytics-Bridging-Header.h file. It should now work in Swift throughout the project.


Now we are ready for adding code to activate the SDK! Be aware of the following 3 phases:

  • Configuration
  • Initialization
  • Adding events or changing dimensions

The configuration and initialization steps should be called inside the common iOS method applicationDidFinishLaunchingWithOptions located in the AppDelegate class.

Once step 1 & 2 is done you can add events at different parts of the game code where some relevant action is happening.


Remember to import the GameAnalytics.h file whenever you need to call the SDK.


The configuration phase happens before initialisation is called. The available configuration options are listed here.

  • build
  • user id
  • available (allowed) custom dimensions
  • available (allowed) resource currencies
  • available (allowed) resource item types


Build is used to specify the current version of your game. Specify it using a string. Recommended to use a 3 digit version like [major].[minor].[patch]:

// Set build version (Swift)
GameAnalytics.configureBuild("alpha 0.1.0")

User ID

The SDK will automatically generate a user id and this is perfectly fine for almost all cases. Sometimes it is useful to supply this user_id manually – for example if you download raw data for processing and need to match your internal user id (could be a database index on your user table) to the data collected through GameAnalytics. Note that if you introduce this into a game that is already deployed (using the automatic id) it will start counting existing users as new users and your metrics will be affected.

Use this from the start of the app lifetime:

// Set custom user id (Swift)

Specifying Allowed Values

For certain types it is required to define a whitelist containing possible unique values during the configuration phase.


When the SDK is being used (after initialization) only the specified values will be allowed. A maximum of 20 values are allowed for each list.


Processing many unique dimension values can be taxing for our servers. A few games with poor implementation can seriously increase cost and affect stability. Games will be blocked if they submit too many unique dimension values. We have this configuration requirement to guide users into planning what dimension values can be used.

GameAnalytics.configureAvailableResourceCurrencies(["gems", "gold"]);
GameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"]);

// Set available custom dimensions
GameAnalytics.configureAvailableCustomDimensions01(["ninja", "samurai"]);
GameAnalytics.configureAvailableCustomDimensions02(["whale", "dolphin"]);
GameAnalytics.configureAvailableCustomDimensions03(["horde", "alliance"]);


Each resource currency string should only contain [A-Za-z] characters.

Event Submission

You can disable event submission (for example if the user denies permission), you can use the following function:


By default event submission is of course enabled. You will still receive configs if you have set any for your game even after disabling event submission.


After setting up your desired configuration you can finally initialize GameAnalytics.

// Initialize (Swift)
GameAnalytics.initialize(withGameKey: "game key", gameSecret: "secret key")

Don’t have any keys yet? Head over here and register your game at the GameAnalytics website!

Once initialize is called it will start the first session and automatically handle session changes based on activity events.

The code snippet below will exemplify how you could configura and initialize GameAnalytics inside your AppDelegate class:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

// ... other code from your project ...

// Enable implementation log (disable in production)

// Set build version

// Set available virtual currencies and item types
GameAnalytics.configureAvailableResourceCurrencies(["gems", "gold"])
GameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"])

// Set available custom dimensions
GameAnalytics.configureAvailableCustomDimensions01(["ninja", "samurai"])
GameAnalytics.configureAvailableCustomDimensions02(["whale", "dolphin"])
GameAnalytics.configureAvailableCustomDimensions03(["horde", "alliance"])

// Initialize
GameAnalytics.initialize(withGameKey:"[game key]", gameSecret:"[secret key]")

return true;