telemetry

Import

React
Angular
Vue.js

// with @dhl-official/react-library:
import { DhlTelementry } from "@dhl-official/react-library"

// with @dhl-official/ui-libraries/react-library:
import { DhlTelementry } from "@dhl-official/ui-libraries/react-library"

If the DUIL has been installed, you can use the web component directly:

<dhl-telementry></dhl-telementry>

// with @dhl-official/vue-library:
import { DhlTelementry } from "@dhl-official/vue-library"

// with @dhl-official/ui-libraries/vue-library:
import { DhlTelementry } from "@dhl-official/ui-libraries/vue-library"

Overview

This component enables the collection of telemetry data. Telemetry and data tracking are important features of our product that allow us to collect and analyze data about how our users interact with our product. This data can help us identify areas for improvement and make informed decisions about how to optimize our product.

In our product, telemetry and data tracking are used to monitor system performance, identify bugs and errors, and track user behavior. This information is used to improve the user experience and optimize the performance of our product.

The data is collected by the DHL User Interface Library Team to improve the quality of the components, gain better insights into the usage of the components' properties, and enhance the overall user and developer experiences.

The telemetry data is sent to the DHL User Interface Library Team's Azure Application Insights instance. To enable this functionality, all components of the DHL User Interface Library are configured to send telemetry data using the code in this component and stencil-library/src/utils/analytics.ts.

The component's props are mapped to custom data attributes and attached to the host element of the component. The analytics.ts file retrieves this components data attributes information to determine whether to send telemetry data.

The telemetry data is sent only if the data-dhl-telemetry-enabled attribute is present, and set to true.
However, it is the developer's responsibility to set this attribute to true or false based on the application's environment.

The component's props are mapped to custom data attributes and attached to the custom component's host element. The prop's name is prefixed with data-dhl-telemetry-. For example, the enabled prop is mapped to data-dhl-telemetry-enabled.

<dhl-telemetry enabled="true"></dhl-telemetry>;

Will render as:

<dhl-telemetry data-dhl-telemetry-enabled="true"></dhl-telemetry>;

Or simply as:

<dhl-telemetry data-dhl-telemetry-enabled></dhl-telemetry>;

What data is collected?

When the telemetry is enabled, the data that is collected is specific per component.\ For each component, the data that is collected is about the values set to each of its properties. To this set of data, the following is added:

projectName: derived from the value projectName
projectRepo: derived from the value projectRepo
projectFramework: auto detected, or overridden by the value set to projectFramework
duilVersion: auto detected
duilDirection: auto detected
duilLang: auto detected
name: component.host.tagName || component.host.nodeName
url: auto detected with window.location.href

So, for example, the complete telemetry data for dhl-button component would look like this:

{
  "projectName": "project-name",
  "projectRepo": "https://git.project-name.example",
  "projectFramework": "Angular",
  "duilVersion": "2.5.5",
  "duilDirection": "ltr",
  "duilLang": "en",
  "name": "undefined",
  "url": "http://localhost:4200/",
  "dataAriaControls": "undefined",
  "dataAriaDisabled": "undefined",
  "dataAriaLabel": "undefined",
  "dataAriaLabelledby": "undefined",
  "dataAriaExpanded": "undefined",
  "dataAutoFocus": "undefined",
  "dataClassName": "custom-class-name",
  "dataTestid": "undefined",
  "dataTracking": "undefined",
  "form": "undefined",
  "dataId": "dhl-button-10yvk8b",
  "isBlock": "false",
  "isFullWidth": "false",
  "isDisabled": "false",
  "clickEvent": "undefined",
  "keyPressEvent": "undefined",
  "size": "md",
  "type": "button",
  "variant": "text",
  "iconSize": "undefined",
  "icon": "undefined",
  "iconOrientation": "right",
  "isRound": "undefined",
  "textVariant": "primary",
  "renderAs": "a",
  "renderAsProps": "{\"href\":\"https://docs.uilibrary.dhl/\",\"target\":\"_blank\"}",
  "isStyled": "false",
  "isDisabledState": "null",
  "iconState": "undefined",
  "hasIcon": "undefined",
  "renderAsPropsState": "{\"href\":\"https://docs.uilibrary.dhl/\",\"target\":\"_blank\"}"
}

How do I know if the telemetry is enabled?

The telemetry is enabled if the data-dhl-telemetry-enabled attribute is set to true. This attribute is set to false by default, but it is the developer's responsibility to set it to true or false based on the application's environment.

When the telemetry is enabled, the developer console will display a message:

+-------------------------------------------+
|                                           |
|       sending telemetry data, visit       |
|  https://docs.uilibrary.dhl/dhl-telemetry |
|           for more information            |
|                                           |
+-------------------------------------------+

If the value of debug is set to true, the developer console logs the full telemetry data for each component.

Usage

Dhl-telemetry

Snippets of code in HTML and JavaScript to show some of the use cases for the component.

simple usage in html

<dhl-telemetry 
  data-dhl-telemetry-enabled="true" 
  data-dhl-telemetry-debug="true"
  data-dhl-telemetry-project-name="Project Name"
  data-dhl-telemetry-project-repo="https://project.repo.com"
  data-dhl-telemetry-project-framework="javascript"
  ></dhl-telemetry>

simple usage with javascript

<dhl-telemetry ></dhl-telemetry>

<script>
  const telemetry = document.querySelector('dhl-telemetry')
  telemetry.setAttribute('data-dhl-telemetry-enabled', 'true');
  telemetry.setAttribute('data-dhl-telemetry-debug', 'true');
  telemetry.setAttribute('data-dhl-telemetry-project-name', 'Project Name');
  telemetry.setAttribute('data-dhl-telemetry-project-repo', 'https://project.repo.com');
  telemetry.setAttribute('data-dhl-telemetry-project-framework', 'javascript');
</script>

caution

Following are some snipped of code to demonstrate how to use the component in different frameworks.
The code is not meant to be complete and exhaustive nor to be used as a blue print but only to exemplify the usage of the component in different frameworks.
The examples may differ in terms of configuration, values set to the attributes, and the way the component is used in the different frameworks; this does not preclude the fact that the component can be used in the different frameworks in the same way.

example usage in Angular

It is suggested to make use if environment variables to set the values of the attributes to ease exclusion of telemetry in production builds.

`environment.development.ts`

import packageInfo from "./path/to/package.json";
export const environment = {
  production: false,
  canSendTelemetry: process.env["NODE_ENV"] !== "production",
  debugTelemetry: process.env["NODE_ENV"] !== "production",
  projectName: packageInfo.name,
  projectVersion: packageInfo.version,
  projectRepo: packageInfo.repository.url,
};

`app.component.ts`

export class AppComponent {
  canSendTelemetry = environment.canSendTelemetry;
  debugTelemetry = environment.canSendTelemetry && environment.debugTelemetry;
  projectName = environment.canSendTelemetry && environment.projectName ? environment.projectName + "@" + (environment.projectVersion || "") : null;
  projectRepo = environment.canSendTelemetry && environment.projectRepo;
}

`app.component.html`

<dhl-telemetry
  *ngIf="canSendTelemetry"
  [enabled]="canSendTelemetry"
  [debug]="debugTelemetry"
  [projectName]="projectName"
  [projectRepo]="projectRepo"
></dhl-telemetry>

example usage in React and Typescript

It is suggested to make use if environment variables to set the values of the attributes to ease exclusion of telemetry in production builds.
In order to understand the npm package.json variables read more here.

`.env.development`

REACT_APP_NAME=$npm_package_name
REACT_APP_VERSION=$npm_package_version
REACT_APP_ALLOW_TELEMETRY=true
REACT_APP_DEBUG_TELEMETRY=true

`App.tsx`

import { DhlTelemetry } from "@dhl-official/react-library";

function App() {
  const [canSendTelemetry] = useState(
    process.env.NODE_ENV !== "production" &&
      process.env.REACT_APP_ALLOW_TELEMETRY === "true"
  );

  const [canDebugTelemetry] = useState(
    process.env.REACT_APP_DEBUG_TELEMETRY === "true"
  );

  const [projectName] = useState(
    process.env.REACT_APP_NAME
      ? process.env.REACT_APP_NAME + "@" + process.env.REACT_APP_VERSION
      : undefined
  );
  return (
    <div>
      {canSendTelemetry && (
        <DhlTelemetry
          enabled={canSendTelemetry}
          debug={canDebugTelemetry}
          projectName={projectName}
        ></DhlTelemetry>
      )}
    </div>
  );
}

example usage in Vue, Typescript, and Vite

It is suggested to make use of environment variables to set the values of the attributes to ease exclusion of telemetry in production builds. In order to understand the npm package.json variables read more here.

`.env.development`

VITE_APP_NAME=$npm_package_name
VITE_APP_VERSION=$npm_package_version
VITE_APP_ALLOW_TELEMETRY=true
VITE_APP_DEBUG_TELEMETRY=false

`App.vue`

export default {
  name: "App",

  data() {
    return {
      canSendTelemetry: import.meta.env.DEV && import.meta.env.VITE_APP_ALLOW_TELEMETRY,
      debugTelemetry: import.meta.env.VITE_APP_DEBUG_TELEMETRY,
      projectName: import.meta.env.VITE_APP_NAME + "@" + import.meta.env.VITE_APP_VERSION,
    };
  },
};
</script>

<template>
  <dhl-telemetry
    v-if="canSendTelemetry"
    .enabled="canSendTelemetry"
    .debug="canSendTelemetry && debugTelemetry"
    .projectName="projectName"
  ></dhl-telemetry>
</template>

Properties

Property	Attribute	Description	Type	Default
`debug`	`data-dhl-telemetry-debug`	Indicates whether debug mode is enabled for telemetry.	`boolean`	`false`
`enabled`	`data-dhl-telemetry-enabled`	Indicates whether the DHL telemetry is enabled.	`boolean`	`false`
`projectFramework`	`data-dhl-telemetry-project-framework`	The framework of the project.	`string`	`null`
`projectName`	`data-dhl-telemetry-project-name`	The name of the project for telemetry data.	`string`	`null`
`projectRepo`	`data-dhl-telemetry-project-repo`	The url of the code repository of the project.	`string`	`null`

Built by DHL User Interface Library Team!

Import

Overview​

What data is collected?​

How do I know if the telemetry is enabled?​

Usage​

Dhl-telemetry​

simple usage in html​

simple usage with javascript​

example usage in Angular​

environment.development.ts​

app.component.ts​

app.component.html​

example usage in React and Typescript​

.env.development​

App.tsx​

example usage in Vue, Typescript, and Vite​

.env.development​

App.vue​

Properties​

Overview

What data is collected?

How do I know if the telemetry is enabled?

Usage

Dhl-telemetry

simple usage in html

simple usage with javascript

example usage in Angular

`environment.development.ts`

`app.component.ts`

`app.component.html`

example usage in React and Typescript

`.env.development`

`App.tsx`

example usage in Vue, Typescript, and Vite

`.env.development`

`App.vue`

Properties