What you will learn

This tutorial will teach you how to generate a notification thanks to Connecthings' Mobile SDK, when a beacon is detected around a user's mobile phone.

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

Step 1: Clone the beacon-tutorial repository

  • Clone the beacon-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 class ApplicationNotification
  • Configure your SDK with:
    • the UUID of your beacon
    • the appropriate Adtag Environment
    • your login, password, and company details you received from Connecthings

Step 3: Create your first notification

  • Implement the BeaconNotification interface, with the method createNotification in the ApplicationNotification class
public class ApplicationNotification extends Application implements BeaconNotification
  public static final int NOTIFICATION_BEACON_ID = 1;
  public void onCreate(){
    super.onCreate();
    //initialisation of the SDK
    [...]
  }
  public int createNotification(BeaconContent beaconContent) {
    //to create your notification
     return NOTIFICATION_BEACON_ID;
  }
  • Register the class that implements the BeaconNotification interface in the AdtagBeaconManager

Note:

The AdtagBeaconManager supports only one BeaconNotification interface 

public class ApplicationNotification extends Application implements BeaconNotification
  public void onCreate(){
    super.onCreate();
    //initialisation of the SDK
    [...]
    // Register the BeaconNotification Interface
    beaconManager.registerBeaconNotification(this);
  }
}
  • Implement a local notification based on the BeaconContent
public int createNotification(BeaconContent beaconContent) {
	Log.d(TAG, "create notification");
        //example of notification code
        if(mNotificationManager==null){
	        mNotificationManager = (NotificationManager)getSystemService(NOTIFICATION_SERVICE);
        }
        Intent notifyIntent = new Intent(Intent.ACTION_MAIN);
	notifyIntent.setClass(getApplicationContext(), MainActivity.class);
        notifyIntent.putExtra(MainActivity.FROM_NOTIFICATION, true);
        PendingIntent intent = PendingIntent.getActivity(this, 0,
                    notifyIntent,  PendingIntent.FLAG_UPDATE_CURRENT);
        NotificationCompat.Builder mNotificationBuilder = new NotificationCompat.Builder(this);
        /**
        Build the title and the description of the notification 
	**/
		              mNotificationBuilder.setContentTitle(beaconContent.getNotificationTitle());
        mNotificationBuilder.setContentText(beaconContent.getNotificationDescription());
        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_BEACON_ID;
}

Note:

The BeaconContent object contains the content associated to the beacon in Adtag.

The BeaconContent object has 2 methods to retrieve the default content for a notification:

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

You can also generate your own text for the title and description of the notification, based on other categories & fields, using the method BeaconContent.getValue(CATEGORY, FIELD).

For example, BeaconContent.getValue("LINE", "DIRECTION") allows to retrieve the DIRECTION field of the LINE category.

Step 4: 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.

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

  3. Put the application in the background

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

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

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

Note:

On some phones with Android 6 and above, it is necessary to enable location on the phone to enable beacon detection when the application is in the background.