Skip to main content

Setup

Download & Installation​

These files contain both a static library and a framework. You can use any of the following methods below to add it to your project (whichever method better suits your project).

You can download the iOS SDK GitHub Repository from here.

Using Static Files​

There are 2 files that need to be places placed inside the Library folder:

  • GameAnalytics.h -> Required header file containing methods for GameAnalytics.
  • libGameAnalytics.a -> Required static library for GameAnalytics when not installing via Cocoapods
  1. Add these 2 files to your Xcode project.
  2. Select to copy the files into your project.

Using the Framework​

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

#import <GameAnalytics/GameAnalytics.h>

Using CocoaPods​

Find our registered pod here. If you have not used pods before, then it is recommended to go to cocoapods.org and read more about it.

Our 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-IOS', '~> 2.2'
end

Afterwards 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.

caution

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

Configure XCode​

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” for Xcode7 (using .tbd libraries):

  • AppTrackingTransparency.framework (only required for XCode 12 and higher)
  • AdSupport.framework
  • SystemConfiguration.framework
  • libsqlite3.tbd
  • libz.tbd
  • libGameAnalytics.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/GameAnalytics.h"

In the Build Settings for the Xcode Swift project locate the section called “Swift Compiler – General” 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.

From iOS 14+ devices the SDK will track IDFA consent status on all events. To track this properly you need to make sure you have shown the IDFA consent dialog before initializing the SDK. This could be done with the following code (shown in Objective-C but hopefully you get the idea what the pattern should look like):

*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 you don't need to use IDFA and you don't have any third party SDKs that need to use IDFA then you don't need to show the IDFA consent dialog (you need to use v4.4.14 or later of the iOS SDK). The GameAnalytics iOS SDK uses IDFV as the user id and it will only add IDFA to events if IDFA consent status is authorized.

Initialize the SDK​

Now we should be ready for adding code to activate the SDK! Follow the below steps:

  • Configuration
  • Initialization
  • Adding events or changing dimensions
info

The configuration and initialization steps should be called inside the applicationDidFinishLaunchingWithOptions method from the AppDelegate class.

Once steps 1 & 2 are 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:

using GameAnalyticsSDK;

Configuration​

The available configuration options are:

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

Build​

Build is used to specify the current version of your game.

Specify it using a string. It is recommended to use a 3 digit version like for example: [major].[minor].[patch].

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

Auto detect app version to use for build field​

There is an option to auto detect app version to use for build field. Just call this before intializing the SDK:

// Auto detect app version (Swift)
GameAnalytics.configureAutoDetectAppVersion(true)

This is the equivalent of manually calling the following snippet:

NSString* build = [[NSBundle mainBundle]  objectForInfoDictionaryKey:@"CFBundleShortVersionString"];
[GameAnalytics configureBuild:build];

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