What you will learn

This tutorial will teach you how to create an alert associated to a specific beacon.

Pre-requisites - What you need to get started

  • A Gitlab Account: The SDK is available through a private Gitlab. You must have received an email with an user account including a link to create a password.
  • Your SDK user information: To initialize the SDK, your should have received a Login, a Password and a Company name.
  • A beacon: A beacon configured on your account is mandatory to test the application.
  • An iOS Device: You need a compatible Bluetooth Low Energy iOS device that is able to detect beacons.
  • The Xcode application: Xcode should be downloaded 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>Beacon>3-Alert folder

SWIFT:

  • Open the sdk-tutorial>ios>SWIFT>Beacon>3-Alert folder

Step 2: Configure the SDK

  • Configure your CocoaPod and .plist files

  • Configure the SDK with:

    • the UUID of your beacon
    • the Adtag Platform you would like to connect,
    • and the login, password, and company informations received from Connecthings.

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

Step 3: Create your first Alert

  • Open the ViewController.h file, and add it to the ATBeaconAlertDelegate protocole
@interface ViewController : UIViewController<ATBeaconAlertDelegate>
  • Open the ViewController.m file

  • Register the BeaconAlertDelegate on the viewDidAppear method

-(void)viewDidAppear:(BOOL)animated{
    [super viewDidAppear:animated];
    [[ATBeaconManager sharedInstance] registerBeaconAlertDelgate:self];
}
  • Unregister the BeaconAlertDelegate in the viewDidDisappear method
-(void)viewDidDisappear:(BOOL)animated{
    [super viewDidDisappear:animated];
    [[ATBeaconManager sharedInstance] registerBeaconAlertDelgate:nil];
}
  • Implement the delegate method to detect nearby beacons
-(BOOL)createBeaconAlert:(ATBeaconContent *)_beaconContent{
}

-(BOOL)removeBeaconAlert:(ATBeaconContent *)_beaconContent actionStatus:(ATBeaconRemoveStatus)_actionStatus{
}

-(void)onNetworkError:(ATRangeFeedStatus *)_feedStatus{
}

Note 1:

When you are notified of a delegate event, you will receive the appropriate callback methods
These callback methods allow you to manage the alert lifecycle:

  • CreateBeaconAlert: once a beacon is detected, the mobile SDK will check the beacon conditions before allowing the alert creation process with this method.
  • RemoveBeaconAlert: once a beacon is not detected anymore or when the beacon does not match the conditions configured in the Alert Strategy anymore, the mobile SDK will proceed with the alert deletion process with this method.
  • OnNetworkError: if the SDK detects that there are network connectivity issues, it checks the device's cache for information on the nearby beacon. If no information is available, the SDK informs the app of the network error with this OnNetworkError method.

Note 2:

The 3 methods above contain the following parameters:

  • _beaconContents: all Adtag data associated to a specific beacon

  • ATBeaconRemoveStatus _actionStatus: indicates the reason of alert removal

    • ATBeaconRemoveStatusBeaconExit: alert removal due to the exit from the beacon's region
    • ATBeaconRemoveStatusConditionInvalid: alert removal due to invalid conditions
  • ATRangeFeedStatus feedStatus: status of the connection with the Adtag Platform - The FEED_STATUS values are:

    • ATRangeFeedStatusInProgress: content download from the Adtag Platform is in progress
    • ATRangeFeedStatusBackendError: download error due to the Adtag Platform
    • ATRangeFeedStatusNetworkError: content download cannot be completed because the device does not have access to an internet network (wifi or cellular)
    • ATRangeFeedStatusBackendSuccess: successful content download

Step 4: Show an alert

How to determine the alert action

  • Use the [beaconContent getAction] method to determine what action to trigger with this beacon
    • This method returns the action defined in Adtag, in the Beacon-Alert-Parameters Action field.
    • You are free to define your own actions in the Adtag Platform
    • Let's say that your application will trigger an alert and the beacon action in the Adtag Platform is set to popup.
    • Learn more about content management with this dedicated tutorial
    • Once the app is notified that an alert can be triggered, the app can push the appropriate action (e.g.: popup view)
-(BOOL)createBeaconAlert:(ATBeaconContent *)_beaconContent{
    if([@"popup" isEqualToString:[_beaconContent getAction]]){
        // create a popup view
        return YES ;
    }
    return NO ;
}

Now that the type of action is determined, the app can retrieve the appropriate content!

How to retrieve the content associated to the beacon alert

  • Use the [beaconContent getAlertTitle] method and the [beaconContent getAlertDescription] to retrieve the alert content from the Adtag Plateform
-(BOOL)createBeaconAlert:(ATBeaconContent *)_beaconContent{
    if([@"popup" isEqualToString:[_beaconContent getAction]]){
        // create a popup view
        NSLog(@"Well done! now you can create your Pop UP");
        _txtAlertMessage.text = [_beaconContent getAlertTitle];
        [_txtAlertMessage setNeedsDisplay];
        _buttonAlert.hidden=false;
        currentAlertBeaconContent = _beaconContent;
        return YES ;
    }
    {...}
  • Complete the method to anticipate other cases: e.g. default action when the type of action associated to the beacon is not recognized
-(BOOL)createBeaconAlert:(ATBeaconContent *)_beaconContent{
    if([@"popup" isEqualToString:[_beaconContent getAction]]){
        // create a popup view
        NSLog(@"Well done! now you can create your Pop UP");
        _txtAlertMessage.text = [_beaconContent getAlertTitle];
        [_txtAlertMessage setNeedsDisplay];
        _buttonAlert.hidden=false;
        currentAlertBeaconContent = _beaconContent;
        return YES ;
    }
    
    _txtAlertMessage.text = @"No POPUP action for beacon";
    [_txtAlertMessage setNeedsDisplay];
    return NO ;
}
  • Include the removeBeaconAlert method to avoid deleting the beacon's action: when it returns "True", the SDK automatically flags the beacon with actionStatus = ATBeaconActionStatusActionIsDone
 -(BOOL)removeBeaconAlert:(ATBeaconContent *)_beaconContent actionStatus:(ATBeaconRemoveStatus)_actionStatus{
    _buttonAlert.hidden= true;
    _txtAlertMessage.text = @"Remove beacon alert action";
    [_txtAlertMessage setNeedsDisplay];
    return YES;
}
  • Finally, include this method to check that there are no network connectivity problems:
-(void)onNetworkError:(ATRangeFeedStatus *)_feedStatus{
   _txtAlertMessage.text = @"Network connectivity problems";
    [_txtAlertMessage setNeedsDisplay];
}

Tips to have in mind when using the default alert behavior

To generate the createBeaconAlert callback

  1. Your beacon must have been added to the Adtag platform with specific content.
  2. Your beacon must match the conditions of the strategy defined in Adtag and in the mobile SDK.
  3. If an alert has already been triggered on the device with the same beacon, the app must remain within range of the beacon for at least 60 seconds (for the beacon's flag to be reset to readyForAction), or the device. must exit and re-enter the beacon's range

To generate the removeBeaconAlert beacon alert callback

  1. You must have received the createBeaconAlert callback.
  2. The createBeaconAlert method must have been processed successfully and have returned "True".
  3. Your beacon must not be detected anymore or your beacon must not match the Alert Strategy conditions anymore.

Step 5: Start testing

If your beacon is already emitting, you must stop/restart the emission process in order to simulate a new region entry for the smartphone, and generate a notification.

There are 2 solutions to stop/restart the emission process:

  • You can put the beacon inside a microwave (but don't start it!)
  • You can remove the battery from the beacon (in that case, depending on the model, it can take up to 30 seconds for the beacon to start emitting again when you put the battery back)
  1. In Xcode, click on "Play" to launch the installation process of the application you just built on your phone

  2. Activate your beacon and put your device in its correct action range (as defined in Adtag)

  3. Wait for a few seconds

  4. The title of the alert appears, as defined in Adtag, along with a button and the following text: Click to get more information.

  5. Click on the button and access the detailed content of the alert.