Iterable's Android SDK is a Java-based Android client for Iterable. This article describes how to install and configure the SDK.
Table of contents
Supported Android versions
Iterable's Android SDK supports Android versions 4.1.2 (API level 16) and higher.
Encrypted data
Depending on your minSdkVersion
, Iterable's Android SDK can encrypt some
data at rest. For more information, read Upgrading to 3.4.0+.
Installation steps
Follow these steps to upgrade the SDK. If you're upgrading from a previous version, also see Upgrading the SDK.
IMPORTANT
If your app targets API level 22 or lower, read Upgrading to 3.4.10+ to learn about some adjustments you'll need to make to your Android project.
IMPORTANT
Some users have reported crashes in apps built with version 3.4.10 of Iterable's Android SDK. We're investigating the issue. In the meantime, please test thoroughly. If you see crashes, revert to version 3.4.9.
1. Set 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.
2. Create 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
WARNING
Never embed server-side API keys in client-side code (whether JavaScript, a mobile application or otherwise), since they can be used to access all of your project's data. For a mobile app, use a mobile API key (if possible, we recommend using JWT authentication for additional security).
If necessary, use different API keys for debug and production builds.
3. Install the SDK
TIP
To determine the latest version of Iterable's Android SDK, see search.maven.org.
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.
WARNING
If you use ProGuard and don't complete this step, some of the SDK's features may not work as expected.
4. Initialize the SDK
Follow these steps to initialize Iterable's Android SDK:
-
First, make a few updates in the
onCreate
method of your app'sApplication
class:-
Create an
IterableConfig
object and pass it toIterableApi.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
- Version 3.4.10 of Iterable's Android SDK provides a configuration option to store in-app messages in memory, rather than in a local file. For more information, read Encrypted data.
- Don't call
IterableApi.initialize
fromActivity#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.
-
If your project is hosted on Iterable's European data center (EUDC), configure the SDK to use Iterable's EU-based API endpoints:
IterableConfig config = new IterableConfig.Builder() // ... other configuration options ... .setDataRegion(IterableDataRegion.EU).build(); IterableApi.initialize(context, "<YOUR_API_KEY>", config);
-
Declare the URL protocols your app supports
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 onIterableConfig.Builder
.For example, this code allows the SDK to handle
http://
,tel://
, andcustom://
links:IterableConfig config = new IterableConfig.Builder() // ... other configuration options ... .setAllowedProtocols(new String[]{"http", "tel", "custom"}).build(); IterableApi.initialize(context, "<YOUR_API_KEY>", config);
IMPORTANT
Iterable's Android SDK handles
https
,action
,itbl
, anditerable
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). -
Decide whether or not to store in-app messages in memory
By default, Iterable's Android SDK stores in-app messages in an unencrypted local file. To instead store in-app messages in memory, use the
setUseInMemoryStorageForInApps(true)
SDK configuration option (defaults tofalse
):IterableConfig config = new IterableConfig.Builder() // ... other configuration options ... .setUseInMemoryStorageForInApps(true).build(); IterableApi.initialize(context, "<YOUR_API_KEY>", config);
For more information about this option, read Upgrading to 3.4.10+.
-
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 config = new IterableConfig.Builder() // ... other configuration options ... .setPushIntegrationName(“<PUSH_INTEGRATION_NAME>“).build(); IterableApi.initialize(context, “<YOUR_API_KEY>“, config);
TIP
To find the name of your Iterable push integration, navigate in Iterable to Settings > Apps and websites, open the mobile app that's associated with your actual app, look at the Details section, and find the Package Name.
-
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:
IterableConfig config = new IterableConfig.Builder() // ... other configuration options ... .setAuthHandler(new IterableAuthHandler() { @Override public String onAuthTokenRequested() { // Insert your implementation here: // return customCustomerImplementation.getTokenFromBackend() } }).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 callsonAuthTokenRequested
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, onIterableConfig
)-
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 anInvalidJwtPayload
error when it makes a request with the new token, it won't call theauthHandler
again until you callsetEmail
orsetUserId
without passing in an auth token).TIP
The
setEmail
andsetUserId
mobile SDK methods accept an optional, prefetched auth token. If you encounter SDK errors related to auth token requests, try using this parameter.
-
-
Once your app knows the user's email (preferred) or user ID, call
setEmail
orsetUserId
:IterableApi.getInstance().setEmail("email@example.com");
IterableApi.getInstance().setUserId("userId");
NOTES
- Don't set an email and user ID in the same session. Doing so causes the SDK to treat them as different users.
- If you've prefetched an auth token, you can pass it directly to
setEmail
andsetUserId
(useful to work around race conditions that can sometimes occur).
-
Register for remote notifications
Iterable's SDK automatically registers a push token with Iterable whenever the app's code calls
setEmail
orsetUserId
. To instead handle token registration manually:When initializing the SDK, disable automatic push token registration by calling
setAutoPushRegistration(false)
onIterableConfig.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
orsetUserId
after the app has already launched (for example, when a new user logs in), callregisterForPush
to register the device for the current user.
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(); } }
NOTES
- This step is mandatory when working with multiple push providers.
- Firebase has deprecated
FirebaseInstanceIdService
. In recent versions, it has been replaced withonNewToken
. - To handle silent push notifications, use a custom
FirebaseMessagingService
.
Upgrading the SDK
This section describes how to upgrade from earlier versions of Iterable's Android SDK.
Upgrading to 3.4.10+
In Android apps with minSdkVersion
23 or higher (Android 6.0)
Iterable's Android SDK now encrypts the following fields when storing them at
rest:
-
email
— The user's email address. -
userId
— The user's ID. -
authToken
— The JWT used to authenticate the user with Iterable's API.
(Note that Iterable's Android SDK does not store the last push payload at rest—before or after this update.)
For more information about this encryption in Android, examine the source code
for Iterable's Android SDK: IterableKeychain
.
This release also allows you to have your Android apps (regardless of minSdkVersion
)
store in-app messages in memory, rather than in an unencrypted local file.
However, an unencrypted local file is still the default option.
To store in-app messages in memory, set the setUseInMemoryStorageForInApps(true)
SDK configuration option (defaults to false
):
IterableConfig config = new IterableConfig.Builder() // ... other configuration options ... .setUseInMemoryStorageForInApps(true).build(); IterableApi.initialize(context, "<YOUR_API_KEY>", config);
When users upgrade to a version of your Android app that uses this version of
the SDK (or higher), and you've set this configuration option to true
, the
local file used for in-app message storage (if it already exists) is deleted
However, no data is lost.
API level 22 and lower
If your app targets API level 23 or higher, this is a standard SDK upgrade, with no special instructions.
If your app targets an API level less than 23, you'll need to make the following changes to your project (which allow your app to build, even though it won't encrypt data):
In
AndroidManifest.xml
, add<uses-sdk tools:overrideLibrary="androidx.security" />
-
In your app's
app/build.gradle
:- Add
multiDexEnabled true
to thedefault
object, underandroid
. - Add
implementation androidx.multidex:multidex:2.0.1
to thedependencies
.
- Add
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
andgetAndTrackDeepLink
, to instance methods. To call these methods, you'll need to first grab an instance of theIterableApi
class by callingIterableApi.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
(anIterableInAppHandler
object). From itsonNewInApp
method, returnInAppResponse.SKIP
.To get the queue of available in-app messages, call
IterableApi.getInstance().getInAppManager().getMessages()
. Then, callIterableApi.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 theaction://
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 theaction://
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
Comments
0 comments
Article is closed for comments.