Iterable's Android SDK

​

​ Iterable's Android SDK is a Java-based Android client for Iterable. The SDK supports Android API versions 15 and higher. This document describes how to install and configure the SDK.

# Table of contents

# Setting up an Iterable push integration

Before installing Iterable's Android SDK, follow the instructions in Setting up Android Push Notifications to set up Firebase, an Iterable mobile app, and an associated push integration.

# Creating a mobile API key

To make calls to Iterable's's API, the SDK needs a mobile API key. To learn how to create one, read API Keys

If necessary, use different API keys for debug and production builds.

# Installing the SDK

To use Iterable's Android SDK in your app, add the SDK and Firebase Messaging as dependencies to your application's build.gradle:

dependencies{
    implementation 'com.iterable:iterableapi:3.4.0'
    // Optional, contains Inbox UI components:
    implementation 'com.iterable:iterableapi-ui:3.4.0' 
    // Version 17.4.0+ is required for push notifications and in-app message features:
    implementation 'com.google.firebase:firebase-messaging:X.X.X' 
}

# ProGuard configuration

If you're using ProGuard when building your Android app, you'll need to add this line of ProGuard configuration to your build:

-keep class org.json.** { *; }

To learn how to do this, check out Android's guide about how to Shrink, obfuscate, and optimize your app.

# Initializing the SDK

Follow these steps to initialize Iterable's Android SDK:

1. First, make a few updates in the onCreate method of your app's Application class:

   • Create an IterableConfig object and pass it to IterableApi.initialize

     IterableConfig config = new IterableConfig.Builder().build();
     IterableApi.initialize(context, "<YOUR_API_KEY>", config);
     

     IterableConfig contains various configuration options for the SDK. For more information, refer to the source code.

     IMPORTANT

     Don't call IterableApi.initialize from Activity#onCreate. Initialize Iterable's SDK when the application is starting, regardless of whether it has been launched to open an activity or in the background as the result of an incoming push notification.

   • Declare the URL protocols you'd like to support

     Starting with version 3.4.0 of Iterable's Android SDK, you'll need to declare the specific URL protocols that the SDK can expect to see on incoming links (and that it should handle as needed). This prevents the SDK from opening links that use unexpected URL protocols.

     To do this, pass the protocols you'd like the SDK to support (as an array of strings) to the setAllowedProtocols method on IterableConfig.Builder.

     For example, this code allows the SDK to handle http://, tel://, and custom:// links:

     Java

     IterableConfig.Builder configBuilder = new IterableConfig.Builder()
       .setAllowedProtocols(new String[]{"http", "tel", "custom"});
     IterableApi.initialize(context, "<YOUR_API_KEY>", config);
     

     Kotlin

     val configBuilder = IterableConfig.Builder()
        .setAllowedProtocols(arrayOf("http","tel","custom"))
     IterableApi.initialize(context, "<YOUR_API_KEY>", configBuilder.build());
     

     IMPORTANT

     Iterable's Android SDK handles https, action, itbl, and iterable links, regardless of the contents of this array. However, you must explicitly declare any other types of URL protocols you'd like the SDK to handle (otherwise, the SDK won't open them in the web browser or as deep links).

   • Set up a push integration

     In Iterable, you'll create logical mobile apps to store information about your real mobile apps—including information about the configuration parameters Iterable needs to send push notifications to them. Iterable refers to these push notification configuration parameters as push integrations.

     TIP

     Older push integrations may not yet be associated in Iterable with a mobile app. However, you can assign them.

     By default, the SDK expects your push integration's name to match your app's package name. However, if your Iterable push integration was created before August 2019, it may have a custom name. To handle this, do one of the following things:

     • In Iterable, assign the existing push integration to a mobile app. If you do this, the SDK will use the push integration that matches your mobile app's package name.

     • Alternatively, specify the custom push integration name when initializing the SDK:

       IterableConfig.Builder configBuilder = new IterableConfig.Builder()
           .setPushIntegrationName(“<PUSH_INTEGRATION_NAME>“);
       IterableApi.initialize(context, “<YOUR_API_KEY>“, configBuilder.build());
       

       TIP

       To find the name of your Iterable push integration, navigate in Iterable to Settings > Mobile Apps, open the mobile app that's associated with your actual app, look at the Push section, and find the Name column for the relevant push integration.

       

   • Write some code to enable your JWT-enabled API key

     If you're using a JWT-enabled API Key, you'll also need to implement the auth token requested callback. This callback should fetch (from your server) a valid JWT (for the current user) and provide it to the SDK:

     Java

     IterableConfig.Builder configBuilder = new IterableConfig.Builder()
         .setAuthHandler(new IterableAuthHandler() {
         @Override
         public String onAuthTokenRequested() {
             // Insert your implementation here:
             // return customCustomerImplementation.getTokenFromBackend()
         }
      });
      IterableConfig config = configBuilder.build();
      IterableApi.initialize(_context, "<YOUR_API_KEY>", config);
     

     To make requests to Iterable's API using a JWT-enabled API key, first fetch a valid JWT for your app's current user from your own server, which must generate it. onAuthTokenRequested provides this JWT to Iterable's Android SDK, which can then append the JWT to subsequent API requests. The SDK automatically calls onAuthTokenRequested at various times:

     • When your app sets the user's email or user ID.
     • When your app updates the user's email.
     • Before the current JWT expires (at a configurable interval set by expiringAuthTokenRefreshPeriod, in seconds, on IterableConfig)
     • When your app receives a 401 response from Iterable's API with a InvalidJwtPayload error code. (however, if the SDK receives a second consecutive 401 with an InvalidJwtPayload error when it makes a request with the new token, it won't call the authHandler again until you call setEmail or setUserId.

2. Once your app knows the user's email (preferred) or user ID, call setEmail or setUserId

   • IterableApi.getInstance().setEmail("email@example.com");
   • IterableApi.getInstance().setUserId("userId");

   NOTE

   Don't set an email and user ID in the same session. Doing so causes the SDK to treat them as different users.

3. Register for remote notifications

   Iterable's SDK automatically registers a push token with Iterable whenever the app's code calls setEmail or setUserId. To instead handle token registration manually:

   • When initializing the SDK, disable automatic push token registration by calling setAutoPushRegistration(false) on IterableConfig.Builder.

   • Whenever necessary, call registerForPush to register the token:

     IterableApi.getInstance().registerForPush();
     

   NOTES

   • Device registration fails when no email or user ID has been set.
   • If you're calling setEmail or setUserId after the app has already launched (for example, when a new user logs in), call registerForPush() to register the device for the current ser.

# Handling Firebase push messages and tokens

The SDK automatically adds a FirebaseMessagingService to the app manifest. To handle incoming push notifications, no extra setup is necessary.

If your application implements its own FirebaseMessagingService, forward onMessageReceived and onNewToken calls to IterableFirebaseMessagingService.handleMessageReceived and IterableFirebaseMessagingService.handleTokenRefresh, respectively:

Java

public class MyFirebaseMessagingService extends FirebaseMessagingService {

    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        IterableFirebaseMessagingService.handleMessageReceived(this, remoteMessage);
    }

    @Override
    public void onNewToken(String s) {
        IterableFirebaseMessagingService.handleTokenRefresh();
    }
}

# Upgrading the SDK

This section describes how to upgrade from earlier versions of Iterable's Android SDK.

# Upgrading to 3.4.0+

• Starting with version 3.4.0 of Iterable's Android SDK, you'll need to declare the URL protocols that the SDK should expect to see on incoming links (and then handle as needed). For more information, read about initializing the SDK.

• Version 3.4.0 changes two static methods on the IterableApi class, handleAppLink and getAndTrackDeepLink, to instance methods. To call these methods, you'll need to first grab an instance of the IterableApi class by calling IterableApi.getInstance(). For example, IterableApi.getInstance().handleAppLink(...).

# Upgrading to 3.3.1+

To resolve a breaking change introduced in Firebase Cloud Messaging version 22.0.0, version 3.3.1 of Iterable's Android SDK bumps the minimum required version of its Firebase Android dependency to 20.3.0.

If upgrading to version 3.3.1 causes your app to crash on launch, or your build to fail, add the following lines to your app's build.gradle file:

android {
    ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    ...
}

# Upgrading to 3.2.0+

Versions 3.2.0+ of the SDK depend on the AndroidX support libraries. To use these versions, you'll need to migrate your app to use AndroidX.

# Upgrading from a version prior to 3.1.0

• In-app messages

  • spawnInAppNotification

    The spawnInAppNotification method is no longer needed and will fail to compile. The SDK now displays in-app messages automatically. There is no need to poll the server for new messages.

  • Handling manually

    To control when in-app messages display (rather than displaying them automatically), set IterableConfig.inAppHandler (an IterableInAppHandler object). From its onNewInApp method, return InAppResponse.SKIP.

    To get the queue of available in-app messages, call IterableApi.getInstance().getInAppManager().getMessages(). Then, call IterableApi.getInstance().getInAppManager().showMessage(message) to show a specific message.

  • Custom actions

    This version of the SDK reserves the iterable:// URL scheme for Iterable-defined actions handled by the SDK and the action:// URL scheme for custom actions handled by the mobile application's custom action handler.

    If you are currently using the itbl:// URL scheme for custom actions, the SDK will still pass these actions to the custom action handler. However, support for this URL scheme will eventually be removed (timeline TBD), so it is best to move templates to the action:// URL scheme as it's possible to do so.

• Deep links

  • Consolidated deep link URL handling

    By default, the SDK handles deep links with the the URL handler assigned to IterableConfig.

# GCM to Firebase migration

To migrate from GCM to Firebase:

• Upgrade the existing Google Cloud project to Firebase.
• Update the server token in the existing GCM-based Iterable push integration, applying the new Firebase token.
• Update the Android app to support Firebase.

If you use the same project and integraton name for Firebase Cloud Messaging, the old tokens remain valid and you won't need to re-register existing devices. If you're using a new project for Firebase Cloud Messaging, and have existing devices on a GCM project with a different sender ID:

• Updating the app will generate new tokens for users, but the old tokens remain valid.
• When migrating from one sender ID to another, when initializing Iterable's SDK, specify legacyGCMSenderId onIterableConfig. This disables old tokens to make sure users won't receive duplicate notifications.

# Troubleshooting

If you're having trouble installing or initializing the SDK, read Testing and Troubleshooting the Iterable SDK.

# Futher reading

• Identifying the User
• Updating User Profiles
• Tracking Events with Iterable's Mobile SDKs
• Setting up Android Push Notifications
• In-App Messages on Android
• Setting up Mobile Inbox on Android
• Customizing Mobile Inbox on Android
• Android App Links
• Deep Links in Push Notifications
• Sample Apps that use Iterable's Android SDK
• Deep Links Setup
• JWT-Enabled API Keys