What you will learn

In our Welcome Notifications document, you learned that you could display an additional notification on your users’ smartphones, the first time they interact with a beacon after a given period of time.

Just like it contains an Auto Beacon Notification, our SDK features a built-in, default Auto Welcome Beacon Notification that allows you to automatically generate a Welcome Notification once the SDK is synchronized with AdTag.

You can choose either to keep this default notification, or replace it with your own custom-built Welcome notification.

This tutorial teaches you how to configure both types of Welcome Notifications.

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 Beacon Notification Tutorial.

Initialize the SDK

Step 1: Clone the sdk-tutorial repository

  • Clone the sdk-tutorial repository
git clone https://github.com/opsct/sdk-tutorial.git
  • Open the android>beacon>4-Welcome-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

Activate & configure your Welcome Notifications in AdTag

Welcome Notifications can be activated and configured directly on our AdTag platform, in the Application Management section.

For additional information on Welcome Notification settings, refer to our Introduction to Welcome Notifications.

Choose your Welcome Notification configuration

Work with Auto Welcome Notifications

Once the Welcome Notification feature is enabled on AdTag, and a content is defined, our SDK automatically starts generating Auto Welcome Notifications. The only element that needs to be configured at SDK level is the icon associated with the notification (optional).

You can customize this icon, by adding the following to your drawable resources folder:

  • icon_beacon_welcome_notification_android4 for Android 4 or below.
  • icon_beacon_welcome_notification for Android 5 and above.

Configure a custom-built Welcome Notification

If you would like to implement notifications that are more customizable than our Auto Welcome Beacon notifications, you can create your own Welcome Notification Builder, as described in the following section.

Welcome Notification model overview

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

The AsyncBeaconWelcomeNotificationListener

The AsyncBeaconWelcomeNotificationListener is an interface that:

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

The createBeaconWelcomeNotification method has two arguments:

  • BeaconWelcomeNotification: the content defined in the App Management section on the Adtag Platform.
  • AsyncBeaconWelcomeNotificationManager: the object used to notify the SDK when the notification is ready to be displayed.

The AsyncBeaconWelcomeNotificationManager

The AsyncBeaconWelcomeNotificationManager is an interface that is mainly in charge of displaying Welcome notifications.

To notify the AsyncBeaconWelcomeNotificationManager of the need to display a notification, you must call the displayBeaconWelcomeNotification method.

The displayBeaconWelcomeNotification method has two arguments:

  • BeaconWelcomeNotification: the content defined in the App Management section on the Adtag Platform.
  • Notification: the notification that will be displayed

The AsyncBeaconWelcomeNotificationImageCreator

The AsyncBeaconWelcomeNotificationImageCreator is a specific implementation of the AsyncBeaconWelcomeNotificationListener interface. It is used to directly download the notification image from AdTag, and to display the beacon notification with the corresponding image for Android 4 and above.

The AsyncBeaconWelcomeNotificationImageCreator must be initialized with:

  • Resources: the appropriate Android resources for compatibility with previous library versions
  • BeaconWelcomeNotificationImageBuilder: builder allowing to create the notification

The BeaconWelcomeNotificationImageBuilder

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

It must implement the buildBeaconWelcomeNotification method, which has one argument - BeaconWelcomeNotificationImage -, and returns the end native Notification.

The BeaconWelcomeNotificationImage

The BeaconWelcomeNotificationImage has 4 additional methods compared to the BeaconWelcomeNotification object:

  • getImage: returns the bitmap associated with the AdTag notification image url
  • hasImage: returns true if the image bitmap is available
  • getThumbnail: returns the bitmap associated with the AdTag notification thumbnail url
  • 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 BeaconWelcomeNotificationImageCreator, to simply customize your notifications with images
  • Option 2: or you can implement your own AsyncBeaconWelcomeNotificationListener 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 AsyncBeaconWelcomeNotificationListener inside the notification demo code folder.

Step 1: Create your own BeaconWelcomeNotificationImageBuilder
  • Create a new class called MyBeaconWelcomeNotificationBuilder
  • Implement the BeaconWelcomeNotificationImageBuilder interface on this class
public class MyBeaconWelcomeNotificationImageBuilder implements BeaconWelcomeNotificationImageBuilder {

    @Override
    public Notification buildWelcomeBeaconNotification(BeaconWelcomeNotificationImage beaconWelcomeNotificationImage) {
        
    }
}

  • Add a Context variable and the associated constructor.
    private Context context;

    public MyBeaconWelcomeNotificationImageBuilder(Context context) {
        this.context = context.getApplicationContext();
    }
Step 2: Set up the notification intent
  • Define the Activity that will be launched when a user clicks on the Welcome notification
    @Override
    public Notification buildWelcomeBeaconNotification(BeaconWelcomeNotificationImage beaconWelcomeNotificationImage) {
       PackageManager packageManager = context.getPackageManager();
        Intent intentPackage = packageManager.getLaunchIntentForPackage(context.getPackageName());
        if(beaconWelcomeNotificationImage.isDeepLinkEmpty()) {
            intentPackage.addCategory(Intent.CATEGORY_HOME);
            intentPackage.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        }else{
            intentPackage = new Intent(Intent.ACTION_VIEW, Uri.parse(beaconWelcomeNotificationImage.getDeepLink()));
        }
        return null;
    }
  • Finish configuring your intent using the BeaconIntent.configureWelcomeNotificationIntent method.
    @Override
    public Notification buildBeaconNotification(BeaconContentImage beaconContentImage) {
        [...]

        BeaconIntent.configureWelcomeNotificationIntent(intentPackage, beaconWelcomeNotificationImage.getWelcomeNotification());
        PendingIntent intent = PendingIntent.getActivity(context, 0,
                intentPackage,  PendingIntent.FLAG_UPDATE_CURRENT);
        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 beaconWelcomeNotification object, using the following method:

getIntent().getExtras().getParcelable(BeaconIntent.WELCOME_NOTIFICATION_CONTENT);
Step 3: Generate the local notification
  • Create a native notification based on the content of the BeaconWelcomeNotificationImage object:
    @Override
    public Notification buildWelcomeBeaconNotification(BeaconWelcomeNotificationImage beaconWelcomeNotificationImage) {
        [...]

        NotificationCompat.Builder mNotificationBuilder = new NotificationCompat.Builder(context);
        mNotificationBuilder.setContentTitle(beaconWelcomeNotificationImage.getTitle());
        mNotificationBuilder.setContentText(beaconWelcomeNotificationImage.getDescription());
        mNotificationBuilder.setContentIntent(intent);
        mNotificationBuilder.setSmallIcon(R.drawable.icon_beacon_welcome_notification);
        mNotificationBuilder.setAutoCancel(true);
        if(beaconWelcomeNotificationImage.hasImage()){
            NotificationCompat.BigPictureStyle style = new NotificationCompat
                    .BigPictureStyle()
                    .bigPicture(beaconWelcomeNotificationImage.getImage());
            if(beaconWelcomeNotificationImage.hasThumbnail()){
                style.bigLargeIcon(beaconWelcomeNotificationImage
                        .getThumbnail());
            }
            mNotificationBuilder.setStyle(style);
        }
        return mNotificationBuilder.build();
    }
Step 4: Register your AsyncBeaconWelcomeNotificationListener
  • Open the ApplicationNotification class
  • Initiate an AsyncBeaconWelcomeNotificationImageCreator with your MyBeaconWelcomeNotificationBuilder class
 public void onCreate(){
        super.onCreate();
        [...]
        AsyncBeaconWelcomeNotificationImageCreator asyncBeaconWelcomeNotificationCreator = new AsyncBeaconWelcomeNotificationImageCreator(new MyBeaconWelcomeNotificationImageBuilder(this), this.getResources());
    }
  • Register it on the AdtagBeaconManager using the registerAsyncBeaconWelcomeNotificationListener method:
 public void onCreate(){
        super.onCreate();
        [...]
        AsyncBeaconWelcomeNotificationImageCreator asyncBeaconWelcomeNotificationCreator = new AsyncBeaconWelcomeNotificationImageCreator(new MyBeaconWelcomeNotificationImageBuilder(this), this.getResources());
        beaconManager.registerAsyncBeaconWelcomeNotificationListener(asyncBeaconWelcomeNotificationCreator);
    }

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.

Note 3:

If you want to perform several tests in a row, make sure that you completely uninstall and reinstall the application each time. Otherwise, you will not be able to see any new Welcome Notifications for the next 12 hours (default setting).

Reminder:

Welcome Notifications are configured for the whole app, and not at beacon level.

This means that the content of the notification is not associated with the specific beacon that the user is interacting with.