iOS Quick Start

πŸ“˜

SDK Integration

If you haven't already integrated the SDK with your project, follow one of these guides first, depending on which package manager you are using:

Now that the SDK has been integrated with your project, let's take a look at how to set up Specto in your application and send your first performance metrics.

Setup

The Specto.setUp(APIKey:) function must be called at application launch, in either the application(_:didFinishLaunchingWithOptions:) method, or the application(_:willFinishLaunchingWithOptions:) method. If you are using a crash reporting library, make sure that the Specto setup happens after the crash reporter setup.

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Crash reporter setup should go before Specto.setUp
        Specto.setUp(APIKey: "Insert your API key here")
        // Any other application setup should go after Specto.setUp
        // ...
        return true
    }
}
@implementation AppDelegate

- (BOOL)application:(UIApplication *)application 
didFinishLaunchingWithOptions:(NSDictionary<UIApplicationLaunchOptionsKey, id> *)launchOptions {
    // Crash reporter setup should go before Specto.setUp
    [Specto setUpWithAPIKey:@"Insert your API key here"];
    // Any other application setup should go after Specto.setUp
    // ...
    return YES;
}

@end

If you are using the SwiftUI app lifecycle, you can implement UIApplicationDelegate methods by adding a UIApplicationDelegateAdaptor to your App:

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    ...
}

Finally, you must implement the application(_:handleEventsForBackgroundURLSession:completionHandler:) method to forward background networking completion events to Specto so that we can correctly handle background trace uploads. Specto uses background trace uploads to reduce network usage while users are actively using your app in the foreground.

func application(_: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {
  Specto.handleEventsForBackgroundURLSession(identifier: identifier, completionHandler: completionHandler)
  // Your own handling code
}
- (void)application:(UIApplication *)application 
handleEventsForBackgroundURLSession:(NSString *)identifier 
  completionHandler:(void (^)(void))completionHandler {
    [Specto handleEventsForBackgroundURLSessionWithIdentifier:identifier completionHandler:completionHandler];
    // Your own handling code
}

We will only handle background events from identifiers owned by the Specto framework, so it is safe to call this method even if you have your own background URL sessions. The handling code for your own sessions can be added after the call to Specto.handleEventsForBackgroundURLSession(identifier:completionHandler:).

Tracing App Startup

Setting up your first performance metric is easy: Specto makes measuring & profiling app startup a one liner. From Apple's documentation on app startup:

An app that takes too long to launch may frustrate the user, and the iOS watchdog process may even terminate it if it takes too long to respond. Users may launch an app many times in a day if it’s part of their regular workflow, and a long launch time causes delays for users waiting to perform a task.

Find the point in your app's startup lifecycle where you consider the app startup to be complete β€” this is typically when the initial content has been loaded and fully rendered, but the definition will vary per-application. At this point, call Specto.markAppStartupComplete(). Multiple calls to this method will have no effect, and only the first call will be considered.

❗️

Calling Specto.markAppStartupComplete() is not optional. You must call this method at some point in your app lifecycle. The framework will not allow other traces to start until the startup trace has completed (or timed out), so not calling this method may lead to performance data not being collected correctly.

To confirm that the startup trace was uploaded, open the Traces tab in the dashboard and check that there was a trace with the interaction dev.specto.startup for your current application version:

🚧

Don't see a startup trace?

Check the following:

  1. If this is the first launch of your app since you integrated the Specto SDK, you may have to launch your app a second time. This is because Specto downloads a remote configuration on the first launch that tells the framework whether tracing should be enabled for that device, and this configuration does not take effect for the startup trace until the next launch.
  2. Check that you are calling Specto.markAppStartupComplete()
  3. Check your build logs to ensure that the specto-upload-symbols tool, as covered in the package manager integration documentation, is running during your app build. If you are building the app in Debug mode, make sure that the --allow_debug flag is being passed to specto-upload-symbols (or switch your scheme to build for Release)
  4. Still doesn't work? Contact us!

What’s Next

Add more instrumentation to your codebase by learning about traces and spans: