Objective-C Setup Guide

Lots of iOS and macOS application are still written in Objective-C, or a mixture of Swift and ObjC. We’ve got you covered either way, and this guide will show you how to set up the TelemetryDeck SDK in your Objective-C application.

Installing the package

The TelemetryDeck Swift package uses Swift Package Manager.

1. Open Xcode and navigate to the project you want to add TelemetryDeck to.
2. In the menu, select File -> Add Packages…. This will open the Swift Package Manager view.
3. Paste https://github.com/TelemetryDeck/SwiftClient into the search field.
4. Select the SwiftClient package that appears in the list
5. Set the Dependency Rule to Up to Next Major Version.
6. Click Add Package.

This will include the TelemetryDeck Swift Client into your app by downloading the source code. Feel free to browse the client’s source code. It’s tiny and you’ll see for yourself how TelemetryDeck is hashing user identifiers before they ever reach the server. Privacy, yay!

Including the package in your target

Xcode will ask you to link the package with your target in the next screen, titles Choose Package Products for SwiftClient. Select the TelemetryClient library and click Add Package.

Initializing the TelemetryDeck package

The TelemetryClient package will provide you with a class TelemetryManager that you’ll use for all interactions with TelemetryDeck. Before you can use that class, you’ll need to initialize it at the start of your app. The ideal place for this is your App Delegate’s application:didFinishLaunchingWithOptions: method:

// Import the TelemetryClient library
@import TelemetryClient;

// ...

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Your other initialization code here ...

    // Initialize the TelemetryDeck client
    TelemetryManagerConfiguration *telemetryConfig =
        [[TelemetryManagerConfiguration alloc] initWithAppID:@"YOUR-APP-ID"];
    [TelemetryManager initializeWith:telemetryConfig];

    // Optional: Set a default user ID. If you don't do this,
    // the SDK will generate a random user ID for you.
    // [TelemetryManager updateDefaultUserTo:@"myuserwhojustloggedin@example.com"];

    return YES;
}

Sending signals

Let’s send a signal to show the app has launched correctly.

See the TelemetryDeck package’s README.md file for more information on how to send signals. For now, let’s just send one signal that tells us the app has launched. Go to your app delegate and below the initialization add this line:

[TelemetryManager send:@"applicationDidFinishLaunching"];

We’re done. This is all you need to send a signal. You don’t need to keep an instance of TelemetryManager and hand it around, just call the send function on the class directly. If you want to add custom metadata payload, add it to the function call like as a dictionary.

This is helpful for additional parameters for filtering or grouping signals. We’ll auto add some metadata for you, like the app version, device model, etc.

[
    TelemetryManager
    send:@"applicationDidFinishLaunching"
    with:@{@"pizzaCheeseMode": @"extraCheesy"}
];

And you’re done! You are now sending signals to the TelemetryDeck server (the signals are marked as Testing Signals in the dashboard, switch on Testing Mode to see them).

You’re all set!

You can now send signals! Don’t overdo it in the beginning. It’s okay if you only send one signal, named applicationDidFinishLaunching in the beginning. This will already give you number of users, number of launches, retention… a lot!

After a while, you can add a send call for each screen in your app, so you can see which screens are used most. We also recommend adding all your custom settings to your metadata each time (except the ones that might identify an individual user please). This way you can see which settings most of your users use.