TelemetryDeck

https://telemetrydeck.com/docs
Admin
TelemetryDeck is a privacy-focused analytics platform that helps developers understand user...
Tokens:96,499
Snippets:963
Trust Score:9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install TelemetryDeck Vue SDK

Source: https://telemetrydeck.com/docs/guides/vue-setup

Install the TelemetryDeck Vue SDK package via npm.

```bash
npm i @peerigon/telemetrydeck-vue --save
```

--------------------------------

### Experiment Query Example

Source: https://telemetrydeck.com/docs/tql/experiment

Example JSON for an experiment query comparing Payscreen A and Payscreen B, with a success criterion of paymentSucceeded. The query uses granularity 'all' and selector filters on the 'type' dimension.

```json
{
  "granularity": "all",
  "queryType": "experiment",
  "sample1": {
    "filter": {
      "dimension": "type",
      "type": "selector",
      "value": "payScreenALaunched"
    },
    "name": "Payscreen A"
  },
  "sample2": {
    "filter": {
      "dimension": "type",
      "type": "selector",
      "value": "payScreenBLaunched"
    },
    "name": "Payscreen B"
  },
  "successCriterion": {
    "filter": {
      "dimension": "type",
      "type": "selector",
      "value": "paymentSucceeded"
    },
    "name": "Payment Succeeded"
  }
}
```

--------------------------------

### Retention query output example

Source: https://telemetrydeck.com/docs/tql/retention

Example output structure for a 3-month retention query. Shows cohort sizes and retention intersections.

```json
{
  "timestamp": "2024-01-01T00:00:00.000Z",
  "_2024-01-01_2024-01-31": 5000,
  "_2024-02-01_2024-02-28": 4200,
  "_2024-03-01_2024-03-31": 3800,
  "retention_2024-01-01_2024-01-31_2024-01-01_2024-01-31": 5000,
  "retention_2024-01-01_2024-01-31_2024-02-01_2024-02-28": 2100,
  "retention_2024-01-01_2024-01-31_2024-03-01_2024-03-31": 1520
}
```

--------------------------------

### Install additional dependencies for Expo

Source: https://telemetrydeck.com/docs/guides/react-setup

For Expo projects, install expo-crypto and text-encoding in addition to the TelemetryDeck SDK.

```bash
npm i -S expo-crypto text-encoding
```

--------------------------------

### Experiment Query Output Example

Source: https://telemetrydeck.com/docs/tql/experiment

Example output of an experiment query, showing the number of users in each cohort, the number of successes, and the z-score and p-value. The timestamp is null when granularity is 'all'.

```json
{
  "timestamp": "2023-01-01T00:00:00.000Z",
  "cohort_1": 181,
  "cohort_2": 616,
  "success": 53,
  "cohort_1_success": 20,
  "cohort_2_success": 53,
  "zscore": 0.9444253447373949,
  "pvalue": 0.34495233502890077
}
```

--------------------------------

### Top N Query Example

Source: https://telemetrydeck.com/docs/tql/topN

Example Top N query that lists the top 10 app versions by user count. Uses a selector filter on appID and a dimension metric with version ordering.

```json
{
  "aggregations": [{ "name": "count", "type": "count" }],
  "dimension": {
    "dimension": "appVersion",
    "outputName": "appVersion",
    "type": "default"
  },
  "granularity": "all",
  "metric": {
    "ordering": "version",
    "type": "dimension"
  },
  "filter": {
    "dimension": "appID",
    "type": "selector",
    "value": "AAABBBCCC"
  },
  "queryType": "topN",
  "threshold": 10
}
```

--------------------------------

### Install TelemetryDeck Web SDK in the <head>

Source: https://telemetrydeck.com/docs/guides/web-setup

Add this script to the <head> section of every page, replacing <YOUR APP ID> with your actual TelemetryDeck App ID. Once installed, TelemetryDeck automatically sends pageView events for every page load.

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

--------------------------------

### QueryContext JSON example

Source: https://telemetrydeck.com/docs/tql/queryContext

Example of a query context specifying a priority of -1, grandTotal enabled, and a cache validity duration of 1440 minutes.

```json
"context": {
  "priority": -1,
  "grandTotal": true,
  "cacheValidityDuration": 1440
}
```

--------------------------------

### Install TelemetryDeck React SDK via NPM

Source: https://telemetrydeck.com/docs/guides/react-setup

Install the TelemetryDeck React SDK using NPM. This is a prerequisite for using the SDK in your React Native or React web application.

```bash
npm install -S @typedigital/telemetrydeck-react
```

--------------------------------

### Group By Query Example

Source: https://telemetrydeck.com/docs/tql/groupBy

Example of a groupBy query that groups events by the majorSystemVersion dimension, filters by a specific appID, and counts the number of signals. The queryType is set to "groupBy" and granularity to "all".

```json
{
  "aggregations": [
    {
      "name": "Number of Signals",
      "type": "eventCount"
    }
  ],
  "dimensions": [
    {
      "dimension": "majorSystemVersion",
      "outputName": "Major System Version",
      "outputType": "STRING",
      "type": "default"
    }
  ],
  "filter": {
    "dimension": "appID",
    "type": "selector",
    "value": "AAABBBCCC"
  },
  "granularity": "all",
  "queryType": "groupBy"
}
```

--------------------------------

### Funnel query example

Source: https://telemetrydeck.com/docs/tql/funnel

Example funnel query that counts users passing through the steps Login, View Product, and Purchase. The steps are defined as FilterStep objects with selector filters on the type dimension.

```json
{
  "queryType": "funnel",
  "granularity": "all",
  "steps": [
    {
      "name": "Login",
      "filter": {
        "type": "selector",
        "dimension": "type",
        "value": "Login"
      }
    },
    {
      "name": "View Product",
      "filter": {
        "type": "selector",
        "dimension": "type",
        "value": "View Product"
      }
    },
    {
      "name": "Purchase",
      "filter": {
        "type": "selector",
        "dimension": "type",
        "value": "Purchase"
      }
    }
  ]
}
```

--------------------------------

### JSON response for user info endpoint

Source: https://telemetrydeck.com/docs/api/api-token

Example response from the /api/v3/users/info endpoint, showing user details such as email, name, and organization. The token has the same permissions as the user account.

```json
{
  "email": "you@example.com",
  "emailIsVerified": true,
  "firstName": "Daniel",
  "id": "BADA55-BADGE5",
  "isFoundingUser": true,
  "lastName": "Jilg",
  "organization": {
    "createdAt": "2020-12-31T23:00:00+0000",
    "name": "TelemetryDeck",
    "updatedAt": "2022-07-11T01:27:20+0000"
  },
  "receiveReports": "weekly"
}
```

--------------------------------

### Top N Query

Source: https://telemetrydeck.com/docs/tql/topN

Documentation for the Top N query type in TQL, including its properties and an example query.

```APIDOC
## Top N Query

### Description
Groups a set of events by a dimension and aggregates them by a metric. Returns the top N values of a dimension ordered by a metric.

### Query Type
`topN`

### Properties

| Property | Description |
|----------|-------------|
| `dimension` | A single DimensionSpec defining the dimension that you want the top taken for. |
| `metric` | A TopNMetricSpec object specifying the metric to sort by for the top list. |
| `threshold` | An integer defining the N in the topN (how many results you want in the top list). |

### Example

```json
{
  "aggregations": [{ "name": "count", "type": "count" }],
  "dimension": {
    "dimension": "appVersion",
    "outputName": "appVersion",
    "type": "default"
  },
  "granularity": "all",
  "metric": {
    "ordering": "version",
    "type": "dimension"
  },
  "filter": {
    "dimension": "appID",
    "type": "selector",
    "value": "AAABBBCCC"
  },
  "queryType": "topN",
  "threshold": 10
}
```
```

--------------------------------

### Scan Query Example

Source: https://telemetrydeck.com/docs/tql/scan

Example of a Scan query that returns raw data rows. It specifies the columns to return, the time interval, a limit of 3 rows, and orders results by timestamp in descending order. Ensure the timestamp column `__time` is included in the columns list when using the `order` property.

```json
{
  "queryType": "scan",
  "columns": ["__time", "appID", "type"],
  "intervals": ["2024-01-01/2024-01-02"],
  "limit": 3,
  "order": "descending"
}
```

--------------------------------

### Create a plain text code block

Source: https://telemetrydeck.com/docs/articles/documentation

Use `text` as the language when no specific programming language applies. This example shows a plain text block with indentation preserved.

```markdown
```text
this is
   just
    plain text
```
```

--------------------------------

### Stop sending signals

Source: https://telemetrydeck.com/docs/guides/flutter-setup

Temporarily stop sending signals, for example if a user opts out. To restart sending events, call the start method again.

```dart
Telemetrydecksdk.stop()
```

--------------------------------

### TelemetryDeck.initialize(config:)

Source: https://telemetrydeck.com/docs/articles/telemetry-client

Initializes the TelemetryDeck SDK with the provided configuration. Must be called at app startup before sending any signals.

```APIDOC
## TelemetryDeck.initialize(config:)

### Description
Initializes the TelemetryDeck SDK with the provided configuration. Must be called at app startup before sending any signals.

### Method
initialize(config:)

### Parameters
- **config** (TelemetryDeck.Config) - Required - The configuration object containing your App ID.

### Request Example
```swift
let config = TelemetryDeck.Config(appID: "<YOUR-APP-ID>")
TelemetryDeck.initialize(config: config)
```

```

--------------------------------

### Use useTelemetryDeck hook to send events

Source: https://telemetrydeck.com/docs/guides/react-setup

Use the useTelemetryDeck hook to get the signal method and send events. The example shows sending a click event and a pageview event in a useEffect.

```jsx
import * as React from "react";
import { useTelemetryDeck } from "@typedigital/telemetrydeck-react";

function Dashboard() {
  const { signal } = useTelemetryDeck();

  const clickHandler = async () => {
    const res = await signal("click", {
      event: "button-click",
      target: "Call to Action",
    });
    console.log(res); // the response of the TelemetryDeck API
  };

  // If you want to track if a user saw a certain page or component just use an effect
  React.useEffect(() => {
    (async () => {
      const { pathname } = window.location;
      await signal("pageview", { component: "dashboard", path: pathname });
    })();
  }, []);

  return (
    <React.Fragment>
      <h1>My Dashboard</h1>
      <button onClick={async () => await clickHandler()}>Click me</button>
    </React.Fragment>
  );
}

export { Dashboard };
```

--------------------------------

### HTTP request to retrieve user info with Bearer token

Source: https://telemetrydeck.com/docs/api/api-token

Send a GET request to /api/v3/users/info with the personal access token in the Authorization header, prefixed with 'Bearer'. The token starts with 'tdpat_' and must be kept secret.

```http
GET /api/v3/users/info HTTP/1.1
Authorization: Bearer tdpat_…
Host: api.telemetrydeckapi.com
```

--------------------------------

### Initialize TelemetryDeck in SwiftUI App struct

Source: https://telemetrydeck.com/docs/guides/swift-setup

Shows the default SwiftUI app entry point, then the recommended initialization of TelemetryDeck in the App struct's init() method, and a single-line alternative. Replace YOUR-APP-ID with your app's Unique Identifier from the TelemetryDeck Dashboard.

```swift
import SwiftUI

@main
struct YourAppNameApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

```swift
import SwiftUI
import TelemetryDeck

@main
struct YourAppNameApp: App {
    init() {
        let config = TelemetryDeck.Config(appID: "YOUR-APP-ID")
        TelemetryDeck.initialize(config: config)
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

```swift
TelemetryDeck.initialize(config: .init(appID: "YOUR-APP-ID"))
```

--------------------------------

### Time network requests with await TelemetryDeck duration signals

Source: https://telemetrydeck.com/docs/articles/duration-events

Measure network request timing from background contexts. Because duration methods are @MainActor, use await when calling from background threads. This example shows starting and stopping a duration signal around a URLSession request, including error handling.

```swift
func fetchData() async throws -> Data {
    // Since we're potentially on a background thread, await is needed
    await TelemetryDeck.startDurationSignal("Network.fetch", parameters: [
        "endpoint": "users/profile"
    ])
    
    do {
        // Perform your network request
        let (data, response) = try await URLSession.shared.data(from: url)
        let statusCode = (response as? HTTPURLResponse)?.statusCode ?? 0
        
        // Again, await is needed here
        await TelemetryDeck.stopAndSendDurationSignal("Network.fetch", parameters: [
            "status": "\(statusCode)",
            "success": "true"
        ])
        
        return data
    } catch {
        await TelemetryDeck.stopAndSendDurationSignal("Network.fetch", parameters: [
            "success": "false"
        ])
        throw error
    }
}
```

--------------------------------

### Create TelemetryDeck instance and wrap app with TelemetryDeckProvider

Source: https://telemetrydeck.com/docs/guides/react-setup

Create a TelemetryDeck instance using createTelemetryDeck with your app ID and pass it to TelemetryDeckProvider, which should be placed high in the component tree.

```jsx
import * as React from "react";
import * as ReactDOM from "react-dom";
import {
  TelemetryDeckProvider,
  createTelemetryDeck,
} from "@typedigital/telemetrydeck-react";
import { Dashboard } from "./Dashboard";

const td = createTelemetryDeck({ appID: process.env.APP_ID, clientUser: "anonymous" });

const App = () => {
  return (
    <div>
      <TelemetryDeckProvider telemetryDeck={td}>
        <Dashboard />
      </TelemetryDeckProvider>
    </div>
  );
};

ReactDOM.render(<App />, document.getElementById("root"));
```

--------------------------------

### Initialize TelemetryDeck in AppDelegate

Source: https://telemetrydeck.com/docs/guides/swift-setup

Shows the default AppDelegate method and the modified version that initializes TelemetryDeck in application(_:didFinishLaunchingWithOptions:). Replace YOUR-APP-ID with your app's Unique Identifier from the TelemetryDeck Dashboard.

```swift
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        return true
    }

    // ...
}
```

```swift
import UIKit
import TelemetryDeck

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        let config = TelemetryDeck.Config(appID: "YOUR-APP-ID")
        TelemetryDeck.initialize(config: config)

        return true
    }
    // ...
}
```

--------------------------------

### Run a TQL query via POST /api/v4/query/tql

Source: https://telemetrydeck.com/docs/api/api-run-query

POST a TQL query to the /api/v4/query/tql endpoint with a personal access token in the Authorization header. The response contains the query results in the result field and the execution time in calculationDuration; allow up to 2 minutes for very complicated requests.

```http
POST /api/v4/query/tql HTTP/1.1
Authorization: Bearer tdpat_…
Content-Type: application/json
Host: api.telemetrydeckapi.com

{
  "aggregations": [
    {
      "type": "eventCount"
    }
  ],
  "dataSource": "com.yourorganization",
  "dimension": {
    "dimension": "modelName",
    "outputName": "modelName",
    "type": "default"
  },
  "filter": {
    "fields": [
      {
        "dimension": "appID",
        "type": "selector",
        "value": "B97579B6-FFB8-4AC5-AAA7-DA5796CC5DCE"
      },
      {
        "dimension": "isTestMode",
        "type": "selector",
        "value": "false"
      }
    ],
    "type": "and"
  },
  "granularity": "all",
  "metric": {
    "metric": "count",
    "type": "numeric"
  },
  "queryType": "topN",
  "relativeIntervals": [
    {
      "beginningDate": {
        "component": "day",
        "offset": -30,
        "position": "beginning"
      },
      "endDate": {
        "component": "day",
        "offset": 0,
        "position": "end"
      }
    }
  ],
  "threshold": 200
}
```

```json
{
  "calculationDuration": 0.21845901012420654,
  "calculationFinishedAt": "2022-07-11T14:00:44+0000",
  "result": {
    "rows": [
      {
        "result": [
          {
            "count": 516,
            "modelName": "iPhone13,1"
          },

          // ...

          {
            "count": 2,
            "modelName": "iPad8,6"
          }
        ],
        "timestamp": "2022-06-11T00:00:00+0000"
      }
    ],
    "type": "topNResult"
  }
}
```

--------------------------------

### Configure TelemetryDeck and RevenueCat on iOS

Source: https://telemetrydeck.com/docs/integrations/revenuecat

Set up TelemetryDeck and RevenueCat on iOS. Initialize TelemetryDeck with your app ID and salt, set a default user, then configure RevenueCat with the pre-hashed TelemetryDeck user ID and app ID as user attributes. Requires the TelemetryDeck SDK to expose a hashed user identifier; otherwise hash manually using SHA256(user_id + salt).

```swift
// 1.
// Initialize TelemetryDeck with your app ID
let telemetrydeckAppID = "AAAAAAAA-BBBB-CCCC-DDDD"
let telemetryDeckConfig = TelemetryDeck.Config(
    appID: telemetrydeckAppID,
    salt: "MY_SECRET_SALT" // optional but recommended
)
TelemetryDeck.initialize(config: telemetryDeckConfig)

// 2.
// Manually set a default user for TelemetryDeck
// We're using IFV here, but you can also use
// e.g. an email address or any other identifying property
let myUserID = UIDevice.current
    .identifierForVendor?.uuidString
    ?? "unknown user"
TelemetryDeck.updateDefaultUserID(to: myUserID)

// 3.
// Set up RevenueCat with your TelemetryDeck App ID
// and the pre-hashed TelemetryDeck User ID
Purchases.configure(withAPIKey: "my_revenuecat_api_key")
Purchases.shared.attribution.setAttributes([
    "$telemetryDeckUserId": TelemetryManager.shared
        .hashedDefaultUser
        ?? "no-user",
    "$telemetryDeckAppId": telemetrydeckAppID
])
```

--------------------------------

### Example TelemetryDeck event JSON

Source: https://telemetrydeck.com/docs/api/signals-reference

Example event payload showing the structure of a TelemetryDeck event, including type, appID, clientUser, receivedAt, and a payload dictionary with automatically added metadata such as platform, buildNumber, and appVersion.

```json
{
  "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",
  }
}
```

--------------------------------

### Import TelemetryDeck SDK

Source: https://telemetrydeck.com/docs/guides/android-setup

Import the TelemetryDeck class at the top of your Kotlin file to use the SDK.

```kotlin
import com.telemetrydeck.sdk.TelemetryDeck
```

--------------------------------

### Initialize TelemetryDeck SDK in browser-based applications

Source: https://telemetrydeck.com/docs/guides/javascript-setup

Initializes the TelemetryDeck SDK in a browser-based application. Replace `<YOUR_APP_ID>` with your app ID from the TelemetryDeck dashboard and `<YOUR_USER_IDENTIFIER>` with a string that uniquely identifies the logged-in user (e.g., an email address). The user identifier is cryptographically anonymized with a hash function. If you cannot specify a user identifier at initialization, you can set it later by setting `td.clientUser`. Note that `td.signal` is an async function that returns a promise.

```javascript
import TelemetryDeck from '@telemetrydeck/sdk';

const td = new TelemetryDeck({
  appID: '<YOUR_APP_ID>'
  clientUser: '<YOUR_USER_IDENTIFIER>',
});
```

--------------------------------

### Example signal object with payload for TelemetryDeck Ingest API v2

Source: https://telemetrydeck.com/docs/ingest/v2

Example JSON object for the TelemetryDeck Ingest API v2 body. Shows all optional properties: `sessionID`, `isTestMode`, `floatValue`, and `payload`. The payload must be a JSON object containing primitives; nested objects are not allowed.

```json
{
  "appID": "AAAA-BBBBBBBB-CCCC-DDDD",
  "clientUser": "myClientUserHash",
  "type": "Curl.Development.apiCall",
  "sessionID": "mySessionID",
  "isTestMode": false,
  "floatValue": 3.14159,
  "payload": {
    "TelemetryDeck.RunContext.locale": "en_US",
    "TelemetryDeck.Device.architecture": "x86_64"
  }
}
```

--------------------------------

### Display an image with markdown syntax

Source: https://telemetrydeck.com/docs/articles/documentation

Displays an image in a docs article. The image file must be placed in the `images` directory at the root of the `docs` repository; files elsewhere are ignored. The path must be prefixed with `/docs/images/` because the Docs repository lives inside a `/docs` folder on deployment.

```markdown
![A screenshot of Apple's Privacy Overview](/docs/images/privacy-overview.png)
```

--------------------------------

### Funnel Query

Source: https://telemetrydeck.com/docs/tql/funnel

Documentation for the Funnel Query, including its properties, FilterStep object, and an example query.

```APIDOC
## Funnel Query

### Description
Groups a set of events by a set of steps and aggregates them by a set of metrics. It is compiled at runtime into a groupBy query but has a simpler syntax.

### Query Type
`funnel`

### Properties

#### steps (required)
- **Type**: List of **FilterStep** objects
- **Description**: The steps of the funnel. Each step contains a filter applied to the data. The first step is applied to all data, the second step is applied to the data that passed the first step, and so on.

#### filter (optional)
- **Type**: Filter
- **Description**: A filter to apply to the data to be queried. Default is no filter apart from base filters.

#### granularity (optional)
- **Type**: string
- **Description**: The granularity of the results. Default is `all`.

### FilterStep Object

#### name (required)
- **Type**: string
- **Description**: The name of the step, used to label the results.

#### filter (required)
- **Type**: Filter
- **Description**: A filter to apply to the data to be queried.

### Example

```json
{
  "queryType": "funnel",
  "granularity": "all",
  "steps": [
    {
      "name": "Login",
      "filter": {
        "type": "selector",
        "dimension": "type",
        "value": "Login"
      }
    },
    {
      "name": "View Product",
      "filter": {
        "type": "selector",
        "dimension": "type",
        "value": "View Product"
      }
    },
    {
      "name": "Purchase",
      "filter": {
        "type": "selector",
        "dimension": "type",
        "value": "Purchase"
      }
    }
  ]
}
```

### How Funnels Work
Internally, a `funnel` query is compiled into a groupBy query with extra aggregations and post-aggregations.

#### Aggregations
Aggregations split signals into buckets and count them by `clientUser` (TelemetryDeck's user identifier).

```json
[
  {
    "type": "filtered",
    "filter": {
      "type": "selector",
      "dimension": "type",
      "value": "appLaunchedByNotification"
    },
    "aggregator": {
      "type": "userCount",
      "name": "appLaunchedByNotification_count"
    }
  },
  {
    "type": "filtered",
    "filter": {
      "type": "selector",
      "dimension": "type",
      "value": "dataEntered"
    },
    "aggregator": {
      "type": "userCount",
      "name": "dataEntered_count"
    }
  }
]
```

#### Post Aggregation
Calculates the intersection of the aggregation buckets to ensure the second stage consists only of users who sent both signals.

```json
[
  {
    "type": "thetaSketchEstimate",
    "name": "app_launched_and_data_entered_count",
    "field": {
      "type": "thetaSketchSetOp",
      "name": "app_launched_and_data_entered_count",
      "func": "INTERSECT",
      "fields": [
        {
          "type": "fieldAccess",
          "fieldName": "appLaunchedByNotification_count"
        },
        {
          "type": "fieldAccess",
          "fieldName": "dataEntered_count"
        }
      ]
    }
  }
]
```
```
Tokens:
Raw