Skip to main content

iOS APIs for React Native

The Pulse React Native SDK on iOS is built on top of the Pulse iOS SDK. This page is for React Native developers who need to call Pulse from native iOS code — in an AppDelegate, a native module, or anything outside the JS bundle.

Using Swift?​

APIs are identical to the iOS SDK . Use PulseSDK wherever the iOS docs show Pulse.shared. Same method names, same parameters.

import PulseReactNativeOtel

// iOS docs show:  Pulse.shared.setUserId("user-1")
PulseSDK.setUserId("user-1")

For everything else — initialize options, instrumentations, consent, user identity, custom spans — follow the iOS API reference and SDK initialization docs directly.

Using Obj-C?​

Only a subset of APIs are available through the Objective-C bridge. The sections below cover every method available through the Objective-C bridge.

Import​

#import <PulseReactNativeOtel-Swift.h>

Initialize​

Call once on the main thread, before the React Native bridge starts.

[PulseSDK pulseInitialize:@"your-api-key"
    dataCollectionState:@"ALLOWED"
       globalAttributes:nil
          configuration:nil
        instrumentations:nil];

Pass nil for any argument you are not customizing.

apiKey​

Project API key. Generate it from Pulse Dashboard

dataCollectionState​

Control how the Pulse iOS SDK collects and exports telemetry, in compliance with GDPR and App Store privacy requirements.

  • @"ALLOWED": SDK fully active — telemetry collected and exported
  • @"PENDING": SDK initialized but paused — telemetry buffered, nothing exported
  • @"DENIED": Terminal — buffer cleared, SDK shuts down. Cannot be undone in the same process.

globalAttributes​

Key/value pairs attached to all telemetry. Uses PulseAttributeValue wrappers (see below).

[PulseSDK pulseInitialize:@"your-api-key"
    dataCollectionState:@"ALLOWED"
       globalAttributes:@{
           @"env": [PulseAttributeValue string:@"production"],
       }
          configuration:nil
        instrumentations:nil];

configuration​

PulseObjcKitConfiguration * — controls which attribute bundles the SDK attaches. Pass nil for defaults.

PulseObjcKitConfiguration *kit = [PulseObjcKitConfiguration new];
kit.includeScreenAttributes  = @YES;
kit.includeNetworkAttributes = @YES;
kit.includeGlobalAttributes  = @YES;

[PulseSDK pulseInitialize:@"your-api-key"
    dataCollectionState:@"ALLOWED"
       globalAttributes:nil
          configuration:kit
        instrumentations:nil];

instrumentations​

Build a PulseObjcInstrumentations instance and pass it as this argument. Omit the argument entirely (nil) or leave properties unset to keep the SDK default for each instrumentation.

PulseObjcInstrumentations *inst = [PulseObjcInstrumentations new];
inst.screenLifecycle = [PulseObjcEnabledConfig disabled];  // common for RN — avoids duplicate screen signals

[PulseSDK pulseInitialize:@"your-api-key"
    dataCollectionState:@"ALLOWED"
       globalAttributes:nil
          configuration:nil
        instrumentations:inst];

For each collector’s shape (PulseObjcEnabledConfig vs richer configs like sessions), see Configuring instrumentations below and SDK initialization — Instrumentations.

Configuring instrumentations​

All instrumentation setup goes on a PulseObjcInstrumentations object passed into pulseInitialize:...:instrumentations:. Omitting a property (or passing nil for instrumentations) keeps the SDK default for that area.

Simple on/off collectors use PulseObjcEnabledConfig. For each property below you can use [PulseObjcEnabledConfig enabled] or [PulseObjcEnabledConfig disabled] — same pattern everywhere.

URL Session​

inst.urlSession = [PulseObjcEnabledConfig enabled];
// or
inst.urlSession = [PulseObjcEnabledConfig disabled];

Crash reporting​

inst.crash = [PulseObjcEnabledConfig enabled];
// or
inst.crash = [PulseObjcEnabledConfig disabled];

Sessions​

Use PulseObjcSessionsConfig for optional lifetime fields when sessions are on:

PulseObjcSessionsConfig *sessions = [PulseObjcSessionsConfig enabled];
sessions.maxLifetimeSeconds = @(1800);
sessions.backgroundInactivityTimeoutSeconds = @(300);
sessions.shouldPersist = @YES;
inst.sessions = sessions;

If your SDK exposes [PulseObjcSessionsConfig disabled] (or equivalent), use that to turn the sessions collector off; otherwise leave inst.sessions unset for SDK defaults.

App lifecycle​

inst.appLifecycle = [PulseObjcEnabledConfig enabled];
// or
inst.appLifecycle = [PulseObjcEnabledConfig disabled];

Screen lifecycle​

inst.screenLifecycle = [PulseObjcEnabledConfig enabled];
// or
inst.screenLifecycle = [PulseObjcEnabledConfig disabled];

App startup​

inst.appStartup = [PulseObjcEnabledConfig enabled];
// or
inst.appStartup = [PulseObjcEnabledConfig disabled];

Interaction​

inst.interaction = [PulseObjcEnabledConfig enabled];
// or
inst.interaction = [PulseObjcEnabledConfig disabled];

Wire it into init:

PulseObjcInstrumentations *inst = [PulseObjcInstrumentations new];
inst.crash = [PulseObjcEnabledConfig enabled];
inst.screenLifecycle = [PulseObjcEnabledConfig disabled];

[PulseSDK pulseInitialize:@"your-api-key"
    dataCollectionState:@"ALLOWED"
       globalAttributes:nil
          configuration:nil
        instrumentations:inst];

PulseAttributeValue​

Used wherever a typed value is needed — global attributes, user properties, event params.

[PulseAttributeValue string:@"value"]
[PulseAttributeValue int:42]
[PulseAttributeValue double:3.14]
[PulseAttributeValue bool:YES]
[PulseAttributeValue stringArray:@[@"a", @"b"]]

Updates data collection state after launch. Values: @"ALLOWED", @"PENDING", @"DENIED".

[PulseSDK pulseSetDataCollectionState:@"ALLOWED"];

See Data collection consent for the full consent flow.

User identity​

Associate telemetry with specific users to enable per-user analysis in the Pulse dashboard.

// Set user ID
[PulseSDK pulseSetUserId:@"user-123"];

// Set a single property
[PulseSDK pulseSetUserProperty:@"plan" value:[PulseAttributeValue string:@"pro"]];

// Replace all user properties at once
[PulseSDK pulseSetUserProperties:@{
    @"plan":   [PulseAttributeValue string:@"pro"],
    @"region": [PulseAttributeValue string:@"us"],
}];

See User identification.

Custom events​

Track business-level interactions, feature usage, and user milestones with named events and arbitrary attributes.

NSTimeInterval ts = [[NSDate date] timeIntervalSince1970] * 1000.0;

[PulseSDK pulseTrackEvent:@"checkout_started"
    observedTimeStampInMs:ts
                   params:@{ @"cart.total": [PulseAttributeValue double:149.99] }];

observedTimeStampInMs is epoch milliseconds.

Non-fatal errors​

// Named non-fatal
[PulseSDK pulseTrackNonFatal:@"payment_failed"
       observedTimeStampInMs:timestampMs
                      params:@{}];

// From an NSError
[PulseSDK pulseTrackNonFatalError:error
          observedTimeStampInMs:timestampMs
                         params:@{ @"context": [PulseAttributeValue string:@"checkout"] }];

Shutdown​

Stops the SDK for this process. Requires a fresh app launch to reinitialize.

BOOL stopped = [PulseSDK shutdown];

Check initialization​

BOOL ready = [PulseSDK pulseIsInitialized];

Not available from Objective-C​

Manual spans (trackSpan / startSpan) and OpenTelemetry access (getOpenTelemetry / getOtelOrThrow) are Swift-only. Two alternatives:

Only writing JS? You still need a native PulseSDK.initialize call before the React Native bridge starts, but everything else can stay on the React Native API reference and RN-specific pages.