iOS SDK v2

You can initialize Liquid singleton (once per app launch) with your app API key. Typically, the best place to do this is on application:willFinishLaunchingWithOptions: method at your AppDelegate.m file.

You can find your App API key on the App Settings of Liquid’s dashboard.

// AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  // assuming that you're using a DEBUG flag
  #ifdef DEBUG
    [Liquid sharedInstanceWithToken:@"YOUR-DEVELOPMENT-APP-TOKEN" development:YES];
  #else
    [Liquid sharedInstanceWithToken:@"YOUR-PRODUCTION-APP-TOKEN"];
  #endif

  // The rest of your code goes here...
  return YES;
}

From this moment on, each time you want to call a Liquid method you can do:

[Liquid sharedInstance];

In order to keep track of a specific user between different sessions and devices (or different app installations) you must identify it with a unique identifier. This will allow you to use analytics based on their information.

This identifier is usually a strong UUID, e.g: "02318f2cdd156d78fd4431". We recommend using your back-end database ID to identify a user. Alternatively, you can use an email or username, provided they cannot be changed.

Tipically, you know more about your user than only his identifier. Liquid allows you to create analytics based on this information through Key-Value user attributes (on a NSDictionary).

For each of the above situations, you should identify your user with one of the following two methods, respectively:

// Only use this method on anonymous users.

[[Liquid sharedInstance] identifyUserWithIdentifier:@"UNIQUE-USER-ID"];
[[Liquid sharedInstance] identifyUserWithIdentifier:@"john.doe@gmail.com" attributes:@{ @"age": @35 }];

It is not mandatory to the user attributes at the moment of user identification. You can set their attributes later using setter methods.

If you never identify your user, all activity will be tracked anonymously. As soon as a user is identified, all that anonymous activity will be automatically aliased to the identified user. This means that you’ll no longer see the anonymous user, but the identified one.

This process of user aliasing is automatic, is the default behavior and is higly recommended that you alias your users. However, if you don’t want this behavior, you may append the prefix alias:false when identifying your user, like shown in the following example:

[[Liquid sharedInstance] identifyUserWithIdentifier:@"john.doe@gmail.com" alias:false];

Probably the most important entity of analytics is an event. Events can be anything you want in the context of your application. It can be a click on a button, a product that is bought or any other interaction. Events are identified by a unique name, and can (optionally) have attributes (Key-Value).

You can track an event anytime you want on your code, using one of the following methods:

[[Liquid sharedInstance] track:@"Click Profile Page"];
[[Liquid sharedInstance] track:@"Buy Product" attributes: @{ @"productId": 123 }];

Track your Monetization metrics

In order to take advantage of the Monetization section of the Dashboard view, you have to send a price attribute on your events, make sure to check the Monetization settings section for detailed information.

User attributes are Key-Value objects stored in the form of a NSDictionary.

Data types of these attributes can be: NSString, NSDate, NSNumber and NSNull. Primitive types are NOT allowed. Use objects only.

An example that includes all this attributes could be:

NSDictionary *userAttributes = @{
  @"name": @"Anna",
  @"woman": @YES,
  @"facebookId": @"123456789",
  @"age": @25
};

Usually you track these attributes when you identify your user, but you can also set those attributes anytime using one of the following methods, depending on the number of attributes you’re tracking:

[[Liquid sharedInstance] setUserAttribute:@25 forKey:@"age"];
[[Liquid sharedInstance] setUserAttributes:@{
  @"age": @25,
  @"name": @"Anna"
}];

Information about the user device is automatically saved by Liquid SDK.

You don’t need to worry about tracking information of the device. The following device attributes are always included on analytics (example):

{
  "App Name": "Wonderful App",
  "App Version": 1.4,
  "App Release Version": 1.4,
  "App Bundle": "io.lqd.wonderfulapp",
  "Vendor": "Apple",
  "Model": "iPhone4,1",
  "Device name": "John Doe's iPhone",
  "System version": 7.1,
  "System language": "en",
  "Locale": "en-US",
  "Screen size": "640x960",
  "Carrier": "Vodafone",
  "Internet Connectivity": "WiFi"
}

If you have information about user geolocation (a CLLocation) you can use Liquid to track device location. All you need to do is to inform Liquid SDK about current device location using the following method:

[[Liquid sharedInstance] setCurrentLocation:YOUR-CLLOCATION-INSTANCE];

Liquid doesn’t automatically track location changes. This means you’re responsible to inform Liquid SDK each time device location changes. This is usually done in your CLLocationManagerDelegate delegated method, like:

- (void)locationManager:(CLLocationManager *)manager didUpdateToLocation:(CLLocation *)newLocation fromLocation:(CLLocation *)oldLocation {
    // The rest of your code...
    [[Liquid sharedInstance] setCurrentLocation:newLocation];
}

From this moment on, all data points sent to Liquid will include latitude and longitude attributes associated to Device entity.

To send push notifications and in-app messages to your users’ through Liquid’s formulas you’ll just need three things:

• Register for push notifications on Apple servers

• Inform Liquid about each device’s APNS (Apple Push Notification) key.

• Notify Liquid SDK to handle incoming push notifications

// AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [application registerForRemoteNotificationTypes:(UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound)];
    return YES;
}

- (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [[Liquid sharedInstance] setApplePushNotificationToken:deviceToken];
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
    [[Liquid sharedInstance] handleRemoteNotification:userInfo forApplication:application];
}

Configure APNS Certificate

To send Push Notifications as your App, Liquid must authenticate with Apple’s Push Notification Service (APNS) using your App’s certificate. Check the Setup push notifications certificates section to learn how to set it up on Liquid dashboard.

Based on variable names, Liquid returns values on six different data types: NSString, UIColor, NSDate, NSInteger, CGFloat and BOOL. These methods return the fallbackValue if the value is not present or valid.

- (NSString *)stringForKey:(NSString *)variableName fallback:(NSString *)fallbackValue;
- (UIColor *)colorForKey:(NSString *)variableName fallback:(UIColor *)fallbackValue;
- (NSDate *)dateForKey:(NSString *)variableName fallback:(NSDate *)fallbackValue;
- (NSInteger)intForKey:(NSString *)variableName fallback:(NSInteger)fallbackValue;
- (CGFloat)floatForKey:(NSString *)variableName fallback:(CGFloat)fallbackValue;
- (BOOL)boolForKey:(NSString *)variableName fallback:(BOOL)fallbackValue;

You should always define fallback values for your dynamic variables. This will avoid strange behaviors in cases where your app is first launched without an Internet connection, but also if you accidentally delete a variable in Liquid dashboard, or define a different data type between your code and Liquid dashboard.

Each time you use a dynamic variable, you can define its fallback value using the fallback: suffix in Liquid KVO (Key-Value Observing) methods:

NSString *title = [[Liquid sharedInstance] stringForKey:@"title" fallback:@"Be welcome!"];
UIColor *bgcolor = [[Liquid sharedInstance] colorForKey:@"loginBgColor" fallback:[UIColor red]];
NSDate *promoDay = [[Liquid sharedInstance] dateForKey:@"promoDay" fallback:[NSDate date]];
NSInteger abTesting = [[Liquid sharedInstance] intForKey:@"loginVersion" fallback:3];
CGFloat discount = [[Liquid sharedInstance] floatForKey:@"discount" fallback:0.25];
BOOL *initialAds = [[Liquid sharedInstance] boolForKey:@"showAds" fallback:YES];

To ease the development process, each time you use a dynamic variable, its fallback value will be sent to Liquid dashboard and stored as default value (only when your app is compiled with Liquid in development mode).

If you use more than a variable for a Target (defined on Liquid dashboard), all variables affected by that target become dependant on each others.

This means that, if a variable value is fallen back, all the other variables on the same Target will be also fallen back.

Situations like these will only occur if you do something really wrong in your variable settings (e.g. data type mismatch between code and Liquid dashboard), but this mechanism will ensure consistency in your app.

Each time your app is open or closed/paused, new values are requested to Liquid. However, they are not immediately loaded by the SDK as it could cause strange behaviors in front of user eyes. By default, when new values are available, they will only be loaded the next time your app is open.

You can change this behavior just by setting autoLoadValues variable to YES after initializing Liquid singleton:

[[Liquid sharedInstance] setAutoLoadValues:YES];

Optionally you can be notified of Liquid internal internal events by implementing LiquidDelegate or NSNotificationCenter interface on your code, to take action when:

• When values are received from Liquid dashboard (not necessarily loaded)
• When values are loaded

Liquid triggers two types of notifications: LQDidReceiveValues and LQDidLoadValues corresponding both situations above.

Follow the steps for your prefered method to receive these notifications in your code.

via NSNotificationCenter

// ViewController.m

- (void)viewDidLoad {
  NSNotificationCenter *notificationCenter = [NSNotificationCenter defaultCenter];
  [notificationCenter addObserver:self name:LQDidReceiveValues
                         selector:@selector(newValues:) object:nil];
  [notificationCenter addObserver:self name:LQDidLoadValues
                         selector:@selector(loadValues:) object:nil];
  // The rest of your code goes here...
}

- (void)newValues:(NSNotification *)notification {
  // Do somthing, e.g: [[Liquid sharedInstance] loadNewValues];
}

- (void)loadValues:(NSNotification *)notification {
  // Do something with new variables, e.g: refresh a view
}

via LiquidDelegate

Because Liquid shared instance is a singleton, you can only set one of your objects as delegated to Liquid events.

As an example, let’s assume you want to delegate this events to one of your View Controllers. Your header file would be something like:

// ViewController.h

#import "Liquid.h"

@interface ViewController : UIViewController <LiquidDelegate>

and your implementation file would be like:

// ViewController.m

- (void)viewDidLoad {
  [super viewDidLoad];
  [[Liquid sharedInstance] setDelegate:self];
  // The rest of your code goes here...
}

- (void)liquidDidReceiveValues {
  // Do somthing with new values, e.g: [[Liquid sharedInstance] loadNewValues];
}

- (void)liquidDidLoadValues {
  // Do something with new variables, e.g: refresh a view
}

Most of the times, it is useful to have all dynamic variables and their fallback values in the same place.

This kind of practice not only improves code organization and readability, but also reutilization of static values in your code.

This way, we recommend you to create FallbackVariables.{h,m} files, like shown on the example below:

// FallbackVariables.h

#import <Foundation/Foundation.h>

@interface FallbackValues : NSObject

extern NSString *const defaultTitle;
extern NSString *const defaultBgColor;
extern NSString *const defaultPromoDay;
extern NSInteger const defaultloginVersion;
extern CGFloat const defaultDiscount;
extern BOOL const defaultShowAds;

@end

// FallbackVariables.m

#import "FallbackValues.h"

@implementation FallbackValues

NSString *const defaultTitle = @"Welcome to our app";
NSString *const defaultBgColor = @"#FF00FF";
NSString *const defaultPromoDay = @"2014-05-11T15:17:03.103+0100";
NSInteger const defaultloginVersion = 3;
CGFloat const defaultDiscount = 0.15f;
BOOL const defaultShowAds = YES;

@end

By doing this, you can now use dynamic Liquid variables like:

NSString *title = [[Liquid sharedInstance] stringForKey:@"title" fallback:defaultTitle];
NSDate *promoDay = [[Liquid sharedInstance] dateForKey:@"promoDay" fallback:[Liquid gettDateFromISO8601String:defaultPromoDay]];
UIColor *bgcolor = [[Liquid sharedInstance] colorForKey:@"textcolor" fallback:[Liquid colorFromString:defaultBgColor]];
NSInteger loginVersion = [[Liquid sharedInstance] intForKey:@"login" fallback:defaultloginVersion];
CGFloat discount = [[Liquid sharedInstance] floatForKey:@"discount" fallback:defaultDiscount];
BOOL showAds = [[Liquid sharedInstance] boolForKey:@"showAds" fallback:defaultShowAds];

while keeping a list of your dynamic variables and fallback values in one unique place.

To send Push Notifications as your app, Liquid must authenticate with Apple’s Push Notification Service (APNS) using your app’s certificate. If you have one already, the steps you must follow are easy:

• First, access your Mac’s Keychain and extract both your app’s certificate and private key. You should have each environment: production and development (sandbox):

• Extract it into the Personal Information Exchange (.p12) format and save it on your computer with any name you like. You can add a password but it is not required:

• Go to your app Settings page in Liquid. In the Notification Settings section you can upload the Certificate you just extracted. Do so for your production and development app;

That’s it! You should now be able to send Push Notifications to your iOS users.

On the Dashboard section (check the demo) you will find your app’s Monetization metrics (Conversions, Purchases and Revenue) for the last 30 days. In order to set these values properly follow the guide bellow.

Conversions

A conversion can be any event (such as a purchase or a sign-up) that you consider important in the context of your app. You can pick up to 5 events and you’ll instantly get insights on how these events performed (converted) in the last 30 days:

• click on Settings and select up to 5 events that you consider to be a conversion

Purchases

Every event that has the attribute price is automatically considered a purchase.

An example would be:

// The price value must be an integer
[[Liquid sharedInstance] track:@"Buy Product" attributes: @{ @"price": 10 }];

Revenue

The sum of all values (integer) of the attribute price included on all events.

If you’re already using AppsFlyer in your app, you can view the user acquisition source on Liquid following this guide:

• On your app, after initializing our SDK set AppsFlyer customer user id to Liquid device unique_id:

[[AppsFlyerTracker sharedTracker] setCustomerUserID:[[Liquid sharedInstance] deviceIdentifier]];

• Select Liquid on the AppsFlyer integration menu, they’ll ask for your Liquid App key that is available in your app settings page.