Configuration

TraceConfig

The TraceConfig object controls SDK behavior. Pass it during initialization.

Android / KMP
iOS

TraceConfig(
    apiKey = "tr_live_xxxxxxxxxxxx",  // Required
    hashSalt = "your_64_char_hex_salt", // Required
    region = Region.US,               // US (default) or EU
    debug = false                     // Enable verbose logging
)

TraceConfig(
    apiKey: "tr_live_xxxxxxxxxxxx",
    hashSalt: "your_64_char_hex_salt",
    region: .us  // .us (default) or .eu
)

TraceConfig is defined in shared code, so it works identically in Android, iOS, and KMP commonMain.

Required parameters

Parameter	Description
`apiKey`	Your app’s API key. Starts with `tr_live_` (production) or `tr_test_` (sandbox).
`hashSalt`	64-character hex string used for privacy-preserving IP hashing. Unique per app.

Optional parameters

Parameter	Default	Description
`region`	`Region.US`	Data region. `Region.US` or `Region.EU`. Must match the region your app was created in.
`debug`	`false`	When `true`, the SDK logs fingerprint data, attribution results, and network calls to the console.
`enabled`	`true`	When `false`, disables all data collection and network requests at initialization. Use for privacy opt-out.

Regions

Trace supports US and EU regions. When you create an app, you choose a region. The SDK must be configured with the same region.

Android / KMP
iOS

// US region (default)
TraceConfig(apiKey = "...", hashSalt = "...", region = Region.US)

// EU region
TraceConfig(apiKey = "...", hashSalt = "...", region = Region.EU)

// US region (default)
TraceConfig(apiKey: "...", hashSalt: "...", region: .us)

// EU region
TraceConfig(apiKey: "...", hashSalt: "...", region: .eu)

Data is pinned to the region — EU app data never touches US servers, and vice versa.

Debug mode

Enable debug logging to see what the SDK is doing:

Android / KMP
iOS

TraceConfig(
    apiKey = "tr_live_xxxxxxxxxxxx",
    hashSalt = "...",
    debug = true
)

TraceConfig(
    apiKey: "tr_live_xxxxxxxxxxxx",
    hashSalt: "...",
    debug: true
)

With debug = true, the SDK logs:

Device fingerprint (screen size, OS version, locale, timezone)
Attribution request/response
Deep link delivery
Event tracking calls

Check Logcat (Android) or Console (iOS) for output tagged Trace.

Test mode

For unit tests and UI tests, use test mode to avoid network calls:

Android / KMP
iOS

TraceConfig.test(
    simulatedDeepLink = DeepLink(
        path = "/product/test_id",
        params = mapOf("color" to "blue"),
        isDeferred = true
    )
)

TraceConfig.test(
    simulatedDeepLink: DeepLink(
        path: "/product/test_id",
        params: ["color": "blue"],
        isDeferred: true
    )
)

In test mode:

No network requests are made
Attribution immediately returns with the simulated result
The simulated deep link (if provided) is delivered to your listener
All behavior is synchronous and deterministic
No platform context is required (no Android Application needed)

Resetting state between tests

Use Trace.resetForTesting() to clear SDK state between test cases. This ensures each test runs in isolation:

Android / KMP
iOS

@BeforeTest
fun setUp() {
    Trace.resetForTesting()
}

override func setUp() {
    super.setUp()
    Trace.shared.resetForTesting()
}

resetForTesting() clears the attribution-done flag, pending deep links, and all registered listeners.

Privacy opt-out

Trace supports a runtime opt-out mechanism for user privacy preferences — for example, after an Apple ATT denial or GDPR consent withdrawal.

Disable at initialization

If you already know the user has opted out (e.g. from a saved preference), pass enabled = false in the config:

Android / KMP
iOS

TraceConfig(
    apiKey = "tr_live_xxxxxxxxxxxx",
    hashSalt = "...",
    enabled = false  // No data collected until enabled
)

TraceConfig(
    apiKey: "tr_live_xxxxxxxxxxxx",
    hashSalt: "...",
    enabled: false  // No data collected until enabled
)

Runtime toggle

Toggle data collection at any time using setEnabled():

Android
iOS

// Disable after user opts out
Trace.setEnabled(false)

// Re-enable if user changes their mind
Trace.setEnabled(true)

// Check current state
val isTracking = Trace.isEnabled

// Disable after user opts out
TraceClient.setEnabled(false)

// Re-enable if user changes their mind
TraceClient.setEnabled(true)

// Check current state
let isTracking = TraceClient.isEnabled

The preference is persisted across app restarts — you don’t need to call setEnabled() every launch.

When disabled:

No fingerprint data is collected
No network requests are made (attribution, events, opens)
Deep link listeners are not fired