Skip to main content

Quick Start

Install and initialize the Pulse React Native SDK in your React Native project.

Using Expo? See the Expo Setup Guide for automatic configuration.

Install Package​

yarn add @dreamhorizonorg/pulse-react-native

The native dependencies are automatically linked via React Native autolinking.

Initialization​

The Pulse React Native SDK requires initialization on both the native and React Native sides.

Native Initialization​

Android​

The React Native SDK requires the Pulse Android SDK to be initialized in your native Android code. This is mandatory for the SDK to function.

Initialize the SDK in your android/app/src/main/java/.../MainApplication.kt:

import android.app.Application
import com.pulsereactnativeotel.Pulse

class MainApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    
    // Initialize Pulse Android SDK as early as possible
    Pulse.initialize(
      application = this,
      endpointBaseUrl = "https://your-backend-url.com"
    )
    // ... other initializations
  }
}

Important: This step is mandatory. Without native SDK initialization, no telemetry will be sent. Initialize the SDK as early as possible in onCreate() to capture app start metrics and early errors.

Note: Replace "https://your-backend-url.com" with your actual Pulse backend endpoint URL where telemetry data will be sent.

iOS​

iOS support is coming soon.

React Native Initialization​

After native platform initialization, enable automatic instrumentation in your app entry point (e.g., App.tsx):

import { Pulse } from '@horizoneng/pulse-react-native';

// Enable auto-instrumentation features
Pulse.start();

function App() {
  // Your app code
}

Auto-Instrumentation​

With the bare minimum setup above, Pulse automatically tracks the following telemetry in your Android app:

Automatically Captured​

The following telemetry is captured automatically without any additional configuration:

  • JS and Android crashes - JavaScript exceptions and native Android crashes
  • Network requests - HTTP requests made via fetch, XMLHttpRequest, or axios
  • ANR and Frozen Frame data - Application Not Responding events and UI jank detection
  • App Startup - Application launch metrics and cold start performance
  • Android Activity/Fragment Lifecycle - Screen transitions and lifecycle events
  • Global Attributes - Service, device, OS, session, and network carrier information included in all telemetry. See Global Attributes for details.

Requires Setup or Configuration​

The following instrumentations require additional setup or configuration:

  • React Native Screen Navigation - Track screen transitions and navigation events. Requires React Navigation setup. See Navigation Instrumentation for setup instructions.
  • Screen Session Instrumentation - Measure time spent on each screen. Requires React Navigation setup. See Navigation Instrumentation for setup instructions.
  • Interaction Instrumentation - Monitor and analyze critical user flows with real-time metrics and insights. Requires Android SDK configuration. See Android Advanced Configuration for setup instructions.
  • Error Boundary - Catch React component rendering errors with fallback UI. Requires wrapping components with Error Boundary. See Error Boundaries for setup instructions.

Verification​

Once initialized, your app will automatically start sending telemetry data to your Pulse backend. With auto-instrumentation enabled, you should immediately see:

  • Network requests (fetch/XMLHttpRequest/axios)
  • Native platform telemetry (App Start, Activity lifecycle events, ANR, frozen frames, etc.)
  • JavaScript and Android crashes

Check your Pulse dashboard to see real-time telemetry from your application.

Advanced Configuration​

The basic initialization above is sufficient for most use cases. However, you can customize the SDK behavior with advanced configuration options.

Enable Specific Instrumentations​

Enable or disable specific instrumentations during Android SDK initialization. For example, to enable interaction instrumentation:

import android.app.Application
import com.pulsereactnativeotel.Pulse

class MainApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    
    Pulse.initialize(
      application = this,
      endpointBaseUrl = "https://your-backend-url.com"
    ) {
      // Enable interaction instrumentation
      interaction {
        enabled(true)
        setConfigUrl { "https://your-backend-url.com/v1/interactions/all-active-interactions/" }
      }
    }
  }
}

Note: Replace the URL in setConfigUrl with your actual backend endpoint URL for interactions configuration. The base path can be customized to match your backend API structure.

Additional Configuration Options​

Configure additional options in the initialize method:

import android.app.Application
import com.pulsereactnativeotel.Pulse
import io.opentelemetry.api.common.Attributes
import io.opentelemetry.api.common.AttributeKey

class MainApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    
    Pulse.initialize(
      application = this,
      endpointBaseUrl = "https://your-backend-url.com",
      // Custom headers for authentication
      endpointHeaders = mapOf(
        "Authorization" to "Bearer your-token",
        "X-API-Key" to "your-api-key"
      ),
      // Global attributes included in all telemetry
      globalAttributes = {
        Attributes.of(
          AttributeKey.stringKey("app.version"), "1.0.0",
          AttributeKey.stringKey("environment"), "production"
        )
      },
      // Disk buffering for offline storage
      diskBuffering = {
        enabled(true)
        maxCacheSize(50 * 1024 * 1024) // 50 MB
      }
    )
  }
}

React Native Configuration​

You can customize auto-instrumentation behavior when calling Pulse.start():

import { Pulse } from '@horizoneng/pulse-react-native';

Pulse.start({
  autoDetectExceptions: true,   // JavaScript error tracking
  autoDetectNetwork: true,      // Network request tracking
  autoDetectNavigation: false   // Disable if not using React Navigation
});

Next Steps​

Now that you have the SDK set up, explore the Instrumentation guides to learn about:

  • Network instrumentation
  • Error instrumentation
  • Navigation instrumentation
  • Custom instrumentation