Skip to main content

API Reference

All public methods on the Pulse object from @dreamhorizonorg/pulse-react-native.

Initialization​

Pulse.start(options?)​

Enables JS-layer instrumentation. Call once in your app entry point after native initialization.

Pulse.start({
    autoDetectExceptions: true,
    autoDetectNetwork:    true,
    autoDetectNavigation: true,
    networkHeaders: {
        requestHeaders:  ['x-request-id'],
        responseHeaders: ['x-response-time'],
    },
});

See Configuration for the full option reference.

Pulse.isInitialized()​

Returns boolean — true if the SDK is initialized.

if (Pulse.isInitialized()) { ... }

Pulse.setDataCollectionState(state)​

Updates consent state at runtime. See Data Collection Consent for valid transitions.

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

Pulse.setDataCollectionState(PulseDataCollectionConsent.ALLOWED);
Pulse.setDataCollectionState(PulseDataCollectionConsent.DENIED);

Pulse.shutdown()​

Permanently shuts down the JS layer. Cannot be reversed in the same process.

Pulse.shutdown();

Pulse.useNavigationTracking(ref, options?)​

React hook — connects Pulse to a React Navigation NavigationContainer. Returns an onReady callback.

const onReady = Pulse.useNavigationTracking(navigationRef, {
    screenSessionTracking:     true,   // default: on
    screenNavigationTracking:  true,   // default: on
    screenInteractiveTracking: false,  // default: off
});

<NavigationContainer ref={navigationRef} onReady={onReady}>

Pulse.markContentReady()​

Ends the screen_interactive span for the current screen. Call when meaningful content has loaded.

Pulse.markContentReady();

See Navigation Instrumentation.

User Identity​

See User Identification for the full pattern.

Pulse.setUserId(id)​

Pulse.setUserId('usr_12345');
Pulse.setUserId(null);  // clear on logout

Pulse.setUserProperty(name, value)​

Pulse.setUserProperty('plan', 'premium');
Pulse.setUserProperty('plan', null);  // remove

Pulse.setUserProperties(properties)​

Pulse.setUserProperties({
    plan:   'premium',
    region: 'us-west',
    verified: true,
});

Custom Telemetry​

Pulse.trackEvent(name, attributes?)​

Emits a named custom event. See Custom Events.

Pulse.trackEvent('purchase_completed', {
    product_id: 'SKU-123',
    price:      49.99,
});

Pulse.reportException(error, isFatal?, attributes?)​

Reports a caught error. See Error Instrumentation.

try {
    await riskyOperation();
} catch (error) {
    Pulse.reportException(error, false, { context: 'checkout' });
}

Pulse.trackSpan(name, options?, action)​

Wraps a function in a span — ends automatically when the function returns or throws. See Custom Spans.

const result = await Pulse.trackSpan('fetch_users', {}, () => api.fetchUsers());

Pulse.startSpan(name, options?)​

Starts a span manually and returns a span object to end later.

const span = Pulse.startSpan('file_upload', {
    attributes: { size_bytes: fileData.length },
});

try {
    await performUpload(fileData);
    span.end(SpanStatusCode.OK);
} catch (error) {
    span.recordException(error);
    span.end(SpanStatusCode.ERROR);
}
warning

Always call span.end(). Leaked spans are flushed eventually but will have incorrect duration.

Global Attributes​

Pulse.setGlobalAttribute(key, value)​

Attaches a key/value pair to all subsequent telemetry. See Global Attributes.

Supported types: string, number, boolean, and arrays of these.

Pulse.setGlobalAttribute('environment', 'production');
Pulse.setGlobalAttribute('feature_flags', ['dark_mode', 'new_checkout']);

Error Boundaries​

<Pulse.ErrorBoundary>​

React component that catches rendering errors and reports them.

<Pulse.ErrorBoundary fallback={<Text>Something went wrong</Text>}>
    <YourComponent />
</Pulse.ErrorBoundary>

Pulse.withErrorBoundary(Component, options)​

HOC variant.

const SafeComponent = Pulse.withErrorBoundary(UserProfile, {
    fallback: <Text>Profile failed to load</Text>,
});

See Error Boundaries.