Configuring your Android project


Updated to version 3.0.1 of Beemray SDK

This section is for Android Studio only. We are not supporting Eclipse anymore since Google has dropped the official support.
If you are using Eclipse, there are plenty of examples online how to import AAR package into the project.

Integrate Beemray SDK in your project

Download Beemray SDK for Android and copy the .aar file into your module's libs directory. Create the directory if it does not exist.

Add this to the top level of your module's build.gradle file:

repositories {
   flatDir {
      dirs 'libs'

Add this to the dependencies section of your module's build.gradle file. Note: if the library file name contains a version number, either rename it to beemray-android-sdk.aar or use the full name in the code:

compile 'com.fasterxml.jackson.core:jackson-core:2.4.3'
compile 'com.fasterxml.jackson.core:jackson-databind:2.4.3'
compile ''
compile ''
compile(name: 'beemray-android-sdk', ext: 'aar')

Add this to the android section of your module's build.gradle file. This is necessary when using com.fasterxml.jackson.core:jackson-core library:

packagingOptions {
   exclude 'META-INF/LICENSE'
   exclude 'META-INF/NOTICE'

Finally, make sure that the value for minSdkVersion is at least 16, which is the lowest supported version; and set your compileSdkVersion to 23 (the latest version so far).

Start the Beemray service

You'll normally start the Beemray service when your application is created. In your app's main activity, import the needed Java classes:


Add the service initialization code to activity's onCreate method, using your own API key:

BeemrayConfiguration conf = new BeemrayConfiguration(API_KEY);
try {
} catch(Throwable t) {
   // Error starting Beemray service !!!


Request runtime permission (Android 6+)

Version 6 of Android introduced runtime permissions. In order to use Android service, you need to ask the user to accept the ACCESS_FINE_LOCATION permission.

The official documentation explains how to request permissions at runtime. Basically, you need to check if permission is granted before starting Beemray, and request it otherwise.

First, define an int constant that you'll use to identify this permission request.


Check if permission is granted or request it using the previously defined constant.

if(PackageManager.PERMISSION_GRANTED == ContextCompat
        .checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION)) {
    // Start Beemray here
} else {
            new String[]{Manifest.permission.ACCESS_FINE_LOCATION},

Additionally, override this method in your activity in order to detect when the user has accepted the permission.

public void onRequestPermissionsResult(int requestCode,
        String permissions[], int[] grantResults) {
    switch (requestCode) {
            // If request is cancelled, the result arrays are empty.
            if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                // Start Beemray here
        // ...

Add a listener for service status

You can use a BroadcastReceiver to listen for changes in Beemray service. Note that you must include this code before the line at which service is started:

BroadcastReceiver receiver = new BroadcastReceiver() {
   public void onReceive(Context context, Intent intent) {
      ServiceState state = (ServiceState) intent.getSerializableExtra(

      if (BeemrayService.class == state.clss()) {
         switch (state.state()) {
             case STARTED:
                // Beemray service started
             case DENIED:
                // Beemray service could not start. Wrong API key?
             case ASYNC:
                // Beemray service accepted start command and will be started soon
             case STOPPED:
                // Beemray service was stopped
             case ERROR:
                // An error occurred while trying to start Beemray service
} } } }; LocalBroadcastManager.getInstance(this).
registerReceiver(receiver, new IntentFilter(Beemray.SERVICE_BROADCAST));

Don't forget to unregister the receiver in order to avoid memory leaks. You can do it in your activity's onDestroy method:

protected void onDestroy() {


Advanced configuration

Besides providing your API key, the BeemrayConfiguration object lets you set some other options that determine how Beemray service behaves.



If persistentNotification is enabled (default), all received beems are added to a single ongoing notification that user cannot delete. If you set this option to true, each received beem will create a new notification that user can slide away.



If this option is true (default), tapping a notification will open a full-screen Beem Box containing all beems received so far. Setting this to false results in a single Beem View being displayed on notification tap. NOTE: When persistentNotification is enabled, Beem Box is always used disregarding the value of useBeemBox option.



Sets a custom icon for Beemray notifications. If this option is not provided, the default icon is used.



Sets a custom icon for notifications created when a new beem is available. If this option is not provided, the resource set for notificationIcon (if any) is used.



Sets a list of key-value mappings of external ID's to be sent to the backend on device registration. The argument must be a java.util.List of com.beemray.types.DeviceMapping elements.


Have more questions? Submit a request