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 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 3 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:

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 permissions to define which customer IDs, events, and properties require JWT.

• Review Tracking for Android SDK for complete tracking implementation.

• Set up push notifications to engage customers.

• Implement in-app personalization for dynamic content.