What you will learn

This tutorial will teach you how to create a Welcome Notification, associated with the first beacon that the SDK detects.

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

Step 1: Clone the sdk-tutorial repository

  • Clone the beacon-tutorial repository
git clone https://github.com/opsct/sdk-tutorial.git
  • Open the android>beacon>6-Welcome-Notification>Starter project with Android Studio

Note:

This project is a continuation of the Notification tutorial project

Step 2: Configure the SDK

  1. Open the ApplicationNotification class
  2. Configure the SDK with:
  • the UUID of your beacon
  • the appropriate Adtag Environment
  • your login, password, and company details you received from Connecthings

Step 3: Configure your first Welcome Notification

  • Open the ApplicationNotification class
  • Create a Beacon Welcome Notification object in the onCreate method:
 public void onCreate(){
        super.onCreate();
        [...]
	BeaconWelcomeNotification beaconWelcomeNotificationOn = new BeaconWelcomeNotification(BeaconWelcomeNotification.TYPE.NETWORK_ON,
                getString(R.string.beacon_welcome_on_title),
                getString(R.string.beacon_welcome _on_description),
                2 * 1000 * 60);

Note:

It exists several constructors to create a Welcome Notification.
The most complete is the BeaconWelcomeNotification(TYPE, title, description, iconId, minDisplayTime, displayCurrentBeaconNotification) constructor:

  • TYPE: defines the type of Welcome Notification, either:
    • NETWORK_ON: Welcome Notification displayed only when the device has access to the internet
    • NETWOK_DOWN: Welcome Notification displayed only when the device is offline
  • title: title of the notification
  • description: description of the notification
  • iconId: icon associated with the notification
  • minDisplayTime: minimum time the notification is displayed
  • displayCurrentBeaconNotification:
    • if set to true, the current beacon notification will be displayed in addition of the welcome notification (The user will received two notifications)
    • if set to false, only the welcome notification will be displayed (The user will receive only one notification - the Welcome Notification)

Step 4: Register your Welcome Notification

  • Use the AdtagBeaconManager.addWelcomeNotification(WelcomeNotification)to register your Welcome Notification
 public void onCreate(){
        super.onCreate();
        [...]
	BeaconWelcomeNotification beaconWelcomeNotificationOn = new BeaconWelcomeNotification(BeaconWelcomeNotification.TYPE.NETWORK_ON, getString(R.string.beacon_welcome_on_title),
         getString(R.string.beacon_welcome_on_description),
			2 * 1000 * 60);      
	beaconManager.addWelcomeNotification(beaconWelcomeNotificationOn);

Step 5: Configure another Welcome Notification for when a user's device network is offline

  • Repeat steps 3 and 4 to create and register another Welcome Notification that can be displayed when a user's smartphone has no internet access.
BeaconWelcomeNotification beaconWelcomeNotificationOff = new BeaconWelcomeNotification(BeaconWelcomeNotification.TYPE.NETWORK_ERROR,
            getString(R.string.beacon_welcome_off_title),
        getString(R.string.beacon_welcome_off_description),
                2*1000*60);

Step 6: About Auto Welcome Notification

Once you have registered a welcome notification, the SDK is able to generate welcome notifications automatically. You don't need more set-up.

If you need more control over the notification, there is the possibility to implement your own Welcome Notification creator. This point is discussed in the next step.

Auto Welcome Notification options

Personalize the Welcome Notification icon

You can personalyse the Welcome Notification icon, adding to your drawable resources folder an image named:

  • icon_beacon_welcome_notification_android4 untill Android 4.
  • icon_beacon_welcome_notification for Android 5 and above.

Disable the Welcome Notifications

You can disable the welcome notifications through this code :

 beaconManager.disableWelcomeNotification()

Step 8: Implement a Welcome Notification Listener

This step is only required if you want to get more control over the Welcome Notification.

  • Implement the BeaconWelcomeNotificationListener interface in the ApplicationNotification class
public class ApplicationNotification extends Application implements BeaconNotification, BeaconWelcomeNotificationListener{
	
	 @Override
    public int createWelcomeNotification(BeaconWelcomeNotification beaconWelcomeNotification) {
        return NOTIFICATION_BEACON_ID;
    }
}
  • Register the BeaconWelcomeNotificationListener interface in the AdtagBeaconManager object, using beaconManager.registerBeaconWelcomeNotificationListener(DefaultNotificationListener).
 public void onCreate(){
	 super.onCreate();
	 [...]
        beaconManager.registerBeaconWelcomeNotificationListener(this);
}
  • Create a notification based on the content of the BeaconWelcomeNotification object
@Override
public int createWelcomeNotification(BeaconWelcomeNotification beaconWelcomeNotification) {
	if(mNotificationManager==null){
        mNotificationManager = (NotificationManager)getSystemService(NOTIFICATION_SERVICE);
    }
    Intent notifyIntent = new Intent(Intent.ACTION_MAIN);
    notifyIntent.setClass(getApplicationContext(), MainActivity.class);
    BeaconIntent.configureWelcomeNotificationIntent(intentPackage, welcomeNotification);

    PendingIntent intent = PendingIntent.getActivity(this, 0,
            notifyIntent,  PendingIntent.FLAG_UPDATE_CURRENT);
    NotificationCompat.Builder mNotificationBuilder = new NotificationCompat.Builder(this);
    mNotificationBuilder.setContentTitle(beaconWelcomeNotification.getTitle());
    mNotificationBuilder.setContentText(beaconWelcomeNotification.getDescription());
    mNotificationBuilder.setContentIntent(intent);
    mNotificationBuilder.setSmallIcon(R.mipmap.ic_launcher);
    mNotificationBuilder.setSound(RingtoneManager.getDefaultUri(RingtoneManager.TYPE_NOTIFICATION));
    mNotificationBuilder.setAutoCancel(true);
    mNotificationBuilder.setVibrate(new long[]{1000, 1000 ,1000});
    mNotificationManager.notify(NOTIFICATION_BEACON_ID, mNotificationBuilder.build());
    return NOTIFICATION_WELCOME_BEACON_ID;
}

Note:

In this demo code, we use the configureWelcomeNotificationIntent method from the BeaconIntent class to configure the notification in order to generate automatic logs when the notification will be cliked.

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 with which the user is interacting.

Step 9: Start testing

If your beacon is already emitting, you must stop/restart the emission process in order to simulate a new region entry for the 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 when you put the battery back)
  1. From Android Studio, launch the installation of the application you have just built on your mobile phone.

    • If you want to perform several tests in a row, to check all situations (with or without internet connection), 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.
  2. Put the application in the background

  3. Remove the beacon from the microwave or put the battery back.

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

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

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 with which the user is interacting.