What you will learn

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

Pre-requisites - What you need to get started

  • Your SDK credentials, including an SDK Login, Password, and Company Key to initialize the SDK.
  • A BLE beacon, which has been configured on your account, in order to test interactions with your app.
  • An iOS Device, with Bluetooth 4.0 and iOs 8 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>Beacon>3-Alert folder

SWIFT:

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

Step 2: Configure the SDK

  • Configure your CocoaPod files and .plist
  • Configure your SDK with:
    • the UUID of your beacon
    • the appropriate Adtag Environment (DEMO / PREPROD / PROD / PROD_US)
    • your SDK credentials
    [[[ATAdtagInitializer sharedInstance] configureUrlType:ATUrlTypeProd andLogin:@"__USER__" andPassword:@"__PSWD__" andCompany:@"__COMPANY__"] synchronize];

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 from the viewDidDisappear method
-(void)viewDidDisappear:(BOOL)animated{
    [super viewDidDisappear:animated];
    [[ATBeaconManager sharedInstance] registerBeaconAlertDelgate:nil];
}
  • Implement the following delegate method to detect nearby beacons:
-(BOOL)createBeaconAlert:(ATBeaconContent *)_beaconContent{
}

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

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

Note 1:

These callback methods allow you to manage the alert lifecycle:

  • createBeaconAlert: when a beacon is detected, our SDK checks the beacon conditions before allowing the alert creation process
  • removeBeaconAlert: when a beacon is no longer detected, or when it no longer matches the conditions configured in the Alert Strategy, our SDK proceeds with the alert deletion process
  • 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

Note 2:

The 3 methods above contain the following parameters:

  • _beaconContents: all Adtag data associated with a specific beacon
  • ATBeaconRemoveStatus: indicates the reason for an alert removal
    • ATBeaconRemoveStatusBeaconExit: alert removal due to the exit from the beacon's region
    • ATBeaconRemoveStatusConditionInvalid: alert removal due to invalid conditions
  • ATRangeFeedStatus: status of the connection with the Adtag Platform - Possible values are:
    • ATRangeFeedStatusInProgress: ongoing content download from Adtag
    • ATRangeFeedStatusBackendError: download error due to Adtag
    • ATRangeFeedStatusNetworkError: incomplete content download because the device does not have access to an internet network (Wi-Fi or cellular)
    • ATRangeFeedStatusBackendSuccess: successful content download

Step 4: Generate an alert

Determine the action associated with your alert

Use the [beaconContent getAction] method to determine what action to trigger with your beacon.

This method returns the value defined in the Beacon-Alert-Parameters Action field in Adtag.

Learn more about content management in Adtag in this dedicated document.

You can set up any value you want in Adtag as long as your application is able to handle this action.

For instance, let's say the action parameter is popup in Adtag, and code a popup view to open once the app is notified that an alert can be triggered.

-(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, your app can work on retrieving the appropriate content:

Retrieve the content associated with the beacon alert

  • Use the methods from the ATBeaconContent to build your alert:
    • [beaconContent getAlertTitle]: returns the title of the alert
    • [beaconContent getAlertDescription]: returns the description of the alert
    • [beaconContent getAlertThumbnail]: returns the Adtag url of the thumbnail image associated with the alert
    • Learn more about the methods in the Adtag data model document
-(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 createBeaconAlert 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 ;
}
  • Implement the removeBeaconAlert method.
    • If you want to avoid deleting the beacon's action when this method is called, make it return false; otherwise, the SDK will automatically flag 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, implement the onNetworkError method to check that there are no network connectivity problems:
-(void)onNetworkError:(ATRangeFeedStatus *)_feedStatus{
   _txtAlertMessage.text = @"Network connectivity problems";
    [_txtAlertMessage setNeedsDisplay];
}

Keep in mind when using the default alert behavior

Generating the createBeaconAlert callback

  1. Your beacon must be registered on the Adtag platform and have associated 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 a device with the same beacon, the app must remain within range of the beacon for at least 60 seconds, or the device must exit and re-enter the beacon's range, for the beacon's flag to be reset to readyForAction

Generating 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 no longer be detected, or must no longer match the Alert Strategy conditions

Step 5: Start testing

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

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

  3. Activate your beacon and place your smartphone in the appropriate action range (as defined in Adtag)

  4. Wait for a few seconds (maximum 1 minute)

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

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