Getting Started - GravitumLabs/gravitum-ios-sdk GitHub Wiki

SDK Import

Let's import the SDK's core library into the project. All the following instructions will be illustrated with the screenshots, it will not take much time.

1. Drag and drop the Library files to your project files, as in the picture below

Drag_&_Drop.png

2. Pop-up with options to add files will appear. Make sure, that in Destination the "Copy items if needed" box is checked.

Copy_if_needed.png

3. Add SystemConfiguration.framework to your project. You can do it with the following steps:

  1. In the project navigator, select your project.
  2. Select your target.
  3. Select the "Build Phases" tab.
  4. Open "Link Binaries With Libraries" expander.
  5. Click the + button.
  6. Select & add SystemConfiguration.framework.

4. With the library integrated, to make sure that there are no problems - make a test build of the Application (cmd + B). There should be no errors.

Test_build.png

Programming guidelines

SDK Initialization

First of all you need to #import Analytics.h:

#import "include/Analytics/Analytics.h"

If you imported Analytics.h file directly, without folders(include/Analytics) - just import it directly:

#import "Analytics.h"

importHeader.png

Let's move to the actual programming and start with the SDK initialization. To properly initialize the Gravitum iOS SDK add the following code to the didFinishLaunchingWithOptions method of your AppDelegate.m class.


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Override point for customization after application launch.

    Analytics * analytics = [[Analytics getAnalytics] initWithParameters:AppToken
                                                                AppSecret:AppSecret
                                                                 SenderId:SenderId];
    /////////////////////////////////////////////////////////////////////////////////
    // Optional
    [analytics SetUserId:   userID];
    [analytics SetUserName: userName;
    [analytics SetGender:   (Gender*)userGender];
    [analytics SetFacebookId: facebookId];
    [analytics SetBirthday: userBirthDay 
                 monthBorn: userBirthMonth 
                  yearBorn: userBirthYear
    ];
    // Optional end
    /////////////////////////////////////////////////////////////////////////////////
    [analytics Init]; //Launch analytics;
    
    return YES;
}

[analytics initWithParameters] requires the following parameters:

  • AppToken: Provided to you by Gravitum
  • AppSecret:Provided to you by Gravitum
  • SenderID: Please use @"". This is in place for a future feature.

[analytics Init] - This method initializes Gravitum Analytics. Please do not forget to call this method.

Important: Let us briefly review the optional methods.

  • The very first optional method is SetUserId. You may provide your own user id in certain cases (e.g. you want to use Google Play Services/Game Center player id as the unique user id for Gravitum service or you have your own web server with the custom player authentication), otherwise, it will be generated automatically. Just make sure, that the Id you provide will be unique for each user.

  • To provide the user name use SetUserName method with the string name. Unlike the used Id, user name may not be unique. What name to provide is up to you without any restrictions.

  • Set user's Facebook Id via SetFacebookId method call. The common approach is to get the user Facebook Id from Facebook SDK itself and provide it to Gravitum Analytics.

  • Last two SetBirthday and SetGender speak for themselves. For e.g [analytics SetGender:(Gender*)Male]; and [analytics SetBirthday:12 monthBorn:02 yearBorn:1987];

Custom User Data

You can set custom unique fields for each user. This fields will be used for filtering the segments from the audience of your application. Important: You can set up to 15 custom fields for each user.

SetCustomFields.png

NSMutableDictionary <NSString*, NSObject *> * customPlayerProperties = [[NSMutableDictionary <NSString*, NSObject *> alloc] init];
[customPlayerProperties setValue:@"Ginger" forKey:@"playerProperty1"];
[customPlayerProperties setValue:[NSNumber numberWithInt:36]  forKey:@"playerProperty2"];
[customPlayerProperties setValue:[NSNumber numberWithFloat:39.5]  forKey:@"playerProperty3"];

[analytics SetCustomProperties:customPlayerProperties];

Now we are done with SDK initialization and are ready to setup events tracking.

Events Tracking

The simplest way to send events is shown below. Use this method if you don't need to send any parameters with your event. Please use this when just the event ID will be enough for you. Take a look at the following code snippet


[[Analytics getAnalytics] SendEvent:@"First_Start"];

To send a custom event with a data bundle (i.e. custom params) use the following code sample. You can provide any event data you want as a NSDictionary or NSMutableDictionary. What data to send with an analytics event depends on your game project.

NSMutableDictionary<NSString*,NSObject*>* eventData = [[NSMutableDictionary<NSString*,NSObject*> alloc] init];
[eventData setValue:@"Hello_data" forKey:@"custom_string_data"];
[eventData setValue:[NSNumber numberWithInteger:10101] forKey:@"custom_int_data"];
[[Analytics getAnalytics] SendEvent:@"sample_event" data:eventData];

Commercial Events Tracking

One more specific Analytics event type is a Purchase event. The common approach is to track the In-App Purchases with such kind of events. So, send this event on every successful In-App Purchase. Provide the product Id, price and the currency code of the real In-App Purchase. These events are separately captured from ordinary gameplay or custom events. Please see SendMonetaryEvent in the API reference section for more details.

For currency codes: please use 3digit ISO 4217codes.


[[Analytics getAnalytics] SendMonetaryEvent:@"coins" price:0.99 currency:@"USD"];

Session Tracking

The last but not least is session tracking feature of Gravitum Service. To setup tracking you have to add two method calls in the right places of your AppDelegate.m class. The first one is [[Analytics getAnalytics] SessionStart];. Add this method to applicationDidBecomeActive method as shown below.


- (void)applicationDidBecomeActive:(UIApplication *)application {
    [[Analytics getAnalytics] SessionStart];
}

[[Analytics getAnalytics] SessionEnd]; method should be called from applicationWillResignActive method from you main activity.


- (void)applicationWillResignActive:(UIApplication *)application {
    [[Analytics getAnalytics] SessionEnd];
}

SessionTracking.png Important: You shouldn't send any events recording session lengths. All the duration tracking events will be sent under the hood. If you need more detailed information about each API, you can find all the SDK API References here.

Push Notifications (Optional)

In order to enable advanced Push Notifications via Gravitum please see: Gravitum APNS Setup