What you will learn:

By integrating our SDK, you can display Beacon Notifications on your app when a beacon is detected nearby.

To make things easier, our SDK contains a default Auto Beacon Notification: this is a built-in notification that is automatically generated when a beacon is detected nearby, as soon as the SDK has been initialized in your app.

You also have the ability to configure custom-built notifications, using our model of interfaces and built-in objects.

In both cases, you can manage the content of your beacon notifications directly on our AdTag platform.

This tutorial tells you more about these Auto and custom-built beacon notifications, and how you can work with them.

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.

Initialize the SDK

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>2-Notification>Starter project with Android Studio

Step 2: Configure the 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

Work with Auto Beacon Notifications

As a reminder, Auto Beacon Notifications are notifications generated by default by the SDK. You can manage their content (text – title & description - , URI, and content image), and disable them if necessary, directly from the AdTag platform, in the Application Management section. The icon associated with the notification can also be customized through the SDK.

Learn more on notification management in AdTag in the AdTag tutorial

Personalizing the notification icon

You can customize the icon associated with your Auto Beacon Notification (not to be confused with the content image associated with the notification, which is managed in AdTag), by adding the following to your drawable resources folder:

  • icon_beacon_notification_android4 - for Android 4 or below.
  • icon_beacon_notification for Android 5 or above.

Create custom-built notifications

If you would like to implement notifications that are more customizable than our Auto Beacon notifications, you can replace them with your own, custom-built beacon notifications, as described in the following section.

Notification Model Overview

First, let’s go through an overview of the notification model, with the corresponding interfaces and built-in objects.

The AsyncBeaconNotificationListener

The AsyncBeaconNotificationListener is an interface that:

  • alerts your application when it has to create a beacon notification, using the createBeaconNotification method.
  • allows your application to complete an asynchronous task of your choice before displaying a notification.

The createBeaconNotification method has two arguments:

  • BeaconContent: the content used to create the notifications
  • AsyncBeaconNotificationManager: the object used to notify the SDK when the notification is ready to be displayed

The AsyncBeaconNotificationManager

The AsyncBeaconNotificationManager is an interface that is mainly in charge of displaying the notification linked with a beacon. Before a notification is triggered, the AsyncBeaconNotificationManager checks that the corresponding beacon is still within range. If so, the notification is displayed; otherwise, nothing appears for the end user.

To notify the AsyncBeaconNotificationManager of the need to display a notification, you must call the displayBeaconNotification method.

The displayBeaconNotification method has two arguments:

  • BeaconContent: the content used to create the notification
  • Notification: the notification that will be displayed

The AsyncBeaconNotificationImageCreator

The AsyncBeaconNotificationImageCreator is a specific implementation of the AsyncBeaconNotificationListener interface. It directly downloads the notification image from AdTag, and to display the beacon notification with the corresponding image for Android 4 and above.

The AsyncBeaconNotificationImageCreator must be initialized with a BeaconNotificationImageBuilder.

The BeaconNotificationImageBuilder

The BeaconNotificationImageBuilder interface allows to create native Notifications once images are downloaded from AdTag by the SDK.

It must implement the buildBeaconNotification method, which has one argument - BeaconContentImage -, and returns the end native notification.

BeaconContentImage

BeaconContentImage has 4 additional methods compared to the BeaconContent object:

  • getImage: returns the bitmap associated with the notification image on AdTag
  • hasImage: returns true if the image bitmap is available
  • getThumbnail: returns the bitmap associated with the thumbnail on AdTag
  • hasThumbnail: returns true if the thumbnail bitmap is available

Note:

You have two options to customize your beacon notifications:

  • Option 1: you can use our pre-built BeaconNotificationImageCreator, to simply customize your notifications with images
  • Option 2: or you can implement your own AsyncBeaconNotificationListener for wider customization abilities

Option 1 is the simpler of the two; option 2 is great if you need to implement your own async tasks

Option 1 will be explored in the following step. If you are interested in option 2, you can find a basic implementation of the AsyncBeaconNotificationListener inside the notification demo code folder.

Step 1: Create your own BeaconNotificationImageBuilder

  • Create a new class named MyBeaconNotificationImageBuilder
  • Implement the BeaconNotificationImageBuilder interface on this class
public class MyBeaconNotificationImageBuilder implements BeaconNotificationImageBuilder {
    @Override
    public Notification buildBeaconNotification(BeaconContentImage beaconContentImage) {
    }
}
  • Add a Context variable and the associated constructor.
    private Context mContext;
    public MyBeaconNotificationImageBuilder(Context mContext) {
        this.mContext = mContext.getApplicationContext();
    }

Step 2: Set up the notification intent

  • Define the Activity that will be launched when a user clicks on a notification
    • We strongly recommend that you leverage the URI field available in AdTag to configure a deep link. This way you can edit it at any point directly from the platform without having to modify your app:
    @Override
    public Notification buildBeaconNotification(BeaconContentImage beaconContentImage) {
        PackageManager packageManager = this.mContext.getPackageManager();
        Intent intentPackage = null;
        if(TextUtils.isEmpty(beaconContentImage.getUri())) {
            intentPackage = packageManager.getLaunchIntentForPackage(this.mContext.getPackageName());
            intentPackage.addCategory(Intent.CATEGORY_HOME);
        }else{
            intentPackage = new Intent(Intent.ACTION_VIEW, Uri.parse(beaconContentImage.getUri()));
        }
        intentPackage.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        PendingIntent intent = PendingIntent.getActivity(this.mContext, 0,
                intentPackage,  PendingIntent.FLAG_UPDATE_CURRENT);
        return null;
    }
  • Finish configuring your intent with the BeaconIntent.configureNotificationIntent method:
    @Override
    public Notification buildBeaconNotification(BeaconContentImage beaconContentImage) {
        [...]
        intentPackage.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        BeaconIntent.configureNotificationIntent(intentPackage, beaconContentImage.getBeaconContent());
        return null;
    }

Note 1:

This method allows you to configure the intent so that it automatically generates SDK analytics.

Note 2:

In your Activity, you can retrieve the beaconContent object, using the following method:

getIntent().getExtras().getParcelable(BeaconIntent.BEACON_CONTENT);

Step 3: Generate the native notification

  • Create a native notification based on the content of the BeaconContentImage object
    @Override
    public Notification buildBeaconNotification(BeaconContentImage beaconContentImage) {
        [...]
        NotificationCompat.Builder mNotificationBuilder = new NotificationCompat.Builder(this.mContext);
        mNotificationBuilder.setContentTitle(beaconContentImage.getNotificationTitle());
        mNotificationBuilder.setContentText(beaconContentImage.getNotificationDescription());
        if(beaconContentImage.hasImage()){
            NotificationCompat.BigPictureStyle style = new NotificationCompat
                    .BigPictureStyle()
                    .bigPicture(beaconContentImage.getImage());
            if(beaconContentImage.hasThumbnail()){
                style.bigLargeIcon(beaconContentImage.getThumbnail());
            }
            mNotificationBuilder.setStyle(style);
        }
        mNotificationBuilder.setContentIntent(intent);
        mNotificationBuilder.setSmallIcon(R.drawable.icon_beacon_notification);
        mNotificationBuilder.setAutoCancel(true);
        return mNotificationBuilder.build();
    }

Note:

The BeaconContent object contains the content associated with the beacon in AdTag. Two methods are available to retrieve the default content of a notification:

  • BeaconContent.getNotificationTitle(): retrieves the title of the notification
  • BeaconContent.getNotificationDescription(): retrieves the description of the notification

You can also base the text of your notifications on other AdTag categories & fields of your choice, using the method BeaconContent.getValue(CATEGORY, FIELD).

For example, BeaconContent.getValue("LINE", "DIRECTION") allows to retrieve the DIRECTION field of the LINE category for a real-time transit schedule use case.

Step 4: Register your AsyncBeaconNotificationListener

  • Open the ApplicationNotification class
  • Initiate an AsyncBeaconNotificationImageCreator with your MyBeaconNotificationImageBuilder class
 public void onCreate(){
        super.onCreate();
        [...]
        AsyncBeaconNotificationImageCreator asyncBeaconNotificationCreator = new AsyncBeaconNotificationImageCreator(new MyBeaconNotificationImageBuilder(this));
    }
  • Register it on the AdtagBeaconManager using the registerAsyncBeaconNotificationListener method:
 public void onCreate(){
        super.onCreate();
        [...]
        AsyncBeaconNotificationImageCreator asyncBeaconNotificationCreator = new AsyncBeaconNotificationImageCreator(new MyBeaconNotificationImageBuilder(this));
        beaconManager.registerAsyncBeaconNotificationListener(asyncBeaconNotificationCreator);
    }

Note:

The AdtagBeaconManager only accepts one AsyncBeaconNotificationListener.

In other words, if you register a new AsyncBeaconNotificationListener, the existing one will be automatically replaced.

Start testing

If your beacon is already emitting, you must stop/restart the emission process in order to simulate a new entry region for your 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 after you reinsert the battery)

  1. In Android Studio, launch the installation of the application you have just built on your mobile phone.

  2. On Android 6 and above, when the application starts, a popup asks for permission to access your smartphone’s location: grant it!

  3. Close your application or leave it running in the background

  4. Remove the beacon from the microwave or reinsert the battery.

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

  6. Click on the notification that has appeared on your screen just for fun.

Note 1:

Some Android 6 and above smartphone models now need location to be activated in order to enable background beacon detection.

Note 2:

On Android, the image associated with a notification can only be displayed if the notification is the first in the smartphone’s list. Some OS versions & smartphone brands offer their users the ability to extend the notification to view the image, when it is not the first in the list.