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.

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

• RxJava
• RxAndroid
• OkHttp
• Retrofit
• OkHttp
• Picasso
• Fresco
• ConstraintLayout
• Joda-Time

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.

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.

Initialization

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:
   

   SwiftKotlin

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

   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

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

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