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 Nexus Account: the SDK is available through a private Nexus. You must have received an email with your user account, including a link to create a password
  • Your SDK user information: in order to initialize the Mobile SDK, you must have received a User Name, a Password and a Company
  • A BLE beacon: a BLE beacon configured on your account is mandatory to test the application
  • An Android Device: you need a compatible Bluetooth Low Energy Android device that is able to detect beacons
  • The Android Studio application: you must have downloaded Android Studio from the Android Developpers’ website
  • You must have completed the 5 minutes QuickStart Tutorial.

Step 1: Clone the sdk-tutorial repository

  • Clone the sdk-tutorial repository
git clone https://github.com/Connecthings/sdk-tutorial.git
  • Open the project android>beacon>3-Alert>Starter with Android Studio

Step 2: Configure your SDK

  • Open the class ApplicationAlert

  • Configure your SDK with:

    • the UUID of your beacon
    • the appropriate Adtag Environment
    • your login, password, and company details you received from Connecthings

If you need more informations, have a look to the how to Configure the SDK in the 5 minutes quickstart tutorial.

Step 3: Create your first Alert

  • Open the activity

  • Implement the BeaconAlertListener interface

  • Register the BeaconAlertListener on the onCreate method

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
     
        adtagBeaconManager.registerBeaconAlertListener(this);
 
  • Implement the abstract methods to detect nearby beacons
 @Override
    public boolean createBeaconAlert(BeaconContent beaconContent) {
    }

    @Override
    public boolean removeBeaconAlert(BeaconContent beaconContent, BeaconAlertStrategyParameter.ATBeaconRemoveStatus atBeaconRemoveStatus) {
    }

    @Override
    public void onNetworkError(FEED_STATUS feed_status) {
    }

Note 1:

When you are notified of a abstract methods, 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:

  • BeaconContent: all Adtag data associated to a specific beacon

  • BeaconRemoveStatus: indicates the reason of alert removal

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

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

Note 3:

When an Activity is implementing the BeaconAlertListener interface, the BeaconAlertListener is automatically registered/unregistered to the AdtagBeaconManager.
If you implement the BeaconAlertListener interface on a fragment object or any other object, you must:

  • register the BeaconAlertListener interface to the AdtagBeaconManager when the activity resumes, using the following code:
adtagBeaconManager.registerBeaconAlertListener(alertListener);
  • unregister the BeaconAlertListener interface to the AdtagBeaconManager when the activity goes to pause, using the following code:
adtagBeaconManager.unRegisterBeaconAlertListener(alertListener);

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.
    • Once the app is notified that an alert can be triggered, the app can push the appropriate action (e.g.: popup view) .
        @Override
      public boolean createBeaconAlert(BeaconContent beaconContent) {
                         
      if(beaconContent.getAction().equals("popup")){ 
              //show popup
      }
          return true;
      }
    

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

  • Use the beaconContent.getAlertDescription() or the beaconContent.getAlertTitle() method to retrieve the alert description from the Adtag Platform

    • This method returns the corresponding beacon description as defined in the Beacon-Alert description field.
        @Override
      public boolean createBeaconAlert(BeaconContent beaconContent) {
                         
         if(beaconContent.getAction().equals("popup")){
            tvBeaconAlert.setText(beaconContent.getAlertTitle());
            return true;
            }
           {...}
      }
    
  • Complete the method to anticipate other cases: e.g. default action when the type of action associated to the beacon is not recognized

    @Override
  public boolean createBeaconAlert(BeaconContent beaconContent) {
                     
     if(beaconContent.getAction().equals("popup")){
        tvBeaconAlert.setText(beaconContent.getAlertTitle());
        return true;
        }
      tvBeaconAlert.setText("No POPUP action for beacon");
      return false ;
  }
  • Include the removeBeaconAlert method to avoid deleting the beacon's action: when it returns "True", the SDK automatically flags the beacon with actionStatus = ATBeaconActionStatusActionIsDone
    @Override
    public boolean removeBeaconAlert(BeaconContent beaconContent, BeaconAlertStrategyParameter.ATBeaconRemoveStatus atBeaconRemoveStatus) {
         tvBeaconAlert.setText("Remove beacon alert action");
        return true;
    }
  • Finally, include this method to check that there are no network connectivity problems:
    @Override
    public void onNetworkError(FEED_STATUS feed_status) {
        tvBeaconAlert.setText("Network connectivity problems");
    }

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

  1. From Android Studio, launch the installation process of the application you have just built on your mobile 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.