What you will learn

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

Prerequisites - 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 Android Device, with Bluetooth 4.0 and Android 4.0 and above, to be able to interact with BLE beacons.
  • The Android Studio application, which you can download from the Android Developers 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 android>beacon>3-Alert>Starter project with Android Studio

Step 2: Configure your SDK

  • Open the ApplicationNotification class
  • Configure the SDK with:
    • the UUID of your beacon
    • the appropriate Adtag Environment (DEMO / PREPROD / PROD / PROD_US)
    • your SDK credentials (your login, password, and company details from Connecthings )
      AdtagInitializer.initInstance(this)
                      .initUrlType(UrlType.DEMO / ... / UrlType.PROD)
                      .initUser("YOUR_USER",  "YOUR_PWD")
                      .initCompany("YOUR_COMPANY_KEY").synchronize();

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

Step 3: Create your first Alert

  • Open the ActivityMain

  • 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 following abstract methods to detect nearby beacons:
 @Override
    public boolean createBeaconAlert(BeaconContent beaconContent) {
    }

    @Override
    public boolean removeBeaconAlert(BeaconContent beaconContent, BeaconAlertStrategyParameter.BeaconRemoveStatus beaconRemoveStatus) {
    }

    @Override
    public void onNetworkError(FEED_STATUS feed_status) {
    }

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:

  • BeaconContent: all Adtag data associated with a specific beacon
  • BeaconRemoveStatus: indicates the reason for an alert removal
    • BEACON_EXIT: alert removal due to the exit of a beacon's region
    • CONDITION_INVALID: alert removal due to invalid conditions
  • feedStatus: status of the connection with the Adtag Platform - Possible values are:
    • IN_PROGRESS: ongoing content download from Adtag
    • BACKEND_ERROR: download error due to Adtag
    • NO_NETWORK_ERROR: incomplete content download because the device does not have access to an internet network (Wi-Fi or cellular)
    • BACKEND_SUCCESS: successful content download

Note 3:

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

  • Register the BeaconAlertListener interface on the AdtagBeaconManager when the activity resumes, using the following code:
adtagBeaconManager.registerBeaconAlertListener(alertListener);
  • Unregister the BeaconAlertListener interface from the AdtagBeaconManager when the activity pauses, using the following code:
adtagBeaconManager.unRegisterBeaconAlertListener(alertListener);

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] (updating-beacon-content-to-the-adtag-platform.html).

You can set up any value you want in Adtag but your application must be 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.

    @Override
  public boolean createBeaconAlert(BeaconContent beaconContent) {
                     
  if(beaconContent.getAction().equals("popup")){ 
          //show popup
  }
      return true;
  }

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

  • Use the methods from the BeaconContent object 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 associated with the alert.
    • Learn more about these methods in the Adtag data model document
    @Override
  public boolean createBeaconAlert(BeaconContent beaconContent) {
                     
     if(beaconContent.getAction().equals("popup")){
        tvBeaconAlert.setText(beaconContent.getAlertTitle());
        return true;
        }
       {...}
  }
  • Complete the createBeaconAlert method to anticipate other cases: e.g. default action when the type of action associated with 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 ;
  }
  • 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
    @Override
    public boolean removeBeaconAlert(BeaconContent beaconContent, BeaconAlertStrategyParameter.BeaconRemoveStatus beaconRemoveStatus) {
         tvBeaconAlert.setText("Remove beacon alert action");
        return true;
    }
  • Finally, implement the onNetworkError method to check that there are no network connectivity problems:
    @Override
    public void onNetworkError(FEED_STATUS feed_status) {
        tvBeaconAlert.setText("Network connectivity problems");
    }

Keep in mind when using the default alert behavior

To generate 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

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

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.