TelemetryDeck SDK

https://pub.dev/documentation/telemetrydecksdk/latest
Admin
TelemetryDeck SDK for Flutter is a Dart package that allows Flutter applications to send signals and...
Tokens:36,492
Snippets:58
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Telemetry SDK

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/Telemetrydecksdk/start

Initializes the Telemetrydecksdk with a provided configuration. This static method enriches default parameters and starts the underlying platform implementation. It requires a `TelemetryManagerConfiguration` object as input.

```dart
static Future<void> start(TelemetryManagerConfiguration configuration) async {
  final enrichedDefaultParameters = await _telemetryProvider.enrich(
    configuration.defaultParameters,
  );
  final stringifiedeParams = enrichedDefaultParameters.map(
    (key, value) => MapEntry(key, value.toString()),
  );
  final enrichedConfiguration = configuration.copyWith(
    defaultParameters: stringifiedeParams,
  );
  await TelemetrydecksdkPlatform.instance.start(enrichedConfiguration);
}
```

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

### Telemetrydecksdk Class API Reference

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/Telemetrydecksdk/generateNewSession

API documentation for the Telemetrydecksdk class, covering its static methods for managing telemetry data. Includes methods for starting, stopping, sending data, and user management.

```APIDOC
Telemetrydecksdk:
  generateNewSession() async
    - Generates a new telemetry session.
    - Returns: A Future<void> that completes when the session is generated.

  navigate(String destination)
    - Navigates to a specified destination.
    - Parameters:
      - destination: The identifier for the destination.
    - Returns: void.

  navigateToDestination(String destination)
    - Navigates to a specified destination.
    - Parameters:
      - destination: The identifier for the destination.
    - Returns: void.

  send(String eventName, {Map<String, dynamic>? data})
    - Sends a telemetry event with optional data.
    - Parameters:
      - eventName: The name of the event to send.
      - data: Optional map of key-value pairs for event data.
    - Returns: void.

  start()
    - Starts the telemetry SDK.
    - Returns: void.

  startDurationSignal(String signalName, {Map<String, dynamic>? data})
    - Starts timing a duration signal with optional data.
    - Parameters:
      - signalName: The name of the signal to start timing.
      - data: Optional map of key-value pairs for the signal.
    - Returns: void.

  stop()
    - Stops the telemetry SDK.
    - Returns: void.

  stopAndSendDurationSignal(String signalName, {Map<String, dynamic>? data})
    - Stops timing a duration signal and sends it with optional data.
    - Parameters:
      - signalName: The name of the signal to stop timing.
      - data: Optional map of key-value pairs for the signal.
    - Returns: void.

  updateDefaultUser(String userId)
    - Updates the default user ID for telemetry.
    - Parameters:
      - userId: The new user ID.
    - Returns: void.
```

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

### Initialize TelemetryDeck Client

Source: https://pub.dev/documentation/telemetrydecksdk/latest/index

Configures and starts the TelemetryDeck client with the provided App ID. This must be called before sending any signals and requires ensuring platform channels are initialized.

```dart
void main() {
  // ensure the platform channels are available
  WidgetsFlutterBinding.ensureInitialized();
  // configure and start the client
  Telemetrydecksdk.start(
    const TelemetryManagerConfiguration(
      appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    ),
  );

  runApp(const MyApp());
}
```

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

### Configure TelemetryManager

Source: https://pub.dev/documentation/telemetrydecksdk/latest/index

Demonstrates how to start the TelemetryDeck SDK with various configuration options within TelemetryManagerConfiguration. This includes setting test mode, a custom salt for user identifiers, a custom API base URL for signal ingestion, and enabling debug logging.

```dart
Telemetrydecksdk.start(
  TelemetryManagerConfiguration(
    appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    testMode: true,
  ),
);
```

```dart
Telemetrydecksdk.start(
  TelemetryManagerConfiguration(
    appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    salt: "<A RANDOM STRING>",
  ),
);
```

```dart
Telemetrydecksdk.start(
  TelemetryManagerConfiguration(
    appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    apiBaseURL: "https://nom.telemetrydeck.com",
  ),
);
```

```dart
void main() {
  Telemetrydecksdk.start(
    TelemetryManagerConfiguration(
      appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      debug: true,
    ),
  );
}
```

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

### Telemetrydecksdk Static Methods API

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/Telemetrydecksdk/navigateToDestination

API documentation for static methods of the Telemetrydecksdk class. This includes method signatures, parameter descriptions, and return types for navigating and sending telemetry data.

```APIDOC
Telemetrydecksdk:
  Static methods:

  navigateToDestination(String destinationPath, {String? clientUser})
    - Navigates to a specified destination path.
    - Parameters:
      - destinationPath: The path to navigate to (String).
      - clientUser: An optional client user identifier (String?).
    - Returns: A Future<void> representing the asynchronous operation.
    - Implementation Example:
      static Future<void> navigateToDestination(String destinationPath,
          {String? clientUser}) async {
        await TelemetrydecksdkPlatform.instance
            .navigateToDestination(destinationPath, clientUser: clientUser);
      }

  generateNewSession()
    - Starts a new telemetry session.
    - Returns: A Future<void>.

  navigate(String destinationPath)
    - Navigates to a specified destination path.
    - Parameters:
      - destinationPath: The path to navigate to (String).
    - Returns: A Future<void>.

  send(String eventName, {Map<String, String>? data})
    - Sends a telemetry event with optional data.
    - Parameters:
      - eventName: The name of the event to send (String).
      - data: Optional key-value pairs for event data (Map<String, String>?).
    - Returns: A Future<void>.

  start()
    - Initializes the telemetry SDK.
    - Returns: A Future<void>.

  startDurationSignal(String signalName)
    - Starts timing a duration signal.
    - Parameters:
      - signalName: The name of the signal to start timing (String).
    - Returns: A Future<void>.

  stop()
    - Stops the current telemetry session.
    - Returns: A Future<void>.

  stopAndSendDurationSignal(String signalName, {Map<String, String>? data})
    - Stops timing a duration signal and sends it with optional data.
    - Parameters:
      - signalName: The name of the signal to stop timing (String).
      - data: Optional key-value pairs for event data (Map<String, String>?).
    - Returns: A Future<void>.

  updateDefaultUser(String? clientUser)
    - Updates the default client user for telemetry.
    - Parameters:
      - clientUser: The new default client user identifier (String?).
    - Returns: A Future<void>.
```

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

### Stop Sending Signals

Source: https://pub.dev/documentation/telemetrydecksdk/latest/index

Prevents the SDK from sending any further signals, including previously cached ones. To resume sending, the `start` method must be called again.

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

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

### Telemetrydecksdk Class API

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/Telemetrydecksdk/startDurationSignal

API documentation for the Telemetrydecksdk class, detailing its static methods for initializing, managing, and sending telemetry data.

```APIDOC
Telemetrydecksdk:
  Static methods:
    generateNewSession(): void
      Description: Generates a new session for telemetry tracking.
      Related: start(), stop()

    navigate(String destination):
      Description: Records a navigation event to a specified destination.
      Parameters:
        destination: The identifier of the destination.
      Related: navigateToDestination()

    navigateToDestination(String destination):
      Description: Records a navigation event to a specified destination.
      Parameters:
        destination: The identifier of the destination.
      Related: navigate()

    send(String signalType, {Map<String, String>? parameters}): Future<void>
      Description: Sends a telemetry signal with a given type and optional parameters.
      Parameters:
        signalType: The type of the signal.
        parameters: Optional key-value pairs for signal data.
      Related: startDurationSignal(), stopAndSendDurationSignal()

    start(String appId, {String? defaultUserID}): Future<void>
      Description: Initializes the telemetry SDK with the application ID and an optional default user ID.
      Parameters:
        appId: The unique identifier for the application.
        defaultUserID: An optional default user identifier.
      Related: stop(), updateDefaultUser()

    startDurationSignal(String signalType, {Map<String, String>? parameters}): Future<void>
      Description: Starts tracking the duration of a specific event or signal.
      Parameters:
        signalType: The type of the signal to start tracking.
        parameters: Optional key-value pairs for signal data.
      Related: stopAndSendDurationSignal()

    stop(): Future<void>
      Description: Stops the current telemetry session.
      Related: start()

    stopAndSendDurationSignal(String signalType, {Map<String, String>? parameters}): Future<void>
      Description: Stops tracking the duration of a signal and sends the completed duration signal.
      Parameters:
        signalType: The type of the signal to stop and send.
        parameters: Optional key-value pairs for signal data.
      Related: startDurationSignal()

    updateDefaultUser(String defaultUserID): Future<void>
      Description: Updates the default user ID for the current telemetry session.
      Parameters:
        defaultUserID: The new default user identifier.
      Related: start()
```

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

### Start and Stop Duration Signals

Source: https://pub.dev/documentation/telemetrydecksdk/latest/index

Facilitates tracking the duration of events. `startDurationSignal` begins tracking, and `stopAndSendDurationSignal` ends tracking, sends the signal, and includes the duration in seconds.

```dart
// start tracking, without sending a signal
TelemetryDeck.startDurationSignal("wizard_step1")

// end tracking, sends the signal including the total duration (excluding background time)
TelemetryDeck.stopAndSendDurationSignal("wizard_step1")
```

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

### Telemetrydecksdk Class API Reference

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/Telemetrydecksdk/updateDefaultUser

API documentation for the Telemetrydecksdk class, covering static and instance methods for managing telemetry sessions, sending data, and navigation.

```APIDOC
Telemetrydecksdk:
  // Static Methods
  static Future<void> updateDefaultUser(String clientUser)
    // Sets a default user identifier for telemetry events.
    // Parameters:
    //   clientUser: The user identifier string.
    // Returns:
    //   A Future<void> that completes when the operation is done.

  static Future<void> generateNewSession()
    // Generates a new session for telemetry tracking.
    // Returns:
    //   A Future<void>.

  static Future<void> start(String appId)
    // Initializes the TelemetryDeck SDK with the application ID.
    // Parameters:
    //   appId: The unique identifier for your application.
    // Returns:
    //   A Future<void>.

  static Future<void> navigate(String screenName)
    // Records a screen view event.
    // Parameters:
    //   screenName: The name of the screen being viewed.
    // Returns:
    //   A Future<void>.

  static Future<void> navigateToDestination(String destinationName)
    // Records a navigation event to a specific destination.
    // Parameters:
    //   destinationName: The name of the destination.
    // Returns:
    //   A Future<void>.

  static Future<void> send(String telemetryType, {Map<String, dynamic>? data})
    // Sends a custom telemetry event.
    // Parameters:
    //   telemetryType: The type of telemetry event (e.g., 'custom_event').
    //   data: Optional map of key-value pairs for event data.
    // Returns:
    //   A Future<void>.

  static Future<void> startDurationSignal(String signalName)
    // Starts timing a duration for a specific signal.
    // Parameters:
    //   signalName: The name of the signal to start timing.
    // Returns:
    //   A Future<void>.

  static Future<void> stopDurationSignal(String signalName, {Map<String, dynamic>? data})
    // Stops timing a duration signal and sends the duration.
    // Parameters:
    //   signalName: The name of the signal to stop timing.
    //   data: Optional map of key-value pairs for event data.
    // Returns:
    //   A Future<void>.

  static Future<void> stopAndSendDurationSignal(String signalName, {Map<String, dynamic>? data})
    // Stops timing a duration signal and sends it immediately.
    // Parameters:
    //   signalName: The name of the signal to stop timing.
    //   data: Optional map of key-value pairs for event data.
    // Returns:
    //   A Future<void>.

  // Instance Methods (inherited from Object)
  // hashCode
  // runtimeType
  // noSuchMethod
  // toString

  // Operators (inherited from Object)
  // operator ==

```

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

### Telemetrydecksdk Class Methods Overview

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/Telemetrydecksdk/stopAndSendDurationSignal

An overview of the static methods available within the Telemetrydecksdk class, providing entry points for various SDK functionalities.

```APIDOC
Telemetrydecksdk Class Static Methods:

- generateNewSession()
  - Generates a new session for telemetry.

- navigate(String destination)
  - Navigates to a specified destination.

- navigateToDestination(String destination)
  - Navigates to a specified destination.

- send(String type, {Map<String, String>? payload})
  - Sends a telemetry event with a given type and payload.

- start(String appId, String telemetryKey)
  - Initializes the TelemetryDeck SDK with application ID and telemetry key.

- startDurationSignal(String signalType, {Map<String, String>? parameters})
  - Starts timing a duration signal.

- stop()
  - Stops the TelemetryDeck SDK.

- stopAndSendDurationSignal(String signalType, {Map<String, String>? parameters})
  - Stops a duration signal and sends it with parameters.

- updateDefaultUser(String userId)
  - Updates the default user ID for telemetry events.
```

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

### Telemetrydecksdk Static Methods

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/Telemetrydecksdk-class

Provides static methods for initializing, managing, and sending telemetry data. Includes session generation, navigation tracking, event reporting, and duration signal management.

```APIDOC
Telemetrydecksdk:
  // Generates a new session for telemetry tracking.
  generateNewSession() → Future<void>
    Description: Initializes a new telemetry session.
    Returns: A Future that completes when the session is generated.

  // Navigates between paths and tracks the navigation event.
  navigate(String sourcePath, String destinationPath, {String? clientUser}) → Future<void>
    Description: Records a navigation event from a source path to a destination path.
    Parameters:
      - sourcePath: The starting path of the navigation.
      - destinationPath: The target path of the navigation.
      - clientUser: Optional identifier for the user performing the navigation.
    Returns: A Future that completes when the navigation event is processed.

  // Navigates directly to a specified destination path.
  navigateToDestination(String destinationPath, {String? clientUser}) → Future<void>
    Description: Records an event indicating navigation to a specific destination.
    Parameters:
      - destinationPath: The target path for navigation.
      - clientUser: Optional identifier for the user.
    Returns: A Future that completes when the navigation event is processed.

  // Sends a custom telemetry signal.
  send(String signalType, {String? clientUser, Map<String, dynamic>? additionalPayload}) → Future<void>
    Description: Sends a custom signal with optional user context and additional payload data.
    Parameters:
      - signalType: The type or name of the signal being sent.
      - clientUser: Optional identifier for the user associated with the signal.
      - additionalPayload: Optional map of key-value pairs for extra data.
    Returns: A Future that completes when the signal is sent.

  // Starts the telemetry manager with a configuration.
  start(TelemetryManagerConfiguration configuration) → Future<void>
    Description: Initializes and starts the telemetry manager with the provided configuration.
    Parameters:
      - configuration: An instance of TelemetryManagerConfiguration.
    Returns: A Future that completes when the manager has started.

  // Starts a duration-based telemetry signal.
  startDurationSignal(String signalType, {Map<String, String>? parameters}) → Future<void>
    Description: Begins timing for a specific signal type, optionally with associated parameters.
    Parameters:
      - signalType: The type of the duration signal.
      - parameters: Optional map of string key-value pairs for signal context.
    Returns: A Future that completes when the duration signal has started.

  // Stops the telemetry manager.
  stop() → Future<void>
    Description: Shuts down the telemetry manager and stops all ongoing operations.
    Returns: A Future that completes when the manager has stopped.

  // Stops a duration signal and sends it with its recorded duration.
  stopAndSendDurationSignal(String signalType, {Map<String, String>? parameters}) → Future<void>
    Description: Stops a previously started duration signal and sends it along with any parameters.
    Parameters:
      - signalType: The type of the duration signal to stop and send.
      - parameters: Optional map of string key-value pairs to include with the sent signal.
    Returns: A Future that completes when the duration signal is stopped and sent.

  // Updates the default client user identifier.
  updateDefaultUser(String clientUser) → Future<void>
    Description: Sets or updates the default user identifier used for subsequent telemetry events.
    Parameters:
      - clientUser: The new default client user identifier.
    Returns: A Future that completes when the default user is updated.

```

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

### TelemetryManagerConfiguration API Documentation

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/TelemetryManagerConfiguration/TelemetryManagerConfiguration

Detailed API documentation for the TelemetryManagerConfiguration class, covering its constructors, properties, and methods for configuring telemetry.

```APIDOC
TelemetryManagerConfiguration:
  Constructors:
    TelemetryManagerConfiguration()
      - Creates a new instance of TelemetryManagerConfiguration.

  Properties:
    apiBaseURL: String
      - The base URL for the telemetry API.
    appID: String
      - The unique identifier for the application.
    debug: bool
      - Enables or disables debug logging.
    defaultParameterPrefix: String
      - The default prefix for custom parameters.
    defaultParameters: Map<String, String>
      - A map of default parameters to be included with every telemetry event.
    defaultSignalPrefix: String
      - The default prefix for custom signals.
    defaultUser: String
      - The default user identifier.
    namespace: String
      - The namespace for telemetry events.
    salt: String
      - A salt used for hashing or security purposes.
    testMode: bool
      - Enables test mode for the telemetry manager.

  Methods:
    copyWith({String? apiBaseURL, String? appID, bool? debug, String? defaultParameterPrefix, Map<String, String>? defaultParameters, String? defaultSignalPrefix, String? defaultUser, String? namespace, String? salt, bool? testMode})
      - Creates a new instance of TelemetryManagerConfiguration with updated properties.
    toMap(): Map<String, dynamic>
      - Converts the TelemetryManagerConfiguration instance to a Map.

  Operators:
    operator ==(Object other): bool
      - Compares this TelemetryManagerConfiguration instance with another object for equality.
```

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

### TelemetryManagerConfiguration Class API

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/TelemetryManagerConfiguration/namespace

Comprehensive API documentation for the TelemetryManagerConfiguration class. It includes details on its constructor, instance properties, and available methods for configuring telemetry.

```APIDOC
TelemetryManagerConfiguration:
  A configuration class for the TelemetryManager.

  Constructors:
    TelemetryManagerConfiguration()
      Initializes a new instance of TelemetryManagerConfiguration.

  Properties:
    apiBaseURL: String?
      The base URL for the telemetry API.
    appID: String?
      The unique identifier for the application.
    debug: bool?
      Enables or disables debug mode for telemetry.
    defaultParameterPrefix: String?
      The default prefix for telemetry parameters.
    defaultParameters: Map<String, String>?
      A map of default parameters to be included with telemetry events.
    defaultSignalPrefix: String?
      The default prefix for telemetry signals.
    defaultUser: String?
      The default user identifier for telemetry events.
    namespace: String?
      The namespace for telemetry events.
    salt: String?
      A salt value used for hashing or security purposes.
    testMode: bool?
      Enables or disables test mode for telemetry.

  Methods:
    copyWith({String? apiBaseURL, String? appID, bool? debug, String? defaultParameterPrefix, Map<String, String>? defaultParameters, String? defaultSignalPrefix, String? defaultUser, String? namespace, String? salt, bool? testMode})
      Creates a new instance of TelemetryManagerConfiguration by copying existing values and applying optional overrides.
      Returns: A new TelemetryManagerConfiguration instance.
    toMap(): Map<String, dynamic>
      Converts the TelemetryManagerConfiguration object into a Map.
      Returns: A map representation of the configuration.

  Operators:
    operator ==(Object other): bool
      Compares this TelemetryManagerConfiguration instance with another object for equality.
      Returns: true if the objects are equal, false otherwise.
```

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

### Telemetrydecksdk.startDurationSignal Implementation

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/Telemetrydecksdk/startDurationSignal

The Dart implementation of the static method `startDurationSignal` which sends duration signals with optional parameters. It prepares the payload by stringifying values and then calls the platform instance to execute the signal.

```Dart
static Future<void> startDurationSignal(
  String signalType,
  {
  Map<String, String>? parameters,
}
) async {
  final payload = parameters ?? {};

  final stringifiedPayload = payload.map(
    (key, value) => MapEntry(key, value.toString()),
  );

  await TelemetrydecksdkPlatform.instance.startDurationSignal(
    signalType,
    parameters: stringifiedPayload,
  );
}
```

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

### Telemetrydecksdk Class API

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/Telemetrydecksdk/start

API reference for the Telemetrydecksdk class, outlining its methods for managing telemetry sessions, sending data, and handling navigation events.

```APIDOC
Telemetrydecksdk:
  start(TelemetryManagerConfiguration configuration)
    - Initializes the SDK with the given configuration.
    - Parameters:
      - configuration: The configuration object for the telemetry manager.
    - Returns: A Future that completes when the SDK has started.

  generateNewSession()
    - Generates a new telemetry session.
    - Returns: void

  navigate(String destination)
    - Records a navigation event to a specified destination.
    - Parameters:
      - destination: The identifier of the destination.
    - Returns: void

  navigateToDestination(String destination)
    - Records a navigation event to a specified destination (alias for navigate).
    - Parameters:
      - destination: The identifier of the destination.
    - Returns: void

  send(String eventName, {Map<String, String>? parameters})
    - Sends a custom telemetry event with optional parameters.
    - Parameters:
      - eventName: The name of the event.
      - parameters: A map of key-value pairs for event parameters.
    - Returns: void

  startDurationSignal(String signalName)
    - Starts timing for a duration signal.
    - Parameters:
      - signalName: The name of the signal to time.
    - Returns: void

  stop(String signalName)
    - Stops timing for a duration signal.
    - Parameters:
      - signalName: The name of the signal to stop.
    - Returns: void

  stopAndSendDurationSignal(String signalName)
    - Stops timing for a duration signal and sends it.
    - Parameters:
      - signalName: The name of the signal to stop and send.
    - Returns: void

  updateDefaultUser(String userId)
    - Updates the default user ID for subsequent telemetry events.
    - Parameters:
      - userId: The new default user ID.
    - Returns: void
```

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

### navigateToDestination Implementation

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/Telemetrydecksdk/navigateToDestination

The Dart implementation of the static navigateToDestination method within the Telemetrydecksdk class. It calls the platform-specific instance to perform the navigation.

```dart
static Future<void> navigateToDestination(String destinationPath,
    {String? clientUser}) async {
  await TelemetrydecksdkPlatform.instance
      .navigateToDestination(destinationPath, clientUser: clientUser);
}
```

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

### TelemetryManagerConfiguration Implementation

Source: https://pub.dev/documentation/telemetrydecksdk/latest/telemetrydecksdk/TelemetryManagerConfiguration/TelemetryManagerConfiguration

The Dart implementation of the TelemetryManagerConfiguration constructor, showing how the provided parameters are assigned to the class's properties.

```dart
const TelemetryManagerConfiguration({
    required this.appID,
    this.apiBaseURL,
    this.defaultUser,
    this.debug,
    this.testMode,
    this.salt,
    this.defaultSignalPrefix,
    this.defaultParameterPrefix,
    this.defaultParameters,
    this.namespace
});
```
Tokens:
Raw