Getting started

Requirements

• Access to Workspaces
• Created Client (customer) API Key
• Minimum Android SDK version - 21
• Supported targetSDKVersion - 30

Installation

Please continue with the below in order to implement our SDK within your application.

1. Set maven path in your root/build.gradle file:

   ...
   allprojects {
       repositories {
           google()
           jcenter()
           maven { url 'https://pkgs.dev.azure.com/Synerise/AndroidSDK/_packaging/prod/maven/v1' }
       }
   }
   

2. 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.

3. 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:4.7.0'
   }
   

4. 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.

Let’s dive into some configurable functionalities:

1. .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.
2. Synerise.settings.tracker.autoTracking.trackMode = TrackMode - sets the mode for view tracking. See Tracker section below.
3. Synerise.settings.tracker.setMinimumBatchSize(int); - sets minimum number of events in queue required to send them. Default value: 10. Value between 1 - 100.
4. 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.
5. 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.
6. Synerise.settings.injector.automatic = boolean; - simple flag may be provided to enable automatic mode in injector. See Injector section for more information.
7. .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.
8. .locationUpdateRequired(OnLocationUpdateListener) - this callback is called on demand via push notification, so it may be called at any point of time.
9. Synerise.settings.tracker.locationAutomatic = boolean; - to obtain user location and send location event automatically.
10. .notificationDefaultChannelId(String) - sets id of Push Notification Channel. For more info please check Injector section below.
11. .notificationDefaultChannelName(String) - sets name of Push Notification Channel. For more info please check Injector section below.
12. .notificationHighPriorityChannelId(String) - sets id of High Priority Push Notification Channel. For more info please check Injector section below.
13. .notificationHighPriorityChannelName(String) - sets name of High Priority Push Notification Channel. For more info please check Injector section below.
14. .baseUrl(String) - you can provide your custom base URL to use your own API.
15. .crashHandlingEnabled(boolean) - for more information, see Crash Handling.
16. .rxJavaErrorHandlingEnabled(boolean) - If set to true, Synerise handles rxJava errors. If false, call RxJavaPlugins.setErrorHandler on your own.
17. .mesaggingServiceType(MessagingServiceType) - Sets the messaging provider: HMS or GMS. When publishing the app to appGallery, we recommend using HMS.
18. .build() - builds the Synerise SDK with the provided data.
    Important: The Synerise.Builder.build() method can be called only once during the entire application lifecycle, so it is recommended to call this method in your Application 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();
    }
}

class App : MultiDexApplication() {
	override fun onCreate() {
        super.onCreate()
        initSynerise()
    }
	private fun initSynerise() {
        val syneriseClientApiKey = accountManager!!.getClientProfileApiKey()
        val 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.ic_cart)
            .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 Profiles 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).

Proguard configuration

The Synerise Android SDK obfuscates code on its own. We highly recommend keeping the entire SDK. Rules:

# keep entire Synerise SDK
-keep class com.synerise.sdk.** { *; }
-keepclassmembers class com.synerise.sdk.** { *; }
-keepclassmembers class com.synerise.sdk.** {
    public <init>();
}

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"/>