Skip to main content

Getting Started with GameAnalytics tvOS SDK

This guide explains how to integrate the GameAnalytics SDK into your tvOS project.

tip

Stay updated with the latest changes by checking the GameAnalytics tvOS SDK Changelog.

1. Before you start​

1.1. Pre-requisites for using the SDK​

  • Xcode (14.0 or newer)
  • CocoaPods (if using CocoaPods for installation)

1.2. Supported platforms​

The tvOS SDK supports the following:

  • tvOS 12.0 and above

2. Install the SDK​

Choose the installation method that best suits your project.

2.1. Using CocoaPods​

Add the following to your Podfile:

target '[YOUR-GAME-PROJECT-NAME]' do
  pod 'GA-SDK-TVOS', '~> 4.11.0'
end

Run the following command in the terminal:

pod install

Open the .xcworkspace file generated by CocoaPods and use it going forward.

caution

When installing through CocoaPods, you should not manually add dependency frameworks/libraries.

3. Configure the SDK​

3.1. Add Required Frameworks and Libraries​

In the "Build Phases" section of your Xcode project, add the following to "Link Binary With Libraries":

  • AppTrackingTransparency.framework (only required for Xcode 12 and higher)
  • AdSupport.framework
  • SystemConfiguration.framework
  • libsqlite3.tbd
  • libz.tbd
  • libGameAnalytics.a (if using static files)

In the "Build Settings" section, add the following to "Other Linker Flags":

  • -lC++

3.2. Swift Setup​

If you are using Swift, create a bridging header file (e.g., GameAnalytics-Bridging-Header.h) and add the following line:

#import "GameAnalytics/GameAnalytics.h"

In the "Build Settings" section, locate "Objective-C Bridging Header" and add the path to your bridging header file.

3.3. SDK Quick Configuration Guide​

Example of a quick configuration:

// Enable log
GameAnalytics.setEnabledInfoLog(true)
GameAnalytics.setEnabledVerboseLog(true)
GameAnalytics.configureAutoDetectAppVersion(true)

let fields: [String: Any] = [
    "test": 666,
    "test_2": "global_hello_world"
]
GameAnalytics.setGlobalCustomEventFields(fields)

// Set user ID
GameAnalytics.configureUserId("userId12345")

// Configure available resources and dimensions
GameAnalytics.configureAvailableResourceCurrencies(["gems", "gold"])
GameAnalytics.configureAvailableResourceItemTypes(["boost", "lives"])
GameAnalytics.configureAvailableCustomDimensions01(["ninja"])

// Set custom dimension (persists across sessions)
GameAnalytics.setCustomDimension01("ninja")

// Initialize SDK
GameAnalytics.initialize(withGameKey: "gameKey", gameSecret: "secretKey")

4. Initialize the SDK​

From tvOS 14+, the SDK tracks IDFA consent status. Ensure you show the IDFA consent dialog before initializing the SDK. Example:

if (@available(tvOS 14, *)) {
    if ([ATTrackingManager trackingAuthorizationStatus] == ATTrackingManagerAuthorizationStatusNotDetermined) {
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
            [GameAnalytics initializeWithGameKey:@"YOUR_GAME_KEY" gameSecret:@"YOUR_SECRET_KEY"];
        }];
    } else {
        [GameAnalytics initializeWithGameKey:@"YOUR_GAME_KEY" gameSecret:@"YOUR_SECRET_KEY"];
    }
} else {
    [GameAnalytics initializeWithGameKey:@"YOUR_GAME_KEY" gameSecret:@"YOUR_SECRET_KEY"];
}

If IDFA is not required, you can skip showing the consent dialog (requires SDK v4.4.14 or later).

info

The GameAnalytics tvOS SDK uses IDFV as the user id and it will only add IDFA to events if IDFA consent status is authorized.

4.2. Initialization​

Call the initialize method with your Game Key and Secret Key:

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

5. Sending Events​

Example:

GameAnalytics.addDesignEvent(withEventId: "testEvent")
GameAnalytics.addBusinessEvent(withCurrency: "USD", amount: 100, itemType: "boost", itemId: "super_boost", cartType: "shop")
GameAnalytics.addResourceEvent(withFlowType: .source, currency: "gems", amount: 10, itemType: "lives", itemId: "extra_life")
GameAnalytics.addProgressionEvent(withProgressionStatus: .start, progression01: "progression01", progression02: "progression02")