5-minutes Quickstart | IOS | SDK 4.3 Connecthings

The Herow SDK allows your app to connect to the Herow platform or the AdTag platform.

The documentation is available for both platform.

What you will learn

You will learn:

to configure your Podfile with our Gitlab and our SDK
to configure the SDK in your application

Pre-requisites - What you need to get started

Your SDK credentials, including an SDK Login, Password, and Company Key to initialize the SDK.
A zone, which has been configured on your herow account.
An iOS Device, with Bluetooth 4.0 and iOs 9 and above.
The Xcode application, which you can download from the App store.

Step 1: Clone the sdk-tutorial repository

Clone the sdk-tutorial repository

git clone https://github.com/Connecthings/sdk-tutorial.git

objectivec

In the cloned sdk-tutorial folder, navigate to ios>ObjectiveC>Zone>1-QuickStart>Starter

SWIFT

In the cloned sdk-tutorial folder, navigate to ios>SWIFT>Zone>1-QuickStart>Starter

Step 2: Configure a Podfile with our Gitlab link

Install CocoaPods $ gem install cocoapods
At the root of the sample repository, check if a Podfile already exists and if not, create it. This can be done by running: $ touch Podfile
Add the following parameters to your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
source 'https://forge.herow.io/pub/Specs'

platform :ios, '9.0'

target 'QuickStart' do
  # Uncomment this line if you are using Swift or would like to use dynamic frameworks
  use_frameworks!
  pod "HerowLocationDetection", '~> 4.3.1'
  # Pods for QuickComplete

  # Pods for testing
  target 'QuickStartTests' do
    inherit! :search_paths
  end

  # Pods for testing UI
  target 'QuickStartUITests' do
    inherit! :search_paths
  end

  post_install do |installer|
    installer.pods_project.targets.each do |target|
        target.build_configurations.each do |configuration|
            configuration.build_settings['SWIFT_VERSION'] = "4.2"
        end
    end
  end

end

Run $ pod update in your project directory

Note:
Your project is linked to the CoreLocation and libsqlite3 frameworks

Step 3: Configure the info.plist

Our SDK accesses two critical frameworks:

the CoreLocation framework to detect the user’s location and iBeacons around
the CoreBluetooth framework to check Bluetooth status

Both of them require explicit permission from the user.

To ask any permission, the iOS system requires an application to provide a description of the framework usage.

This description can be configured in the info.plist file, by adding the following keys:

The three keys for the location permission

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.</string>

"Privacy - Bluetooth Peripheral Usage Description"" for Bluetooth permission

<key>NSBluetoothPeripheralUsageDescription</key>
<string>Your description goes here</string>

Warning:
If you forget to configure any of these usage descriptions:
the application may crash when trying to use the CoreLocation framework
the App Review Team will reject your application

Step 4: Configure the SDK inside the AppDelegate

Initialize the SDK

Add a HerowInitializer parameter to your AppDelegate

@implementation AppDelegate {
    HerowInitializer *herowInitializer;
}

var herowInitializer: HerowInitializer?

In the didFinishLaunchingWithOptions method, initialize and configure the HerowInitializer object with your SDK credentials & environment, and launch synchronization with the Herow Platform

Switch to Swift

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    herowInitializer = [HerowInitializer shared];
    [[[herowInitializer configPlatform: HerowPlatform.prod]
        configUserWithLogin:@"your username" password:@"your password" company:@"your company"] synchronize];
    return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    herowInitializer = HerowInitializer.shared
    herowInitializer?.configPlatform(Platform.prod).configUser(login: "your username", password: "your password", company: "your company").synchronize()
    return true
}

Note 1:
The synchronize method allows to set up the SDK with a configuration file downloaded from the Herow platform.
The SDK will start the zone detection process only when the file download is complete.
This configuration file is saved in cache, and the SDK checks for updates at regular intervals.

Note 2:
The HerowInitializer allows you to configure your access to the various Herow platforms and AdTag platforms. Connecthings gives you access to one or several of the following environments:
preProd: The pre-production platform of the Herow platform
preProdAdtag: The pre-production platform of the AdTag platform
prod: The production platform of the Herow platform
prodAdtag: The production platforms of the AdTag platform

Warning:
You will get two different access keys:
An access key to log into the Herow Platform
An access key to use with our mobile SDK. This access key is composed of a login (identifier on Herow), a password (API_KEY on herow) and your company name. Please make sure you use the good credentials to connect the SDK to the correct Herow Platform, otherwise your application won't be able to detect zones.

Step 5: Enable your app to receive local Notifications

Register your application on the notification center

Open the AppDelegate.m file
Register your application on the notification center, taking care of managing code for iOs 9 and below and iOs 10 and higher

Switch to Swift

-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
  [...]
  if (SYSTEM_VERSION_LESS_THAN(@"10.0") && [application respondsToSelector:@selector(registerUserNotificationSettings:)]) {
      [application registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:UIUserNotificationTypeAlert|UIUserNotificationTypeSound categories:nil]];
  } else {
    UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
    [center requestAuthorizationWithOptions:(UNAuthorizationOptionSound | UNAuthorizationOptionAlert)
                          completionHandler:^(BOOL granted, NSError * _Nullable error) {
                              if (!error) {
                                  NSLog(@"request authorization succeeded!");
                              }
                          }];
  }
  return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    [...]
    if #available(iOS 10.0, *) {
        let center = UNUserNotificationCenter.current()
        center.requestAuthorization(options: [.alert, .sound]) { (granted, error) in
          if (error == nil) {
              NSLog("request authorization succeeded!");
          }
        }
    } else if(UIApplication.instancesRespond(to: #selector(UIApplication.registerUserNotificationSettings(_:)))){
            UIApplication.shared.registerUserNotificationSettings(UIUserNotificationSettings (types: [.alert, .sound], categories: nil))
    }
    return true
}

Note 1:
On iOS 8 and above, you must register your application on the notification center, even if you are only using local notifications.

Note 2:
With iOs 10, Apple has introduced a new way of managing registration with the UNUserNotificationCenter.
Apple recommends to use it and if you don't you will not receive any local notifications under iOS 11+.

Step 6: Generate Notification analytics

For iOs 9: the didReceiveNotification method

Open the AppDelegate
Implement the didReceiveNotification method

Switch to Swift

- (void) application:(UIApplication *)application
didReceiveLocalNotification:(UILocalNotification *)notification {
    [HerowDetectionManager didReceivePlaceNotification:[notification userInfo]];
}

func application(_ application: UIApplication, didReceive notification: UILocalNotification) {
    HerowDetectionManager.shared.didReceivePlaceNotification(notification.userInfo)
}

For iOs 10+: Notifications analytics are automatically handled.

be sure to call the HerowInitializer.synchronize() after having register the UNUserNotificationCenterDelegate to the UNUserNotificationCenter

Step 7: Realize an action when a local notification is clicked

Add the HerowReceiveNotificationContentDelegate to the AppDelegate. This delegate allows the app to be notified when a user clicks on a local notification.

Switch to Swift

@interface AppDelegate : UIResponder <UIApplicationDelegate, UNUserNotificationCenterDelegate, HerowReceiveNotificationContentDelegate>

class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate, HerowReceiveNotificationContentDelegate {

Switch to Swift

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [...]
    [HerowDetectionManager.shared registerReceiveNotificatonContentDelegate:self];
    return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    HerowDetectionManager.shared.registerReceiveNotificatonContentDelegate(self)
    return true
}

Implement the didReceivePlaceNotification and the didReceiveWelcomeNotification method of the HerowReceiveNotificationContentDelegate to allow your application to be explicitly notified when a notification generated by the SDK is clicked.

Switch to Swift

- (void) didReceivePlaceNotification:(HerowPlaceNotification *)placeNotification {
    NSLog(@"Do an action when the local notification is clicked - for example open a controller");
}

- (void) didReceiveWelcomeNotification:(HerowPlaceWelcomeNotification *)welcomeNotification {
    NSLog(@"Do an action when the local notification is clicked - for example open a controller");
}

func didReceivePlaceNotification(_ placeNotification: HerowPlaceNotification) {
    NSLog("open a controller with a place notification")
}

func didReceiveWelcomeNotification(_ welcomeNotification: HerowPlaceWelcomeNotification) {
    NSLog("open a controller with a place welcome notification")
}

Step 8: with Herow

Set a campaign on Herow platform

Connect you to the Herow Platform.
Create a zone at 200m of your office with a radius of 100m.
Create a campaign associated to the zone.
Don’t forget to launch the campaign !

Generate your first notification

Install the application
Accept the location permission and notification permission
Close your application or leave it running in the background
Go physically with your device in the zone you have just created before, you will receive the notification. This could take few seconds for your device to localize you are into the zone, and send you the notification associated.
Click on the notification that appears on your screen just for fun

Note:
To increase the efficiency of the SDK, make sure that the device has a good network signal and enable the Wifi.

Warning:
Think to make your application compliant with the GDPR, otherwise the SDK won't collect any data.
You can refer to our dedicated tutorial

Step 8(Bis): with AdTag

Configure a content associated to your beacon

Connect you to the AdTag Platform.
Find your Beacon
Configure a notification content in the SDK Content tab

Generate your first notification

Install the application
Accept the location permission and notification permission
Close your application or leave it running in the background
Put the battery back in your beacon (if the battery is on, remove it, and wait few minutes before putting it back)
Click on the notification that appears on your screen just for fun

Warning:
Think to make your application compliant with the GDPR, otherwise the SDK won't collect any data.
You can refer to our dedicated tutorial