Installation and configuration (Android)

In this article, you will find out how to install, configure, and initialize the Synerise SDK in an Android mobile application. While performing the actions from this guide, keep the presented order.

Important: The Settings article contains additional information about SDK behaviors you may need prior to configuration.

If you want to find out what kind of benefits you can get from integrating with mobile SDK, go here.

Requirements


You need:

  • Access to a workspace
  • A Profile API Key
    When creating the API key, use allowlisting or denylisting to only allow the events you intend to use.
  • Minimum Android SDK version: 21
  • Supported targetSDKVersion: 33

3rd Party Frameworks

Installation


  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. Add dependency to your project/build.gradle file:

        buildscript {
            repositories {
                google()
                jcenter()
            }
            dependencies {
                classpath 'com.android.tools.build:gradle:3.4.2'
            }
        }
        
    Important: We guarantee stability only on Android Gradle plugin 3.4.2 or lower.
  3. Import dependency in your app/build.gradle file and apply the plugin:

        apply plugin: 'com.android.application'
    
        ...
        dependencies {
        ...
        // Synerise Android SDK;
        implementation 'com.synerise.sdk:synerise-mobile-sdk:ANDROID_SDK_VERSION'
        // Replace ANDROID_SDK_VERSION with the version, for example 5.4.0;
        // Check latest version at https://github.com/Synerise/android-sdk/blob/master/CHANGELOG.md
        }
        

  4. For Android Studio versions older than 3.5: Go to File > Settings > Build, Execution, Deployment > Instant Run and make sure that Instant Run is disabled.

Configuration


For your convenience, Synerise.Builder makes it possible to configure SDK behavior depending on your needs.

Note: The Synerise.Builder.with(..) method is mandatory.

The basic callbacks you need:

  • .pushRegistrationRequired(OnRegisterForPushListener) - Synerise SDK may request registering a customer for push notifications. This callback is called after a customer signs in, signs up, or deletes an account.

  • .baseUrl(String) - This callback lets you provide your custom base URL to use your own domain for connecting to the Synerise API

    Note: If you use Synerise hosted in Google Cloud (app.geb.synerise.com), you must initialize a custom API environment and use https://api.geb.snrapi.com as the baseUrl builder method.
  • .mesaggingServiceType(MessagingServiceType) - This callback sets the messaging provider: Huawei Mobile Services (HMS) or Google Mobile Services (GMS). When publishing the app to appGallery, we recommend using HMS.

Click to expand the full list of callbacks

Callbacks Description
.build() Builds the Synerise SDK with the provided data. The Synerise.Builder.build() method can be called only once during the entire application lifecycle, so you must call this method in your Application class.
.crashHandlingEnabled(boolean) For more information, see the Crash Handling section.
.notificationDefaultChannelId(String) Sets the ID of Push Notification Channel.
.notificationDefaultChannelName(String) Sets the name of Push Notification Channel.
.notificationHighPriorityChannelId(String) Sets the ID of High Priority Push Notification Channel.
.notificationHighPriorityChannelName(String) Sets the name of High Priority Push Notification Channel.
.rxJavaErrorHandlingEnabled(boolean) If set to true, Synerise handles rxJava errors.
If false, you need to call rxJavaPlugins.setErrorHandler on your own.
.syneriseDebugMode(boolean) When true, enables full network traffic logs. It is not recommended to use debug mode in a release version of your app. Debug mode is disabled by default.
Synerise.settings.injector.automatic = boolean; When true, enables automatic mode in the injector.
Synerise.settings.tracker.autoTracking.trackMode = TrackMode Sets the mode for view tracking.
Synerise.settings.tracker.locationAutomatic = boolean; Use to obtain customer location and send the location event automatically.
Synerise.settings.tracker.setAutoFlushTimeout(int); Sets the maximum time (in ms) since the last event queue was sent before attempting to automatically send another queue. Default value: 5000 ms. Minimum value: 50 ms.
Synerise.settings.tracker.setMaximumBatchSize(int); Sets the maximum number of events which may be sent in a single batch. Default value: 100. You can set the value between 1 and 100.
Synerise.settings.tracker.setMinimumBatchSize(int); Sets the minimum number of events in queue required to send them. Default value: 10. You can set the value between 1 and 100.

Initialization


WARNING: Synerise SDK must be initialized in the Application class. This is because Synerise SDK performs some operations while the application is running in the background.
  1. Initialize Synerise Android SDK by using the with method and provide:

    • Application name
    • Application instance
    • API Key
      1. To get the Profile (client) API key, go to Synerise > Settings > API keys.
      2. On the list of the keys, select the one you created as a part of requirements.
      3. In the General section, click Show.
      4. Copy the API key.
  2. Add the key in your Application sub-class:

     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
    
    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/")
                            .setRequestValidationSalt("YOUR_REQUEST_VALIDATION_SALT")
                            .build();
        }
    }
    

  3. 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>
Important: Secure sensitive keys (for example, clientApiKey and requestValidationSalt) with mechanisms like string obfuscation or encryption.

Troubleshooting


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 at this link.

AndroidManifest Merger

Sometimes, AndroidManifest Merger errors may occur. In that case, paste the 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"/>

Work Manager

Work Manager is a mechanism to schedule and run code in the background to keep your app up to date. Synerise supports using Work Manager since SDK version 5.21.0.

Benefits

Currently, the SDK uses background tasks only to refresh the registration token for push notifications every 20 days. In these situations, the SDK invokes the onRegisterForPushRequired(origin:) callback method or onRegisterForPushRequired() callback method.

Setting up

Work Manager is configured out of the box without any special configuration.

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>();
}
😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker