Merge pull request #837 from NordicSemiconductor/enhance/telemetry_api

Enhance telemetry API

Changelog.md

@@ -7,6 +7,29 @@ This project does _not_ adhere to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) but contrary to it
 every new version is a new major version.
 
+## 151.0.0 - 2024-01-23
+
+### Changed
+
+-   Renamed exported object `usageData` to `telemetry` and type
+    `UsageDataMetadata` to `TelemetryMetadata`.
+-   Renamed several function in the `telemetry` object:
+    -   `enable()` → `setUsersAgreedToTelemetry(true)`
+    -   `disable()` → `setUsersAgreedToTelemetry(false)`
+    -   `reset()` → `setUsersWithdrewTelemetryAgreement()`
+    -   `isEnabled()` → `getIsSendingTelemetry()` (which now does not log
+        anymore)
+    -   `sendUsageData()` → `sendEvent()`
+-   In the component `ErrorBoundary` the property `sendUsageData` is renamed to
+    `sendTelemetryEvent`.
+
+### Steps to upgrade when using this package
+
+-   If they are imported from shared, rename `usageData` and `UsageDataMetadata`
+    as well as the renamed functions mentioned above.
+-   In usages of the component `ErrorBoundary`, rename the property
+    `sendUsageData` to `sendTelemetryEvent`.
+
 ## 150.0.0 - 2024-01-18
 
 ### Removed
@@ -216,7 +239,7 @@ every new version is a new major version.
 
 ### Fixed
 
--   Telemtry: Metadata was not removed on request, when being in the main
+-   Telemetry: Metadata was not removed on request, when being in the main
     process. This is not critical because this code isn't yet executed in real
     life.
 

nrfutil/sandbox.ts

@@ -332,7 +332,7 @@ export class NrfutilSandbox {
     ) =>
         new Promise<void>((resolve, reject) => {
             let aborting = false;
-            telemetry.sendUsageData(`running nrfutil ${this.module}`, {
+            telemetry.sendEvent(`running nrfutil ${this.module}`, {
                 args,
                 exec: command,
             });
@@ -513,7 +513,7 @@ export class NrfutilSandbox {
     ) =>
         new Promise<void>((resolve, reject) => {
             let aborting = false;
-            telemetry.sendUsageData(`running nrfutil ${this.module}`, {
+            telemetry.sendEvent(`running nrfutil ${this.module}`, {
                 args,
                 exec: command,
             });

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nordicsemiconductor/pc-nrfconnect-shared",
-    "version": "150.0.0",
+    "version": "151.0.0",
     "description": "Shared commodities for developing pc-nrfconnect-* packages",
     "repository": {
         "type": "git",
@@ -25,7 +25,7 @@
         "prepare": "ts-node scripts/installHusky.ts",
         "release-shared": "ts-node scripts/release-shared.ts",
         "prepare-shared-release": "ts-node scripts/prepare-shared-release.ts",
-        "clean": "rimraf dist typings/generated dist scripts/nordic-publish.js",
+        "clean": "rimraf dist typings/generated scripts/nordic-publish.js",
         "postinstall": "ts-node scripts/postinstall.ts"
     },
     "dependencies": {

src/Device/DeviceSelector/DeviceSelector.tsx

@@ -71,7 +71,7 @@ export default ({
     const doDeselectDevice = useCallback(
         (device?: Device) => {
             if (device) {
-                telemetry.sendUsageData(
+                telemetry.sendEvent(
                     'device deselected ',
                     simplifyDevice(device)
                 );
@@ -120,7 +120,7 @@ export default ({
             dispatch(setSelectedDeviceInfo(deviceInfo));
             onDeviceSelected(device, autoReselected);
 
-            telemetry.sendUsageData('device selected', {
+            telemetry.sendEvent('device selected', {
                 device: simplifyDevice(device),
                 deviceInfo,
             });

src/Device/deviceLister.ts

@@ -180,7 +180,7 @@ export const startWatchingDevices =
 
             const action = async (device: Device) => {
                 if (hasValidDeviceTraits(device.traits, deviceListing)) {
-                    telemetry.sendUsageData(
+                    telemetry.sendEvent(
                         'device connected',
                         simplifyDevice(device)
                     );

src/ErrorBoundary/ErrorBoundary.test.tsx

@@ -44,14 +44,14 @@ describe('ErrorBoundary', () => {
     });
 
     it('can take custom reporting functions', () => {
-        const sendUsageData = jest.fn();
+        const sendTelemetryEvent = jest.fn();
 
         render(
-            <ErrorBoundary sendUsageData={sendUsageData}>
+            <ErrorBoundary sendTelemetryEvent={sendTelemetryEvent}>
                 <Child />
             </ErrorBoundary>
         );
-        expect(sendUsageData).toHaveBeenCalled();
+        expect(sendTelemetryEvent).toHaveBeenCalled();
     });
 
     it('should render error boundary component when there is an error', () => {

src/ErrorBoundary/ErrorBoundary.tsx

@@ -32,7 +32,7 @@ interface Props {
     devices?: Device[];
     appName?: string;
     restoreDefaults?: () => void;
-    sendUsageData?: (message: string) => void;
+    sendTelemetryEvent?: (message: string) => void;
 }
 
 const genericRestoreDefaults = () => {
@@ -61,11 +61,15 @@ class ErrorBoundary extends React.Component<
     }
 
     componentDidCatch(error: Error) {
-        const { devices, selectedDevice, selectedSerialNumber, sendUsageData } =
-            this.props;
+        const {
+            devices,
+            selectedDevice,
+            selectedSerialNumber,
+            sendTelemetryEvent,
+        } = this.props;
 
-        sendUsageData != null
-            ? sendUsageData(error.message)
+        sendTelemetryEvent != null
+            ? sendTelemetryEvent(error.message)
             : sendErrorReport(error.message);
 
         generateSystemReport(

src/index.ts

@@ -77,8 +77,8 @@ export {
 export { openUrl, openFile } from './utils/open';
 export { default as systemReport } from './utils/systemReport';
 
-export { default as usageData } from './telemetry/telemetry';
-export { type default as UsageDataMetadata } from './telemetry/TelemetryMetadata';
+export { default as telemetry } from './telemetry/telemetry';
+export { type default as TelemetryMetadata } from './telemetry/TelemetryMetadata';
 export { default as classNames } from './utils/classNames';
 export { truncateMiddle } from './utils/truncateMiddle';
 

src/telemetry/TelemetrySender.ts

@@ -33,44 +33,42 @@ export default abstract class TelemetrySender {
         this.isTelemetryAllowedForCurrentApp &&
         getHasUserAgreedToTelemetry() === true;
 
-    /**
-     * @deprecated Use `getIsSendingTelemetry` instead
-     * @returns {boolean} If telemetry is enabled
-     */
-    isEnabled() {
-        const isSendingTelemetry = this.getIsSendingTelemetry();
-        this.logger?.debug(`Telemetry is ${isSendingTelemetry}`);
-
-        return isSendingTelemetry;
-    }
-
-    async enable() {
-        persistHasUserAgreedToTelemetry(true);
-        this.sendUsageData('Telemetry Opt-In');
+    async sendAgreementEvent() {
+        this.sendEvent('Telemetry Opt-In');
 
         const { platform, arch } = await si.osInfo();
-        this.sendUsageData('Report OS info', { platform, arch });
+        this.sendEvent('Report OS info', { platform, arch });
+    }
 
-        this.logger?.debug('Usage data has been enabled');
+    sendDisagreementEvent() {
+        this.sendMinimalEvent('Telemetry Opt-Out');
     }
 
-    disable() {
-        persistHasUserAgreedToTelemetry(false);
-        this.sendMinimalUsageData('Telemetry Opt-Out');
-        this.logger?.debug('Usage data has been disabled');
+    async setUsersAgreedToTelemetry(hasAgreed: boolean) {
+        persistHasUserAgreedToTelemetry(hasAgreed);
+
+        if (hasAgreed) {
+            await this.sendAgreementEvent();
+        } else {
+            this.sendDisagreementEvent();
+        }
+
+        this.logger?.debug(
+            `Telemetry has been ${hasAgreed ? 'enabled' : 'disabled'}`
+        );
     }
 
-    reset() {
+    setUsersWithdrewTelemetryAgreement() {
         deleteHasUserAgreedToTelemetry();
-        this.sendMinimalUsageData('Telemetry Opt-Reset');
-        this.logger?.debug('Usage data setting has been reset');
+        this.sendMinimalEvent('Telemetry Opt-Reset');
+        this.logger?.debug('Telemetry has been reset');
     }
 
-    sendMinimalUsageData(action: string) {
-        this.sendUsageData(action, { removeAllMetadata: true });
+    sendMinimalEvent(action: string) {
+        this.sendEvent(action, { removeAllMetadata: true });
     }
 
-    abstract sendUsageData(
+    abstract sendEvent(
         action: string,
         metadata?: TelemetryMetadata
     ): MaybePromise<void>;

src/telemetry/TelemetrySenderInMain.ts

@@ -58,9 +58,9 @@ export default class TelemetrySenderInMain extends TelemetrySender {
 
     getClient = () => this.client ?? this.initClient();
 
-    sendUsageData = (action: string, metadata?: TelemetryMetadata) => {
+    sendEvent = (action: string, metadata?: TelemetryMetadata) => {
         this.getClient().trackEvent({ name: action, properties: metadata });
-        this.logger?.debug(`Sending usage data ${JSON.stringify(action)}`);
+        this.logger?.debug(`Sending event ${JSON.stringify(action)}`);
     };
 
     sendPageView = (pageName: string) =>

src/telemetry/TelemetrySenderInRenderer.ts

@@ -63,9 +63,9 @@ export default class TelemetrySenderInRenderer extends TelemetrySender {
 
     getClient = () => this.client ?? this.initClient();
 
-    sendUsageData = async (action: string, metadata?: TelemetryMetadata) => {
+    sendEvent = async (action: string, metadata?: TelemetryMetadata) => {
         (await this.getClient()).trackEvent({ name: action }, metadata);
-        this.logger?.debug(`Sending usage data ${JSON.stringify(action)}`);
+        this.logger?.debug(`Sending event ${JSON.stringify(action)}`);
     };
 
     sendPageView = async (pageName: string) =>

src/telemetry/telemetry.ts

@@ -47,10 +47,12 @@ const getTelemetrySenderIfEnabled = () => {
 
 const setLogger = (logger: Logger) =>
     getTelemetrySenderUnconditionally().setLogger(logger);
-const enable = () => getTelemetrySenderUnconditionally().enable();
-const isEnabled = () => getTelemetrySenderUnconditionally().isEnabled();
-const disable = () => getTelemetrySenderUnconditionally().disable();
-const reset = () => getTelemetrySenderUnconditionally().reset();
+const setUsersAgreedToTelemetry = (hasAgreed: boolean) =>
+    getTelemetrySenderUnconditionally().setUsersAgreedToTelemetry(hasAgreed);
+const getIsSendingTelemetry = () =>
+    getTelemetrySenderUnconditionally().getIsSendingTelemetry();
+const setUsersWithdrewTelemetryAgreement = () =>
+    getTelemetrySenderUnconditionally().setUsersWithdrewTelemetryAgreement();
 const enableTelemetry = () =>
     getTelemetrySenderUnconditionally().allowTelemetryForCurrentApp();
 
@@ -59,8 +61,8 @@ const enableTelemetry = () =>
 const getFriendlyAppName = () =>
     packageJson().name.replace('pc-nrfconnect-', '');
 
-const sendUsageData = (action: string, metadata?: TelemetryMetadata) =>
-    getTelemetrySenderIfEnabled()?.sendUsageData(
+const sendEvent = (action: string, metadata?: TelemetryMetadata) =>
+    getTelemetrySenderIfEnabled()?.sendEvent(
         `${getFriendlyAppName()}: ${action}`,
         flatObject(metadata)
     );
@@ -83,12 +85,11 @@ const sendErrorReport = (error: string | Error) =>
 
 export default {
     setLogger,
-    disable,
-    enable,
-    isEnabled,
-    reset,
+    setUsersAgreedToTelemetry,
+    setUsersWithdrewTelemetryAgreement,
+    getIsSendingTelemetry,
     sendErrorReport,
-    sendUsageData,
+    sendEvent,
     sendPageView,
     sendMetric,
     sendTrace,

src/utils/useHotKey.ts

@@ -18,7 +18,7 @@ const useNewHotKey = (shortcut: Shortcut, deps: DependencyList = []) => {
 
         Mousetrap.bind(shortcut.hotKey, (_e, combo) => {
             shortcut.action();
-            telemetry.sendUsageData('pressed hotkey', { combo });
+            telemetry.sendEvent('pressed hotkey', { combo });
         });
 
         return () => {