#docs #articles #setup

Navigation Signals

TelemetryDeck can track how users navigate through your app when you send navigation signals. Here's how these need to look like.

Format

A navigation signal is a regular TelemetryDeck signal of type TelemetryDeck.Navigation.pathChanged. It has parameters for version number, source and destination paths, and an identifier, which is the source path and destination path concatenated with ->. Using this identifier, we can track how users navigate through your app.

{
  "appID": "<AAAA-BBBBBBBB-CCCC-DDDD>",
  "clientUser": "<myClientUserHash>",
  "type": "TelemetryDeck.Navigation.pathChanged",
  "payload": {
    "TelemetryDeck.Navigation.schemaVersion": "1",
    "TelemetryDeck.Navigation.identifier": "<source> -> <destination>",
    "TelemetryDeck.Navigation.sourcePath": "<source>",
    "TelemetryDeck.Navigation.destinationPath": "<destination>"
  }
}

Values in angle brackets (< >) are placeholders and should be replaced with actual values.

The signal type should always be TelemetryDeck.Navigation.pathChanged for navigation signals.

Here’s what each parameter should contain:

KeyDescription
TelemetryDeck.Navigation.schemaVersionThe version of the schema. Should always be "1". We’ll use this to account for if we ever need to update this schema.
TelemetryDeck.Navigation.identifierThe source navigation path, followed by ->, followed by the destination navigation path. This is the most important part of the navigation schema, we’ll use this to build directed graphs.
TelemetryDeck.Navigation.sourcePathA navigation path that describes the source of the navigation.
TelemetryDeck.Navigation.destinationPathA navigation that describes the destination of the navigation.

Navigation Paths are strings that describe a location or view in your application or website. They must be delineated by either . or / characters. Delineation characters at the beginning and end of the string are ignored. Use the empty string "" for navigation from outside the app.

Examples:

  • index
  • settings.user.changePassword
  • /blog/ios-market-share

Automatic Navigation Tracking

Since TelemetryDeck navigation signals are slightly cumbersome to create manually, we’re aiming to provide convenience methods for our SDKs that will automatically track navigation signals for you. These methods will be in one of two flavors, either a method that you call with a source and destination, or a method that you call with just a destination.

TelemetryDeck.navigationPathChanged(from: <source>, to <destination>)

Calling this method will automatically create a navigation signal with the given source and destination.

TelemetryDeck.navigationPathChanged(to: <destination>)

Calling this method with just a destination will use the previously last used source as the source for the navigation signal.

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.