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
projectId	String	✅ Yes	Your Pulse project ID (found in Dashboard → Settings)
globalAttributes	(() -> Attributes)?	❌ No	Global attributes provider function
sessionConfig	SessionConfig	❌ No	Session configuration (defaults to SessionConfig.withDefaults())
diskBuffering	(DiskBufferingConfigurationSpec.() -> Unit)?	❌ No	Disk buffering configuration
instrumentations	(InstrumentationConfiguration.() -> Unit)?	❌ No	Instrumentation configuration block

Example:

PulseSDK.INSTANCE.initialize(
    application = this,
    projectId = "your-project-id",
    globalAttributes = {
        Attributes.of(
            AttributeKey.stringKey("app.version"), "1.0.0",
            AttributeKey.stringKey("environment"), "production"
        )
    }
) {
    interaction { enabled(true) }
    activity { enabled(true) }
    networkMonitoring { enabled(true) }
    anrReporter { enabled(true) }
}

Instrumentation Options

Block	Description
activity { }	Android Activity lifecycle tracking
fragment { }	Android Fragment lifecycle tracking
networkMonitoring { }	Automatic HTTP request instrumentation
anrReporter { }	Application Not Responding detection
crashReporter { }	Native crash reporting
slowRenderingReporter { }	Slow and frozen frame detection
interaction { }	User interaction flow monitoring

All instrumentation blocks support enabled(Boolean) to toggle them on or off.

---

PulseSDK.INSTANCE.isInitialized()

Check if the SDK has been successfully initialized.

Returns: Boolean - true if initialized, false otherwise

Example:

if (PulseSDK.INSTANCE.isInitialized()) {
    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:

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	Any?	✅ Yes	Property value. Pass null to remove the property

Example:

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

---

PulseSDK.INSTANCE.setUserProperties(block)

Set multiple user properties at once.

Parameter	Type	Required	Description
block	MutableMap<String, Any?>.() -> 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: emptyMap())

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: emptyMap())

Example:

try {
    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: emptyMap())

Example:

try {
    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, action)

Create a span with automatic lifecycle management. The span starts when the action 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?>	❌ No	Span attributes for context (default: emptyMap())
action	() -> T	✅ Yes	Code block to execute within the span

Example:

PulseSDK.INSTANCE.trackSpan(
    spanName = "fetch_user_data",
    params = mapOf(
        "user_id" to "12345",
        "operation" to "get_profile"
    )
) {
    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?>	❌ No	Span attributes (default: emptyMap())

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 {
    processBatch1()
    processBatch2()
    processBatch3()
} finally {
    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) {
    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()
    val tracer = otelRum.openTelemetrySdk.getTracer("custom")
} catch (e: IllegalStateException) {
    Log.e("PulseSDK", "SDK not initialized", e)
}

Shutdown

PulseSDK.INSTANCE.shutdown()

Shut down the Pulse SDK: flush and release OpenTelemetry resources, uninstall instrumentation, and stop accepting telemetry. Shutdown is terminal in the current process — the SDK cannot be re-initialized; use a fresh app process to enable Pulse again.

---

Next Steps

• Explore Advanced Configuration
• Check Troubleshooting for common issues