This guide explains how to integrate an mtribes Space into your Android application.
You'll learn how to synchronize changes from your Space into your codebase using our CLI's code generation, and how to use this code to control the UX of your end users.
- An Android project ready to integrate with mtribes
- An mtribes Space with at least one Collection and Experience
- The mtribes CLI installed
- Android code generated for your Space
Our SDK is designed to use in modern Android applications with support for backward compatibility,
up to devices running
API 21(Android 5.0).
Kotlin is treated as our first class language in the SDK with 100% Java interoperability in
Generated code is basically an Android library module which contains Kotlin code. But don't worry if your app is written in Java, as we always try to keep the experience and compatibility intact.
We use RxJava2 for our asynchronous functionalities, which is the only supported method at present. We're working on providing more options in the future, for example: coroutines.
We only support
AndroidX as support libraries are now deprecated.
With your Space code generated, you're ready to integrate mtribes into your Android application.
In the code examples which follow, we'll build out an example Space containing:
homepageCollection, which contains:
bodySection, which supports:
On successful completion, an Android library module will be generated. This newly generated module will
be automatically added to your project
If run outside of your root directory, you'll need to add your generated module manually to
To see the module in your Android Studio project navigator,
Sync Project with Gradle Files.
- Add the module dependency in your application
build.gradlefile just as the CLI prompts.
The generated Android module uses Kotlin with 100% Java interoperability in mind. We've made sure the integration experience for both languages are seamless.
Manually updating the version of the core library is not recommended. We suggest you always use the CLI to synchronize with the latest versions. The library cannot be used independently as we treat the CLI generated module and the library as a single entity.
With your Space configured and code generated, you can now import and use Experience instances to control elements of your UX.
The entry point to the mtribes platform is the
Mtribes singleton class included within the
generated module. With that comes the initialization functionality, which should be the first
function you call in your application code.
The recommended way of invoking this is via the entry point of your app workflow, typically in the
Application.onCreate() method, just before
Client is a top-level object for configuring your mtribes SDK.
Client instance is generated along with your Space integration code and can be accessed via
Defaults are sensible, but can be overridden to further harmonize mtribes with your application.
Example: Disable session locking to enable Section and Experience change events during a user session.
It's best to configure the Client before starting the session, but configuration can be adjusted at any time.
Before accessing an Experience, it's important to start a session for the active user, so we can serve them personalized states.
We represent an mtribes session via the
session object, which you can access via
Start a session for an anonymous user.
This should be done:
- on app launch if the user is anonymous
- when a user logs out
It's important to wait for the completion of
accessing Experiences and Sections.
Logged in user
Starting a session for a logged in user is similar to an anonymous one, except you must provide their unique identifier.
This should be done:
- on app launch if the user is already logged in
- when a user logs in
Again, wait for the completion of
accessing Experiences and Sections.
A user ID should be opaque and not personally identifiable. For example, you should avoid email addresses, social security numbers or similarly personal information.
If you don't have an opaque ID for a user, you can use a secure hashing algorithm
such as SHA256 to encode it before
passing it to
When starting a session, you can also provide fields with values specific to the user. These open up powerful Tribe targeting options in the mtribes platform.
Example 1: Start a session for an anonymous user with a contextual property of
Example 2: Start a session for a logged in user with a contextual property of
We currently support the following contextual property types.
Date: ISO-8601 UTC string encoded timestamp e.g.
"2020-12-02T02:45:02.076Z"This must include the date and time.
A maximum of 50 contextual properties can be active at one time. You can remove unused properties to make room for new ones in the contextual property settings page.
To avoid exceeding these limits or sending PII by mistake, we recommend selecting specific contextual properties to include when starting a session.
With the session primed, you can now check whether Experiences modeled in the Space are enabled for a user, and if so, what custom data properties have been defined for them.
Sections contain a list of child Experiences defined at runtime by a Scheduler in the mtribes platform. You can iterate over these child Experiences and render each in turn, depending on its type.
Each Section defines its
Supported Experience types
enum. You can use these as switch cases/when expressions and render appropriately.
The state of an Experience or Section may change for a user during their session. You can monitor these changes and reflect them in your code.
If you want published change events to fire during a user's session, then you'll
need to set Client.sessionLock to
false. By default, session
locking is enabled to avoid published changes negatively impacting UX.
To help you gather user analytical behavioral patterns associated with an
Experience, we expose a
Analytic events support a
Action to help with event
classification. These properties are encoded as a string in the format
<category>/<action>. If only
<action> is provided, a default Category of
user is assumed.
Here are a few examples from our banner Experience above.
Trusted Identity helps ensure the authenticity of users identified into your mtribes Space. View our comprehensive Trusted Identity guide to understand what this is and how to enable it.
Once you have a hashed user signature returned from your server, you should pass this as an option when starting a session for a logged in user.
You can enable internal SDK logs to get a deeper understanding of some workflows.
It's common practice to use a custom logger or a third party library like Timber for logging in an Android app code base.
To make the logging experience seamless and consistent, you could use your own logger but conform to the
Following is an example where you can use Timber with Debug build configuration in your app.