Embrace.io iOS SDK

Welcome to the iOS SDK! Embrace.io helps you monitor the performance and stability of your mobile apps and keep your users happy. We provide unmatched visibility into the experiences your users are having, and give you the information and insights you need to maximize the performance of your app.

The purpose of this guide is to help you quickly get started with the Embrace.io SDK and begin sending data from your app.

Get Started

1. Installing the Embrace.io SDK
2. Monitoring the performance of your app startup
3. Identifying your users
4. Logging error messages

To send additional context and information and get even more out of the Embrace.io dashboard, check out our documentation site.

Have questions? Contact us on Slack or at [email protected].

Installation

The Embrace.io SDK is available through CocoaPods. Add the following line to your Podfile.

pod 'EmbraceIO'

Initialization

You initialize Embrace.io by calling startWithKey: from within your AppDelegate, passing in your provided API key. We strongly recommend that you place the Embrace initialization call on the first line of your application:didFinishLaunchingWithOptions callback. This ensures the most accurate reporting time for your application's startup process, and allows Embrace to begin instantly monitoring other SDKs that your app initializes throughout the rest of its lifecycle.

Please 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.

Initializing the Embrace.io SDK is also what triggers the beginning of the startup event.

Objective-C

in AppDelegate.m

#import <Embrace/Embrace.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
	[[Embrace sharedInstance] startWithKey:<YOUR-API-KEY>];
	
	...
	
	return YES;
}

Swift

in AppDelegate.swift

import Embrace

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    Embrace.sharedInstance().start(withKey: <YOUR-API-KEY>)
    
    ...
    
    return true
}

Ending App Startup

The Embrace.io SDK automatically begins recording the startup event once it's intialized, so the next step is to inform the SDK that app startup is complete. Where you put this call is entirely dependent on the structure of your app — common use cases are once a user's home feed is loaded, a sign-in screen is displayed, or more generally the instant before the first screen becomes interactive.

If you have more than one location in your app where startup could end, such as in a push notification handler or various screens for logged in/logged out users, it's okay to add multiple endAppStartup calls. This ensures that you don't see erroneous failed startups on your dashboard in the event that a code path is followed where the startup is not ended.

Objective-C

E.g. in SomeViewController.m

#import <Embrace/Embrace.h>

- (void)viewDidLoad
{
	...
	
	[[Embrace sharedInstance] endAppStartup];
}

Swift

E.g. in SomeViewController.swift

import Embrace

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

Boom. Your app is now sending data for the startup event, as well as monitoring for CPU, memory, and networking issues over the course of the user's session.

Identifying Users

The Embrace.io SDK allows you to add identifiers to the current user so that you can associate them with your own internal data and also perform searches and segmentation in the web dashboard.

Custom Identifiers

You can set an identifier, username, or email on any user via the setUserIdentifier:, setUsername:, and setUserEmail: functions.

Objective-C

[[Embrace sharedInstance] setUserIdentifier:@"123"];
[[Embrace sharedInstance] setUsername:@"max"];
[[Embrace sharedInstance] setUserEmail:@"[email protected]"];

Swift

Embrace.sharedInstance().setUserIdentifier("123")
Embrace.sharedInstance().setUsername("max")
Embrace.sharedInstance().setUserEmail("[email protected]")

These attributes can be reset later with calls to clearUserIdentifier, clearUsername, and clearUserEmail.

Logging Errors and Info Messages

When you want visibility into something instantaneous that happens in your application, you can send info or error messages to Embrace.io for insight into what was happening to the user.

These messages contain diagnostic information, the current thread's stack trace, and any custom properties that you specify. Error messages also capture screenshots so that you can see what the device was displaying at the moment of the error. (Screenshots can be enabled/disabled via a method parameter.)

Logging Messages

Error messages are triggered with a call to logErrorMessage:screenshot:properties:, where the message is a string that can be searched for later in the web dashboard, and properties is an optional dictionary of (maximum 10) properties. screenshot determines whether a screenshot should be taken at the moment of the log.

Info messages can be sent with a call to logInfoMessage:properties:, with the same message and properties parameters as the error logs.

Objective-C

// Log an error message
NSString *error = @"checkout_error";
[[Embrace sharedInstance] logErrorMessage:logMessage screenshot:YES properties:nil];
// Log an info message
NSString *info = @"something_happened";
[[Embrace sharedInstance] logInfoMessage:info properties:@{@"screen": @"checkout"}];

Swift

// Log an error message
Embrace.sharedInstance().logErrorMessage("something_bad", screenshot: true, properties: [:])
// Log an info message
Embrace.sharedInstance().logInfoMessage("something_happened", properties: ["error": "not_found"])

​ The info and error messages will be grouped and displayed on the main page of the Embrace.io dashboard.

Additional Features

Check out our documentation site to see instructions for

• Logging app moments (measuring the time duration of various interactions or features)
• Adding enhanced networking monitoring
• Tagging users with personas for segmentation
• Uploading DSYM files to show more information in stack traces

Support

Issues or questions? Contact us on Slack or at [email protected].