Skip to main content

API Reference

All public methods on Pulse.shared.

Initialization​

initialize(...)​

Initializes the SDK. Call once, as early as possible. Subsequent calls in the same process are ignored.

Pulse.shared.initialize(
    endpointBaseUrl: "https://your-backend.com",
    apiKey: "your-api-key"
)

See Configuration for the full parameter list.

setDataCollectionState(_ newState: PulseDataCollectionConsent)​

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

Pulse.shared.setDataCollectionState(.allowed)
Pulse.shared.setDataCollectionState(.denied)

shutdown()​

Permanently shuts down the SDK — flushes pending telemetry, uninstalls instrumentations, clears persisted state. Cannot be reversed in the same process.

Pulse.shared.shutdown()

User Identity​

See User Identification for the full pattern.

setUserId(_ id: String?)​

Pulse.shared.setUserId("usr_12345")
Pulse.shared.setUserId(nil)  // clear on logout

setUserProperty(name:value:)​

Pulse.shared.setUserProperty(name: "user.plan", value: AttributeValue.string("premium"))
Pulse.shared.setUserProperty(name: "user.plan", value: nil)  // clear

setUserProperties(_:)​

Two overloads — dictionary or builder closure:

// Dictionary
Pulse.shared.setUserProperties([
    "user.plan":   AttributeValue.string("premium"),
    "user.region": AttributeValue.string("us-east"),
])

// Builder closure
Pulse.shared.setUserProperties { props in
    props["user.plan"] = AttributeValue.string("premium")
}

Custom Telemetry​

trackEvent(name:observedTimeStampInMs:params:)​

Emits a named custom event.

ParameterTypeDescription
nameStringEvent name
observedTimeStampInMsDoubleEpoch milliseconds
params[String: AttributeValue]Optional attributes
Pulse.shared.trackEvent(
    name: "purchase_completed",
    observedTimeStampInMs: Date().timeIntervalSince1970 * 1000,
    params: [
        "item.id":    AttributeValue.string("sku_123"),
        "item.price": AttributeValue.double(49.99),
        "quantity":   AttributeValue.int(2),
    ]
)

trackNonFatal(name:observedTimeStampInMs:params:)​

Reports a named non-fatal error.

Pulse.shared.trackNonFatal(
    name: "api_timeout",
    observedTimeStampInMs: Int64(Date().timeIntervalSince1970 * 1000),
    params: [
        "endpoint":   AttributeValue.string("/api/feed"),
        "timeout_ms": AttributeValue.int(5000),
    ]
)

trackNonFatal(error:observedTimeStampInMs:params:)​

Reports a Swift Error. Extracts type, message, and stacktrace automatically.

do {
    try riskyOperation()
} catch {
    Pulse.shared.trackNonFatal(
        error: error,
        observedTimeStampInMs: Int64(Date().timeIntervalSince1970 * 1000),
        params: ["context": AttributeValue.string("data_sync")]
    )
}

trackSpan(name:params:action:)​

Wraps a closure in a span. Ends automatically when the closure returns or throws.

let result = Pulse.shared.trackSpan(name: "parse_response") {
    try JSONDecoder().decode(Response.self, from: data)
}

startSpan(name:params:) / span.end()​

For spans with a lifetime that spans call boundaries.

let span = Pulse.shared.startSpan(
    name: "file_upload",
    params: ["file.size_bytes": AttributeValue.int(fileData.count)]
)
defer { span.end() }

try await performUpload(fileData)
warning

Always call span.end(). Leaked spans are flushed on the next export cycle but will have incorrect duration.

OpenTelemetry Access​

getOpenTelemetry() -> OpenTelemetry?​

Returns the underlying OpenTelemetry instance. Returns nil if the SDK is shut down.

if let otel = Pulse.shared.getOpenTelemetry() {
    let tracer = otel.tracerProvider.get(
        instrumentationName: "my-library",
        instrumentationVersion: "1.0.0"
    )
}

getOtelOrThrow() -> OpenTelemetry​

Same as above but crashes with a fatal error if the SDK is shut down or not initialized. Use when you are certain the SDK is active.

Status​

isSDKInitialized() -> Bool​

Returns true if the SDK is initialized and actively collecting.

guard Pulse.shared.isSDKInitialized() else { return }

isShutdown: Bool​

Returns true if shutdown() has been called.