Skip to main content

API Reference

All public methods on PulseSDK.INSTANCE.

Initialization​

initialize(...)​

Initializes the SDK. Call once in Application.onCreate() as early as possible. Subsequent calls are ignored.

PulseSDK.INSTANCE.initialize(
    application = this,

    apiKey = "your-api-key",
    dataCollectionState = PulseDataCollectionConsent.ALLOWED,
)

See Configuration for the full parameter list.

isInitialized()​

Returns Boolean — true if the SDK is initialized and actively collecting.

if (PulseSDK.INSTANCE.isInitialized()) { ... }

setDataCollectionState(newState)​

Updates consent state at runtime. See Data Collection Consent for valid transitions.

PulseSDK.INSTANCE.setDataCollectionState(PulseDataCollectionConsent.ALLOWED)
PulseSDK.INSTANCE.setDataCollectionState(PulseDataCollectionConsent.DENIED)

shutdown()​

Permanently shuts down the SDK — flushes pending telemetry, uninstalls instrumentations. Cannot be reversed in the current process.

PulseSDK.INSTANCE.shutdown()

User Identity​

See User Identification for the full pattern.

setUserId(id)​

PulseSDK.INSTANCE.setUserId("usr_12345")
PulseSDK.INSTANCE.setUserId(null)  // clear on logout

setUserProperty(name, value)​

PulseSDK.INSTANCE.setUserProperty("plan", "premium")
PulseSDK.INSTANCE.setUserProperty("plan", null)  // remove

setUserProperties(block)​

PulseSDK.INSTANCE.setUserProperties {
    put("email", "user@example.com")
    put("plan", "premium")
    put("verified", true)
}

Custom Telemetry​

trackEvent(name, observedTimeStampInMs, params)​

Emits a named custom event. See Custom Events.

PulseSDK.INSTANCE.trackEvent(
    name = "purchase_completed",
    observedTimeStampInMs = System.currentTimeMillis(),
    params = mapOf("product_id" to "SKU-123", "price" to 49.99),
)

trackNonFatal(name, observedTimeStampInMs, params)​

Reports a named non-fatal error. See Error Tracking.

PulseSDK.INSTANCE.trackNonFatal(
    name = "api_timeout",
    observedTimeStampInMs = System.currentTimeMillis(),
    params = mapOf("endpoint" to "/api/feed"),
)

trackNonFatal(throwable, observedTimeStampInMs, params)​

Reports a caught exception — extracts type, message, and stack trace automatically.

try {
    riskyOperation()
} catch (e: Exception) {
    PulseSDK.INSTANCE.trackNonFatal(
        throwable = e,
        observedTimeStampInMs = System.currentTimeMillis(),
        params = mapOf("context" to "checkout_flow"),
    )
}

trackSpan(spanName, params, action)​

Wraps a block in a span. Ends automatically when the block returns or throws. See Custom Spans.

PulseSDK.INSTANCE.trackSpan("fetch_user_data", mapOf("user_id" to "123")) {
    apiClient.getUser("123")
}

startSpan(spanName, params)​

Starts a span and returns an () -> Unit to end it manually.

val endSpan = PulseSDK.INSTANCE.startSpan("image_upload")
try {
    performUpload()
} finally {
    endSpan()
}
warning

Always call the returned function. Leaked spans will have incorrect duration.

OpenTelemetry Access​

getOtelOrNull()​

Returns OpenTelemetryRum? — the underlying OTel RUM instance, or null if not initialized.

getOtelOrThrow()​

Returns OpenTelemetryRum — throws IllegalStateException if not initialized.

val tracer = PulseSDK.INSTANCE.getOtelOrNull()
    ?.openTelemetry
    ?.tracerProvider
    ?.get("my-instrumentation")

Next Steps​