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
- Your zone must be registered on the Herow platform and have associated content.
- 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
- You must have received the createInAppAction callback
- The createInAppAction method must have been processed successfully and have returned true
- Your zone must no longer be detected
Step 5: Start testing
Configure a in-Action tag compaign on the Herow Platform
In Xcode, click on "Play" to launch the installation of the application you have just built on your phone
When the application starts, popups ask for permission to access your phone location & notifications: grant them!
Wait for a few seconds
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.