API Reference

Complete API documentation for the Pulse Android SDK.

Initialization

PulseSDK.INSTANCE.initialize()

Initialize the Pulse SDK. Must be called in your Application.onCreate() method as early as possible.

Parameter	Type	Required	Description
application	Application	✅ Yes	Your application instance
endpointBaseUrl	String	✅ Yes	Backend endpoint URL for sending telemetry data
endpointHeaders	Map<String, String>	❌ No	Custom HTTP headers (default: emptyMap())
globalAttributes	(() -> Attributes)?	❌ No	Global attributes provider function
diskBuffering	(DiskBufferingConfigurationSpec.() -> Unit)?	❌ No	Disk buffering configuration
instrumentations	(InstrumentationConfiguration.() -> Unit)?	❌ No	Instrumentation configuration block

Example:

PulseSDK.INSTANCE.initialize(
    application = this,
    endpointBaseUrl = "https://your-backend.com",
    endpointHeaders = mapOf("Authorization" to "Bearer token"),
    globalAttributes = {
        Attributes.of(
            AttributeKey.stringKey("app.version"), "1.0.0",
            AttributeKey.stringKey("environment"), "production"
        )
    }
) {
    interaction { enabled(true) }
    activity { enabled(true) }
    network { enabled(true) }
    anr { enabled(true) }
}

---

PulseSDK.INSTANCE.isInitialized()

Check if the SDK has been successfully initialized.

Returns: Boolean - true if initialized, false otherwise

Example:

if (PulseSDK.INSTANCE.isInitialized()) {
    // SDK is ready to use
    PulseSDK.INSTANCE.trackEvent("app_started", System.currentTimeMillis())
}

User Identification

PulseSDK.INSTANCE.setUserId(id)

Set or clear the current user ID. This identifier will be included in all subsequent telemetry data.

Parameter	Type	Required	Description
id	String?	✅ Yes	User ID. Pass null to clear the current user ID

Example:

// Set user ID
PulseSDK.INSTANCE.setUserId("user_12345")

// Clear user ID (on logout)
PulseSDK.INSTANCE.setUserId(null)

---

PulseSDK.INSTANCE.setUserProperty(name, value)

Set a single user property that will be included with all telemetry data.

Parameter	Type	Required	Description
name	String	✅ Yes	Property name
value	String	✅ Yes	Property value

Example:

PulseSDK.INSTANCE.setUserProperty("email", "user@example.com")
PulseSDK.INSTANCE.setUserProperty("subscription_tier", "premium")

---

PulseSDK.INSTANCE.setUserProperties(block)

Set multiple user properties at once using a builder pattern.

Parameter	Type	Required	Description
block	AttributesBuilder.() -> Unit	✅ Yes	Properties builder block

Example:

PulseSDK.INSTANCE.setUserProperties {
    put("email", "user@example.com")
    put("subscription_tier", "premium")
    put("account_type", "enterprise")
}

Event Tracking

PulseSDK.INSTANCE.trackEvent(name, observedTimeStampInMs, params?)

Track a custom event for business analytics and user behavior tracking.

Parameter	Type	Required	Description
name	String	✅ Yes	Event name (e.g., "button_clicked", "purchase_completed")
observedTimeStampInMs	Long	✅ Yes	Timestamp in milliseconds when the event occurred
params	Map<String, Any>?	❌ No	Additional event attributes (default: null)

Example:

PulseSDK.INSTANCE.trackEvent(
    name = "product_viewed",
    observedTimeStampInMs = System.currentTimeMillis(),
    params = mapOf(
        "product_id" to "12345",
        "product_name" to "Widget Pro",
        "category" to "electronics",
        "price" to 99.99
    )
)

Error Tracking

PulseSDK.INSTANCE.trackNonFatal(name, observedTimeStampInMs, params?)

Report a non-fatal error with a custom message. Use this for errors that don't crash the app but should be tracked.

Parameter	Type	Required	Description
name	String	✅ Yes	Error name or message
observedTimeStampInMs	Long	✅ Yes	Timestamp in milliseconds when the error occurred
params	Map<String, Any>?	❌ No	Additional error attributes for context (default: null)

Example:

try {
    // Some operation that might fail
    processPayment()
} catch (e: PaymentException) {
    PulseSDK.INSTANCE.trackNonFatal(
        name = "payment_processing_failed",
        observedTimeStampInMs = System.currentTimeMillis(),
        params = mapOf(
            "error_code" to e.code,
            "payment_method" to "credit_card",
            "amount" to 99.99
        )
    )
}

---

PulseSDK.INSTANCE.trackNonFatal(throwable, observedTimeStampInMs, params?)

Report a non-fatal exception. Automatically captures stack trace and exception details.

Parameter	Type	Required	Description
throwable	Throwable	✅ Yes	Exception to report
observedTimeStampInMs	Long	✅ Yes	Timestamp in milliseconds when the error occurred
params	Map<String, Any>?	❌ No	Additional error attributes for context (default: null)

Example:

try {
    // Some operation that might throw
    val result = apiCall()
} catch (e: NetworkException) {
    PulseSDK.INSTANCE.trackNonFatal(
        throwable = e,
        observedTimeStampInMs = System.currentTimeMillis(),
        params = mapOf(
            "endpoint" to "/api/users",
            "retry_count" to 3
        )
    )
}

Performance Tracing

PulseSDK.INSTANCE.trackSpan(spanName, params, block)

Create a span with automatic lifecycle management. The span starts when the block begins and ends when it completes (or throws an exception).

Parameter	Type	Required	Description
spanName	String	✅ Yes	Span name (e.g., "database_query", "api_call")
params	Map<String, Any>	✅ Yes	Span attributes for context
block	() -> T	✅ Yes	Code block to execute within the span

Returns: T - Result of the executed block

Example:

val result = PulseSDK.INSTANCE.trackSpan(
    spanName = "fetch_user_data",
    params = mapOf(
        "user_id" to "12345",
        "operation" to "get_profile"
    )
) {
    // Your code here - span automatically tracks duration
    apiClient.getUserProfile("12345")
}

---

PulseSDK.INSTANCE.startSpan(spanName, params)

Create a span with manual lifecycle control. You must call the returned function to end the span.

Parameter	Type	Required	Description
spanName	String	✅ Yes	Span name
params	Map<String, Any>	✅ Yes	Span attributes

Returns: () -> Unit - Function to call when the span should end

Example:

val endSpan = PulseSDK.INSTANCE.startSpan(
    spanName = "complex_operation",
    params = mapOf("operation_type" to "batch_processing")
)

try {
    // Perform operations
    processBatch1()
    processBatch2()
    processBatch3()
} finally {
    // Always end the span
    endSpan()
}

OpenTelemetry Access

PulseSDK.INSTANCE.getOtelOrNull()

Get the underlying OpenTelemetry RUM instance. Returns null if the SDK is not initialized.

Returns: OpenTelemetryRum? - The OpenTelemetry RUM instance, or null if not initialized

Example:

val otelRum = PulseSDK.INSTANCE.getOtelOrNull()
if (otelRum != null) {
    // Access OpenTelemetry APIs directly
    val tracer = otelRum.openTelemetrySdk.getTracer("custom")
}

---

PulseSDK.INSTANCE.getOtelOrThrow()

Get the underlying OpenTelemetry RUM instance. Throws an exception if the SDK is not initialized.

Returns: OpenTelemetryRum - The OpenTelemetry RUM instance

Throws: IllegalStateException - If the SDK is not initialized

Example:

try {
    val otelRum = PulseSDK.INSTANCE.getOtelOrThrow()
    // Access OpenTelemetry APIs directly
    val tracer = otelRum.openTelemetrySdk.getTracer("custom")
} catch (e: IllegalStateException) {
    // Handle case where SDK is not initialized
    Log.e("PulseSDK", "SDK not initialized", e)
}

Next Steps

• Explore Advanced Configuration
• Check Troubleshooting for common issues