Upgrade Guide

Upgrading from iOS 5x SDK to Apple 6x SDK

Summary

Embrace Apple SDK is now configured in your code
Moments have been replaced by Traces
Replace deprecated method calls with new ones
Some features have been deprecated and removed
Some features still have to be migrated

SDK initialization and configuration is triggered in-code

As of version 6.0.0, Embrace Apple SDK no longer uses a .plist file to hold Embrace-specific configuration. Instead, you should set up the SDK in your code.

As close as possible to the launch of your app, you should initialize the SDK with the Embrace client. The various configuration options for the Embrace Apple SDK are set using an Embrace.Options object that you can tailor to your needs.

Here is example SwiftUI App object in which the SDK is configured, and then started:

import EmbraceIO
import SwiftUI

struct NewEmbraceApp: App {
    init() {
        do {
            try Embrace
                .setup(
                    options: Embrace.Options(
                        appId: "12345"
                        logLevel: .default,
                        crashReporter: EmbraceCrashReporter(),
                        // Other configuration options
                    )
                )
                .start()
        } catch let e {
            print("Error starting Embrace \(e.localizedDescription)")
        }
    }
}

For more information about starting the SDK in-code, please read The Embrace Client. For more information on configuration options, please read Configuring the SDK.

Moments have been replaced by Traces

Moments have not been added to the Embrace Apple 6 SDK, and will not be available when upgrading from version 5 to version 6. We made this decision as part of our migration to build on top of OpenTelemetry APIs and to standardize the telemetry coming from our SDKs.

Luckily, Traces serve the same purposes as Moments, with greatly enhanced capabilities. Built on OTel Spans, Performance Traces capture end-to-end journeys made of multiple spans. Traces can contain many spans as "children", as well as attributes and events that offer flexibility on the client and numerous aggregation options on the backend. This instrumentation allows you trace an entire process by breaking it down into smaller units of work.

A span is simply an operation occurring over a period of time. Using spans, you can track how long operations within the app take, and more. Note that, in building on existing OTel APIs, the Embrace Apple SDK does not have instrumentation for an object called a "trace". Instead, a trace is the root span for a given workflow.

Sample usage

Here is an example of how spans and traces replace and enhance the existing Moment feature:

Swift

/* ******************************* */
// Using Moments in Embrace 5.X
Embrace.sharedInstance().startMoment(withName: "add-cart-item")
// Perform add cart logic
Embrace.sharedInstance().endMoment(withName: "add-cart-item")

/* ******************************* */
// Using Traces in Embrace 6.X (shorthand)
Embrace.recordSpan(name: "add-cart-item") { span in
    // perform add cart logic
}

/* ******************************* */
// Using Traces in Embrace 6.x (full)
let span = Embrace.client?.buildSpan(name: "add-cart-item")
                .startSpan()
// Perform add cart logic
span?.end()

Traces can be instrumented in the same places as your Moments. The benefit of Tracing is you can extend a Span by adding parent/child relationships or by adding specific point-in-time "SpanEvents".

Swift

/* ******************************* */
// Tracing in Embrace 6.x
// Create root span
let addCartSpan = Embrace.client?.buildSpan(name: "add-cart-item")
                .startSpan()


// Add SpanEvent
addCartSpan?.addEvent(name: "quantity-changed")

// Add child Span
let addCartUIUpdateSpan = Embrace.client?.buildSpan(name: "add-cart-ui-update")
                            .setParent(addCartSpan)
                            .startSpan()
// Perform UI update logic
addCartUIUpdateSpan.end()

// Perform other add-cart-item logic
addCartSpan?.end()

Replace deprecated method calls with new ones

Unless otherwise noted below, the Apple 6 SDK calls its methods on Embrace.client and iOS 5 SDK calls its methods on Embrace.sharedInstance()

iOS 5	Apple 6	Comments
`.isStarted`	`.started`
`.startWithLaunchOptions`	`.setup(options)` and `.start()`
`.getLastRunEndState`	`.lastRunEndState()`
`.addSessionProperty`	`.metadata.addProperty(key:value:lifespan:)`	Adding a property to a session.
`.removeSessionProperty`	`.metadata.removeProperty(key:lifespan:)`	Remove a property to a session.
`.endSession`	`.endSession`
`.getCurrentSessionId`	`.currentSessionId()`
`.logBreadcrumbWithMessage("this is a crumb")`	`add(event: .breadcrumb("this is a crumb"))`	Breadcrumbs are now SpanEvents on the Session Span
`.startSpanWithName`	`.buildSpan(name:type:attributes:)` and `.startSpan()`
`.stopSpanWithId`	`.buildSpan(name:type:attributes:)` and `.endSpan()`
`.addSpanEventToSpanId`	`.addEvent(name:)` on existing Span
`.addSpanAttributesToSpanId`	`.setAttribute(key:value:)` on existing Span
`.recordCompletedSpanWithName`	`.recordSpan<T>(name:type:attributes:, spanOperation)`
`.logMessage`	`.log(_ message:severity:timestamp:attributes:)`
`.logNetworkRequest`	Not yet available
`.setUserIdentifier`	`.metadata.userIdentifier = "jk12345lol"`
`.clearUserIdentifier`	`.metadata.userIdentifier = nil`
`.setUsername`	`.metadata.userName = "EmBot"`
`.clearUsername`	`.metadata.userName = nil`
`.setUserEmail`	`.metadata.userEmail = "embot@embrace.io"`
`.clearUserEmail`	`.metadata.userEmail = nil`
`.setUserPersona`	`.metadata.add(persona:lifespan:)`
`.setUserAsPayer`	`.metadata.add(persona:lifespan:)`	There're a set of already exposed `PersonaTag` like `.payer`
`.clearUserPersona`	`.metadata.removePersonaTag(value: lifespan:)`
`.clearUserAsPayer`	`.metadata.removePersonaTag(value: lifespan:)`	There're a set of already exposed `PersonaTag` like `.payer`
`.clearAllUserPersonas`	`.metadata.removeAllPersonaTags(lifespans:)`
`.getDeviceId`	`.currentDeviceId()`

Features that have been deprecated and removed

As noted above, Moments have been deprecated and are not available in Embrace Apple 6. Other deprecated features include:

NSURLConnection capture
Screenshots
App disk usage (including free disk space and CPU "spike")
.startView and .endView have been removed. Use spans with the SpanType .ux to record information about your view lifecycles

Features still to be migrated

In upcoming minor versions, you can expect to see familiar features from the iOS 5 SDK. While these are useful and will remain in use, we chose to prioritize migration of important paradigms like Traces and Auto-instrumentation while building on OpenTelemetry signals. Some upcoming features include:

Config Capabilities
- Remote config to disable network capture based on URL regexes
- Local config to disable URLs to capture
- Local config to disable webview capture
- Local config to enable stripping of webview query params
Manually instrumenting network requests
Network body capture
Extension Insights

Upgrading from iOS 5x SDK to Apple 6x SDK​

SDK initialization and configuration is triggered in-code​

Moments have been replaced by Traces​

Sample usage​

Replace deprecated method calls with new ones​

Features that have been deprecated and removed​

Features still to be migrated​