Requirements - Minimum Android and Google Play services versions

The Bitplaces Android SDK requires that your application is targeted to Android 4.0.4 (API Level 15) or newer, and it has been tested against the Google Play services SDK version 11.8.0, so we recommend you build your app against version 11.8.0 or newer of the Google Play services library.

Some parts of the SDK are written in Kotlin, so the SDK has a dependency on the Kotlin standard library. The SDK is, as of the current release, built and tested against the 1.2.50 version of the Kotlin runtime.

Adding the Bitplaces SDK to your Android project

We distribute the SDK as an AAR bundle that you can add to your project's libs folder and build.gradle file.

Integrating the Bitplaces Android SDK into your project broadly consists of the following four steps:

  1. adding the provided bitplaces-android-sdk.aar file to your libs folder,
  2. updating your build.gradle file with the corresponding dependencies,
  3. ensuring the Google Play services SDK is integrated with your app, and
  4. modifying your Android application manifest to make it aware of the SDK.

Adding the required library files to your project's libs folder and updating your build.gradle file

  1. Copy the provided bitplaces-android-sdk.aar file into your project. We suggest you create a libs folder in your project file tree (if it doesn't already exist) that will contain the libraries you link.
  2. As a minimum, your app's build.gradle file should contain the following items:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
buildscript {
    ext.kotlin_version = '1.2.50'
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.1.2'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

repositories {
    maven {
        url "https://maven.google.com"
    }
    jcenter()
    flatDir {
        dirs 'libs'
    }
}

dependencies {
    // Google Play services
    implementation 'com.google.android.gms:play-services-location:11.8.0+'
    implementation 'com.google.android.gms:play-services-ads:11.8.0+'

    // If your app uses GCM for push notifications ##DEPRECATED##
    implementation 'com.google.android.gms:play-services-gcm:11.8.0+'
    // OR, if your app uses FCM,
    implementation 'com.google.firebase:firebase-messaging:11.8.0+'

    // Support library
    implementation "com.android.support:support-v4:27.1.1" // or the latest version compatible with your targetSdkVersion

    // Firebase job dispatcher library to offer JobScheduler-like compatibility on Android versions < 21
    implementation 'com.firebase:firebase-jobdispatcher:0.8.5'

    // Kotlin standard library. See kotlin_version above.
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"

    // Bitplaces SDK
    implementation(name: 'bitplaces-android-sdk', ext: 'aar')

    // Android Beacon Library
    implementation 'org.altbeacon:android-beacon-library:2.13.1'

    // Logging
    implementation 'org.slf4j:slf4j-api:1.7.25'
    implementation 'com.github.tony19:logback-android:1.1.1-11'

    // Support for badge notifications on selected devices.
    implementation 'me.leolin:ShortcutBadger:1.1.18@aar'
}

android {
    compileSdkVersion 27
    defaultConfig {
        minSdkVersion 15
        targetSdkVersion 27 // or your desired target version
    }
}

Ensuring the Google Play services SDK is integrated with your app

The Bitplaces SDK depends on the Google Play services SDK. If you have not yet set up your project with Play services refer to Google's Setting Up Google Play Services documentation for a step by step guide. Please note that as of SDK release 2.0.0 the recommended minimum version of the Google Play services library to build against is 11.8.0.

If you want to selectively compile Google Play services APIs into your executable, select at least:

  • com.google.android.gms:play-services-ads:11.8.0+
  • com.google.android.gms:play-services-location:11.8.0+
  • and one of these two:
    • com.google.android.gms:play-services-gcm:11.8.0+ if you want to keep using the deprecated and discontinued GCM notifications for a little longer or
    • com.google.firebase:firebase-messaging:11.8.0+ if you want to use the currently recommended Firebase (FCM) notifications
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
dependencies {
    // (...)
    // All apps
    implementation 'com.google.android.gms:play-services-location:11.8.0+'
    implementation 'com.google.android.gms:play-services-ads:11.8.0+'

    // If your app uses GCM for push notifications ##DEPRECATED##
    implementation 'com.google.android.gms:play-services-gcm:11.8.0+'
    // OR, if your app uses FCM,
    implementation 'com.google.firebase:firebase-messaging:11.8.0+'
}

Push Notifications

The Bitplaces SDK works with either GCM or FCM as a push notifications provider. Each of the sections below will assume either one or the other. Please follow the instructions for the service you've chosen for your app.

If you still depend on GCM as your push notifications provider, GCM is deprcated and needs to be updated GCM FAQ. Consider convincing your manager to migrate to FCM immediatly. For more information on the migration process check the Migrate a GCM Client App for Android to Firebase Cloud Messaging tutorial.

Making your application manifest aware of the SDK

A number of SDK components will be merged into your manifest automatically by the build process, but the following ones need to be added manually because they require your application's package name to be explicitly specified.

If you are using deprecated GCM

Declare the following BroadcastReceiver inside your manifest's application element in order to receive GCM notifications:

1
2
3
4
5
6
<receiver android:name="com.bitplaces.sdk.android.BitplacesGCMBroadcastReceiver" android:permission="com.google.android.c2dm.permission.SEND">
  <intent-filter>
    <action android:name="com.google.android.c2dm.intent.RECEIVE"/>
    <category android:name="YourPackageName"/>
  </intent-filter>
</receiver>

Note that android:name in the category element must be replaced with your application's package name (and the category element itself is not required for applications targeted to minSdkVersion 16 and higher).

Also, ensure your manifest contains the following permission declaration and usage, making sure to substitute YourPackageName with the package name of your app, otherwise your app won't be able to receive push notifications:

1
2
<uses-permission android:name="YourPackageName.permission.C2D_MESSAGE"/>
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

If you are using FCM

If you're using Firebase, ensure your manifest contains the following permission declaration and usage, making sure to substitute YourPackageName with the package name of your app:

1
2
<uses-permission android:name="YourPackageName.permission.C2D_MESSAGE"/>
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

If the Bitplaces SDK is be the only component of your app using Google's Instance ID API

Using deprecated GCM

Add the following service declaration in your manifest's application element:

1
2
3
4
5
6
7
8
<service
    android:name="com.bitplaces.sdk.android.BitplacesInstanceIDListenerService"
    android:enabled="true"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.android.gms.iid.InstanceID" />
    </intent-filter>
</service>

Using FCM

Add the following service declaration in your manifest's application element:

1
2
3
4
5
6
7
8
<service
    android:name="com.bitplaces.sdk.android.BitplacesFirebaseInstanceIDListenerService"
    android:enabled="true"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.INSTANCE_ID_EVENT" />
    </intent-filter>
</service>

If other components of your app use Google's Instance ID API

Using deprecated GCM

Your manifest must already contain a declaration for your own InstanceIDService, which extends Play services' InstanceIDListenerService, as described in Instance ID: Android Implementation. Make sure to notify the Bitplaces SDK of the need to refresh the Instance ID derived tokens in your own InstanceIDService.onTokenRefresh() by calling the refreshInstanceIDToken(boolean, String, BitplacesOperationCompletionHandler<Void>) method in the BitplacesSDK instance:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import android.content.Context;
import com.bitplaces.sdk.android.BitplacesSDK;
import com.google.android.gms.iid.InstanceIDListenerService;

public class MyInstanceIDListenerService extends InstanceIDListenerService {
    @Override
    public void onTokenRefresh() {
        // Here your own, existing implementation of onTokenRefresh()
        // (...)
        Context context = getApplicationContext();

        BitplacesSDK.getInstance().refreshInstanceIDToken(false, null, null)
    }
}

Using FCM

Your manifest must already contain a declaration for your own InstanceIDService, which extends Firebase services' FirebaseInstanceIdService, as described in Monitor token generation. Make sure to notify the Bitplaces SDK of the need to refresh the Instance ID derived tokens in your own InstanceIDService.onTokenRefresh() by calling the refreshInstanceIDToken(boolean, String, BitplacesOperationCompletionHandler<Void>) method in the BitplacesSDK instance:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import android.content.Context;
import com.bitplaces.sdk.android.BitplacesSDK;
import com.google.firebase.iid.FirebaseInstanceId;
import com.google.firebase.iid.FirebaseInstanceIdService;

public class MyInstanceIDListenerService extends FirebaseInstanceIdService {
    @Override
    public void onTokenRefresh() {
        // Here your own, existing implementation of onTokenRefresh()
        // (...)

        String refreshedToken = FirebaseInstanceId.getInstance().getToken();
        BitplacesSDK.getInstance().refreshInstanceIDToken(true, refreshedToken, null)
    }
}

Adding a listener service to receive messages

Using deprecated GCM

Add the following service declaration in your manifest's application element:

1
2
<service
    android:name="com.bitplaces.sdk.android.BitplacesGCMIntentService" />

Using FCM

Add the following service declaration in your manifest's application element:

1
2
3
4
5
6
<service
    android:name="com.bitplaces.sdk.android.BitplacesFCMListenerService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
</service>

If Using FCM, Add your FCM Server Key to your Bitplaces Release

If using FCM to send push notifications to your app, you'll need to add your Firebase app's Server Key to your Bitplaces release:

  • Firstly, follow these instructions to add Firebase to your app.
  • Then head over to your Firebase Console, select your project, then go to Settings > Cloud Messaging.
  • Then click on Add Server Key to create an FCM key that Bitplaces will use to send notifications to your app.
  • Finally, go to your Bitplaces Console, under Settings > Apps select the Android release of your app and add the Server Key there.

If Using FCM, Initialize the Firebase SDK First

Easy to miss! Make sure to call FirebaseApp.initializeApp(getApplicationContext()) before initializing the BitplacesSDK.