Configure Android SDK with JWT authentication

This guide walks you through configuring the Exponea Android SDK to route mobile tracking data through Data hub event streams and implementing JWT authentication.

📱

Platform guide

This guide is for Android developers. If you're using iOS, see Configure iOS SDK with JWT authentication.

Prerequisites

Before configuring Data hub integration:

• Event stream created: You need at least one event stream in Data hub.

• Event stream credentials: Your stream ID from Data hub (found in Events > your stream > Access security).

• For JWT authentication: Backend infrastructure capable of generating and signing JWT tokens using your JWT signing keys.

Configure SDK for Data hub

Use the StreamConfig initialization to route tracking through event streams:

val configuration = ExponeaConfiguration()

configuration.integrationConfig = StreamConfig(
    baseUrl = "https://api.exponea.com",
    streamId = "YOUR_STREAM_ID"
)

Exponea.init(this, configuration)

🚧

Warning

The following configuration options are not supported with StreamConfig and will be ignored: advancedAuthEnabled, AuthorizationProvider, integrationRouteMap.

For all other configuration parameters, see Exponea Android SDK configuration.

Set up JWT authentication

If your event stream uses JWT signed-only permissions for customer IDs, events, or properties, you must provide JWT tokens to authenticate tracking requests.

Set JWT token

You can provide the JWT token in three ways:

During SDK initialization:

Include the token in CustomerIdentity when you initialize the SDK:

Exponea.init(
    this,
    configuration,
    customerIdentity = CustomerIdentity(
        customerIds = mapOf("registered" to "[email protected]"),
        sdkAuthToken = "your-jwt-token"
    )
)

During customer identification:

Include the token when calling identifyCustomer():

Exponea.identifyCustomer(
    customerIdentity = CustomerIdentity(
        customerIds = mapOf("registered" to "[email protected]"),
        sdkAuthToken = "your-jwt-token"
    )
)

For complete identifyCustomer() usage, see Identify customers.

Independently after initialization:

Set the token at any point:

kotlin

Exponea.setSdkAuthToken("your-jwt-token")

📘

Note

setSdkAuthToken() is only supported with StreamConfig. Calling it with ProjectConfig logs a warning and is ignored.

Token storage and lifecycle

The SDK stores JWT tokens persistently across app restarts. The token is automatically cleared when:

• anonymize() is called.

• identifyCustomer() is called without a token in CustomerIdentity.

❗️

Warning

The JWT token is tied to the current customer IDs. When customer IDs change (via identifyCustomer() or anonymize()), the SDK clears the token. Always provide a fresh token for the new customer identity.

Implement token refresh callback

Register an SdkAuthCallback to receive notifications of authentication failures and supply fresh tokens:

Exponea.sdkAuthCallback = object : SdkAuthCallback {
    override fun onAuthFailure(error: SdkAuthError) {
        val newToken = fetchNewTokenFromYourBackend()
        Exponea.setSdkAuthToken(newToken)
    }
}

🚧

Important

SdkAuthCallback is invoked on a background thread. You can block it while waiting for an asynchronous token fetch (for example, an HTTP call to your backend). The SDK re-reads the token after the callback returns.

Generate JWT tokens

Your backend must generate JWT tokens that match the event stream's validation requirements.

Header:

• alg: Algorithm (HS256, HS384, or HS512).

• kid: Your signing key ID from Data hub.

Payload:

• ids: Map of customer identifiers (example: {"registered": "user123"}).

• exp: Expiration timestamp (Unix epoch).

Key requirements:

• The token must be signed with one of your JWT signing keys.

• Customer IDs in the token must exactly match the IDs sent in tracking requests.

• Expiration should match your session duration (maximum 90 days).

For complete JWT specification and backend code examples (Node.js, Python), see the backend implementation guide in [JWT authentication for Web SDK].

Validate and troubleshoot implementation

For common issues and solutions, see Validate and troubleshoot mobile SDK integration.

Next steps

After implementing Data hub integration:

• [Configure event stream security and permissions] to define which customer IDs, events, and properties require JWT.

• Review [Android SDK tracking] for complete tracking implementation.

• [Set up push notifications] to engage customers.

• Implement [in-app personalization] for dynamic content.