Using the Android App Messaging SDK

Our Android App Messaging SDK uses [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging/) to send push notifications to your Android app users. To embed in your native Android apps, complete the following tasks: 1. [Install the SDK](#section-installing-the-sdk) 2. [Configure the SDK](#section-configuring-the-android-sdk) 3. [Initialise the SDK](#section-initialising-the-android-sdk) 4. *Optional:* [Change the icon or colour of your push notifications](#section-changing-the-icon-or-colour-of-push-notification) [block:callout] { "type": "info", "body": "You can use either standard callbacks or observable streams to handle asynchronous requests. If you want to use observable streams, you need to add the RxJava library to your app. This tutorial explains how to use standard callbacks, but you can find a full sample of the RxJava code in the ['Android sample code' section](#section-android-sample-code).", "title": "Handling asynchronous requests" } [/block] # Installing the SDK 1. Add the App Messaging SDK to your module-level `build.gradle` file and change the `minSDKVersion` attribute to 16 using the snippet below: [block:code] { "codes": [ { "code": "defaultConfig {\n...\nminSdkVersion 16\n...\n}\nDependencies {\n...\nimplementation 'com.comapi:foundation:1.2.0'\n}", "language": "java" } ] } [/block] [block:callout] { "type": "warning", "body": "The SDK has a `minSDKVersion` attribute of 16, your attribute must have a value of at least 16.", "title": "Seeing a 'Manifest merger' error?" } [/block] 2. Add the Google services plugin to your module-level `build.gradle` file using the snippet below: [block:code] { "codes": [ { "code": "apply plugin: 'com.google.gms.google-services'", "language": "java" } ] } [/block] 3. Add the following dependencies to your module-level `build.gradle` file using the snippet below: [block:code] { "codes": [ { "code": "implementation ('com.google.android.gms:play-services-base:15.0.1') {force = true}\nimplementation ('com.google.firebase:firebase-messaging:17.0.0') {force = true}", "language": "java" } ] } [/block] [block:callout] { "type": "success", "body": "Remember to synchronise `build.gradle` files after making any changes.", "title": "Sync Now" } [/block] # Configuring the Android SDK Before you can configure the Android SDK, you need the following: * The value of the [API space ID field in Engagement Cloud](doc:creating-a-push-notification-profile-new#section-finding-your-api-space-id) * A class that [creates a JWT token](https://developer.dotdigital.com/v2/docs/creating-a-json-web-token-new#section-android-jwt-code-sample) 1. Create a new instance of the `ComapiConfig` class, pass your API Space Id to the `apiSpaceId()` method, and an instance of the class that creates a JWT to the `authenticator()` method using the snippet below: [block:code] { "codes": [ { "code": "ComapiConfig config = new ComapiConfig() .apiSpaceId(\"<API_SPACE_ID>\") .authenticator(new ChallengeHandler());", "language": "java" } ] } [/block] ## Displaying push notifications when the app is in the foreground Push notifications are automatically displayed only while the app is in the background. These notifications are sent to the system tray and launch your app when users tap them. If you want to display the push notification message while the app is in the foreground, do the following: 1. Create a class that implements the `pushMessageListener` class (here, we've called the example class `PushHandler`). You'll need to decide what you want to do with the push notification and implement the logic by overriding the `onMessageReceived()` [method](https://firebase.google.com/docs/cloud-messaging/android/receive). This method is called when a push notification is received while the app is in the foreground. [block:callout] { "type": "info", "body": "If a push notification is delivered while the app is in the foreground, you can build your own in the 'onMessageReceived()` method that [creates a link to a particular activity in your app](https://developer.android.com/training/notify-user/build-notification#click).", "title": "Deep links" } [/block] [block:code] { "codes": [ { "code": "public class PushHandler implements PushMessageListener {\n\n @Override\n public void onMessageReceived(RemoteMessage message) {\n // Check if message contains a notification payload.\n if (message.getNotification() != null) {\n Log.i(\"TAG\", \"Push notification: \" + message.getNotification().getBody());\n // Do something with the message to notify the user\n // Example\n createNotificationChannel(context);\n Notification.Builder b = new Notification.Builder(context);\n b.setAutoCancel(true)\n .setDefaults(NotificationCompat.DEFAULT_ALL)\n .setWhen(System.currentTimeMillis())\n .setSmallIcon(R.drawable.common_google_signin_btn_icon_dark)\n .setContentTitle(\"foreground message\")\n .setContentText(body)\n .setContentInfo(\"INFO\");\n if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {\n b.setChannelId(\"test_channel_id1\");\n }\n NotificationManager nm = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);\n nm.notify(1, b.build());\n }\n }\n}\n\nprivate void createNotificationChannel(Context context) {\n // Create the NotificationChannel, but only on devices that have the Google API 26+ because the NotificationChannel class is new and not in supported in older libraries\n if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {\n CharSequence name = \"test channel\";\n String description = \"some description\";\n int importance = NotificationManager.IMPORTANCE_DEFAULT;\n NotificationChannel channel = new NotificationChannel(\"test_channel_id1\", name, importance);\n channel.setDescription(description);\n // Register the channel with the system; you can't change the importance\n // or other notification behaviors after this\n NotificationManager notificationManager = context.getSystemService(NotificationManager.class);\n notificationManager.createNotificationChannel(channel);\n }\n}", "language": "java" } ] } [/block] 2. Pass your class to the `pushMessageListener()` on the `ComapiConfig` object [block:code] { "codes": [ { "code": "config.pushMessageListener(new PushHandler());", "language": "java" } ] } [/block] ## Configuring logs and proxy servers You can set internal file logs, console logs, and network logs to the following levels. By default all log levels are set to `WARNING`: * `OFF` * `FATAL` * `ERROR` * `WARNING` * `INFO` * `DEBUG` To change the log levels, add the following line to the `ComapiConfig` object and use the appropriate method on the `LogConfig` object: [block:code] { "codes": [ { "code": ".logConfig(new LogConfig().setFileLevel(LogLevel.DEBUG).setConsoleLevel(LogLevel.INFO).setNetworkLevel(LogLevel.ERROR));", "language": "java" } ] } [/block] You can also set a custom limit for the size of internal log files by calling the following method on the `ComapiConfig` object: [block:code] { "codes": [ { "code": ".logSizeLimitKilobytes(limit);", "language": "java" } ] } [/block] If your app connects through a proxy server, add the following line to the `ComapiConfig` object: [block:code] { "codes": [ { "code": ".apiConfiguration(new APIConfig().proxy(\"http://xx.xxx.xx.xxx:xxxx\"));", "language": "java" } ] } [/block] # Initialising the Android SDK [block:callout] { "type": "warning", "body": "Initialisation needs to be performed in the `onCreate()` [method](https://developer.android.com/reference/android/app/Application#onCreate() of the Android `Application` class so that your app users' profiles don't change every time they open the app.", "title": "Where to initialise the Android SDK in the activity lifecycle" } [/block] 1. After you've configured the SDK, import the `com.google.firebase.FirebaseApp` class into your java file, and initialise the Firebase SDK. [block:code] { "codes": [ { "code": "FirebaseApp.initializeApp(this);", "language": "java" } ] } [/block] 2 Pass the `ComapiConfig` object to one of the following initialisation methods. These methods return a `ComapiClient` object that you can use to access the `session` and `profile` services, which are used to create and update the user's profile. * The `initialiseShared()` method: When you use this method, the SDK stores the 'ComapiClient' object, and you can access it at any time by calling the `Comapi.getShared()` method (Java) or the `RxComapi.getShared()` method (RxJava) * The `initialise()` method: When you use this method, you need to store the `ComapiClient` object yourself. The `getShared()` method is not available when you use this method. [block:code] { "codes": [ { "code": "public class MyApplication extends Application {\n\n @Override\n public void onCreate()\n {\n super.onCreate();\n \n \tFirebaseApp.initializeApp(this);\n\n ComapiConfig config = new ComapiConfig();\n //<API space ID> string must be the same as the value of the 'API space ID' field in your push notification profile in Engagement Cloud. \n config.apiSpaceId(\"<API space ID>\");\n //Set handler for authentication challenges (SDK asks for a JWT token)\n config.authenticator(new ChallengeHandler());\n\n Comapi.initialiseShared(this, config, new Callback<ComapiClient>() {\n @Override\n public void success(final ComapiClient client) {\n //Use ComapiClient object to communicate with services\n }\n @Override\n public void error(Throwable t) {\n\t\t\t\t\t\t\t//Error\n }\n }); ", "language": "java" } ] } [/block] # Changing the icon or colour of push notification Our Android SDK uses [Firebase Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging/) to send push notifications to your Android app users. As such, you can use the Android `<meta-data>` [tag](https://developer.android.com/guide/topics/manifest/meta-data-element) in your `AndroidManifest.xml` file to change the icon and colour of your push notifications. [block:code] { "codes": [ { "code": "\n<meta-data\nandroid:name=\"com.google.firebase.messaging.default_notification_icon\"\nandroid:resource=\"@mipmap/ic_launcher_round\" />\n\n<meta-data\nandroid:name=\"com.google.firebase.messaging.default_notification_color\"\nandroid:resource=\"@color/colorAccent\" />", "language": "java" } ] } [/block] [block:callout] { "type": "success", "body": "Now ensure your app passes an email address to the SDK for the app user to ensure they get a contact created in Engagement Cloud by [following these instructions](setting-up-push-notifications-new#section-pass-app-user-information-to-the-sdk)", "title": "Next steps" } [/block] # Android Sample Code [block:code] { "codes": [ { "code": "package com.example.testapp;\n\nimport com.google.firebase.FirebaseApp;\n\nimport com.comapi.Comapi;\nimport com.comapi.ComapiClient;\nimport android.app.Application;\n\nimport com.comapi.Callback;\nimport com.comapi.ComapiConfig;\nimport com.comapi.Session;\nimport com.comapi.internal.network.ComapiResult;\n\nimport java.util.HashMap;\nimport java.util.Map;\n\npublic class MyApplication extends Application {\n\n @Override\n public void onCreate()\n {\n super.onCreate();\n \n FirebaseApp.initializeApp(this);\n\n ComapiConfig config = new ComapiConfig();\n //<API space ID> string must be the same as the value of the 'API space ID' field in your push notification profile in Engagement Cloud.\n config.apiSpaceId(\"<API space ID>\");\n //Set the handler for authentication challenges (SDK asking for JWT token)\n config.authenticator(new AuthChallengeHandler());\n\n Comapi.initialiseShared(this, config, new Callback<ComapiClient>() {\n @Override\n public void success(final ComapiClient client) {\n if(client.getSession() != null && client.getSession().isSuccessfullyCreated()) {\n client.service().profile().getProfile(client.getSession().getProfileId(), new Callback<ComapiResult<Map<String, Object>>>() {\n @Override\n public void success(ComapiResult<Map<String, Object>> result) {\n Map <String, Object> additionalMap = new HashMap<>();\n //Add the user's email address to the profile\n additionalMap.put(\"email\", \"exampleappuser1@gmail.com\");\n client.service().profile().patchMyProfile(additionalMap, result.getETag(), new Callback<ComapiResult<Map<String, Object>>>() {\n @Override\n public void success(ComapiResult<Map<String, Object>> result) {\n }\n @Override\n public void error(Throwable t) {\n }\n });\n }\n @Override\n public void error(Throwable t) {\n }\n }\n );\n } else {\n client.service().session().startSession(new Callback<Session>() {\n @Override\n public void success(Session result) {\n\n }\n\n @Override\n public void error(Throwable t) {\n\n }\n });\n }\n\n }\n\n @Override\n public void error(Throwable t) {\n //Error\n }\n });\n }\n}", "language": "java", "name": "Java sample application" } ] } [/block] [block:code] { "codes": [ { "code": "package com.example.testapp;\n\nimport android.app.Application;\n\nimport com.google.firebase.FirebaseApp;\n\nimport com.comapi.ComapiConfig;\nimport com.comapi.RxComapi;\nimport com.comapi.RxComapiClient;\nimport com.comapi.internal.network.ComapiResult;\n\nimport java.util.HashMap;\nimport java.util.Map;\n\nimport rx.Observable;\nimport rx.Subscriber;\nimport rx.functions.Func1;\n\npublic class MyApplication extends Application {\n\n @Override\n public void onCreate()\n {\n super.onCreate();\n \n FirebaseApp.initializeApp(this);\n\n RxComapi.initialise(\n this, new ComapiConfig()\n //<API space ID> string must be the same as the value of the 'API space ID' field in your push notification profile in Engagement Cloud.\n .apiSpaceId(\"<API space ID>\")\n //Set the handler for authentication challenges (SDK asking for JWT token)\n .authenticator(new ChallengeHandler(getSharedPreferences(Const.PREFS_NAME, MODE_PRIVATE)))\n ).flatMap(new Func1<RxComapiClient, Observable<RxComapiClient>>() {\n @Override\n public Observable<RxComapiClient> call(final RxComapiClient client) {\n if (client.getSession() != null && client.getSession().isSuccessfullyCreated()) { \n return Observable.fromCallable(new Callable<RxComapiClient>() {\n @Override\n public RxComapiClient call() throws Exception {\n return client;\n }\n });\n } else {\n return client.service().session().startSession().map(new Func1<Session, RxComapiClient>() {\n @Override\n public RxComapiClient call(Session session) {\n return client;\n }\n });\n }\n }\n }).flatMap(new Func1<RxComapiClient, Observable<ComapiResult<Map<String, Object>>>>() {\n @Override\n public Observable<ComapiResult<Map<String, Object>>> call(final RxComapiClient client) {\n if (!client.getSession().isSuccessfullyCreated()) {\n return Observable.error(new Exception(\"Failed to update profile\"));\n }\n return client.service()\n .profile()\n .getProfile(client.getSession().getProfileId())\n .flatMap(new Func1<ComapiResult<Map<String, Object>>, Observable<ComapiResult<Map<String, Object>>>>() {\n @Override\n public Observable<ComapiResult<Map<String, Object>>> call(ComapiResult<Map<String, Object>> result) {\n Map<String, Object> additionalMap = new HashMap<>();\n //Add the user's email address to the profile\n additionalMap.put(\"email\", \"exampleappuser1@gmail.com\");\n return client.service().profile().patchMyProfile(additionalMap, result.getETag());\n }\n }\n );\n }\n }).subscribe(new Subscriber<ComapiResult<Map<String, Object>>>() {\n @Override\n public void onCompleted() {\n }\n @Override\n public void onError(Throwable e) {\n }\n @Override\n public void onNext(ComapiResult<Map<String, Object>> result) {\n }\n });\n }\n}\n", "language": "java", "name": "RxJava sample application" } ] } [/block]

API overview

Push notifications

REST

Account information

Address books

Campaigns

Contacts

Contact data fields

Custom from addresses

Document folders

Image folders

Preferences

Programs

Segments

Server time

SMS

Surveys and forms

Templates

Transactional data

Transactional email

SOAP