Skip to main content

Expo Setup

Installation​

1. Install Package​

yarn add @dreamhorizonorg/pulse-react-native

2. Configure Plugin​

Add the Pulse plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "@dreamhorizonorg/pulse-react-native",
        {
          "endpointBaseUrl": "https://your-backend-url.com"
        }
      ]
    ]
  }
}

Note: This plugin will modify your MainApplication.kt to initialize Pulse SDK and configure the endpoint base URL to send telemetry data. See Configuration section to configure additional options.

3. Run Prebuild​

Run prebuild to generate native projects and apply the plugin. This may run automatically when you build your app, but run it once after configuration to ensure the plugin is applied:

npx expo prebuild --clean

Note: If you're using expo run:android or EAS Build, prebuild may run automatically. However, it's recommended to run it once after adding the plugin configuration.

4. Initialize SDK​

Initialize the SDK in your app entry point (e.g., App.tsx):

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

Pulse.start();

export default function App() {
  // Your app code
}

5. Run Your App​

# Run on Android
npx expo run:android

Auto-Instrumentation​

With the basic 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 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.

Configuration​

Configure additional options in your plugin configuration:

{
  "expo": {
    "plugins": [
      [
        "@dreamhorizonorg/pulse-react-native",
        {
          "endpointBaseUrl": "https://your-backend-url.com",
          "endpointHeaders": {
            "Authorization": "Bearer your-token",
            "X-API-Key": "your-api-key"
          },
          "globalAttributes": {
            "environment": "production",
            "app.version": "1.0.0"
          },
          "instrumentation": {
            "interaction": {
              "enabled": true,
              "url": "https://your-backend-url.com/v1/interactions/all-active-interactions/"
            },
            "activity": true,
            "network": true,
            "anr": true,
            "crash": true,
            "slowRendering": false,
            "fragment": true
          }
        }
      ]
    ]
  }
}

Configuration Options​

endpointBaseUrl (Required)​

Base URL of your Pulse backend where telemetry data will be sent.

"endpointBaseUrl": "https://your-backend-url.com"

endpointHeaders (Optional)​

Custom HTTP headers for authentication. Add authentication headers for backend requests.

"endpointHeaders": {
  "Authorization": "Bearer your-token",
  "X-API-Key": "your-api-key"
}

globalAttributes (Optional)​

Global attributes included in all telemetry. Supports strings, numbers, booleans, and arrays.

"globalAttributes": {
  "environment": "production",
  "app.version": "1.0.0",
  "releaseChannel": "production"
}

instrumentation (Optional)​

Enable or disable specific instrumentations. All options default to true if not specified. Set to false to disable an instrumentation.

"instrumentation": {
  "interaction": {
    "enabled": true,
    "url": "https://your-backend-url.com/v1/interactions/all-active-interactions/"
  },
  "activity": true,
  "network": true,
  "anr": true,
  "crash": true,
  "slowRendering": false,
  "fragment": true
}

Instrumentation Options:

  • interaction - Monitor user flows with real-time metrics
    • enabled - Enable/disable interaction instrumentation
    • url - URL to fetch interaction configuration
  • activity - Track Android Activity lifecycle events
  • network - Monitor network requests automatically
  • anr - Detect Application Not Responding (ANR) events
  • crash - Capture native Android crashes
  • slowRendering - Detect slow rendering and frozen frames
  • fragment - Track Android Fragment lifecycle events

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.

Next Steps​