Hangit SDK for iOS Integration Guide Table of Contents Version ........................................................................................................................ 2 Overview ..................................................................................................................... 2 Installing the iOS SDK Framework ................................................................................ 4 Download the SDK Framework files .................................................................................................................. 4 Add the SDK Framework files to your project ............................................................................................... 4 Link the SDK files to your project ........................................................................................................................ 5 Edit your Build Settings ........................................................................................................................................... 5 Adding objects and methods ........................................................................................ 5 Add iOS 8 Compatibility ........................................................................................................................................... 6 Receiving SDK Location Updates ......................................................................................................................... 6 Add an Observer to your class ............................................................................................................................... 6 Consuming Hangit Campaigns ............................................................................................................................. 7 Add a Hangit DataService object to your class ............................................................................................. 7 Consuming Hangit Offers ............................................................................................. 8 Add a Hangit DataService object to your class ............................................................................................. 8 Adding the Hangit Offers Map. Class Type: Apple MapKit ........................................................................ 8 Add the MapModule to your class ....................................................................................................................... 8 Version Date 3/10/2015 Version 2.0.1 Author John Dutchak 4/7/2015 2.0.2 John Dutchak Version Notes Update battery optimizations. Support for Callback Update documentation on integration Update SDK to one binary for both Device and Simulator Overview HANGIT WAS FOUNDED ON THE PRINCIPLE THAT MOBILE LOCATION ON SMARTPHONES CHANGES EVERYTHING. Traditional display and search marketing are too passive to perform well on mobile. The HangIt™ Platform enables app publishers and marketers to electronically “hang” messages and marketing anywhere and have their target customers notified on their smartphones when they get there. With HangIt SDK, app publishers and marketers can get in front of their customers at precisely the right place and time and deliver a rich notification that is sure to get their attention. Local Notifications HangIt delivers location-‐driven notifications that capture mobile customers’ attention, whether the app is in the foreground or background. We don’t do display ads. New Marketing Channel HangIt provides an entirely new channel for marketers. And for publishers, HangIt yields purely incremental revenue. Open SDK HangIt™ SDK works with a growing network of apps to provide location-‐driven messaging and marketing, driving customer engagement and new ad revenue. Precise First-‐Party Location HangIt™ SDK collects first-‐party location data directly from the phone – by definition our location data is as good as it gets. Measurable Conversion HangIt measures mobile marketing from offer delivery through redemption at the point of sale. We map the customer journey. Latest version
The latest version of the Hangit iOS SDK Framework is 2.0.0 (15) and was released March, 5th 2015.
Overview
This document shows you a quick way to start using the Hangit iOS SDK Framework for location-aware
apps. You will find code examples for core features, and best practices that developers should follow.
Installing the iOS SDK Framework In this section we’ll run through the steps to add our Framework to your Xcode project.
You will not be able to monitor changes for CoreMotion using the
Simulator, you will need to test and run your project on a real device.
If this is your first time out with Xcode and iOS App development, then we recommend you read Apple’s
introductory guide.
Download the SDK Framework files Clone the git repo - git clone https://github.com/hangit/iOS_SDK_2.git
Change to Example folder - cd iOS_SDK_2/Example
CocoaPods - pod install
Add the SDK Framework files to your project 1.
Create a new project in Xcode and give it a name.
2.
3.
Create an empty folder in your project directory.
Extract the ios_hangitsdk.zip file and copy the resource
bundle HangitResources.bundle to your new folder.
4.
Choose File
> Add Files to Your ProjectName.
5.
6.
Select your new folder containing the SDK files
In Added folders, select Create groups and in Add
to targets, choose your
project and click Add.
7.
Drag the Hangit.framework file to your Embedded
8.
projects target.
Import the framework header file to the view controller that will be using the SDK #import
<Hangit/Hangit.h>.
Binaries section under General for your
Link the SDK files to your project In XCode 6, the SDK will be linked automatically to your project.
If you need to manually link the files, or just check that they are there:
1.
2.
In the project navigator, select your project.
Click Build Phases -> Link Binary
3.
Check that Hangit.framework is already added, if it isn’t:
4.
Click the Add button (+).
5.
Select Hangit.framework and click Add.
With Libraries.
Edit your Build Settings We need to add the -ObjC linker flag to our project:
1.
2.
In the project navigator, select your project.
Select the Build Settings tab
3.
Scroll down to the Other
Linker Flags build setting under the Linking collection, or
Linker Flags” into the search bar.
Set the value of the Other Linker Flags build setting to -ObjC.
type “Other
4.
Your project now references the Hangit SDK Framework and your installation is complete.
Adding objects and methods Now we can start using objects and methods from the SDK. First we need to establish a session with your
app and the SDK.
Go to your ViewController.h and can add the following. The process is simple and all our objects are
modular and configurable to fit your apps design pattern.
Make this View Controller a SessionManagerDelegate
And implement its methods:
#import <Hangit/Hangit.h> @interface ViewController : UIViewController <Sessi
onManagerDelegate> /* Hangit SessionManager */ @property (nonatomic, strong) SessionManager *sessionManager; /* Hangit MapManager */ @property (nonatomic,
strong) MapManager *mapManager; /* Hangit ListView */ @property (nonatomic, strong) OfferListView *offerListView; /* Hangit sessionKey Property */ @prope
rty (nonatomic, retain) NSString * sessionKey; Add the sessionManager property and create it's sharedInstance.
Add to viewDidLoad()
sessionManager = [SessionManager sharedInstance]; sessionManager.delegate = s
elf; //Push Notification To Users sessionManager.presentNotifications = YES; //Present Offers To Users sessionManager.presentOfferView = YES; //Present O
ffers Full Screen To Users sessionManager.presentOfferFullScreen = NO; _sessi
onKey = [sessionManager startSessionUsingLocation:@"YOURAPIKEY"]; The _sessionKey property will contain the unique key for this app's session providing continued
communication with the Hangit network allowing this user to receive offers specific to them and their
location.
Add iOS 8 Compatibility For your app to work correctly with iOS 8 you have to add a new key to your project’s plist file.
1.
2.
In the project navigator, select your project.
Select your projects Info.plist file
3.
Add the following key string pair to the file.
<key>NSLocationAlwaysUsageDescription</key> <string>Uses background location</
string> The string can be empty, or defined by you the developer, the content is not important.
1.
In the project navigator, select your project.
2.
Select your projects Target and choose Capabilities
3.
Turn on Background Modes.
4.
Select "Location updates" and "Background fetch"
iOS 8 compatability is now complete.
Receiving SDK Location Updates In the following example we’ll show you how the Hangit SDK can provide your app with the device's location
updates. This will save time from implementing your own location manager.
Add an Observer to your class In our example, we have used the ViewController.m class for simplicity, you can create the Observer on any
class in your project.
First we’ll include the Hangit SDK Framework.
<Hangit/Hangit.h>
And Implement the NSNotificationCenter Observer and callback method
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selec
tor(locationNotification:) name:@"hangitLocationNotification" object:nil]; -‐ (void) locationNotification:(NSNotification *)notification{ if ([notification object]) { CLLocation * location = [[notification
object] objectForKey:@"Location"]; NSLog(@"location callback: %@", lo
cation); } } This code has created an Observer that will monitor for location updates received in the Hangit SDK. You
can consume these location updates in any ViewController in your app for your development location
requirements and to send to our DataService to comsume Hangit JSON Campaigns & Offers.
Requirement: Implement the didReceiveNotification callback to your AppDelegate.m
/* Hangit AppDelegate NotificaitonManager Requirement */ -‐ (void)application:(
UIApplication *)application didReceiveLocalNotification:(UILocalNotification *
)notification { [[NSNotificationCenter defaultCenter] postNotificationName
:@"hangitNotificationReceived" object:notification]; } [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(not
ificationReceived:) name:@"hangitNotificationReceived" object:nil]; -‐ (void) notificationReceived:(NSNotification *)notification { if ([notification ob
ject]) { NSLog(@"notification callback: %@", [notification object]); } } Consuming Hangit Campaigns In the following example we’ll show you how the Hangit SDK can provide your app with raw JSON
Campaign data allowing you to use it in any way that meets your requirements.
Add a Hangit DataService object to your class In our example, we have used the ViewController.m class for simplicity; you can create the Observer on
any class in your project.
And Implement the DataService object and callback method
CLLocation * myLocation = [[CLLocation alloc] initWithLatitude:28.550 longitud
e:-‐81.400]; [[DataService instance] getLocationsWithLocation:myLocation sessionKey:@"1234567890" completion:^(NSMutableArray *parametersArr
ay, NSMutableArray *targetsArray, NSMutableArray *offersArray,
NSMutableArray *redemptionsArray, NSError *error) { NSLo
g(@"%@", parametersArray); NSLog(@"%@", targetsArray); NSLog(@"%@", of
fersArray); NSLog(@"%@", redemptionsArray); }]; This code has created a Hangit DataService object that will retrieve Campaign, Offer and Redemption data
in raw JSON format within X meters from your users reported location. Each response is converted to a
NSMutable Array.
Consuming Hangit Offers In the following example we’ll show you how the Hangit SDK can provide your app with raw JSON Offers
associated with a Campaign.
Add a Hangit DataService object to your class In our example, we have used the ViewController.m class for simplicity; you can create the Observer on
any class in your project.
And Implement the DataService object and callback method
CLLocation * myLocation = [[CLLocation alloc] initWithLatitude:28.550 longitud
e:-‐81.400]; [[DataService instance] getOffersWithLocation:myLocation sessionKey:@"1234567890" completion:^(NSMutableArray *offersArray, NSE
rror *error) { DLog(@"%@", offersArray); }]; This code has created a Hangit DataService object that will reteive any Offers in raw JSON format for the
Campaign associated with it based on location. Each response is converted to a NSMutable Array.
Adding the Hangit Offers Map. Class Type: Apple MapKit In the following example we’ll show you how to can create a Hangit Offers Map to visually monitor Offers
based on the users current location.
Add the MapModule to your class In our example, we have used the ViewController.m class for simplicity; you can create the MapModule on
any class in your project.
And Implement the Hanigt MapManager
mapManager = [[MapManager alloc] initWithNibName:@"MapManager" bundle:
[NSBundle bundleWithPath:[[NSBundle mainBundle] pathForResource:@"Hang
itResources" ofType:@"bundle"]]]; /* 1. Add the map to the current view and d
efine the frame parameters */ map.view.frame = CGRectMake(0,0,320,200); map.
view.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFl
exibleHeight; [self.view addSubview:map.view]; This code has placed the Offers Map on your view controller. You can decide what size you would like the
map frame rect to be in order to fit with the design of your app.
Adding the Hangit Offers List. Class Type: UITableView
In the following example we’ll show you how to can create a Hangit Offers UITableView List to display all
Offers based on the users current location.
And Implement the Hanigt OfferListView
offerListView = [[OfferListView alloc] initWithNibName:@"OfferListView" bundle:[NSBundle bundleWithPath:[[NSBundle mainBundle] pathForResour
ce:@"HangitResources" ofType:@"bundle"]]]; /* 1. Add the UITableView to the c
urrent view and define the frame parameters */ offerListView.view.frame = CGR
ectMake(0,0,320,200); offerListView.view.autoresizingMask = UIViewAutoresizin
gFlexibleWidth | UIViewAutoresizingFlexibleHeight; [self.view addSubview:offe
rListView.view]; This code has placed the Offers ListView on your view controller. You can decide what size you would like
the table view frame rect to be in order to fit with the design of your app.
Adding the Hangit Settings View. Class Type: UITableView
In the following example we’ll show you how to can create a Hangit Settings UITableView to display the SDK
settings.
@property (nonatomic, strong) SettingsController * settingsController;
And Implement the Hangit Settings View
settingsController = [[SettingsController alloc] initWithNibName:@"SettingsCon
troller" bundle:[NSBundle bundleWithPath:[[NSBundle mainBundle] pathFo
rResource:@"HangitResources" ofType:@"bundle"]]]; /* 1. Add the UITableView t
o the current view and define the frame parameters */ settingsController.view
.frame = CGRectMake(0,0,320,200); settingsController.view.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight; [self.vie
w addSubview:settingsController.view]; This code has placed the Settings Controller on your view controller. You can decide what size you would
like the table view frame rect to be in order to fit with the design of your app.