What you will learn

You will learn:

  • to configure your Podfile with our Gitlab and our SDK.
  • to configure the HEROW 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/herowio/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
  • 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
  use_frameworks!
  pod "HerowLocationDetection", '~> 6.3.0'
  # 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'] = "5.0"
                configuration.build_settings['SUPPORTS_UIKITFORMAC'] = 'NO'
                configuration.build_settings['SUPPORTS_MACCATALYST'] = 'NO'
            end
        end
    end

end
  • Run $ pod update in your project directory

Note:

Your project is linked to the CoreLocation and libsqlite3 frameworks

Note:

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

Note:

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.2.2-comp'

Step 3: Configure the info.plist

Our SDK accesses two critical frameworks:

  • the CoreLocation framework to detect the user’s location
  • 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 motion one.

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

Note:

From the HEROW SDK version 6.3 onwards, a click and collect feature running as a background service is available for temporary user tracking when the app is in the background. This feature does not work with the Always Location permission.

  • NSMotionUsageDescription for motion permission
<key>NSMotionUsageDescription</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 Store Review Team will reject your application

Step 4: Configure the SDK inside the AppDelegate

Initialize the SDK

  • Import HerowConnection module

Switch to Swift

@import HerowConnection;
import HerowConnection
  • Add a HerowInitializer parameter to your AppDelegate

Switch to Swift

@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

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 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: GDPR Opt-ins

The HEROW SDK only works if the GDPR opt-in is given by the end-user. The SDK comes with two different opt-ins:

  • the USER_DATA opt-in (mandatory): collect the IDFV and the location data of the user. Default to false.

  • the STATUS opt-in (not mandatory): collect various analytics, default to true

Test if the opt-ins have been given

The method optinsNeverAsked from the HerowInitializer return true if the opt-ins have never been asked.

Switch to Swift

if ([herowInitializer optinsNeverAsked]) {

}
if herowInitializer.optinsNeverAsked() {

}

Update the opt-ins permissions

The method updateOptin from the HerowInitializer allow to update the optin permission.

Switch to Swift

[herowInitializer updateOptin:OptinUSER_DATA permission:true];
herowInitializer.updateOptin(.USER_DATA, permission: true)

Notify the SDK about the opt-ins permission update

Once, all the opt-ins have been updated, you must notify the SDK about it calling allOptinsAreUpdated from the HerowInitializer.

Switch to Swift

[herowInitializer allOptinsAreUpdated];
herowInitializer.allOptinsAreUpdated()

Calling this method launches:

  • the remote synchronization of the opt-ins with the Herow Platform.
  • the analytics treatment depending on the opt-ins

Note 1:

If the user is offline, or the synchronization with the Herow Platform meets an error, the SDK will automatically retry to synchronize the opt-ins with the Herow Platform later on.

Note 2:

Keep in mind that the user can update the opt-ins at any time. Always think to call the method allOptinsAreUpdated when the opt-ins have been updated.

Check the opt-ins status

Use the method isOptinAuthorized from the HerowInitializer to check the status of an opt-in.

Switch to Swift

[herowInitializer isOptinAuthorized:OptinUSER_DATA];
herowInitializer.isOptinAuthorized(.USER_DATA)

Step 6: Setting a Custom ID

To set a custom ID, make the following call as soon as the user logs in:

HerowInitializer.getInstance().setCustomId("hashUserEmail");

If the user logout, you can use the removeCustomId method.

HerowInitializer.getInstance().removeCustomId();

Step 7: 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:

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 8: Receiving notifications while application is on Foreground

By default, the HEROW SDK displays notifications while your application is in the Background only. To receive notifications in Foreground:

⋅⋅1. Add delegate UNUserNotificationCenterDelegate in AppDelegate class

⋅⋅2. Set the UNUserNotificationCenter delegate

Switch to Swift

        UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
        center.delegate = self;
        let center = UNUserNotificationCenter.current()
        center.delegate = self

⋅⋅3. Implement willPresent function

Switch to Swift

     - (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
         completionHandler(UNNotificationPresentationOptionAlert | UNNotificationPresentationOptionBadge | UNNotificationPresentationOptionSound);
     }
     @available(iOS 10.0, *)
       @objc  public func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (_ options: UNNotificationPresentationOptions) -> Void) {
           completionHandler(  [.badge, .alert, .sound])
       }

Step 9: 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 {
    HerowDetectionManager.shared.registerReceiveNotificatonContentDelegate(self)
    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")
}