No description or website provided.
Objective-C
Latest commit 7fdf278 Jan 19, 2016 @ms7s ms7s Fix typo

README.md

iOS SDK

The INFINARIO iOS SDK is available at this Git repository: https://github.com/Infinario/ios-sdk.

Installation

  1. Download the latest release of the iOS SDK
  2. Unzip / untar the downloaded SDK into a preferred directory
  3. Locate file InfinarioSDK.xcodeproj in the unpacked SDK directory
  4. Drag & drop the file InfinarioSDK.xcodeproj to your XCode project in Project navigator
  5. In XCode, click on your project in Project navigator, scroll down the General tab and locate Embedded Binaries section
  6. Click on the Plus sign button (titled Add items)
  7. In the newly opened dialog window, please select InfinarioSDK.framework under <Your project> > InfinarioSDK.xcodeproj > Products and click Add

After completing the steps above, the INFINARIO iOS SDK should be included in your app, ready to be used.

Usage

Basic Interface

Once the IDE is set up, you may start using the INFINARIO library in your code. Firstly, you need to import main header file InfinarioSDK.h with the following code: #import <InfinarioSDK/InfinarioSDK.h>. Secondly, you need to know the URI of your INFINARIO API instance (usually https://api.infinario.com)and your project token (located on the Project management / Overview page in the web application). To interact with the INFINARIO SDK, you need to obtain a shared instance of the INFINARIO class using the project token (the URI parameter is optional):

// Use public Infinario instance
Infinario *infinario = [Infinario getInstance:@"projectToken"];

// Use custom Infinario instance
Infinario *infinario = [Infinario getInstance:@"projectToken" andWithTarget:@"http://url.to.your.instance.com"];

To start tracking, the customer needs to be identified with their unique customerId. The unique customerId can either be an instance of NSString, or NSDictionary representing the customerIds as referenced in the API guide. Setting

NSString *customerId = @"123-foo-bar";
is equivalent to
NSDictionary *customerId = @{@"registered": @"123-foo-bar"};
In order to identify a customer, call one of the identifyWithCustomer or identifyWithCustomerDict methods on the obtained INFINARIO instance as follows:
// Identify a customer with their NSString customerId
[infinario identify:customerId];

// Identify a customer with their NSDictionary customerId
[infinario identifyWithCustomerDict:customerId];

The identification is performed asynchronously and there is no need to wait for it to finish. Until they are sent to the INFINARIO API, all tracked events are stored in the internal SQL database.

You may track any event by calling the track method on the INFINARIO instance. The track method takes one mandatory and two optional arguments. The first argument is a NSString *type argument categorizing your event. This argument is required. You may choose any string you like.

The next two arguments are NSDictionary *properties and NSNumber *timestamp. Properties is a dictionary which uses NSString keys and the value may be any NSObject which is serializable to JSON. Properties can be used to attach any additional data to the event. Timestamp is a standard UNIX timestamp in seconds and it can be used to mark the time of the event's occurrence. The default timestamp is preset to the time when the event is tracked.

NSDictionary *properties = @{@"item_id": @45};
NSNumber *timestamp = [NSNumber numberWithLong:[[NSDate date] timeIntervalSince1970]];

// Tracking of buying an item with item's properties at a specific time
[infinario track:@"item_bought" withProperties:properties withTimestamp:timestamp];

// Tracking of buying an item at a specific time
[infinario track:@"item_bought" withTimestamp:timestamp];

// Tracking of buying an item with item's properties
[infinario track:@"item_bought" withProperties:properties];

// Basic tracking that an item has been bought
[infinario track:@"item_bought"];

The INFINARIO iOS SDK provides you with means to store arbitrary data that is not event-specific (e.g. customer age, gender, initial referrer). Such data is tied directly to the customer as their properties. To store such data, the update method is used.

NSDictionary *properties = @{@"age": @34};

// Store customer's age
[infinario update:properties];

Automatic events

INFINARIO iOS SDK automatically tracks some events on its own. Automatic events ensure that basic user data gets tracked with as little effort as just including the SDK into your game. Automatic events include sessions, installation, identification and payments tracking.

Sessions

Session is a real time spent in the game, it starts when the game is launched and ends when the game goes to background. If the player returns to game in 60 seconds (To change TIMEOUT value, call setSessionTimeOut), game will continue in current session. Tracking of sessions produces two events, session_start and session_end. To track session start call trackSessionStart from applicationDidBecomeActive method and to track session end call trackSessionEnd from applicationDidEnterBackground in AppDelegate.m

//AppDelegate.m

@property Infinario *infinario;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Override point for customization after application launch.
    self.infinario = [Infinario getInstance: @"projectToken"];

    return YES;
}

- (void)applicationDidBecomeActive:(UIApplication *)application {
    // Restart any tasks that were paused (or not yet started) while the application was inactive. If the application was previously in the background, optionally refresh the user interface.
    [self.infinario trackSessionStart];
}

- (void)applicationDidEnterBackground:(UIApplication *)application {
    // Use this method to release shared resources, save user data, invalidate timers, and store enough application state information to restore your application to its current state in case it is terminated later.
    // If your application supports background execution, this method is called instead of applicationWillTerminate: when the user quits.
    [self.infinario trackSessionEnd];
}

Both events contain the timestamp of the occurence together with basic attributes about the device (OS, OS version, SDK, SDK version and device model). Event session_end contains also the duration of the session in seconds. Example of session_end event attributes in JSON format:

{
  "duration": 125,
  "device_model": "iPhone",
  "device_type": "mobile",
  "ip": "10.0.1.58",
  "os_name": "iOS",
  "os_version": "8.1.0",
  "sdk": "iOS SDK",
  "sdk_version": "1.1.1"
  "app_version": "1.0.0"
}

Installation

Installation event is fired only once for the whole lifetime of the game on one device when the game is launched for the first time. Besides the basic information about the device (OS, OS version, SDK, SDK version and device model), it also contains additional attribute called campaign_id which identifies the source of the installation. For more information about this topic, please refer to the aquisition documentation. Example of installation event:

{
  "campaign": "Advertisement on my website",
  "campaign_id": "ui9fj4i93jf9083094fj9043",
  "link": "https://itunes.apple.com/us/...",
  "device_model": "iPhone",
  "device_type": "mobile",
  "ip": "10.0.1.58",
  "os_name": "iOS",
  "os_version": "8.1.0",
  "sdk": "iOS SDK",
  "sdk_version": "1.1.1"
}

Identification

Identification event is tracked each time the identify() method is called. It contains all basic information regarding the device (OS, OS version, SDK, SDK version and device model) as well as registered attribute which identifies the player. Example of an identification event:

{
  "registered": "player@email.com",
  "device_model": "iPhone",
  "device_type": "mobile",
  "ip": "10.0.1.58",
  "os_name": "iOS",
  "os_version": "8.1.0",
  "sdk": "iOS SDK",
  "sdk_version": "1.1.1"
}

Payments

INFINARIO iOS SDK automatically tracks all payments made in the game as the SDK instance listens on [SKPaymentQueue defaultQueue] for successful transactions. Purchase events (called hard_purchase) contain all basic information about the device (OS, OS version, SDK, SDK version and device model) combined with additional purchase attributes brutto, item_id and item_title. Brutto attribute contains price paid by the player. Attribute item_title consists of human-friendly name of the bought item (e.g. Silver sword) and item_id corresponds to the product identifier for the in-app purchase as defined in your iTunes Connect console. Example of purchase event:

{
  "gross_amount": 0.911702,
  "currency": "EUR",
  "payment_system": "iTunes Store",
  "product_id": "silver.sword",
  "product_title": "Silver sword",
  "device_model": "iPad",
  "device_type": "tablet",
  "ip": "10.0.1.58",
  "os_name": "iOS",
  "os_version": "8.1.0",
  "sdk": "iOS SDK",
  "sdk_version": "1.1.1"
}

Virtual payment

If you use virtual payments (e.g. purchase with in-game gold, coins, ...) in your project, you can track them with a call to trackVirtualPayment.

[infinario trackVirtualPayment:@"currency" withAmount:@3 withItemName:@"itemName" withItemType:@"itemType"];

Segmentation

If you want to get current segment of your player, just call getCurrentSegment. You will need id of your segmentation and project secret token.

[infinario getCurrentSegment:@"segmentaionId" withProjectSecret:@"projectSecret" withCallBack:^(BOOL wasSuccessful, InfinarioSegment *segment, NSString *error) {
    NSString *name = [segment getName];
}];

Push notifications

The INFINARIO web application allows you to easily create complex scenarios which you can use to send push notifications directly to your players. The following section explains how to enable receiving push notifications in the INFINARIO iOS SDK.

Apple Push certificate

For push notifications to work, you need a push notifications certificate with a corresponding private key in a single file in PEM format. The following steps show you how to export one from the Keychain Access application on your Mac:

  1. Launch Keychain Access application on your Mac
  2. Find Apple Push certificate for your app in Certificates or My certificates section (it should start with "Apple Development IOS Push Services:" for development certificate or "Apple Production IOS Push Services:" for production certificate)
  3. The certificate should contain a private key, select both certificate and its corresponding private key, then right click and click Export 2 items
  4. In the saving modal window, choose a filename and saving location which you prefer and select the file format Personal Information Exchange (.p12) and then click Save
  5. In the next modal window, you will be prompted to choose a password, leave the password field blank and click OK. Afterwards, you will be prompted with you login password, please enter it.
  6. Convert p12 file format to PEM format using OpenSSL tools in terminal. Please launch Terminal and navigate to the folder, where the .p12 certificate is saved (e.g. ~/Desktop/)
  7. Run the following command openssl pkcs12 -in certificate.p12 -out certificate.pem -clcerts -nodes, where certificate.p12 is the exported certificate from Keychain Access and certificate.pem is the converted certificate in PEM format containing both Apple Push certificate and its private key
  8. The last step is to upload the Apple Push certificate to the INFINARIO web application. In the INFINARIO web application, navigate to Project management -> Settings -> Notifications
  9. Copy the content of certificate.pem into Apple Push Notifications Certificate and click Save

Now you are ready to implement Push Notifications into your iOS application.

INFINARIO iOS SDK

By default, receiving of push notifications is disabled. You can enable it by calling the registerPushNotifications method. Please note that this method needs to be called only once. Push notifications remain enabled until they are unregistered. After registering for push notifications, iOS automatically calls didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken which is a good place to send the device token to the INFINARIO web application using method addPushNotificationsToken. See code sample from AppDelegate.m below and Apple Push Notifications Documentation for more details.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // self.infinario is @property Infinario *infinario;
    self.infinario = [Infinario getInstance:@"projectToken" andWithCustomer:@"some_player_id"];
    return YES;
}

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    NSLog(@"token: %@", deviceToken);
    [self.infinario addPushNotificationsToken:deviceToken];
}

- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
    NSLog(@"failed obtaining token: %@", error);
}

Flushing events

All tracked events are stored in the internal SQL database. By default, Infinario iOS SDK automagically takes care of flushing events to the Infinario API. This feature can be turned off with method disableAutomaticFlushing which takes no arguments. Please be careful with turning automatic flushing off because if you turn it off, you need to manually call flush to flush the tracked events manually everytime there is something to flush.

[infinario enableAutomaticFlushing];

[infinario disableAutomaticFlushing];
[infinario flush];