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.

Using Swift Package Manager

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>

Using CocoaPods

2.2. Using CocoaPods

Add the following to your Podfile:

target '[YOUR-GAME-PROJECT-NAME]' do
  pod 'GA-SDK-IOS', '~> 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.

Using Framework

2.3. Using the Framework

Download the iOS SDK from the GameAnalytics iOS SDK releases page.

Add the GameAnalytics.framework to your Xcode project.

When using the framework, import GameAnalytics as follows:

#import <GameAnalytics/GameAnalytics.h>

Using Static Files

2.4. Using Static Files

Download the iOS SDK from the GameAnalytics iOS SDK releases page.

Add the following files to your Xcode project:

• GameAnalytics.h (Required header file containing methods for GameAnalytics)
• libGameAnalytics.a (Required static library for GameAnalytics)

info

Make sure to select "Copy items if needed" when adding the files to your project.

---

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:

Swift

// 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")

Objective-C

// Enable log
[GameAnalytics setEnabledInfoLog:YES];
[GameAnalytics setEnabledVerboseLog:YES];

[GameAnalytics configureAutoDetectAppVersion:YES];

NSMutableDictionary *fields = [[NSMutableDictionary alloc] init];
fields[@"test"] = @666;
fields[@"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 initializeWithGameKey:@"gameKey" gameSecret:@"secretKey"];

---

4. Initialize the SDK

4.1. IDFA Consent Status

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:

Swift

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

Objective-C

[GameAnalytics initializeWithGameKey:@"game key" gameSecret:@"game secret"];

---

5. Sending Events

Example:

Swift

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

Objective-C

[GameAnalytics addDesignEventWithEventId:@"testEvent"];
[GameAnalytics addBusinessEventWithCurrency:@"USD" amount:100 itemType:@"boost" itemId:@"super_boost" cartType:@"shop"];
[GameAnalytics addResourceEventWithFlowType:GAFlowTypeSource currency:@"gems" amount:10 itemType:@"lives" itemId:@"extra_life"];
[GameAnalytics addProgressionEventWithProgressionStatus:GAProgressionStatusStart progression01:@"progression01" progression02:@"progression02"];

---