Merge branch 'main' into feature/error-with-id

.github/ISSUE_TEMPLATE/documentation-feedback.md

@@ -4,11 +4,10 @@ about: Suggest an idea for this project
 title: Feedback for [URL]
 labels: documentation
 assignees: voidedmain, winsmith
-
 ---
 
 **Is your feedback related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+A clear and concise description of what the problem is. Ex. I'm always frustrated when […]
 
 **Describe the solution you'd like or the information you're missing**
 A clear and concise description of what you want to happen.

.styles/Vocab/Base/accept.txt → .styles/config/vocabularies/Base/accept.txt

@@ -8,34 +8,26 @@ Objective-C
 groupBy
 stepNames
 superset
-timeseries
+[Tt]imeseries
 queryType
 dataSource
 relativeIntervals
 baseFilters
 postAggregations
-Timeseries
-doubleSum
+[dD]oubleSum
 unioned
-doubleAny
-stringAny
+[dD]oubleAny
+[sS]tringAny
 accessor
-hyperUnique
+[hH]yperUnique
 numericFirst
-doubleMax
+[dD]oubleMax
 doubleGreatest
-DoubleSum
-DoubleMax
-DoubleAny
-StringAny
 HyperUnique
 DimensionSpec
 TopNMetricSpec
 pseudonymize
-Donut
-Identifer
-identifer
-donut
+[dD]onut
 UIKit
 SDK
 GitHub
@@ -53,4 +45,23 @@ retarget
 devs
 swifty
 anonymization
-glowy
+glowy
+pseudonymization
+namespaced
+Bool
+Vue
+(npm|NPM)
+async
+Superwall
+sampleFactor
+testMode
+injective
+Payscreen
+clientUser
+appVersion
+buildNumber
+prepending
+destructure
+crypto
+typedigital
+enum

.styles/config/vocabularies/Base/reject.txt

@@ -0,0 +1,2 @@
+identifer
+Identifer

README.md

@@ -2,6 +2,6 @@
 
 Welcome to the public documentation for TelemetryDeck. The output of these pages is hosted at https://telemetrydeck.com/docs.
 
-We're very grateful for pull requests or issues that improve things or let us know about errata and missing or unclear bits of information! <3
+We're incredibly grateful for pull requests or issues that improve things or let us know about errata and missing or unclear bits of information! <3
 
 Check out `articles/documentation.md` for an overview of how documentation pages are formatted.

api/default-parameters.md

@@ -56,7 +56,6 @@ Information about the context the app runs in, such as whether it's running in a
 - `TelemetryDeck.RunContext.targetEnvironment`: The target environment of the app.
 - `TelemetryDeck.RunContext.extensionIdentifier`: The identifier of the extension the app is running in. This provides a value such as `com.apple.widgetkit-extension` when TelemetryDeck is run from a widget.
 
-
 ## User Preference
 
 Information about the user's preferences, such as language and region.
@@ -80,7 +79,7 @@ Information about which TelemetryDeck API this signal was sent to .
 
 ## Deprecated Parameters
 
-These parameters are deprecated because they are not yet namespaced, and will be removed in a future release. All of them have replacements in some namespaces. See the [grand rename](/articles/grand-rename/) article for a mapping of the old names to the new ones.
+These parameters are deprecated because they are not yet namespaced, and will be removed in a future release. All of them have replacements in some name spaces. See the [grand rename](/articles/grand-rename/) article for a mapping of the old names to the new ones.
 
 - `platform`: The platform of the device.
 - `systemVersion`: The version of the operating system.

api/insights-reference.md

@@ -102,7 +102,7 @@ If you enter a breakdown key for an Insight, calculation will switch from time s
 
 **Hints:**
 
-1. Breakdowns pair well with the Donut Chart as a Chart Type.
+1. Breakdowns pair well with the donut chart as a Chart Type.
 2. If you're interested in the number of **users** per e.g. system version instead of the number of signals, enabled the _unique by user_ option in _Signal Type_.
 
 ---

api/signals-reference.md

@@ -11,7 +11,7 @@ lead: A Signal is the representation of one event happening in one instance of y
 Signals are an indication that **an event** happened in your app, which is used by a **user**. Signals consist of these parts:
 
 - **Signal Name** – A string that indicates which kind of event happened.<br>In this case we'll use `applicationDidFinishLaunching`, but it can be `databaseUpdated` or `settingsScreenOpened` or `pizzaModeActivated` (I totally love that last one!)
-- **User Identifer** – A string that identifies your user.<br>This can be an email address or a username, or a random ID that you generate once and store somewhere. It should always be the same for all the signals you send from a certain instance of the app. If you don't supply a user identifier, `TelemetryDeck` will generate one for you.
+- **User Identifier** – A string that identifies your user.<br>This can be an email address or a username, or a random ID that you generate once and store somewhere. It should always be the same for all the signals you send from a certain instance of the app. If you don't supply a user identifier, `TelemetryDeck` will generate one for you.
 - **A Metadata Payload** – Metadata is a dictionary `[String: String]` of additional data about your app that might be interesting to analyze.<br>`TelemetryDeck` will always add the user's OS Version, Platform, Build Number and App Version to the metadata, but you can specify additional info like, `numberOfEntriesInDatabase` (an int cast to string) or `pizzaModeAnchoviesEnabled` (a Boolean cast to string).
 
 As TelemetryDeck is an analytics software, it analyzes events that occur in your apps' life cycles. In TelemetryDeck,

articles/grand-rename.md

@@ -7,17 +7,17 @@ lead: To avoid ambiguity and clean up things for the long term, we have decided
 
 ## 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 defualt signal & a bunch of parameters automatically. To keep things simple, we named the signal `newSessionBegan` and the parameters `appVersion` and `locale`, for example.
+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.
 
-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 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](https://telemetrydeck.com/docs/articles/signal-type-naming/). 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.
+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](https://telemetrydeck.com/docs/articles/signal-type-naming/). 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 strived for 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 redirections, this change should have no effect on our existing customers, but long term, it should make things more consistent. 🎉
+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:
 
@@ -74,25 +74,25 @@ Here's a full overview of all the changes we have done:
 | NewSessionBegan            | TelemetryDeck.Session.started                           |
 | newSessionBegan            | TelemetryDeck.Session.started                           |
 | -------------------------- | ------------------------------------------------------- |
-| buildNumber                | TelemetryDeck.AppInfo.buildNumber                       |
-| dartVersion                | TelemetryDeck.AppInfo.dartVersion                       |
-| appVersion                 | TelemetryDeck.AppInfo.version                           |
-| architecture               | TelemetryDeck.Device.architecture                       |
-| brand                      | TelemetryDeck.Device.brand                              |
-| modelName                  | TelemetryDeck.Device.modelName                          |
-| operatingSystem            | TelemetryDeck.Device.operatingSystem                    |
-| platform                   | TelemetryDeck.Device.platform                           |
-| majorSystemVersion         | TelemetryDeck.Device.systemMajorVersion                 |
-| majorMinorSystemVersion    | TelemetryDeck.Device.systemMajorMinorVersion            |
-| systemVersion              | TelemetryDeck.Device.systemVersion                      |
-| extensionIdentifier        | TelemetryDeck.RunContext.extensionIdentifier            |
-| isAppStore                 | TelemetryDeck.RunContext.isAppStore                     |
-| isDebug                    | TelemetryDeck.RunContext.isDebug                        |
-| isSimulator                | TelemetryDeck.RunContext.isSimulator                    |
-| isTestFlight               | TelemetryDeck.RunContext.isTestFlight                   |
-| locale                     | TelemetryDeck.RunContext.locale                         |
-| targetEnvironment          | TelemetryDeck.RunContext.targetEnvironment              |
-| telemetryClientVersion     | TelemetryDeck.SDK.nameAndVersion                        |
+| `buildNumber`              | TelemetryDeck.AppInfo.buildNumber                       |
+| `dartVersion`              | TelemetryDeck.AppInfo.dartVersion                       |
+| `appVersion`               | TelemetryDeck.AppInfo.version                           |
+| `architecture`             | TelemetryDeck.Device.architecture                       |
+| `brand`                    | TelemetryDeck.Device.brand                              |
+| `modelName`                | TelemetryDeck.Device.modelName                          |
+| `operatingSystem`          | TelemetryDeck.Device.operatingSystem                    |
+| `platform`                 | TelemetryDeck.Device.platform                           |
+| `majorSystemVersion`       | TelemetryDeck.Device.systemMajorVersion                 |
+| `majorMinorSystemVersion`  | TelemetryDeck.Device.systemMajorMinorVersion            |
+| `systemVersion`            | TelemetryDeck.Device.systemVersion                      |
+| `extensionIdentifier`      | TelemetryDeck.RunContext.extensionIdentifier            |
+| `isAppStore`               | TelemetryDeck.RunContext.isAppStore                     |
+| `isDebug`                  | TelemetryDeck.RunContext.isDebug                        |
+| `isSimulator`              | TelemetryDeck.RunContext.isSimulator                    |
+| `isTestFlight`             | TelemetryDeck.RunContext.isTestFlight                   |
+| `locale`                   | TelemetryDeck.RunContext.locale                         |
+| `targetEnvironment`        | TelemetryDeck.RunContext.targetEnvironment              |
+| `telemetryClientVersion`   | TelemetryDeck.SDK.nameAndVersion                        |
 
 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.

articles/navigation-signals.md

@@ -71,7 +71,7 @@ Calling this method will automatically create a navigation signal with the given
 
 Calling this method with just a destination will use the previously last used source as the source for the navigation signal.
 
-This is very convenient, but might produce incorrect graphs if you don't call it from every screen in your app.
+This is convenient, but might produce incorrect graphs if you don't call it from every screen in your app.
 Suppose you have 3 tabs "Home", "User" and "Settings", but only set up navigation in "Home" and "Settings". If
 a user taps "Home", "User" and "Settings" in that order, that'll produce an incorrect navigation signal with
 source "Home" and destination "Settings", a path that the user did not take.

articles/preset-errors.md

@@ -8,18 +8,16 @@ tags:
 lead: TelemetryDeck ships with a set of insights that can be useful to learn what kind of issues your users encounter most in your apps. Here's how to set them up.
 ---
 
-
 ## Why Track Errors?
 
 Success is often defined in numbers such as Monthly Active Users (MAU) or Monthly Recurring Revenue (MRR). Churn is a metric that tracks the percentage of active/paying users who stopped using/paying for your app.
 
-A smooth experience without bugs & issues is one of the key factors contributing to a lower churn rate. If you do a good job in continuuously fixing the most common issues with your product, you're on the right track for success. That's why it's important that you detect any common issues your users get stuck at while using your app.
+A smooth experience without bugs & issues is one of the key factors contributing to a lower churn rate. If you do a good job in continuously fixing the most common issues with your product, you're on the right track for success. That's why it's important that you detect any common issues your users get stuck at while using your app.
 
 {% noteinfo "What Error Handling Really Is" %}
 Error Handling is any logic that detects that something unexpected happened and reacts to that information in some useful way. It's commonly interpreted as 'showing an error message to a user', but that's just the most basic form of Error Handling. Other common things you can do to improve your app are Empty States (Why is this empty?), Call-to-Actions (What can I do?), and Auto-Repair (resiliency against common unexpected user input). But always make sure to give some form of feedback instead of failing silently, which makes your app feel broken.
 {% endnoteinfo %}
 
-
 ## Sending the Signal
 
 To report unexpected events to TelemetryDeck, send the event name `TelemetryDeck.Error.occurred` with the parameter `TelemetryDeck.Error.id` set to something that can be used to group errors of the same kind. For example, using the Swift SDK you could simply pass `error.localizedDescription` whenever an exception is thrown that you don't expect to happen:
@@ -124,9 +122,9 @@ Each of these has a dedicated chart in the "Errors" tab, you just need to report
 
 Here's some guidance on when to use which category in Swift:
 
-* A clear sign to report a `thrown-exception` error is a `do-catch` clause or uses of `try?` in Swift where you can send the error signal when it returns `nil`.
-* Whenever you you make use of the nil-coalescing operator `??` or unwrap an Optional with `if-let` or `guard-let`, potentially some kind of conversion of user input into another type might happen with a fallback behavior – this is a typical `user-input` error.
-* Search for any uses of [`assert`](https://developer.apple.com/documentation/swift/assert(_:_:file:line:)) or [`assertionFailure`](https://developer.apple.com/documentation/swift/assertionfailure(_:file:line:)) in your code and additionally report these detected unexpected states of your app during runtime as `app-state` errors. If you weren't aware, the `assert`/`assertionFailure` functions are similar to `fatalError`/`precondition`/`preconditionFailure` with the difference that they only stop program execution during DEBUG builds, not in production builds.
+- A clear sign to report a `thrown-exception` error is a `do-catch` clause or uses of `try?` in Swift where you can send the error signal when it returns `nil`.
+- Whenever you make use of the nil-coalescing operator `??` or unwrap an Optional with `if-let` or `guard-let`, potentially some kind of conversion of user input into another type might happen with a fallback behavior – this is a typical `user-input` error.
+- Search for any uses of [`assert`](<https://developer.apple.com/documentation/swift/assert(_:_:file:line:)>) or [`assertionFailure`](<https://developer.apple.com/documentation/swift/assertionfailure(_:file:line:)>) in your code and additionally report these detected unexpected states of your app during runtime as `app-state` errors. If you weren't aware, the `assert`/`assertionFailure` functions are similar to `fatalError`/`precondition`/`preconditionFailure` with the difference that they only stop program execution during DEBUG builds, not in production builds.
 
 A full signal that reports a `user-input` category error could end up looking something like this in Swift:
 
@@ -160,9 +158,8 @@ TelemetryDeck.errorOccurred(
 
 Please note that when calling the `TelemetryDeck.errorOccurred(identifiableError:)` function, the category is implicitly set to `.thrownException`, but you can override it if needed.
 
-
 ## Effect on Privacy & App Tracking Transparency
 
 If you are sending dynamic values such as `error.localizedDescription` or if any of the parameter fields contain user-dynamic data such as file paths or input data, some user data might be sent to TelemetryDeck. It really depends on the nature of this data and how you plan to use it that influences what fields in App Tracking Transparency you need to add. You might need to adjust your privacy report accordingly.
 
-But TelemetryDeck does not attempt to link collected data to the users identity, nor do we use data for tracking purposes. To protect your users privacy, we urge you to not send any data that might identify your users.
+TelemetryDeck does not attempt to link collected data to the users identity, nor do we use data for tracking purposes. To protect your users privacy, we urge you to not send any data that might identify your users.