SwiftSDK 2.0

We're releasing version 2.0 of our Swift SDK today, with updates to other SDKs to follow. You don't need to update right away, but when you do, you'll get better scoped signal data!

For example, previously we sent the system version in a payload key named majorSystemVersion. Now we're additionally sending it as TelemetryDeck.Device.systemMajorVersion. This helps prevent collisions, improves sorting, and makes it clearer what's being sent.

We'll be sending both names at the same time for a long time to make the transition as smooth as possible.

Why are we doing this?

When we started TelemetryDeck, it was clearly scoped to the iOS platform and we naturally started with a Swift client first. To get to speed quickly, we decided to send a default signal and a bunch of parameters automatically. To keep things simple, we named the signal newSessionBegan and the parameters appVersion and locale, for example.

But over time, we added more and more SDKs and now we have 5, but only 4 of them are also called “SDK”: The initial Swift client was simply called “SwiftClient”. We also used platform-specific names for signal types and payload keys, leading to different names in some places.

In the meantime we also learned the power of grouping signal names and event parameters as documented in our naming guideline.

Because we sort everything alphabetically in our UI, it’s a natural help in finding things more quickly if related things have the same prefix. Also, users could accidentally use the same signal or parameter name and override ours, causing confusion in the insight data.

After more than 3 years working on TelemetryDeck, we think it’s about time to streamline things for a more clear long-term future.

Do I need to act right now?

You don't need to do anything right now. And you're not losing data, even if you upgrade right now.

To make sure these changes don’t affect existing customers with existing insights anytime soon, we decided to keep sending the old names for a transition period of at least 1 year while also sending the new ones. We recommend using the new ones for any new insights you create and will elaborate ways to support our users in transitioning any existing insights before we fully migrate.

What's changing?

Our main goals with our new naming scheme were to be internally consistent, but at the same time to make sure the names are abstract enough to work flexibly for changes to come in the foreseeable future. Too abstract names can be confusing and cumbersome, so we've additionally strived for clarity.

The most obvious change was to rename our Swift repository from “SwiftClient” to “SwiftSDK”. Thanks to GitHub redirections, this change should have no effect on our existing customers, but long term, it should make things more consistent. 🎉

For our signals & parameters, we decided to prefix them with TelemetryDeck to make the source clear and avoid ambiguity. Additionally, we analyzed all the signals and parameters we currently send and some future ones we have in our roadmap and namespaced them – for example, all SDK related info is now prefixed SDK.

See our Grand Rename article for a list of all new namespaces.

We also renamed these APIs to be more clear:

1. TelemetryManager.send("A", with: ["a": "b"]) is now TelemetryDeck.signal("A", parameters: ["a": "b"])
2. TelemetryManager.initialize(with:) is now TelemetryDeck.initialize(config:)
3. The optional for parameter to override the user ID was renamed to customUserID to be more clear.

Xcode should automatically prompt you to change occurrences of the old APIs in to the new ones.

How to update

To update to the new version of TelemetryDeck's Swift SDK, you'll need to manually set the major Version number to 2.0.0 in your Xcode project or Swift Package file.

Thank you

We hope you like these changes as much as we do! While we did our best to not affect any data, we might have missed something, so please contact us if you run into any issues.