Getting started
Requirements
- Access to a Business Profile
- Created Client (customer) API Key
- Minimum Android SDK version - 21
Installation
Please continue with the below in order to implement our SDK within your application.
-
Set maven path in your
root/build.gradle
file:... allprojects { repositories { google() jcenter() maven { url "https://synerise.bintray.com/Android" } } }
-
Import dependency in your
project/build.gradle
file:buildscript { repositories { google() jcenter() } dependencies { classpath 'com.android.tools.build:gradle:3.4.2' } }
Note: We guarantee stability only on Android Gradle plugin 3.4.2 or lower. -
Import dependency in your
app/build.gradle
file and apply plugin:apply plugin: 'com.android.application' ... dependencies { ... // Synerise Android SDK implementation 'com.synerise.sdk:synerise-mobile-sdk:3.6.20' }
-
Android Studio versions older than 3.5: ensure that
Instant Run
is disabled.Tip: Android Studio: File -> Settings -> Build, Execution, Deployment -> Instant Run
Configuration
For your convenience, Synerise.Builder
makes it possible to configure SDK behavior depending on your needs!
Synerise.Builder.with(..)
method is mandatory.Let’s dive into some configurable functionalities:
.notificationIcon(@DrawableRes int)
- if you’re using campaign banners or push messages, it is recommended to pass your custom notification icon. This icon is presented as a small notification icon. Note, that required icon must be a drawable resource (not mipmap) due to Android O adaptive icons restrictions. When you send campaign banners/walkthrough and your phone is off, Firebase will use firebase default icon. You should set it in your android manifest..syneriseDebugMode(boolean)
- simple flag may be provided in order to enable full network traffic logs. It is not recommended to use debug mode in release version of your app. Debug mode is disabled by default.Synerise.settings.tracker.autoTracking.trackMode = TrackMode
- sets the mode for view tracking. See Tracker section below.Synerise.settings.tracker.setMinimumBatchSize(int);
- sets minimum number of events in queue required to send them. Default value: 10. Value between 1 - 100.Synerise.settings.tracker.setMaximumBatchSize(int);
- sets maximum number of events, which may be sent in a single batch. Default value: 100. Value between 1 - 100.Synerise.settings.tracker.setAutoFlushTimeout(int);
- sets time required to elapse before event’s queue will attempt to be sent. Default value: 5000 ms . Minimum value: 50 ms.Synerise.settings.injector.automatic = boolean;
- simple flag may be provided to enable automatic mode in injector. See Injector section for more information..pushRegistrationRequired(OnRegisterForPushListener)
- Synerise SDK may request you to register customer for push notifications. This callback is called at after customer signs in, signs up or deletes account..locationUpdateRequired(OnLocationUpdateListener)
- this callback is called on demand via push notification, so it may be called at any point of time.Synerise.settings.tracker.locationAutomatic = boolean;
- to obtain user location and send location event automatically..notificationDefaultChannelId(String)
- sets id of Push Notification Channel. For more info please check Injector section below..notificationDefaultChannelName(String)
- sets name of Push Notification Channel. For more info please check Injector section below..notificationHighPriorityChannelId(String)
- sets id of High Priority Push Notification Channel. For more info please check Injector section below..notificationHighPriorityChannelName(String)
- sets name of High Priority Push Notification Channel. For more info please check Injector section below..baseUrl(String)
- you can provide your custom base URL to use your own API..crashHandlingEnabled(boolean)
- for more information, see Crash Handling..build()
- builds the Synerise SDK with the provided data.Important: TheSynerise.Builder.build()
method can be called only once during the entire application lifecycle, so it is recommended to call this method in yourApplication
class.
Initialization
First of all, you need to initialize Synerise Android SDK by using the with
method and provide:
- API Key,
Application name
Application instance
To get the client API key, sign in to your Synerise account and visit https://app.synerise.com/spa/modules/settings/apikeys/list.
Then, generate a new API key for the “Client” audience.
Add the key in your Application
sub-class:
public class App extends MultiDexApplication {
@Override
public void onCreate() {
super.onCreate();
initSynerise();
}
private void initSynerise() {
String syneriseClientApiKey = getString(R.string.synerise_clientool/api_key);
String appId = getString(R.string.app_name);
Synerise.settings.tracker.autoTracking.trackMode = FINE;
Synerise.settings.tracker.setMinimumBatchSize(10);
Synerise.settings.tracker.setMaximumBatchSize(100);
Synerise.settings.tracker.setAutoFlushTimeout(5000);
Synerise.settings.injector.automatic = false;
Synerise.settings.tracker.locationAutomatic = true;
Synerise.Builder.with(this, syneriseClientApiKey, appId)
.notificationIcon(R.drawable.notification_icon)
.notificationIconColor(ContextCompat.getColor(this, R.color.amaranth))
.syneriseDebugMode(true)
.pushRegistrationRequired(this)
.locationUpdateRequired(this)
.notificationDefaultChannelId("your-channel-id")
.notificationDefaultChannelName("your-channel-name")
.notificationHighPriorityChannelId("your-high-channel-id")
.notificationHighPriorityChannelName("your-high-channel-name")
.baseUrl("http://your-base-url.com/")
.build();
}
}
Add the key in your /values
strings file (for example, strings.xml
):
<resources>
<string name="app_name" translatable="false">Your GREAT application name</string>
<string name="synerise_client_api_key" translatable="false">EF1AD0E0-532B-6AEE-6010-DEDC78F6E155</string> <!-- replace with valid client api key -->
...
</resources>
Crash handling
Crash handler allows you to find users whose mobile applications crashed and to see information about that in their customer cards in CRM as events.
Configuration
You can enable crash handling for Synerise SDK by using the Synerise.crashHandlingEnabled(true)
method.
When it is enabled, SyneriseSDK passes info about user application crashes as dedicated events to the backend (client.applicationCrashed
is the action
parameter of those events).
Errors
MultiDex
Sometimes, MultiDex errors may occur. In that case enable MultiDex as follows (API >= 21):
defaultConfig {
applicationId "com.your.app"
minSdkVersion 21
...
multiDexEnabled true
}
or for API < 21:
defaultConfig {
applicationId "com.your.app"
minSdkVersion 20
...
multiDexEnabled true
}
dependencies {
...
// MultiDex
implementation 'com.android.support:multidex:1.0.3'
...
}
public class YourApp extends MultiDexApplication {
@Override
public void onCreate() {
super.onCreate();
...
}
You can find more information about MultiDex under this link: https://developer.android.com/studio/build/multidex.html
AndroidManifest Merger
Sometimes, AndroidManifest Merger errors may occur. In that case paste following code in your AndroidManifest application tag.
<application
...
tools:replace="android:theme">
Also, if your app did not ask for location permission, remove it from your app with:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/>