Skip to main content

Installation

Install the Pulse Android SDK in your Android project.

Requirements​

Before installing, ensure your project meets the following requirements:

Android​

  • minSdk: 21+
  • Android Gradle Plugin: 8.3.0+

Java/Kotlin​

  • Compatible with both Java and Kotlin projects

Note: If your minSdk < 26, enable corelib desugaring and set android.useFullClasspathForDexingTransform=true in gradle.properties. See #73.

Add Dependency​

Add the Pulse Android SDK dependency to your app's build.gradle[.kts]:

dependencies {
    //...
    // check the latest version from https://central.sonatype.com/artifact/in.horizonos/pulse-android-sdk/versions
    implementation("in.horizonos:pulse-android-sdk:0.0.1-alpha")
    //...
}

Initialize SDK​

Initialize the Pulse SDK in your Application class, as early as possible in onCreate():

import android.app.Application
import android.util.Log
import com.pulse.android.sdk.PulseSDK
import io.opentelemetry.android.OpenTelemetryRum
import io.opentelemetry.api.common.AttributeKey
import io.opentelemetry.api.common.Attributes

class MainApplication : Application() {
    var otelRum: OpenTelemetryRum? = null

    override fun onCreate() {
        super.onCreate()
        // you can use this Otel RUM instance to access the underlying the Otel Java APIs
        otelRum = initializePulse()
    }

    private fun initializePulse(): OpenTelemetryRum? = runCatching {
        PulseSDK.INSTANCE.initialize(
            application = this,
            endpointBaseUrl = "https://your-backend-url.com",
            globalAttributes = {
                Attributes.of(
                    AttributeKey.stringKey("app.version"), "1.0.0",
                    AttributeKey.stringKey("environment"), "production"
                )
            }
        ) {
            // Enable/disable specific instrumentations
            interaction { enabled(true) }
            activity { enabled(true) }
            fragment { enabled(false) }
            network { enabled(true) }
            anr { enabled(true) }
            slowRendering { enabled(true) }
        }
        PulseSDK.INSTANCE.getOtelOrNull()
    }.onFailure {
        Log.e("PulseSDK", "Initialization failed", it)
    }.getOrNull()
}

Permissions​

To get detailed network information (subtype, carrier name, etc.), add the following permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

For API 33+:

<uses-permission android:name="android.permission.READ_BASIC_PHONE_STATE" />
Without permissions
  • Only basic connection type is available
  • Carrier name may be limited to SIM-provided name

With permissions:

  • Full connection subtype (LTE, 5G, etc.)
  • Standardized carrier name (e.g., "T-Mobile-US")
  • Mobile country code (MCC) and network code (MNC)
  • ISO country code (ICC)

Verification​

After installation, verify the SDK is initialized:

val isReady = PulseSDK.INSTANCE.isInitialized()
if (isReady) {
    Log.d("PulseSDK", "SDK initialized successfully")
}

Next Steps​

Now that you've installed the Pulse Android SDK, you can start instrumenting your application:

  • Custom Events - Track custom user interactions and business events
  • Error Tracking - Manually report and track errors in your application
  • Custom Spans - Create custom spans to track specific operations and workflows

Configure Attributes​

Enhance your telemetry data by configuring attributes that provide context for all your events and spans:

  • Global Attributes - Set attributes that are automatically included with all telemetry data, such as app version, environment, or custom metadata
  • User Attributes - Identify and track users across sessions by setting user attributes like user ID, user tags, or other identifiers

Best Practices​

Initialize Early: Call initialize() as early as possible in your Application.onCreate() to capture app start metrics accurately:

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // Initialize Pulse first
        PulseSDK.INSTANCE.initialize(
            application = this,
            endpointBaseUrl = "https://your-backend.com"
        )
        // ... other initializations
    }
}

Next Steps​

Once installed and initialized, explore the below Instrumentation guides to learn about: