Skip to main content

Setup

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.

Framework​

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

info

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.

target '[YOUR-GAME-PROJECT-NAME]' do
  pod 'GA-SDK-TVOS'
end

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.

tip

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

Limitations​

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.

Integration​

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.

tip

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

Configuration​

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​

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)
GameAnalytics.configureUserId("user1234567879")

Specifying Allowed Values​

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

caution

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.

danger

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"]);

info

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:

GameAnalytics.setEnabledEventSubmission(false);
info

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.

Initialization​

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

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

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)
    GameAnalytics.setEnabledInfoLog(true)
    GameAnalytics.setEnabledVerboseLog(true)

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

    // 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;
}