Skip to content

Update web setup docs (and ingest api v3 reference) #145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
winsmith wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update web setup docs (and ingest api v3 reference) #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 62 additions & 12 deletions guides/web-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
Once you have your App ID, edit the source code of your website and add the following code snippet to the `<head>` section of every page, making sure to replace `<YOUR APP ID>` with your actual App ID:

```html
<script
<script async
src="https://cdn.telemetrydeck.com/websdk/telemetrydeck.min.js"
data-app-id="<YOUR APP ID>"
></script>
Expand All @@ -41,44 +41,69 @@

If you like, you can switch your [TelemetryDeck Dashboard](https://dashboard.telemetrydeck.com/) to Website mode. To do that, navigate to the relevant app in the Dashboard, click **App Settings** in the sidebar, and change the **Overview Layout** to **Show Data for a blog or static website**.

## Test Mode
## Options and parameters

By default, all events sent from `localhost` or an IP address in the [private IP address ranges](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces) are automatically marked as test events. This is to prevent test signals from polluting your data.
### App ID `data-app-id` (Required)

It is also possible to mark all signals as test signals by setting the dataset attribute `data-is-test-mode` to `true`.
### Test Mode `data-is-test-mode` (Optional)

By default, all events sent from `localhost` or an IP address in the [private IP address ranges](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces) are automatically marked as test events. This is to prevent test events from polluting your data.

It is also possible to mark all events as test events by setting the dataset attribute `data-is-test-mode` to `true`.

```html
<script
<script async
src="https://cdn.telemetrydeck.com/websdk/telemetrydeck.min.js"
data-app-id="<YOUR APP ID>"
data-is-test-mode="true"
></script>
```
To see test events, you can enable **Test Mode** in the Dashboard.

### Disable Engagement `data-page-engagement` (Optional)

If you don't want to collect `TelemetryDeck.Web.pageLeave` events and their metrics, you can disable them by passing `data-page-engagement="false"`:

To see test signals, you can enable **Test Mode** in the Dashboard.

```html
<script async
src="https://cdn.telemetrydeck.com/websdk/telemetrydeck.min.js"
data-app-id="<YOUR APP ID>"
data-page-engagement="false"
></script>
```

### Custom Ingest Endpoint `data-api` (Optional)

Use the `data-api` parameter to point the Web SDK to a custom TelemetryDeck v3 ingest endpoint.

## Privacy Policy and Opt-Out

You don't need to update your privacy policy, [but we recommend you do it anyway](/docs/guides/privacy-faq/#do-i-need-to-add-telemetrydeck-to-my-privacy-policy%3F).

## What data is collected?

Signals automatically contain the following data, although various data points may be missing depending on the user's browser, privacy settings or network connection, or they might be not applicable.
The TelemetryDeck Web SDK automatically sends two events per page per user to TelemetryDeck: `pageview` and `TelemetryDeck.Web.pageLeave`.

### `pageview`

### URL Data
`pageview` events are fired when a page first loads and automatically contain the following data, although various data points may be missing depending on the user's browser, privacy settings or network connection, or they might be not applicable.

#### URL Data

- `url`: The URL of the page that was loaded
- `path`: The relative path of the page, i.e. the URL minus host and protocol
- `referrer`: The URL of the page that referred the user to this page
- `type`: The type of event. This is always `pageView` for page views.
- `type`: The type of event. This is always `pageview` for page views.

### Origin and Country Data
#### Origin and Country Data

- `locale`: The locale of the user, e.g. `en-US` or `de-DE`
- `country.isoCode`: The ISO code of the country the user is in, e.g. `US` or `DE`
- `country.isInEuropeanUnion`: Whether the user is in the European Union
- `continent.code`: The code of the continent the user is in, e.g. `EU` or `NA`

### Campaign and Referrer Data
#### Campaign and Referrer Data

- `utm_campaign`: The UTM campaign of the page, if any
- `utm_source`: The UTM source of the page, if any
Expand All @@ -88,7 +113,7 @@
- `source`: The source parameter of the page, if any
- `ref`: The ref parameter of the page, if any

### Browser and System Data
#### Browser and System Data

- `systemVersion`: The version of the operating system the user is using
- `platform`: The platform the user is using, e.g. a Mac or an iPhone or an Android Phone
Expand All @@ -101,6 +126,23 @@
- `isTouchCapable`: Whether the user's device supports touch input
- `isBot`: Whether the user is a bot

### `TelemetryDeck.Web.pageLeave`

`TelemetryDeck.Web.pageLeave` events are fired the first time the page is hidden or unloaded: tab switch, tab close, navigation away, app switch on mobile. They do not fire again if the visitor returns to the tab. These events contain information about how much the visitor engaged with the page in question:

#### URL Data

- `url`: The URL of the page that was loaded
- `path`: The relative path of the page, i.e. the URL minus host and protocol
- `referrer`: The URL of the page that referred the user to this page
- `type`: The type of event, i.e. `TelemetryDeck.Web.pageLeave`

#### Engagement Data

- `TelemetryDeck.PageEngagement.scrollDepth`: A number between 0 and 100. The deepest point of the page that has been in the viewport, as a percentage of total page height. A page that fits in the viewport reports 100 without any scrolling.

Check failure on line 142 in guides/web-setup.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'viewport'?

Raw Output:
{"message":"[Vale.Spelling] Did you really mean 'viewport'?","location":{"path":"guides/web-setup.md","range":{"start":{"line":142,"column":198},"end":{"line":142,"column":206}}},"severity":"ERROR","code":{"value":"Vale.Spelling"}}

Check failure on line 142 in guides/web-setup.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'viewport'?

Raw Output:
{"message":"[Vale.Spelling] Did you really mean 'viewport'?","location":{"path":"guides/web-setup.md","range":{"start":{"line":142,"column":126},"end":{"line":142,"column":134}}},"severity":"ERROR","code":{"value":"Vale.Spelling"}}
- `TelemetryDeck.PageEngagement.scrollDepthMilestone`: String, one of "0", "25", "50", "75", "100": A quantified version of scroll depth for better clustering
- `TelemetryDeck.PageEngagement.engagedSeconds`: Number, whole seconds the page was visible in the foreground (i.e. only while the tab is visible, background time is excluded)

## User Identifiers

Our user identifiers are designed to be as privacy-friendly as possible. We do not use cookies or fingerprinting to track users. Instead, combine the IP Address, the App ID, and the User Agent string, and a daily-changing salt to create a unique identifier for each user. This identifier is then hashed using SHA-256 to protect the user's privacy.
Expand All @@ -118,6 +160,14 @@

{% endnoteinfo %}

## What's new in 3.0

Web SDK 3.0, released on September 23, 2026, introduced these changes. If you use the Web SDK without pointing it at a custom API, none of these should be breaking changes:

- We updated the format that web events are sent to a more simplified format
- We are sending these new events to the new Web v3 API
- Events no longer contain the `telemetryClientVersion` property. Instead, the property is now named `TelemetryDeck.SDK.nameAndVersion`

## What to do next

Now that you've integrated TelemetryDeck, learn how to use the analytics platform to gain valuable insights about your users:
Expand Down
59 changes: 38 additions & 21 deletions ingest/default-parameters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
---
title: Default Parameters
description: A list of default parameters that our SDKs send with every signal.
lead: A list of default parameters that our SDKs send with every signal.
description: A list of default parameters that our SDKs send with every event.
lead: A list of default parameters that our SDKs send with every event.
---

Most of TelemetryDeck's SDKs send a set of default parameters with every signal. These are not required to be sent by the user, but are useful. Our default UI will use them to provide more context. All of these parameters are namespaced under `TelemetryDeck` to avoid conflicts.
Most of TelemetryDeck's SDKs send a set of default parameters with every event. These are not required to be sent by the user, but are useful. Our default UI will use them to provide more context. All of these parameters are namespaced under `TelemetryDeck` to avoid conflicts.

## Main Parameters

These parameters are sent with every signal and are currently not namespaced. Please avoid using them in your own code.
These parameters are sent with every event and are currently not namespaced. Please avoid using them in your own code.

- `appID` (String): The ID of the app.
- `clientUser` (String): The ID of the user.
- `type` (String): The type of the signal.
- `receivedAt` (Date): The date and time the signal was received by TelemetryDeck.
- `count` (Int): The number of events sent with the signal (automatically incremented by the server)
- `isTestMode` (Bool): Whether the signal was sent in test mode.
- `type` (String): The type of the event.
- `receivedAt` (Date): The date and time of the event. Ingest API v1 and v2 default this to the time the server received the event and move older dates into the last 24 hours. Ingest API v3 stores the value as sent.
- `count` (Int): The number of events sent with the event (automatically incremented by the server)
- `isTestMode` (Bool): Whether the event was sent in test mode. Stored as the string `true` or `false`. Every dashboard query filters on this value.
- `sessionID` (String): The ID of the session.
- `floatValue` (Double): A float value that can be sent with the signal.
- `floatValue` (Double): A float value that can be sent with the event.

## App Info

Expand Down Expand Up @@ -93,24 +93,31 @@

## Web Analytics

Web analytics have their own sets of parameters that are usually determined by the web ingest api when you send events from the Web SDK. However, you can send these with any SDK and they will show up in the web analytics dashboard.
Web analytics have their own sets of parameters that are usually determined by the web ingest API when you send events from the Web SDK. The server derives them from the request on the [v3 web events endpoint](/docs/ingest/v3/#web-events-endpoint) (Web SDK 3.0 and later) and on the older `/v2/w/` endpoint. However, you can send these with any SDK and they will show up in the web analytics dashboard.

By default the web SDK will send signals of type `pageView` with the following parameters:
By default the Web SDK sends events of type `pageview` with the following parameters. Web SDK 3.0 and later also send one `TelemetryDeck.Web.pageLeave` event per page load, see [Page Engagement](#page-engagement) below.

These parameters are currently not namespaced. Expect this to change in the future.

#### Client Data

The Web SDK sends these with every event:

- `locale` (String): The locale of the visitor's browser, e.g. `en-US`.
- `referrer` (String): The URL of the page that referred the visitor, e.g. `https://example.com`. Empty if there is none.
- `TelemetryDeck.SDK.name`, `TelemetryDeck.SDK.version`, `TelemetryDeck.SDK.nameAndVersion` (String): See [SDK](#sdk) above. Web SDK 3.0 sends these instead of the deprecated `telemetryClientVersion`.

#### URL Data

- `url` (String): The URL of the page, e.g. `https://example.com/about`.
- `url` (String): The URL of the page without query string and fragment, e.g. `https://example.com/about`.
- `host` (String): The host portion of the URL, e.g. `example.com`.
- `path` (String): The path portion of the URL, e.g. `/about` or `/blog/my-post`.
- `scheme` (String): The scheme portion of the URL, e.g. `https`.
- `referer` (String): The referrer of the page, e.g. `https://example.com`.
- `TelemetryDeck.Navigation.identifier` (String): String that uniquely identifies the navigation in the format `referrer -> url`.

#### URL Parameters

TelemetryDeck will extract URL these URL parameters from the url and offer them as parameters attached to the signal:
TelemetryDeck will extract these URL parameters from the URL and offer them as parameters attached to the event. All other query parameters are dropped.

- `combinedSource` (String): The value of either `ref`, `source`, `utm_source` or `src` in that order of preference.
- `ref`
Expand All @@ -137,7 +144,7 @@
- `majorMinorSystemVersion` (String): The major and minor version of the operating system, extracted from the user agent string.
- `platform` (String): The platform of the device (macOS, iOS, Windows, etc.), extracted from the user agent string.
- `modelName` (String): The model name of the device, extracted from the user agent string.
- `browserName` (String): The browser family, extracted from the user agent string.
- `browser` (String): The browser family, extracted from the user agent string.
- `browserVersion` (String): The browser version, extracted from the user agent string.
- `device` (String): The type of device, extracted from the user agent string.
- `isMobile` (Bool): Whether the device is a mobile device, extracted from the user agent string.
Expand All @@ -146,9 +153,19 @@
- `isDesktop` (Bool): Whether the device is a desktop, extracted from the user agent string.
- `isBot` (Bool): Whether the device is a bot, extracted from the user agent string and additional heuristics.

Events from the v3 web endpoint store these booleans as `true` and `false`. Events from the older `/v2/w/` endpoint store them as `True` and `False`. Filter on both spellings when you query data from both.

Check failure on line 156 in ingest/default-parameters.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'booleans'?

Raw Output:
{"message":"[Vale.Spelling] Did you really mean 'booleans'?","location":{"path":"ingest/default-parameters.md","range":{"start":{"line":156,"column":45},"end":{"line":156,"column":53}}},"severity":"ERROR","code":{"value":"Vale.Spelling"}}

#### Page Engagement

Web SDK 3.0 and later send one event of type `TelemetryDeck.Web.pageLeave` per page load, the first time the page is hidden or unloaded. It carries the URL, country, and browser parameters listed above plus these engagement parameters:

- `TelemetryDeck.PageEngagement.scrollDepth` (Double): The deepest point of the page that has been in the viewport, as a percentage of the page height from `0` to `100`. A page that fits in the viewport reports `100`.

Check failure on line 162 in ingest/default-parameters.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'viewport'?

Raw Output:
{"message":"[Vale.Spelling] Did you really mean 'viewport'?","location":{"path":"ingest/default-parameters.md","range":{"start":{"line":162,"column":195},"end":{"line":162,"column":203}}},"severity":"ERROR","code":{"value":"Vale.Spelling"}}

Check failure on line 162 in ingest/default-parameters.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'viewport'?

Raw Output:
{"message":"[Vale.Spelling] Did you really mean 'viewport'?","location":{"path":"ingest/default-parameters.md","range":{"start":{"line":162,"column":107},"end":{"line":162,"column":115}}},"severity":"ERROR","code":{"value":"Vale.Spelling"}}
- `TelemetryDeck.PageEngagement.scrollDepthMilestone` (String): The scroll depth rounded down to one of `0`, `25`, `50`, `75`, or `100`. Use this for grouping.
- `TelemetryDeck.PageEngagement.engagedSeconds` (Double): Whole seconds the page was visible in the foreground. Time in a background tab is not counted.

## Navigation Analytics

Navigation analytics signals have these parameters, which can be included in any signal type.
Navigation analytics events have these parameters, which can be included in any event type.

- `TelemetryDeck.Navigation.schemaVersion` (String): The schema version of the navigation. Must be `1`.
- `TelemetryDeck.Navigation.sourcePath` (String): The source path of the navigation, e.g. `/host/info/about` or `app.settings.privacy`.
Expand All @@ -174,10 +191,10 @@

## API

Information about which TelemetryDeck API this signal was sent to.
Information about which TelemetryDeck API this event was sent to.

- `TelemetryDeck.API.Ingest.version` (String): The Ingest API Version this signal was sent to. This will get overwritten by the ingest API server.
- `TelemetryDeck.API.namespace` (String): The namespace in which to store your data. This usually gets set by the ingest API server when you call it via the `/v2/namespace/<namespace>/` endpoint.
- `TelemetryDeck.API.Ingest.version` (String): The Ingest API version this event was sent to. The ingest API server always sets this value. It is `v1` for the v1 API, `v2` for the v2 API, `v2web` for the v2 web endpoint, `events.v3` for the [v3 events endpoint](/docs/ingest/v3/#events-endpoint), and `web.v3` for the [v3 web events endpoint](/docs/ingest/v3/#web-events-endpoint).
- `TelemetryDeck.API.namespace` (String): The namespace in which to store your data. The ingest API server sets this from the URL when you call the `/v2/namespace/<namespace>/` or `/v3/<namespace>/` endpoint, and from the `namespace` property of an event sent to `/v3/w/`.

## RevenueCat Parameters

Expand Down Expand Up @@ -211,8 +228,8 @@
- `region` (String): The region of the user.
- `appLanguage` (String): The language of the app.
- `preferredLanguage` (String): The preferred language of the user.
- `telemetryClientVersion` (String): The version of the TelemetryDeck SDK.
- `telemetryAPIVersion` (String): The API Version this signal was sent to.
- `telemetryClientVersion` (String): The version of the TelemetryDeck SDK. Replaced by `TelemetryDeck.SDK.nameAndVersion`. The v2 ingest API copies the value over when the new key is missing.
- `telemetryAPIVersion` (String): The API version this event was sent to. Replaced by `TelemetryDeck.API.Ingest.version`.

## Reserved Parameters

Expand Down
Loading
Loading