Skip to main content

Getting Started with GameAnalytics iOS SDK

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

tip

Stay updated with the latest changes by checking the GameAnalytics iOS 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 iOS SDK supports the following:

  • iOS 12.0 and above

2. Install the SDK​

Choose the installation method that best suits your project.

2.1. Using Swift Package Manager​

Add the GameAnalytics SDK to your project using Swift Package Manager:

  1. In Xcode, go to File > Add Packages.
  2. Enter the following URL: https://github.com/GameAnalytics/GA-SDK-IOS.
  3. Select the version you want to use and add the package to your project.

Once added, import GameAnalytics as follows:

For Swift projects:

import GameAnalytics

For Objective-C projects:

#import <GameAnalytics/GameAnalytics.h>

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 iOS 14+, the SDK tracks IDFA consent status. Ensure you show the IDFA consent dialog before initializing the SDK. Example:

if (@available(iOS 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 iOS 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")