Configuration

Complete reference for all Pulse.shared.initialize(...) parameters. If you just need a quick working setup, see Installation.

note

The SDK ignores subsequent initialize() calls. Call it once, as early as possible.

---

Required

Parameter	Description
apiKey	Project API key
dataCollectionState	Initial consent — .allowed, .pending, or .denied (see Data Collection Consent)

---

Telemetry Enrichment

globalAttributes

Key/value pairs attached to every span and log. Supported types: .string, .int, .double, .bool, and array variants.

globalAttributes: [
    "environment": AttributeValue.string("production"),
    "app.version": AttributeValue.string("2.1.0"),
]

See Global Attributes for the full list of what the SDK auto-attaches alongside your values.

resource

Override OpenTelemetry resource attributes (device model, OS, service name). Your values win over SDK defaults.

resource: { attributes in
    attributes["service.name"] = .string("MyApp-iOS")
    attributes["deployment.environment"] = .string("staging")
}

---

SDK Behavior

configuration

Controls which attribute groups are injected into every span and log. All are on by default.

Method	When called
disableScreenAttributes()	Stop injecting screen.name
disableNetworkAttributes()	Stop injecting network.connection.type / subtype
disableGlobalAttributes()	Stop injecting your custom globalAttributes

configuration: { config in
    config.disableScreenAttributes()  // don't inject screen.name into every signal
}

dataCollectionState

Value	Behavior
.allowed	Telemetry collected and exported
.pending	SDK starts normally; export is gated until you call setDataCollectionState(.allowed)
.denied	Full SDK startup is skipped for this process — nothing is collected (see Data Collection Consent)

Pulse.shared.initialize(
    apiKey: "your-api-key",
    dataCollectionState: .pending  // wait for user consent before exporting
)

Use .pending to gate export behind a user consent prompt. See Data Collection Consent.

---

Instrumentations

instrumentations — the closure passed to initialize() that toggles and configures each built-in telemetry collector (URLSession, crashes, screens, sessions, and so on). Each area has a dedicated guide below.

On by default:

Instrumentation	DSL key	Guide
URLSession	urlSession { }	Network
Crash reporting	crash { }	Crashes
Screen lifecycle	screenLifecycle { }	Screen Lifecycle
Session management	sessions { }	Sessions
App startup timing	appStartup { }	App Startup
App lifecycle events	appLifecycle { }	App Lifecycle
User flow tracking	interaction { }	Interaction

Needs extra setup:

Instrumentation	What's needed	Guide
Session replay	Enable from Pulse Dashboard	Session Replay
UIKit tap	Enable from Pulse Dashboard	UIKit Tap
Geo attributes	ACCESS_COARSE_LOCATION permission	Location

Use the instrumentations block to disable or configure any default instrumentation:

instrumentations: { config in
    // disable a default instrumentation
    config.crash { $0.enabled(false) }
}

Each instrumentation has its own guide with all available options linked in the table above.

---

Before-Send Callbacks

Inspect, modify, or drop any signal before it is exported. Return nil to drop.

Parameter	Signature	Use
beforeSendSpan	(ReadableSpan) -> ReadableSpan?	Filter or annotate spans
beforeSendLog	(ReadableLogRecord) -> ReadableLogRecord?	Filter or annotate logs
beforeSendMetric	(MetricData) -> MetricData?	Filter metrics

beforeSendSpan: { span in
    span.name.contains("/health") ? nil : span  // drop health-check spans
},
beforeSendLog: { log in
    log.attributes["log.level"]?.description == "debug" ? nil : log
}

---

Advanced OpenTelemetry

Direct access to the OTel pipeline for custom processors or exporters:

tracerProviderCustomizer: { builder in
    builder.add(spanProcessor: MyCustomSpanProcessor())
    return builder
},
loggerProviderCustomizer: { processors in
    [MyCustomLogProcessor()] + processors  // prepend before Pulse's own processors
}

---

Remote Config

The SDK fetches a server-side config from your Pulse backend on every launch — in the background, non-blocking. The fetched config is persisted on device and applied on the next launch, so mid-session behavior stays consistent.

Everything below can be changed from the Pulse dashboard without shipping an app update:

• Enable or disable instrumentations — turn crash reporting, network, session replay, tap tracking, or interaction on/off
• Set a default sampling rate — e.g. collect telemetry from 10% of all sessions globally
• Rule-based sampling — override the default rate for specific OS versions, app versions, countries or platforms (e.g. 100% sampling on iOS 16, 10% on all others)
• Drop attributes — remove sensitive or noisy attributes from all matching signals without touching app code
• Add attributes — inject computed or static key/value pairs into matching signals

note

First launch: Pulse.shared.initialize() defaults apply (including instrumentations). After that: config saved from a previous launch is used on the next launch. Settings → SDK Configuration shows which instrumentations and features are on.

---

Shutdown

Permanently shuts down the SDK. All subsequent API calls are no-ops and cannot be reversed in the same process.

Pulse.shared.shutdown()

Uninstalls all instrumentations and swizzles, flushes and shuts down processors, deletes persisted telemetry, and clears session data from UserDefaults.

---

Advanced

logLevel

For debugging and troubleshooting only. The SDK is silent by default (.none) and should stay that way in production — logs may include internal URLs, session identifiers, and config details.

Pulse.shared.initialize(
    apiKey: "your-api-key",
    dataCollectionState: .allowed,
    logLevel: .debug  // dev only — remove before release
)

All logs tagged PulseSDK.

Level	What you see
.verbose	Internal event matching, render paths, replay payloads
.debug	Export latency, config fetch results, feature toggles
.info	Session start/end, SDK init, consent changes
.warn	Export failures, recoverable errors
.error	Unrecoverable errors
.none	Silent — default

warning

Never ship with logLevel set to anything other than .none. Gate it behind a debug flag if you want it on automatically in debug builds:

#if DEBUG
    logLevel: .debug
#endif

---

Next Steps

Now that the SDK is configured, explore what you can do with it:

I want to…	Go to
Configure a specific instrumentation	Instrumentation guides
Track business events	Custom Events
Report handled errors	Error Tracking
Measure operation durations	Custom Spans
Attach user identity to telemetry	User Identification
Add global metadata to all signals	Global Attributes
Gate collection behind consent	Data Collection Consent
Browse all public methods	API Reference
Upload symbol file	Upload Symbols