Add new Grand Rename article explaining why and how it's done

[Jeehut]

@winsmith These are my renaming suggestions. If approved, I can create pull requests on all mobile SDKs that apply them. I would also go through other docs and adjust references accordingly once approved, I only adjusted one article so far.

TODOs that still need to be discussed or are out of my scope are:

• Renaming the SwiftClient to Swift SDK on GitHub. (As long as you don't create a new repo with the old name, GitHub will redirect to the new name automatically.)
• I marked all the Android lifecycle signals as "Deleted" assuming they would get deleted. Maybe I should even remove them from the list here, but they are currently there, so I added them so we can discuss.

[winsmith]

I like these a lot, individual thoughts follow.

• This is indeed the perfect time to also rename the Swift Client to Swift SDK.
• operatingSystem and platform – I think there is some history here, but
• Regarding these namespaced entries, we also have TelemetryDeck.Presets.Onboarding.step. Should Presets also be a namespace, or do you want to rename that to something else?
• Can you please note which entries should not be strings? If we're sending floats or ints (which is very advisable in some cases) , I'll need to tell the server in advance.
• I very much like the idea of running old and new signal parameters in parallel for a year. We can then also warn users to migrate off older versions of the SDK using a banner or something.

[winsmith]

Add this point please

• Metrics: Information about app and device performance

[Jeehut]

@winsmith In 5070788 I added:

Metric: Information about app and device performance, such as memory (RAM), battery, or charging status.

Wasn't sure what examples to put there as we don't have any metrics yet (I'm assuming they are planned soon). Let me know if I misunderstood or just Resolve Conversation if it looks good.

[winsmith]

We don't need that information in the SDK, because it can be derived from the modelName. To do that, we use Druid's lookups, and we feed them with this data.

[Jeehut]

Where do you use Druid's lookups? Can users easily use the device type as well? I can't find any field here:

Even if that was possible, I feel like doing such a device type lookup afterwards seems overkill to me and requires regular updates of the library. At least on all Apple platforms, getting the device type is super easy so the SDK could do it. Haven't checked for Android though, maybe it's harder there...

[winsmith]

Touché, lookups can't be set via the visual editor yet. But I think that should be an easy addition.

[Jeehut]

I removed the Device.type parameter now from the document in b055c42 and I created https://github.com/TelemetryDeck/web/issues/1620 so we don't forget to add the parameter via Druid lookups to the visual editor, like you had suggested (as it's probably an easy addition).

Please mark as Resolved if it looks good now.

[winsmith]

Can't we derive that form TelemetryDeck.SDK.version?

[Jeehut]

Yes, we could derive that, I'm just not an expert in that and can't tell how easy it is to write logic in requests or how scalable it is, you're the expert there. I was also just trying to come up with more useful stuff that we could put under the SDK group name because there was only version for now, but I guess this is not needed then…

[winsmith]

Lookups 😍 lookups everywhere!

[winsmith]

Oh and speaking of stuff we can put under the SDK namespace:

TelemetryDeck.SDK.version could be just the version string, with a separate parameter for the SDK ... platform, like TelemetryDeck.SDK.platform. Not sure if platform is the correct naming here, do you have better suggestions?

{
  "TelemetryDeck.SDK.version": "2.0.0",
  "TelemetryDeck.SDK.platform": "SwiftSDK"
}

[Jeehut]

I think TelemetryDeck.SDK.platform is quite good, only alternative that comes to my mind is TelemetryDeck.SDK.framework if you want to avoid platform.

[Jeehut]

On second thought platform doesn't seem quite right given that most SDKs are named by programming languages. If we go by Platform, the Kotlin SDK should be renamed to AndroidSDK and the Swift one to AppleSDK, for example. But I think platform is too easy to misunderstand and confuse with TelemetryDeck.Device.platform, so we should avoid it.

For SwiftSDK / KotlinSDK / FlutterSDK, we could use language, variant, type, id, or simply name. I chatted a bit with ChatGPT and we figured name is probably the most flexible and clear one. Let me know if you disagree, I don't have a strong feeling about the naming here.

[Jeehut]

I just split the old telemetryClientVersion up to TelemetryDeck.SDK.name and TelemetryDeck.SDK.version, but for compatibility reasons I kept the old style and renamed that to TelemetryDeck.SDK.nameAndVersion. See 1f2f3a5. Please mark as Resolved if it looks good now.

[winsmith]

Please use "we" instead of "I"

[Jeehut]

I will make the adjustment and also do a quick search for other places where "I" is used. If "I" is used here, it might be in other places, too.

[Jeehut]

I replaced all uses of 'I' with 'We' where it referred to the author in 1c80966. Please mark as Resolved if it looks good now.

[winsmith]

I'd suggest not promising auto-migration right now. Instead, let's promise that existing SDKs (we might call it SwiftSDK 2.0.0) will send new and deprecated parameters, but SwiftSDK 3.0.0 will drop the deprecated parameters when we release it in a year.

In the coming year, we can then present a sort of "Migration Wizard" that will try to automatically update filters when it runs, and also list GroupBy Queries and similar insights that might need to be manually updated.

We can either run this Wizard on the server in the background, if we're sure we can auto-migrate everything, or we can run it on the frontend with user interaction if we think some user consent is required.

[kkostov]

I can imagine some folks may ask if sending both signal types would also mean they'd be billed as two signals?

Not sure how the TD backend works, so I'm thinking why task the client with the migration? Perhaps we could find a way to make it so existing apps don't have to migrate right away but new apps can adopt the new signal types. And then v3 will no longer allow sending deprecated signal types.

For example, in v2.0, we extend the configuration object with a boolean parameter like TelemetryDeck.useModernSignalTypes set to false by default. This will be included in the additional payload which the server can use to rename the parameters during ingestion.

Users are welcome to set this to true in order to adopt the new signal types early during v2 (e.g. for new apps). When v3 is launched, the value is set to true and can no longer be overwritten.

[Jeehut]

Alright, I will make the adjustment, seems like a good approach as well! 👍

Maybe there won't be many affected when you consider to deprecate in 3.0 and just showing a warning when old fields are used could be enough for those few users left with old insights.

[Jeehut]

By the way, if you want to make a major new release of the SDK for this rename, I would change my opinion on the scope of this PR and include the consistency of the calls across all SDKs. My main problem with them is that in the docs, we don't have the option to write the correct calls for every SDK, so we have to pick one. But if the APIs all were named consistently, we could simply write one piece of code in the docs, and the other platforms would look very similar if not exactly the same.

I just had a great discussion with @kkostov on Discord (we happened to meet today in the channel!) and we agreed that for Swift, Kotlin, and Flutter renaming TelemetryManager.send(:with:) to TelemetryDeck.signal(:parameters:) and additionally streamlining also the requestImmediateSync() approach introduced in TelemetryDeck/SwiftSDK#136 (rather than having two separate functions in Android) would be better. We also thought about TelemetryDeck.record(signal:parameters:) if you prefer that.

We would also check if the initialization code has differently named APIs and adjust that, too. It should be totally possible to make these renaming changes without breaking existing code (via overloads and maybe deprecations).

What do you think? @winsmith @timidak

[Jeehut]

@kkostov Oh, I'm just seeing your comment now, it seems we were writing at the same time and GitHub didn't indicate in any way that there was a new comment when I sent mine.

I did think about your approach, but firstly the duplicate parameters won't count as a new signal, so users shouldn't be concerned. The one extra signal we will send for the TelemetryDeck.Session.started on app start shouldn't make a big difference as most apps send multiple signals during a session and the percentage of one extra signal per session becomes relatively low.

If anything, I would suggest that we give users the option to opt-out of the deprecated calls and exclusively send the new ones. Users just need to make sure they update their insights to the new ones if they have any in those cases and then they wouldn't have any additional signals. But like I said above, I'm not even sure if this is necessary. If we were to migrate all the Android lifecycle events over, then you would be right, but I'm assuming they are going to get removed soon (maybe alongside the 2.0 migration?). I can imagine they produce a lot of signals, like each time a user looks up something to answer the questions in my crossword puzzle game and and return to the app, it's at least 2 signals for every lookup which can lead to >100 signals per user per puzzle.

[Jeehut]

@winsmith If the only reason we were using a queue on mobile devices is to reduce battery drain, then I shouldn't have bothered to write the logic for requestImmediateSync() and just made it a simple syncImmediately(). I really thought it's about server load. 😅

[kkostov]

The verb for sending a signal is signal

So just to be clear @winsmith @Jeehut, the Grand Rename will result in dropping send method and repurposing queue as signal to provide the same functionality (appending signals to the cache), correct?

Note: In the Kotlin SDK the existing queue method drops signals older than 24h. The mindset at the time was that "important, don't drop it" signals would go out using send and others using queue.

Note2: The Flutter SDK exports a send method which routes to send on iOS and queue on Android.

[Jeehut]

So just to be clear @winsmith @Jeehut, the Grand Rename will result in dropping send method and repurposing queue as signal to provide the same functionality (appending signals to the cache), correct?

"Dropping" sounds like an immediate breaking change, but it's correct in general. In the Swift SDK I'm keeping all existing methods and just mark them as deprecated while they'll continue to work. But a fix-it is provided (or at least a message) that helps with the migration and no app using the SDK today will run into build errors, but just warnings, see the attributes of these functions. Until we decide it's time to fully drop them.

Note: In the Kotlin SDK the existing queue method drops signals older than 24h. The mindset at the time was that "important, don't drop it" signals would go out using send and others using queue.

I'm not aware of any signal dropping in Swift, I also wouldn't expect that to happen and given that the queue will be the only option going forward, you should probably turn off the "drop after 24 h".

Note2: The Flutter SDK exports a send method which routes to send on iOS and queue on Android.

That sounds reasonable as the old "send" is similar to "queue" on Android. Both will be "signal" in the future though, and I just created the PR for the future Swift SDK in TelemetryDeck/SwiftSDK#153 which contains the renaming changes in commit TelemetryDeck/SwiftSDK@b6c7d43.

[Jeehut]

Please note that I found a for parameter and also a floatValue parameter on the send function. I renamed for to customUserID to be consistent with the configurations defaultUserIdentifier (which could be renamed to defaultUserID in the future). The floatValue didn't change. But I found that the order was like this:

1. Signal Name (required)
2. Custom User ID
3. Float Value
4. Parameters

It's more common to place parameters used more often at the front though and ones that are usually skipped to fall back to the default values at the end. So I changed the order as follows:

1. Signal Name (required)
2. Parameters
3. Float Value
4. Custom User ID

To still provide fix-its for most case, I added a copy of the function which only takes the Signal Name and Parameters and made sure it's favored over the function with more parameters if only 2 are provided. Otherwise, Xcode is unable to apply fix-its when the order of parameters change, but I think fix-its can be really useful to save time in migration.

[Jeehut]

@kkostov I'm not gonna edit any of the Android / Flutter Setup documents, I think it's safer if you do the changes as soon as you've worked on the rename.

[winsmith]

Hey @kkostov, @pichfl and @timidak, I'd love your feedback on these changes regarding renaming and cleaning up parameters the SDK is sending.

[Jeehut]

@winsmith I just addressed all comments and also updated my original comment here, removing the TODOs we already clarified and adding one new entry. I also updated TelemetryDeck/SwiftSDK#149 accordingly with the suggested changes. Now to your main comment points:

operatingSystem and platform – I think there is some history here

Does that mean we should keep them "as-is"? I can understand that, I have no strong feelings here. Just wanted to bring it up that it confused me while we were talking renaming stuff.

Regarding these namespaced entries, we also have TelemetryDeck.Presets.Onboarding.step. Should Presets also be a namespace, or do you want to rename that to something else?

I think we should stick to 3 parts, so TelemetryDeck.Presets.Onboarding.step is too long. I will make sure to adjust the PRs where I introduce the presets after this has been merged (or maybe before). But I think it's a separate discussion. I will add any new group names to the renaming document on those PRs.

Can you please note which entries should not be strings? If we're sending floats or ints (which is very advisable in some cases) , I'll need to tell the server in advance.

For these two new fields sending a number could help:

1. TelemetryDeck.Device.screenResolutionWidth
2. TelemetryDeck.Device.screenResolutionHeight

Let me know if you change them, I have implemented them as Strings for now.
There's one more we might send an integer for, but I'm not sure if it really makes a difference:

1. TelemetryDeck.AppInfo.buildNumber: This is an integer on all mobile platforms.

[Jeehut]

I want to point out a few changes I made in the latest commits:

1. I renamed AppContext to RunContext to further clarify its difference to AppInfo to avoid confusion.
2. I introduced the new prefix UserPreference for region and preferredLanguage, the latter I could then shorten to just language.

I would like to also point out one renaming decision I had made earlier in this PR which is easy to miss:
I had changed the order of words in the old majorSystemVersion and majorMinorSystemVersion in the new names to have the same prefix system (for the very same reasons we have prefixes at all: better grouping). They are now systemVersion, systemMajorVersion, and systemMajorMinorVersion.

[Jeehut]

I just updated more documents alongside creating TelemetryDeck/SwiftSDK#153 which applies the changes to the SwiftSDK. Please note that before we ship this to production, I should be doing a full test with the whole onboarding process from creating a new app to setting up everything following the docs to make sure nothing is broken.

I did not touch the Objective-C code by the way, neither in the docs, nor in the SDK. I consider Obj-C as "deprecated" in itself, so renaming anything there seems to be waste of time to me. Let me know if you think otherwise.

[winsmith]

I just updated more documents alongside creating TelemetryDeck/SwiftClient#153 which applies the changes to the SwiftSDK. Please note that before we ship this to production, I should be doing a full test with the whole onboarding process from creating a new app to setting up everything following the docs to make sure nothing is broken.

Fantastic work, and yes please do a full test run.

I did not touch the Objective-C code by the way, neither in the docs, nor in the SDK. I consider Obj-C as "deprecated" in itself, so renaming anything there seems to be waste of time to me. Let me know if you think otherwise.

Sensible, I agree with this decision.

[Jeehut]

@winsmith I just did a full setup run to test if the Swift setup guide looks good and everything is right with the Swift SDK. I found a couple of bugs and fixed them. From my point of view, the Swift part of the grand rename is now ready. So this and TelemetryDeck/SwiftSDK#153 could be both merged. Don’t forget to rename the SwiftClient to SwiftSDK after the merge.

I personally don’t think there’s need to wait for the Android/Flutter SDK before merging this, because:

1. I have not touched any of their setup guides (only the Swift one), so they can be updated at a later time.
2. As long as we don’t market the “Grand Rename” article, no one will be aware of it.
3. As long as there’s no new 2.0.0 release on GitHub of the SwiftSDK, no one will notice the change (unless they rely on the main branch, which should be rare).

But feel free to take your time to think about it and give me feedback.

I’ll be focusing on the Purchases & Errors presets feature next. I will rebase the branches on top of the grand-rename branches and make sure make all adjustments needed and to include a built-in solution for the presets in the SwiftSDK so setting up the presets is even less typing work.

[winsmith]

Fantastic work, please go ahead with the merge!