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 ID and SDK Key on Herow to initialize the SDK.
  • A zone, which has been configured on your herow account.
  • An iOS Device, with 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


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


  • In the cloned sdk-tutorial folder, navigate to ios>SWIFT>Zone>1-QuickStart>Starter
  • 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
  pod "HerowLocationDetection", '~> 6.1.1'
  # Pods for QuickComplete

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

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

	post_install do |installer|
        installer.pods_project.targets.each do |target|
            target.build_configurations.each do |configuration|
                configuration.build_settings['SWIFT_VERSION'] = "5.0"
                configuration.build_settings['SUPPORTS_UIKITFORMAC'] = 'NO'
                configuration.build_settings['SUPPORTS_MACCATALYST'] = 'NO'

  • Run $ pod update in your project directory


Your project is linked to the CoreLocation and libsqlite3 frameworks


On iOS, if you are using cocoapods 1.7.x or higher version, and you encounter an error when runinng pod install command, you will need to follow these steps:

1- Clean your cocoapods cache

rm -Rf ~/.cocoapods/repos/

rm -Rf Pods Podfile.lock

2- Add Herow Specs repository with the following commands

pod repo add herow-pub-specs https://forge.herow.io/pub/Specs master

3- Redo your pod install command

pod install


If you need to remove the "use_frameworks!" option from your Podfile, you can do it and replace the "HerowLocationDetection" version by the following one:

pod "HerowLocationDetection", '6.1.1-comp'

Step 3: Configure the info.plist

Our SDK accesses three critical frameworks:

  • the CoreLocation framework to detect the user’s location and iBeacons around
  • the CoreBluetooth framework to check Bluetooth status
  • the CoreMotion framework to get complementary informations about the travel mode

All of them require an explicit permission from the user but the SDK do not require the Bluetooth and the motion ones.

In addition, the iOS system requires an application to provide a description of the framework usage.

These descriptions can be configured in the info.plist file, by adding the following keys:

  • The three keys for the location permission
<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>
<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>
<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
<string>Your description goes here</string>
<string>Your description goes here</string>
  • NSMotionUsageDescription for motion permission
<string>Your description goes here</string>


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]
        configAppWithIdentifier:@"your SDK ID" sdkKey:@"your SDK Key"] synchronize];
    return YES;
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    herowInitializer = HerowInitializer.shared
    herowInitializer?.configPlatform(Platform.prod).configApp(identifier: "your SDK ID", sdkKey: "your SDK Key").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 HEROW platform. HEROW gives you access to one or several of the following environments:

  • preProd: The pre-production platform of the HEROW platform
  • prod: The production platform of the HEROW platform


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 an SDK ID and SDK Key on Herow. 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: [UIApplication.LaunchOptionsKey: 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.shared didReceivePlaceNotification:[notification userInfo]];
func application(_ application: UIApplication, didReceive notification: UILocalNotification) {

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 {
  • Register the AppDelegate to the HerowDetectionManager

Switch to Swift

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [HerowDetectionManager.shared registerReceiveNotificatonContentDelegate:self];
    return YES;
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    return true
  • Implement the didReceivePlaceNotification 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");
func didReceivePlaceNotification(_ placeNotification: HerowPlaceNotification) {
    NSLog("open a controller with a place notification")

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

  1. Install the application

  2. Accept the location permission and notification permission

  3. Close your application or leave it running in the background

  4. 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.

  5. Click on the notification that appears on your screen just for fun


To customize the notification aspect you can follow this tutorial.


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


Think to make your application compliant with the GDPR, otherwise the SDK won't collect any data.

You can refer to our dedicated tutorial