The Embrace Developer Hub

Welcome to the Embrace documentation. You'll find comprehensive guides and documentation to help you start working with Embrace as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

iOS Quick Integration

Welcome to the iOS SDK! The basic integration is two simple and detailed via the self-service flow. The complete integration is outlined below.

Once completed, verify the success of the integration using the Live Integration feature located in 'Recent Sessions' tab in the dashboard.

Step 1: Initialize the iOS SDK

Add the SDK to your app

The Embrace SDK is available through CocoaPods. (If you do not use CocoaPods, please download the SDK following these instructions.)

Add the Embrace.io pod to your Podfile:
pod 'EmbraceIO'
Don’t forget to run "pod install"!

Initialize the SDK

Initialize the Embrace SDK as early as possible, so we can correctly track crashes, ANRs, OOMs, and termination.

// In `AppDelegate.m`

#import <Embrace/Embrace.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *) launchOptions
{
    // replace with your APP_ID, which is a 5-character value, e.g. "aBc45"
    [[Embrace sharedInstance] startWithKey:@"APP_ID"];

    ...
    return YES;
}
// In `AppDelegate.swift`

import Embrace

func application(_ application: UIApplication, didFinishLaunchingWithOptions 
    launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool 
{
    // replace with your APP_ID, which is a 5-character value, e.g. "aBc45"
    Embrace.sharedInstance().start(withKey: "APP_ID")

    ...
    return true
}

Instantiate the Embrace SDK synchronously, i.e. not on a dispatch_async block. Embrace does most of its processing on async queues, but instantiating synchronously helps us best catch any issues during your app's startup.

If you haven't receive an App ID and API Token, reach out to us via support@embrace.io or on Slack.

Step 2: Crash Reporting and Symbolication

Stacktraces are useful for crashes and logging (error and warning .)

Crash Reporting

Embrace is crash agnostic -- we support both Crashlytics and our own crash reporting solution.
If you use Crashlytics* and prefer to continue to use it, then skip this step. If you'd like to use Embrace for crash reporting, please refer to the Crash Reporting section of these docs.

Crashlytics Migration Information

Google Firebase has acquired Crashlytics (and Fabric.) If you plan to continue to use Crashlytics, we recommend reading the Google migration plan.

Symbolication

By default, stacktraces will only show memory addresses, so they have to be symbolicated to actually become useful. Symbolication will replace the memory addresses with function names, file paths, and line numbers.

To configure DSYM uploads for your build process:

  1. Add a custom Run Script build phase in Xcode.
  2. Navigate to the “Build Phases” tab in your app’s target.
  3. Click the + icon in the upper-left and select “New Run Script Phase”
  4. Within the Run Script, type in the following, replacing APP_ID (5-char string) and API_TOKEN (32-digit hex value) with the values for your application:
    EMBRACE_ID=APP_ID EMBRACE_TOKEN=API_TOKEN "${PODS_ROOT}/EmbraceIO/run.sh"
  5. Build and run your app.

Not seeing dSYMs?

Make sure that the Debug Information Format under the Build Options of the target is set to DWARF with dSYM file.

If you have Bitcode-enabled builds, you may need to download dSYMs from Apple and upload them to our service. Instructions for uploading dSYM archives are available here

Step 3: Define the App Startup

Ensuring that your app is as responsive as possible at Startup is obviously important. Embrace tracks the time it takes to complete and, more importantly, whether the user abandons it.

The Embrace SDK automatically records the startup event once the SDK is initialized. You must explictly tell us when when the Startup ends. Place the following call everywhere a user can interact with the app after startup. Most often you will need to place the end of Startup call at:

  1. The home screen after the splash screen is displayed
  2. Promotions on start of the app
  3. Item pages which are reachable via deep links
// E.g. in `SomeViewController.m`
#import <Embrace/Embrace.h>

- (void)viewDidLoad
{
    ...
    [[Embrace sharedInstance] endAppStartup];
}
// E.g. in `SomeViewController.swift`
import Embrace

override func viewDidLoad() {
    ...
    Embrace.sharedInstance().endAppStartup()
}

For more information and options on implementing startup, go to Define App Startup.

Step 4: Identify your Users

You must identify the user in order to search for the user in the dashboard, associate the user with your own internal data, and link to any third-party integrations, such as Zendesk.

Tag users with one or more identifiers as early as possible in the startup and whenever in the app the identifier may be set; for example, after registering.

[[Embrace sharedInstance] setUserIdentifier:@"123"];
[[Embrace sharedInstance] setUsername:@"max"];
[[Embrace sharedInstance] setUserEmail:@"brian@embrace.io"];
Embrace.sharedInstance().setUserIdentifier("123")
Embrace.sharedInstance().setUsername("max")
Embrace.sharedInstance().setUserEmail("brian@embrace.io")

For more information and options on tagging and untagging users, go to Identify Your Users.

Step 5: Define App Moments

An app Moment - Moment - A section of the app that blocks the user from progressing until it finishes loading, processing, etc. identifies locations in your app where your users may be blocked from an experience; e.g. not able to progress to the next screen. The best example is app Startup, and others include Purchase (from click to accept/reject) and Video start (from click to play.)

Think of Moments as a Start / Stop watch through which Embrace measures time taken, abandonment rates, and other important metrics that affect user experiences. Screenshots and stacktraces are automatically taken to provide additional context.

// Start Moment when user clicks or preceding when an app requests friend list.
[[Embrace sharedInstance] startMomentWithName:@"get_friend_list"];

// End Moment after friend list appears
[[Embrace sharedInstance] endMomentWithName:@"get_friend_list"];
// Start Moment when user clicks or preceding when an app requests friend list.
Embrace.sharedInstance().startMoment(WithName:"get_friend_list");

// End Moment after friend list appears
[[Embrace sharedInstance] endMoment(WithName:"get_friend_list");

You should define at least 3-4 moments in your app that are of utmost importance. We have provided Default Flows for easier integration. Please refer to Purchase Flow, User Registration Flow, Subscription Flow.

Please refer to Define App Moments, for more complex use cases for Moments
1) Examples like ViewController loads and wrapping Network calls
2) Adding optional parameters or for more complex control over behavior

Step 6: Add Error Logging and Breadcrumbs

A well-placed and descriptive log message is the developer's chance to help themselves:

  1. Provides a much clearer view of what's happening on your users' phones within a user session. Context!
  2. Gathers stacktraces and screenshots
  3. Alerts to unusual activity and spikes
  4. Makes user flows visible (Breadcrumbs!)

Add Breadcrumbs, Info, Warning and Error log messages throughout your app for whenever errors and context are expected and visibility is valuable. Think error conditions, events that may precede an error, handled errors, etc. or wherever you might want a screenshot or stacktrace.

// Sample code - note: not all properties are required but are shown here as examples. Stacktraces are sent for all three log types

// Log an error message (Screenshot default:on)
NSString *error = @"checkout_error";
[[Embrace sharedInstance] logMessage:error 
    withSeverity:EMBSeverityError 
    properties:nil
    takeScreenshot: YES];

// Log a warning message  (Screenshot default:on)
NSString *warnng = @"checkout_retry";
[[Embrace sharedInstance] logMessage:warning 
   withSeverity:EMBSeverityWarning
   properties:@{@"foo": @"bar"}
   takeScreenshot: NO];

// Log an info message  (Screenshot default:off)
NSString *info = @"checkout_success";
[[Embrace sharedInstance] logMessage:info 
    withSeverity:EMBSeverityInfo 
    properties:@{@"screen": @"checkout"}
    takeScreenshot: YES];

// Add a breadcrumb to the User Timeline (stacktraces and screenshots not applicable)
[[Embrace sharedInstance] logBreadcrumbWithMessage:
 		@"Your 64-char-or-less message here"];
// Sample code - note: not all properties are required but are shown here as examples. Stacktraces are sent for all three log types

// Log an error message (Screenshot default:on)
Embrace.sharedInstance().logMessage("checkout_error", 
    with: .error, 
   properties: [:], 
   takeScreenshot: true)

// Log a warning message  (Screenshot default:on)
Embrace.sharedInstance().logMessage("checkout_retry",
    with: .warning, 
    properties:["foo": "bar"], 
    takeScreenshot: false)

// Log an info message  (Screenshot default:off)
Embrace.sharedInstance().logMessage("checkout_success", 
    with: .info, 
    properties:["error": "not_found"],
    takeScreenshot: true)
    
// Add a breadcrumb to the User Timeline (stacktraces and screenshots not applicable)
Embrace.sharedInstance().logBreadcrumb(
		withMessage: "Your 64-char-or-less message here")

When to use each type:

  • Errors - exceptions, handled exceptions, and egregious issues on which you'd like to be alerted
  • Warnings - potential errors that do not rise to the same level of an error and for which you may want an alert
  • Info - log info of interest that you'd like to see aggregated across user timelines
  • Breadcrumbs - context to events that will only display on a user timeline and will not be aggregated or alerted

To add optional properties for greater visibility and for best practices, please refer to Add Error Logs and Breadcrumbs.

Verify and Test your integration

While integrating the Embrace SDK, it's extremely easy to verify using the Live Integration feature in the dashboard.

Plug-in your device and see in real-time the messages sent from your application. To successfully use the Live Integration page under Recent Sessions and be connected to Xcode.

When testing, verify the following events are set correctly:

  1. Startup Moment
  2. User Identifier
  3. Log Message (Error, Warning or Info)
  4. Breadcrumbs

Questions?

Contact us at support@embrace.io or on Slack.


iOS Quick Integration


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.