Lime SDK for iOS

In order to connect your mobile application to the Lime Cloud service, you must follow couple simple steps. This manual describes the most common scenarios of the SDK integration. Advanced SDK options are described in our API reference, or you can contact us by e-mail at hello@lime-company.eu or via the contact form integrated in the admin console.

Current version: 2.0.0

Installation

Lime SDK is available through CocoaPods, a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries like Lime SDK in your projects.

To install Lime SDK for iOS, simply add the following lines to your Podfile:

platform :ios, "8.0"
use_frameworks!

pod 'LimeSDK'

Alternatively, you can manually download our SDK package (classes and assets from the LimeSDK folder) and add it to your iOS project using drag&drop.

Features

Basic configuration

There are couple steps that are the same for anything you might want to do with Lime SDK, such as:

• Configure your APP_KEY
• Registering for push notifications
• Setting the API base URL (for custom deployments)

This code snippet illustrates these steps:

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

  // In case of a custom deployment, set up your API URL here - as the very first statement
  [[Lime sharedInstance] setApiBase:@"https://my-api.herokuapp.com/1/"];

  // Set your API KEY value, right after you application launches
  [[Lime sharedInstance] setAppKey:@"app_12345678901234567890234567890"];

  // Ask user for permission to receive notifications anytime before you actually need it
  [[Lime sharedInstance] registerNotifications];

}

User profile synchronization

Whenever your application learns a new information about its user, you can synchronize the new data with server:

LimeUser * user = [Lime sharedInstance].currentUser;
user.internalId = @"INT_ID_1234567890";
user.name = @"John";
user.surname = @"Smith";
user.sex = kLimeUserSexMale;
user.tags = @["premium", "active"];
[[Lime sharedInstance] synchronizeCurrentUser];

You do not need to worry about some attributes being nil before calling synchronizeCurrentUser. You need to fill in only the new information you just learned - the Lime cloud automatically merges user data based on the internally generated user token value.

Analytics

You can log any analytics event using a single line of code:

[[Lime sharedInstance] logAnalyticsEvent:@"event_name"];

You may also include parameters with the event - note that the parameter values must be either NSString or NSNumber instances:

[[Lime sharedInstance] logAnalyticsEvent:@"event_name" parameters:@{
  @"paramString": @"Anything",
  @"paramNumber": @(20)
}]

Push notifications

In case you registered for the push notifications as mentioned above and your application has a "Push notifications" capability enabled, you are almost all set. Your application is ready to receive the push notifications from the Lime cloud and interpret them appropriately, you simply need to handle them.

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

  // Set your APP KEY first
  [[Lime sharedInstance] setAppKey:@"app_ca497261c9768bed00cf95cdaf9ecfc5"];

  // Ask user for permission to receive notifications anytime before you actually need it
  [[Lime sharedInstance] registerNotifications];

  // Handle the notification after the app was just started
  NSDictionary * info = [launchOptions objectForKey:UIApplicationLaunchOptionsRemoteNotificationKey];
  [[Lime sharedInstance] handleRemoteNotificationInfo:info];

  return YES;
}

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)token {
  // Send the push token you obtained from APNs to the Lime Cloud
  [[Lime sharedInstance] sendPushToken:token];
}


- (void) application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
  // Handle the notification when the app is running
  [[Lime sharedInstance] handleRemoteNotificationInfo:userInfo];
}

Support chat

You can automatically fire the support chat user interface using a single line of code:

[[Lime sharedInstance] openChat];

This code will perform all task necessary to present the chat window modally, using the default slide-up animation.

The chat functionality can be improved using the push notifications. Make sure to register your application for push notifications by calling the registration method in your AppDelegate (see above). Also, make sure you set your APP_KEY value.

iBeacon monitoring and geofencing

The simplest use-case for the Lime SDK iBeacon and geofencing is an automated proximity based messaging and analytics. In this scenario, the SDK performs following steps automatically:

• Download the SDK configuration.
• Monitor for regions (iBeacon and geofences) defined in Lime SDK.
• In case region is found, ask for an associated campaigns.
• Download the campaigns and display notifications connected to it (on app background only).
• If user opens the notification, render the content associated with the rule.
• Automatically sends all analytic events to the Lime cloud.

Before you implement any code, you need to change your Info.plist file in order to declare the location services (iBeacon and geofencing support is part of CoreLocation). Add the NSLocationAlwaysUsageDescription key (String). The value of this key should be a text explaining the purpose of using the iBeacons within your application. User decides if he/she grants permissions to the application based on this text.

Example of an explanatory text:

"In order to automatically show you a discount voucher after you enter our store, we need to be able to determine your location even if you are not actively using your application."

Use the following code for the basic Lime SDK iBeacon and geofencing support integration:

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

  // ...
  // ... Basic configuration goes here, see above
  // ...

  // Start fetching an application context
  [[Lime sharedInstance] startFetchingLocationContext];

  // Handle notification in case app is launching
  UILocalNotification * notif = [launchOptions objectForKey:UIApplicationLaunchOptionsLocalNotificationKey];
  [[Lime sharedInstance] handleAppLaunch:notif];

  return YES;
}

- (void)application:(UIApplication *)app didReceiveLocalNotification:(UILocalNotification *)notif {
  // Handle notifications when your app is running on background
  [[Lime sharedInstance] handleAppLaunch:notif];
}

Your application can now receive notifications from Lime cloud based on the campaigns you created and display the content in your application.

Client-side notification frequency handling

While the lime cloud offers mechanisms for setting up the notification frequency, it may be handy to handle the notification frequency on the client side as well. The notificationDelegate property of Lime class allows application to determine if the notification should be displayed or not, or to notice that notification was displayed / suppressed:

[Lime sharedInstance].notificationDelegate = self;

The notificationDelegate instance should conform to LimeNotificationDelegate protocol that offers following callback methods (all of them are optional):

- (void)lime:(Lime *)lime didDisplayNotification:(LimeContentRule *)contentRule {
  // code called when the notification was displayed
}

- (void)lime:(Lime *)lime didSuppressNotification:(LimeContentRule *)contentRule {
  // code called when the notification was suppressed
}

- (BOOL)lime:(Lime *)lime shouldDisplayNotification:(LimeContentRule *)contentRule {
  // business logics that determines if the notification should be shown or not
  return YES;
}

Using these methods, application code is able to handle the notification displaying precisely. For example it can store the timestamp in lime:didDisplayNotification: and compare this timestamp in lime:shouldDisplayNotification, or it can use any internal logics to determine if the notification should be displayed or not.

Listening to content nearby

In case an application needs more control over displaying the content, Lime has more detailed scanning initialization method startFetchingContextForApplicationKey:contentUpdatedCallback:. This method is handy for example when implementing an interactive guide or in case the content connected with beacons must be modified on the clients side before being displayed.

Here is an example usage of this method:

[[Lime sharedInstance] startFetchingContextForApplicationKey:@"app_123456789012345678901234567890"
contentUpdatedCallback:^(NSArray * addedContentRules, NSArray * droppedContentRules) {
  // list of all available content - LimeContentRule instances - can be accessed
  // using the `currentContent` property of Lime instance
  NSArray * contentRules = [Lime sharedInstance].currentContent;
  if (addedContentRules.count || droppedContentRules.count) {
    // there are some new or old content rules available
  }
}];

API Reference

Advanced features of our mobile SDK are documented in our API reference.

http://assets.lime-company.eu/docs/ios/html/Classes/Lime.html

Author

Lime - HighTech Solutions s.r.o.

• Website: http://www.getlime.io/
• Twitter: https://twitter.com/lime_company
• E-mail: hello@lime-company.eu

License

Lime SDK for iOS is available under GPLv3 license. See the LICENSE file for more info.