TelemetryDeck's Grand Rename

Motivation

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 like one does, we decided to send a default signal & a bunch of parameters automatically. To keep things simple, we named the signal newSessionBegan and the parameters appVersion and locale, for example.

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 the platform-specific terminology for things, leading to different names in some places. And 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.

Consistency, Longevity, and Clarity

Our main goals with our new naming scheme were to be internally consistent, but at the same time 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 additionally strove for clarity.

The most obvious change was to rename our Swift repository from “SwiftClient” to “SwiftSDK”. Thanks to GitHub’s redirection feature, 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 grouped them as follows:

Signals

• Session: Anything related to starting, pausing, continuing, or ending a user session.

Parameters

• AppInfo: Information about the specific app build, such as version, build number, or SDKs compiled with.
• Device: All about the device running the application, such as operating system, model name, or architecture.
• Metric: Information about app and device performance, such as memory (RAM), battery, or charging status.
• RunContext: The context the app runs in, such as simulator, debug mode, or target environment.
• SDK: Information about the TelemetryDeck SDK, such as its name or version number.
• UserPreference: Any choices the user made to express personal preferences, such as language & region.
• Navigation: Information about how a user is navigating through the app, such as URL paths or view controllers.

Filling the Gaps

While doing the rename, we also noticed some missing variants of parameters that could be useful. So we added the following variants:

• TelemetryDeck.AppInfo.versionAndBuildNumber: Combines the app version and build into one String, such as 1.7.1 (build 22).
• TelemetryDeck.Device.orientation: One of Portrait, Landscape, or Fixed.
• TelemetryDeck.Device.screenResolutionWidth: The resolution width of the screen in pixel/points (whatever is most common on platform).
• TelemetryDeck.Device.screenResolutionHeight: The resolution height of the screen in pixel/points (whatever is most common on platform).
• TelemetryDeck.Device.timeZone: The timezone expressed by the UTC offset, such as UTC+0 (London), UTC+9 (Tokyo), or UTC-8 (San Francisco).
• TelemetryDeck.RunContext.language: The language the app is currently used in (one of the supported languages).
• TelemetryDeck.SDK.name: Just the TelemetryDeck SDK’s name that was used to send the signal, such as SwiftSDK, KotlinSDK, or FlutterSDK.
• TelemetryDeck.SDK.version: Just TelemetryDeck SDK’s version that was used to send the signal, such as 1.5.1.
• TelemetryDeck.UserPreference.region: The regional identifier of the users country setting, e.g. US for United States.
• TelemetryDeck.UserPreference.language: The language most preferred by the user on this device (might not be supported by app).

These could be useful to create even more accurate charts to make better informed data-driven decisions.

Full Migration Table

Here’s a full overview of all the changes we have done:

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.