Skip to content
GitLab

Integration guide · Changes

Page history
Updated Integration guide (markdown => textile) authored by Christophe Janot's avatar Christophe Janot
Hide whitespace changes
Inline Side-by-side
Integration-guide.textile 0 → 100644
View page @ f0866e55
## Installation
Choose the appropriate installation guide for your build system before continuing with the integration:
- [[Installation with Gradle|Installation-with-Gradle]]
- [[Installation with Eclipse/Ant|Installation-with-Eclipse-Ant]]
## Configuration of the SDK
After installation via Gradle/.AAR files, continue with the configuration of the SDK.
Starting with 2.2.0, the initialisation process changed a little bit. The previous initialisation scheme is still available but is now deprecated.
The B4S SDK require 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
android:name="com.ezeeworld.b4s.android.sdk.sample.SampleApp"
android:label="@string/app_name" >
...
<meta-data android:name="by.neer.sdk.APP_ID" android:value="MY-APP-ID" />
...
</application>
```
And 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);
MonitoringManager.ensureMonitoringService(this);
```
### Prevent your application from mock locations
On Android, some applications (like Lockito) can generate mock locations (typically for debuting purpose). By default, mock locations are authorised by the Neer.by SDK. You can disable them with the following code :
```java
B4SSettings.get().setDiscardMockLocations(true);
```
### Application tagging
You can tag your application with the B4S SDK. You can set two values: The first parameter is the event descriptor and the second the user data associated to the event.
```java
B4S.event("Launch","No Data");
```
You can even set your own data dictionary.
```java
Hashtable tags = new Hashtable();
tags.put("Key1","String1");
tags.put("Key2","String2");
tags.put("Key3",4);
B4STag.event("Test", tags);
```
### 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()`).
You can retrieve the required Sender ID from the [Google Firebase Console](https://console.firebase.google.com).
You also need to note the Legacy Server Key and register it in the B4S backoffice (in your Application setting).
### Customer data
B4S can relate beacon interactions to individual customers. Supplying the customer details is typically done on startup and/or after a user signed in to his/her account. In these cases you can update te SDK with this customer data (which is persisted; no need to call every time).
```java
B4SUserProperty.get().store(B4SUserProperty.USER_FIRST_NAME, "Jean-Michel");
B4SUserProperty.get().store(B4SUserProperty.USER_LAST_NAME, "Bécatresse");
B4SUserProperty.get().store(B4SUserProperty.USER_GENDER, B4SUserProperty.Gender.Male);
```
### Deep linking
Notifications such as web links or simple messages are handled directly by the SDK. For deep linking (and deep linking only), there are three options:
- `DeepLinkStyle.LaunchActivityClearTask` - (Default) Deep links are delivered to your launch Activity, and always in a new task (with an Activity restart)
- `DeepLinkStyle.LaunchActivityDirect` - Deep links are delivered to your launch Activity; if this is already running the Intent is delivered directly to your `onNewIntent` lifecycle method
- `DeepLinkStyle.BroadcastReceiver` - Deep links are broadcasted with a `com.ezeeworld.b4s.android.sdk.notifications.DEEP_LINK` Intent action type
The strategy can be set by calling a static method, typically after you have initialized the SDK in your `Application` class:
```java
NotificationService.registerDeepLinkStyle(NotificationService.DeepLinkStyle deepLinkStyle);
```
When you configure to use `DeepLinkStyle.BroadcastReceiver` deep links, the application can and must register a `BroadcastReceiver` that handles the deep links, such as opening a specific Activity or starting a Service. In your `AndroidManifest.xml` you declare:
```xml
<receiver android:name=".DeepLinkReceiver">
<intent-filter>
<action android:name="com.ezeeworld.b4s.android.sdk.notifications.DEEP_LINK" />
</intent-filter>
</receiver>
```
The `DeepLinkReceiver` can, in its simplest form, simply relay the broadcasts to some other Activity:
```java
public class DeepLinkReceiver extends BroadcastReceiver {
@Override
public void onReceive(Context context, Intent intent) {
intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK); // Required as no Activity context is available
context.startActivity(intent);
}
}
```
Deep link `Intent`s contain a bundle of extras to respond appropriately:
- `NotificationService.INTENT_SHOW` - (int) Hash code of the interaction that was matched
- `NotificationService.INTENT_INTERACTION` - (String) Name interaction that was matched
- `NotificationService.INTENT_CAMPAIGNNAME` - (String) Name of the campaign the matched interaction belongs to
- `NotificationService.INTENT_INTERACTIONNAME` - (String) Unique ID of the interaction that was matched
- `NotificationService.INTENT_TITLE` - (String) Message title, defaults to interaction name if no custom title was supplied
- `NotificationService.INTENT_MESSAGE` - (String) Message, in which customer name, beacon name, shop name, etc. were already substituted
- `NotificationService.INTENT_SHOPNAME` - (String) Name of the interaction's shop
- `NotificationService.INTENT_SHOPCLIENTREF` - (String) The free-form string set on the shop as client reference
- `NotificationService.INTENT_GROUPNAME` - (String) Name of the interaction's group
- `NotificationService.INTENT_ACTIONID` - (String) The free-form string with the campaign action id set as deep link reference
- `NotificationService.INTENT_BEACONNAME` - (String) Name of the matched beacon as configured in the SDK
- `NotificationService.INTENT_BEACONID` - (IBeaconID) Beacon identification, including technical name (B4S:XXXX:XXXX), UDID, major and minor
- `NotificationService.INTENT_BEACONCLIENTREF` - (String) The free-form string set on the beacon as client reference
- `NotificationService.INTENT_DISTANCE` - (double) Distance estimate in meters
- `NotificationService.INTENT_SHOPLATITUDE` - (double) Latitude of the shop associated to the notification
- `NotificationService.INTENT_SHOPLONGITUDE` - (double) Longitude of the shop associated to the notification
## Notifications customisation
Icons, icon background colour and vibration can be customised on notifications.
```java
B4SSettings.get().setNotificationBackgroundColor(0xff111111);
B4SSettings.get().setCustomNotificationSmallIcon(R.drawable.ic_notifsmall);
B4SSettings.get().setCustomNotificationLargeIcon(R.drawable.ic_notiflarge);
B4SSettings.get().setShouldVibrateOnNotification(true);
```
## Android 6
With Android 6.0 (API level 23) a new permission system was introduced by Google. On Android 6 devices, users can manually manage permissions on a per-application basis. If an app targets Android 6 (using targetSdkVersion 23 and compileSdkVersion 23), an app also needs to deal with runtime permissions. This means that permissions such as location access (which is now a so-called 'dangerous' permission) needs to be explicitly requested with a permission request pop-up. Until SDK version 1.4.2, the B4S SDK does not handle this automatically and therefor the integrator needs to [handle permission request dialogs manually](https://developer.android.com/training/permissions/requesting.html).
From version 1.5.0 onwards this will be handled for you by the SDK. A request to access the user location will automatically be shown when access was not yet granted. It is important to note that this affects any application when running on an Android 6 device, even those that still target API level 22 or lower.
\ No newline at end of file