What you will learn

This tutorial will teach you how to create an in-app action associated with a specific zone.

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 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/opsct/sdk-tutorial.git

ObjectiveC:

  • Open the sdk-tutorial>ios>ObjectiveC>Zone>3-InApp-Action folder

SWIFT:

  • Open the sdk-tutorial>ios>SWIFT>Zone>3-InApp-Action folder

Step 2: Configure the SDK

  • Configure your CocoaPod files and .plist
  • Configure your SDK with:
    • the appropriate Herow Environment ( PREPROD / PROD )
    • your SDK credentials

Switch to Swift

[[[[HerowInitializer sharedInstance] configPlatform: HerowPlatform.prod]
									 configAppWithIdentifier:@"your username"
									 sdkKey:@"your SDK Key"]
									 synchronize];


herowInitializer = HerowInitializer.shared
herowInitializer?.configPlatform(Platform.prod)
				 .configApp(identifier: "your username", sdkKey: "your SDK Key")
				 .synchronize()

If you need more informations, have a look to the 5 minutes quickstart tutorial

Step 3: Create your first InApp-Action

  • Open the ViewController.h file, and add it to the HerowInAppActionDelegate protocol

Switch to Swift

@interface ViewController : UIViewController <HerowInAppActionDelegate>

class ViewController: UIViewController, HerowInAppActionDelegate {
    ...
}

  • Open the ViewController.m file

  • Register the HerowInAppActionDelegate on the viewDidAppear method thanks to an HerowDetectionManager:

Switch to Swift

- (void)viewWillAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [[HerowDetectionManager shared] registerInAppActionDelegate:self];
}

override func viewWillAppear(_ animated: Bool) {
    super.viewDidAppear(animated);
    HerowDetectionManager.shared.registerInAppActionDelegate(self)
}
  • Unregister the HerowInAppActionDelegate from the viewDidDisappear method

Switch to Swift

- (void)viewWillDisappear:(BOOL)animated {
    [super viewDidDisappear:animated];
    [[HerowDetectionManager shared] unregisterInAppActionDelegate];
}

override func viewWillDisappear(_ animated: Bool) {
    super.viewDidAppear(animated);
    HerowDetectionManager.shared.unregisterInAppActionDelegate()
}
  • Implement the methods of the HerowInAppActionDelegate, so that your app is notified of a potential upcoming in-app action.

Switch to Swift

- (BOOL)createInAppAction:(HerowPlaceInAppAction * _Nonnull)placeInAppAction statusManager:(id<InAppActionStatusManagerDelegate> _Nonnull)statusManager {

}

- (BOOL)removeInAppAction:(HerowPlaceInAppAction * _Nonnull)placeInAppAction inAppActionRemoveStatus:(enum InAppActionRemoveStatus)inAppActionRemoveStatus {

}

func createInAppAction(_ placeInAppAction: HerowPlaceInAppAction, statusManager: InAppActionStatusManagerDelegate) -> Bool {

}

func removeInAppAction(_ placeInAppAction: HerowPlaceInAppAction, inAppActionRemoveStatus: InAppActionRemoveStatus) -> Bool {

}

Note 1:

These callback methods allow you to manage the in-app action lifecycle:

  • createInAppAction: to be notified to create an in-app action. When a zone is detected, our SDK checks that it matches the conditions configured on Herow before allowing the in-app action creation process
  • removeInAppAction: to be notified to remove an in-app action. When a zone is no longer detected, or when it no longer matches the conditions configured on Herow, our SDK proceeds with the in-app action deletion process

Note 2:

The 2 methods above contain the following parameters:

  • HerowPlaceInAppAction: all Herow data associated with a specific technology (zone, beacon, qrcode...)
  • InAppActionStatusManagerDelegate: delegate which gives you the possibility to declare an in-app action as done
  • InAppActionRemoveStatus: indicates the reason for a removal
    • PLACE_EXIT: InApp Action removal due to the exit of a place's region
    • CONDITION_INVALID: InApp Action removal due to invalid conditions

Step 4: Generate an in-app action

Determine the action associated with your in-app action

Use the placeInAppAction.getTag() method to determine the tag.

This method returns the value defined in the tag field on Herow.

You can set up any value you want on Herow if your application is able to handle this tag.

For instance, if the tag parameter is configured as restaurant on Herow, then the developer needs to code a related view so that it is opened when an in-app action is triggered.

Switch to Swift

- (BOOL)createInAppAction:(HerowPlaceInAppAction * _Nonnull)placeInAppAction statusManager:(id<InAppActionStatusManagerDelegate> _Nonnull)statusManager {
    if([@"restaurant" isEqualToString:[placeInAppAction getTag]]){
        //Show a dedicated view when a user is in a restaurant
        NSLog(@"Well done! now you can create your alert action");
        _txtAlertMessage.text = [placeInAppAction getTag];
        [_txtAlertMessage setNeedsDisplay];
        _buttonAlert.hidden=false;
        currentPlaceInAppAction = placeInAppAction;
        return YES;
    }
    return NO;
}

 func createInAppAction(_ placeInAppAction: HerowPlaceInAppAction, statusManager: InAppActionStatusManagerDelegate) -> Bool {
    if ("restaurant" == placeInAppAction.getTag()) {
        //Show a dedicated view when a user is in a restaurant
        print("Well done! now you have created your alert action")
        self.txtAlertMessage.text = placeInAppAction.getTag()
        txtAlertMessage.setNeedsDisplay()
        buttonInAppAction.isHidden = false
        currentPlaceInAppAction = placeInAppAction
        return true
    }
    return false
}

Now that the type of action is determined function of the tag, your app can work on retrieving the appropriate content:

  • Complete the createInAppAction method to anticipate other cases: e.g. default action when the type of action associated to a zone is not recognized

Switch to Swift

- (BOOL)createInAppAction:(HerowPlaceInAppAction * _Nonnull)placeInAppAction statusManager:(id<InAppActionStatusManagerDelegate> _Nonnull)statusManager {
    if([@"restaurant" isEqualToString:[placeInAppAction getTag]]){
        //Show a dedicated view when a user is in a restaurant
        NSLog(@"Well done! you have created your first in-app action");
        _txtAlertMessage.text = [placeInAppAction getTag];
        [_txtAlertMessage setNeedsDisplay];
        _buttonAlert.hidden=false;
        currentPlaceInAppAction = placeInAppAction;
        return YES ;
    }
    _txtAlertMessage.text = @"No zone is detected";
    [_txtAlertMessage setNeedsDisplay];
    return NO ;
}

func createInAppAction(_ placeInAppAction: HerowPlaceInAppAction, statusManager: InAppActionStatusManagerDelegate) -> Bool {
    if ("restaurant" == placeInAppAction.getTag()) {
        //Show a dedicated view when a user is in a restaurant
        print("Well done! you have created your first in-app action")
        self.txtAlertMessage.text = placeInAppAction.getTag()
        txtAlertMessage.setNeedsDisplay()
        buttonInAppAction.isHidden = false
        currentPlaceInAppAction = placeInAppAction
        return true
    }
    self.txtAlertMessage.text = "No zones detected"
    txtAlertMessage.setNeedsDisplay()
    return false
}
  • Implement the removeInAppAction method.
    • If you want to avoid deleting the in-app action when this method is called, make it return false; otherwise, the SDK will automatically flag the zone with actionStatus = InAppActionStatus.DONE

Switch to Swift

- (BOOL)removeInAppAction:(HerowPlaceInAppAction * _Nonnull)placeInAppAction inAppActionRemoveStatus:(enum InAppActionRemoveStatus)inAppActionRemoveStatus {
    _buttonAlert.hidden= true;
    _txtAlertMessage.text = @"The In-App Action has been removed";
    [_txtAlertMessage setNeedsDisplay];
    return YES;
}

func removeInAppAction(_ placeInAppAction: HerowPlaceInAppAction, inAppActionRemoveStatus: InAppActionRemoveStatus) -> Bool {
    print("Well done! now you have removed your in-app action")
    buttonInAppAction.isHidden = true
    txtAlertMessage.text = "The In-App Action has been removed"
    txtAlertMessage.setNeedsDisplay()
    return true
}

Keep in mind when using the default in-app action behavior

Generating the createInAppAction callback

  1. Your zone must be registered on the Herow platform and have associated content.
  2. If an in-app action has already been triggered on a device in the same zone, the app must remain within the zone for at least 60 seconds, or the device must exit and re-enter the zone, for the zone’s flag to be reset to readyForAction

Generating the removeInAppAction callback

  1. You must have received the createInAppAction callback
  2. The createInAppAction method must have been processed successfully and have returned true
  3. Your zone must no longer be detected

Step 5: Start testing

  1. Configure a in-Action tag compaign on the Herow Platform

  2. In Xcode, click on "Play" to launch the installation of the application you have just built on your phone

  3. When the application starts, popups ask for permission to access your phone location & notifications: grant them!

  4. Wait for a few seconds

  5. The tag of the in-app action appears, as defined in Herow, along with a button and the following text: Click to get more information.