Swift Setup Guide

Prerequisites

This guide assumes you have already created a TelemetryDeck account. If you haven’t yet, please sign up now!

Installing the Swift 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/SwiftSDK into the search field.
4. Select the SwiftSDK package that appears in the list
5. Set the Dependency Rule to Up to Next Major Version
6. Press Add Package to continue

This will include the TelemetryDeck Swift SDK 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, titled Choose Package Products for SwiftSDK. Set the Add to target column to your app target for TelemetryDeck (not “TelemetryClient”, which is deprecated) and click Add Package to complete the integration.

Initializing the TelemetryDeck Swift Package

The TelemetryDeck package will provide you with a class TelemetryDeck 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. We strongly recommend doing so as soon as possible, as you won’t be able to send Signals before the TelemetryDeck is initialized.

This is slightly different depending on whether you use SwiftUI or UIKit’s AppDelegate to manage your app’s lifecycle, so let’s look at these individually.

You only need one way of initializing the TelemetryDeck SDK, either SwiftUI/SceneKit or AppDelegate. If your app is new, you’ll likely want to use SwiftUI/SceneKit.

Initialization with SwiftUI

For Scene-based SwiftUI applications, we recommend adding the initialization to your @main App struct! Open YourAppNameApp.swift and look for code that looks like this:

import SwiftUI

@main
struct YourAppNameApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

This is the entry point to your app. Now let’s add the initialization here.

Import the TelemetryDeck Package by adding import TelemetryDeck. Then add an init() method to your App struct that creates a TelemetryDeck.Config instance and hands it to TelemetryDeck.initialize(config:), using the Unique Identifier of your app that you copied into your clipboard earlier. If you don’t have that anymore, you can get it at any time from the TelemetryDeck Dashboard.

Your code should now look like this:

import SwiftUI
import TelemetryDeck

@main
struct YourAppNameApp: App {
    init() {
        let config = TelemetryDeck.Config(appID: "YOUR-APP-ID")
        TelemetryDeck.initialize(config: config)
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

If you prefer to have it on a single line, you can also write:

TelemetryDeck.initialize(config: .init(appID: "YOUR-APP-ID"))

Your app is now ready to use TelemetryDeck. You can skip the next section which explains setup for UIKit-based apps.

Initialization in an AppDelegate based app

If you use AppDelegate to manage your app’s life cycle, open the file AppDelegate.swift and look for the method application(:didFinishLaunchingWithOptions:). It will probably look similar to this:

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        return true
    }

    // ...
}

By default, Xcode even adds a comment here to tell you where to add stuff that should happen right after launch.

Now, import the TelemetryDeck package and configure the TelemetryDeck using the Unique Identifier of your app that you copied into your clipboard earlier. If you don’t have that anymore you can get it at any time from the TelemetryDeck Dashboard.

import UIKit
import TelemetryDeck

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        let config = TelemetryDeck.Config(appID: "YOUR-APP-ID")
        TelemetryDeck.initialize(config: config)

        return true
    }
    // ...
}

You are now ready to send signals!

Sending signals

Let’s send a signal to show that something has happened in your app.

The default way to set a user identifier is TelemetryDeck.updateDefaultUserID. This way you only have to set it once, or when it changes, such as user login. See the TelemetryDeck SDK’s README.md file for more information on how to send signals.

Let’s imaging your app is a pizza oven monitor and we want to send a signal that tells us the user has tapped the “Start Baking” button. Go to the place in your code where the user taps the button and add the following code:

TelemetryDeck.signal("Oven.Bake.startBaking")

And done. This is all you need to send a signal. You do not need to keep an instance of TelemetryDeck and hand it around, just call the static signal function on the class directly. If you want to add a custom parameters, add them to the function call like this:

TelemetryDeck.signal(
    "Oven.Bake.startBaking",
    parameters: [
        "numberOfTimesPizzaModeHasActivated": "\(dataStore.pizzaMode.count)",
        "pizzaCheeseMode": "\(dataStore.pizzaCheeseMode)"
    ]
)

And you’re done! You are now sending signals to the TelemetryDeck server. 🎉

Run your app and confirm that your first signal arrived in the “Recent Signals” tab on TelemetryDeck. Don’t forget to turn on “Test Mode” to see signals sent in debug builds!

Configuring Default Signal Properties (Optional)

When initializing TelemetryDeck, you can configure some defaults to help keep your signals organized and consistent:

let config = TelemetryDeck.Config(appID: "YOUR-APP-ID")

// Add a prefix to all signal names
config.defaultSignalPrefix = "App."
// With this set, calling signal("launched") will actually send "App.launched"

// Add a prefix to all parameter names
config.defaultParameterPrefix = "MyApp."
// This prefixes all keys in your parameters dictionary

// Set parameters that will be included with every signal
config.defaultParameters = {[
    "theme": UserDefaults.standard.string(forKey: "theme") ?? "default",
    "isPayingUser": FreemiumKit.shared.hasPurchased ? "true" : "false",
]}
// These parameters will be merged with any additional parameters you specify in signal() calls

Fill out Apple’s app privacy details

Something you need to do before you can upload your app to the App Store is going through Apple’s privacy details on App Store Connect. This informs your users about what data is collected, and how it is collected.

Although TelemetryDeck is privacy friendly, as we only handle not personally identifiable information, you still need to click through the privacy details.

We have a handy guide where we go over each step that is required.

Privacy Policy and Opt-Out

You don’t need to update your privacy policy, but we recommend you do it anyway.

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 App.launched. This will already give you number of users, number of launches, system versions, retention, and more!

After a while, you can add a signal for each screen in your app, so you can see which screens your users use most. It’s also recommended to add all your custom settings to your metadata each time. This way you can see which settings most of your users use.