Skip to content
GitLab

Integration guide · Changes

Page history
Separated Gradle/Eclipse installation guides authored by Eric Kok's avatar Eric Kok
Hide whitespace changes
Inline Side-by-side
Integration-guide.md
View page @ f1eef379
## Requirements
The B4S SDK uses **Bluetooth 4.0 BLE**, also called Low Energy or Bluetooth Smart Ready. It is available on most new Android devices, with a minimum of **Android 4.3**.
The B4S SDK is a compiled JAR that can be dropped (together with its dependencies) directly into the `libs` folder in Eclipse, Android Studio or compiled with Ant. The SDK is currently targeting API level 19 (Android 4.4) with minimal API level 18 (Android 4.3) for Bluetooth BLE support.
The SDK depends on the Jackson and EventBus libraries, which are all Apache License 2.0-licensed. Finally, it depends on the Google Play Services for its Location Services, Advertiser ID and Cloud Messaging support. See instructions below how to obtain and add this, as it is not included in the B4S SDK package.
## Installation
### Add dependencies
When using Gradle as your build system, simply **add the `b4s-android-sdk.jar` to your /libs folder** and add or update the following dependencies (where `play-services-gcm` can be omitted if push messaging is not needed):
```gradle
dependencies {
compile 'de.greenrobot:eventbus:2.3.0'
compile 'com.squareup.retrofit:retrofit:2.0.0-beta1'
compile 'com.squareup.retrofit:converter-jackson:2.0.0-beta1'
compile 'com.google.android.gms:play-services-location:8.1.0'
compile 'com.google.android.gms:play-services-ads:8.1.0'
compile "com.google.android.gms:play-services-gcm:8.1.0"
compile fileTree(dir: 'libs', include: ['*.jar'])
}
```
When still using Eclipse/Ant/Maven to build your application, drop the jar files found in [`sdk/libs`](https://github.com/ezeeworld/B4S-Android-SDK/tree/master/sdk/libs) directly into the `libs` folder of your existing Android project. Next, add the Play Services as library project, if not yet done:
Choose the appropriate installation guide for your build system before continuing with the integration:
1. Import the Google Play Services library project. If not installed yet, use the Android SDK Manager to install this. It is advised to copy the library project to your local directory from `android-sdk/extras/google/google_play_services/libproject`. Import the `google-play-services_lib` directory using File -> Import... -> Existing Android Code Into Workspace wizard. Make sure it is marked as Library Project in the Android properties.
2. Open the properties page of your Android project and add the for the google-play-services_lib as library project dependency. The jar files in `libs` should already be adopted into your Android Private Libraries build.
- [[Installation with Gradle|Installation-with-Gradle]]
- [[Installation with Eclipse/Ant|Installation-with-Eclipse-Ant]]
## Configuration of the SDK
### Define B4S services
1. Open your project AndroidManifest.xml
2. Add the required permissions for access to internet, Bluetooth LE, location and the boot receiver:
```xml
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />
```
3. For location updates, the Google Play Services requires some meta data in the `<application>` tag.
```xml
<meta-data android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
```
4. Add the B4S services to the `<application>` element to allow background scanning for and interacting with beacons.
```xml
<!-- Background monitoring for beacons -->
<service
android:name="com.ezeeworld.b4s.android.sdk.monitor.MonitoringManager"
android:exported="true"
tools:ignore="ExportedService">
<intent-filter>
<action android:name="com.ezeeworld.b4s.android.sdk.monitor.B4S_ENSURE_SCANNING" />
<action android:name="com.ezeeworld.b4s.android.sdk.monitor.B4S_QUERY_SCHEDULE" />
<action android:name="com.ezeeworld.b4s.android.sdk.monitor.B4S_SCHEDULE_RESULT" />
<action android:name="com.ezeeworld.b4s.android.sdk.monitor.B4S_QUERY_VERSION" />
<action android:name="com.ezeeworld.b4s.android.sdk.monitor.B4S_REPORT_VERSION" />
</intent-filter>
</service>
<service
android:name="com.ezeeworld.b4s.android.sdk.monitor.ScanService"
android:exported="false" />
<service
android:name="com.ezeeworld.b4s.android.sdk.monitor.InteractionService"
android:exported="true"
tools:ignore="ExportedService">
<intent-filter>
<action android:name="com.ezeeworld.b4s.android.sdk.monitor.B4S_OBSERVATIONS" />
</intent-filter>
</service>
<service
android:name="com.ezeeworld.b4s.android.sdk.notifications.NotificationService"
android:exported="false" />
<activity
android:name="com.ezeeworld.b4s.android.sdk.monitor.WebViewInteractionActivity"
android:configChanges="orientation|keyboardHidden"
android:exported="true"
android:noHistory="true" />
<receiver android:name="com.ezeeworld.b4s.android.sdk.monitor.SystemEventReceiver">
<intent-filter>
<action android:name="android.intent.action.ACTION_USER_PRESENT" />
<action android:name="android.intent.action.BOOT_COMPLETED" />
</intent-filter>
</receiver>
```
5. If you use the push messaging feature of the B4S SDK, also add the push services. Outside of the `<application>` you need additional permissions:
```xml
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
<permission android:name="com.ezeeworld.b4s.android.sdk.gcm.permission.C2D_MESSAGE" android:protectionLevel="signature" />
```
and in the `<application>` tag the push services registration:
```xml
<!-- Push messaging -->
<receiver
android:name="com.google.android.gms.gcm.GcmReceiver"
android:exported="true"
android:permission="com.google.android.c2dm.permission.SEND">
<intent-filter>
<action android:name="com.google.android.c2dm.intent.RECEIVE" />
<category android:name="com.ezeeworld.b4s.android.sdk.gcm" />
</intent-filter>
</receiver>
<service
android:name="com.ezeeworld.b4s.android.sdk.push.GcmListenerService"
android:exported="false">
<intent-filter>
<action android:name="com.google.android.c2dm.intent.RECEIVE" />
</intent-filter>
</service>
<service
android:name="com.ezeeworld.b4s.android.sdk.push.InstanceIDListenerService"
android:exported="false">
<intent-filter>
<action android:name="com.google.android.gms.iid.InstanceID" />
</intent-filter>
</service>
```
After installation via Gradle/.AAR files or Eclipse/.JAR files, continue with the configuration of the SDK.
6. The B4S SDK required initialization of the library with the unique application ID (provided by Ezeeworld). It is suggested to do so in the application object. Make sure the application object refers to the `Application` object first, for example:
The B4S SDK requirs initialization of the library with the unique application ID (provided by Ezeeworld). It is strongly recommended to do so in the application object. If no `Application` is yet defined, add it in your `AndroidManifest.xml`, for example:
```xml
<application
......@@ -145,7 +17,7 @@ When still using Eclipse/Ant/Maven to build your application, drop the jar files
android:label="@string/app_name" >
```
and in the `Application` instance (here `SampleApp`) `onCreate` method call `init` and make sure the `MonitoringService` runs upon the first app start. Replace `MY-APP-ID` with your unique application ID.
and in the `Application` instance (here `SampleApp`) `onCreate` method call `init` and make sure the monitoring service runs upon the first app start. Replace `MY-APP-ID` with your unique application ID.
```java
B4SSettings settings = B4SSettings.init(this, "MY-APP-ID");
......@@ -153,7 +25,7 @@ When still using Eclipse/Ant/Maven to build your application, drop the jar files
MonitoringManager.ensureMonitoringService(this);
```
Logging is turned off by default; use the `B4SSettings` object returned on initialization to enable debugging (using `setShouldLogDebug` and `setShouldLogVerbose`) as well as to change various other settings.
Logging is turned off by default; use the `B4SSettings` object returned on initialization to enable debugging (using `setShouldLogDebug` and `setShouldLogVerbose`) as well as to change various other settings.
### Application tagging
......@@ -175,7 +47,7 @@ You can even set your own data dictionary.
### Push messaging
To enable support for push messages via the Google Cloud Messaging and B4S servers, call set on the `B4SSettings` instance returned by `B4SSettings.init()` (or use `B4SSettings.get()`). By supplying the GCM Sender ID this way, push messaging support will be enabled. While the token registration is fully managed, you do need to call this every time (typically in your `Application` object, right after `init()`).
To enable support for push messages via the Google Cloud Messaging and B4S servers, call set on the `B4SSettings` instance returned by `B4SSettings.init()` (or use `B4SSettings.get()`). By supplying the GCM Sender ID this way, push messaging support will be enabled. While the token registration is fully managed, you **do** need to call this every time (typically in your `Application` object, right after `init()`).
You can retrieve the required Sender ID from the [Google Developer Console](https://console.developers.google.com/). You also need to note the Server API Key and (let us) register it in the B4S backoffice.
......