Events Reference

Events are an indication that an event happened in your app, which is used by a user. Events consist of these parts:

• Event Type – A string that indicates which kind of event happened.
  In this case we’ll use applicationDidFinishLaunching, but it can be databaseUpdated or settingsScreenOpened or pizzaModeActivated (I totally love that last one!)
• User Identifier – A string that identifies your user.
  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 events 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.
  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. Through aggregation and statistical analysis, your Insights can then extract meaningful data out of the set of events you have received.

Here is an example event:

{
  "type": "PlayAction",
  "appID": "8BADF00D",
  "clientUser": "C00010FFBAAAAAADDEADFA11",
  "receivedAt": "2021-04-14T16:41:15+0000",
  "payload": {
    "isAppStore": "true",
    "platform": "iOS",
    "targetEnvironment": "native",
    "buildNumber": "2",
    "isSimulator": "false",
    "modelName": "iPhone12,1",
    "operatingSystem": "iOS",
    "isTestFlight": "false",
    "appVersion": "3.12.0",
    "architecture": "arm64",
    "systemVersion": "iOS  14.4.2",
  }
}

Type

Events always have a type. This is a short string that describes the event just happened. It is recommended to use short, camel-cased half-sentences like these:

• App.launchedRegularly
• App.enteredBackground
• Settings.opened

When you’re setting up your Insights later, you’ll be able to filter by Event Type.

Client User

Events have a clientUser property, which stores a string. All events with the same client user property will be assumed to originate from the same user.

By default, the client user will be a UUID, usually supplied by the devices identifierForVendor method. But you can overwrite this by supplying your own client user identifier: If you’d rather not track users at all, you can pass an empty string instead. This will effectively disable user counting, but you can still count sessions and events, and get a good idea of your user base this way.

The TelemetryDeck client library will hash any value saved into this property before sending it to the server. In addition, the server will also hash any client user value again, just to be extra sure. We really do not want to know your users’ email addresses!

Metadata Payload

Events have a metadata payload dictionary that contains things like platform, os version, and any data you throw in there. This is highly useful for filtering and aggregation insights.

The default client library will automatically send a base payload with these keys:

• TelemetryDeck.AppInfo.buildNumber
• TelemetryDeck.AppInfo.dartVersion
• TelemetryDeck.AppInfo.version
• TelemetryDeck.AppInfo.versionAndBuildNumber
• TelemetryDeck.Device.architecture
• TelemetryDeck.Device.brand
• TelemetryDeck.Device.modelName
• TelemetryDeck.Device.operatingSystem
• TelemetryDeck.Device.orientation
• TelemetryDeck.Device.platform
• TelemetryDeck.Device.screenResolutionWidth
• TelemetryDeck.Device.screenResolutionHeight
• TelemetryDeck.Device.systemMajorVersion
• TelemetryDeck.Device.systemMajorMinorVersion
• TelemetryDeck.Device.systemVersion
• TelemetryDeck.Device.timeZone
• TelemetryDeck.RunContext.extensionIdentifier
• TelemetryDeck.RunContext.isAppStore
• TelemetryDeck.RunContext.isDebug
• TelemetryDeck.RunContext.isSimulator
• TelemetryDeck.RunContext.isTestFlight
• TelemetryDeck.RunContext.language
• TelemetryDeck.RunContext.locale
• TelemetryDeck.RunContext.targetEnvironment
• TelemetryDeck.SDK.name
• TelemetryDeck.SDK.nameAndVersion
• TelemetryDeck.SDK.version
• TelemetryDeck.UserPreference.region
• TelemetryDeck.UserPreference.language

You can add any additional keys and values, or overwrite existing ones. For example, it might be a good idea to send your application’s settings with each call. This way, you’ll get a good overview of which percentage of your users have a certain feature enabled, and which configurations deserve the most effort from you.

Time Stamp

Events have a “receivedAt at” property that is set to the time (in UTC) when the event was generated on the device. This allows you to group them by time.

Events used to be called Signals

In previous versions of TelemetryDecks, events used to be called signals. We’ve renamed them to events because that made a lot more sense semantically.