[x-license] Introduce usage telemetry

.codesandbox/ci.json

@@ -4,6 +4,7 @@
   "node": "20",
   "packages": [
     "packages/x-license",
+    "packages/x-telemetry",
     "packages/x-data-grid",
     "packages/x-data-grid-pro",
     "packages/x-data-grid-premium",
@@ -19,6 +20,7 @@
   ],
   "publishDirectory": {
     "@mui/x-license": "packages/x-license/build",
+    "@mui/x-telemetry": "packages/x-telemetry/build",
     "@mui/x-data-grid": "packages/x-data-grid/build",
     "@mui/x-data-grid-pro": "packages/x-data-grid-pro/build",
     "@mui/x-data-grid-premium": "packages/x-data-grid-premium/build",

.eslintrc.js

@@ -299,6 +299,12 @@ module.exports = {
         ],
       },
     },
+    {
+      files: ['packages/x-telemetry/**/*{.tsx,.ts,.js}'],
+      rules: {
+        'no-console': 'off',
+      },
+    },
     ...buildPackageRestrictedImports('@mui/x-charts', 'x-charts', false),
     ...buildPackageRestrictedImports('@mui/x-charts-pro', 'x-charts-pro', false),
     ...buildPackageRestrictedImports('@mui/x-codemod', 'x-codemod', false),
@@ -311,6 +317,7 @@ module.exports = {
     ...buildPackageRestrictedImports('@mui/x-tree-view', 'x-tree-view', false),
     ...buildPackageRestrictedImports('@mui/x-tree-view-pro', 'x-tree-view-pro', false),
     ...buildPackageRestrictedImports('@mui/x-license', 'x-license'),
+    ...buildPackageRestrictedImports('@mui/x-telemetry', 'x-telemetry'),
 
     ...addReactCompilerRule(chartsPackages, ENABLE_REACT_COMPILER_PLUGIN_CHARTS),
     ...addReactCompilerRule(dataGridPackages, ENABLE_REACT_COMPILER_PLUGIN_DATA_GRID),

babel.config.js

@@ -22,6 +22,7 @@ const defaultAlias = {
   '@mui/x-data-grid-pro': resolveAliasPath('./packages/x-data-grid-pro/src'),
   '@mui/x-data-grid-premium': resolveAliasPath('./packages/x-data-grid-premium/src'),
   '@mui/x-license': resolveAliasPath('./packages/x-license/src'),
+  '@mui/x-telemetry': resolveAliasPath('./packages/x-telemetry/src'),
   '@mui/x-date-pickers': resolveAliasPath('./packages/x-date-pickers/src'),
   '@mui/x-date-pickers-pro': resolveAliasPath('./packages/x-date-pickers-pro/src'),
   '@mui/x-charts': resolveAliasPath('./packages/x-charts/src'),

docs/data/guides/telemetry/telemetry.md

@@ -0,0 +1,75 @@
+---
+packageName: '@mui/x-telemetry'
+---
+
+# MUI X Telemetry guide
+
+<p class="description">MUI X Telemetry collects anonymous usage data to help improve the library. This guide walk you through how to opt-in, opt-out, and configure telemetry.</p>
+
+## Opting In
+
+Currently, **Telemetry is disabled by default**. To opt-in, you can use one of the following methods:
+
+### Setting the Environment Variable
+
+You can set the `MUI_X_TELEMETRY_DISABLED` environment variable to `false` to enable telemetry:
+
+```bash
+MUI_X_TELEMETRY_DISABLED=false
+```
+
+> Note that some frameworks may require you to prefix the environment variable with `REACT_APP_`, `NEXT_PUBLIC_`, etc.
+
+### Import telemetry settings from `@mui/x-license` package
+
+You can use `muiXTelemetrySettings` to enable telemetry:
+
+```js
+import { muiXTelemetrySettings } from '@mui/x-license';
+
+muiXTelemetrySettings.enableTelemetry();
+```
+
+### Setting the Flag in Your Application
+
+You can set the `__MUI_X_TELEMETRY_DISABLED__` flag in your application to `false` to enable telemetry:
+
+```js
+import { ponyfillGlobal } from '@mui/utils';
+
+ponyfillGlobal.__MUI_X_TELEMETRY_DISABLED__ = false;
+```
+
+## Opting Out
+
+To opt-out of telemetry, you can use one of the following methods:
+
+### Setting the Environment Variable
+
+You can set the `MUI_X_TELEMETRY_DISABLED` environment variable to `true` to disable telemetry:
+
+```bash
+MUI_X_TELEMETRY_DISABLED=true
+```
+
+> Note that some frameworks may require you to prefix the environment variable with `REACT_APP_`, `NEXT_PUBLIC_`, etc.
+
+### Import telemetry settings from `@mui/x-license` package
+
+You can use `muiXTelemetrySettings` to disable telemetry:
+
+```js
+import { muiXTelemetrySettings } from '@mui/x-license';
+
+muiXTelemetrySettings.disableTelemetry();
+```
+
+### Setting the Flag in Your Application
+
+You can set the `__MUI_X_TELEMETRY_DISABLED__` flag in your application to `true` to disable telemetry:
+
+```js
+import { ponyfillGlobal } from '@mui/utils';
+
+ponyfillGlobal.__MUI_X_TELEMETRY_DISABLED__ = true;
+```

docs/pages/_app.js

@@ -8,6 +8,7 @@ import NextHead from 'next/head';
 import PropTypes from 'prop-types';
 import { useRouter } from 'next/router';
 import { LicenseInfo } from '@mui/x-license';
+import { muiXTelemetrySettings } from '@mui/x-telemetry';
 import { ponyfillGlobal } from '@mui/utils';
 import PageContext from 'docs/src/modules/components/PageContext';
 import GoogleAnalytics from 'docs/src/modules/components/GoogleAnalytics';
@@ -24,6 +25,8 @@ import { DocsProvider } from '@mui/docs/DocsProvider';
 import { mapTranslations } from '@mui/docs/i18n';
 import * as config from '../config';
 
+// Enable telemetry for internal purposes
+muiXTelemetrySettings.enableTelemetry();
 // Remove the license warning from demonstration purposes
 LicenseInfo.setLicenseKey(process.env.NEXT_PUBLIC_MUI_LICENSE);
 

docs/pages/x/guides/telemetry.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from 'docsx/data/guides/telemetry/telemetry.md?muiMarkdown';
+
+export default function Page() {
+  return <MarkdownDocs {...pageProps} disableAd />;
+}

docs/public/_redirects

@@ -19,6 +19,7 @@
 /r/x-pro-svg-link https://mui.com/x/introduction/licensing/#pro-plan 302
 /r/x-premium-svg https://mui.com/static/x/premium.svg 302
 /r/x-premium-svg-link https://mui.com/x/introduction/licensing/#premium-plan 302
+/r/x-telemetry-postinstall-troubleshoot https://github.com/mui/mui-x/issues/new?assignees=&labels=status%3A+waiting+for+maintainer%2Cbug+%F0%9F%90%9B&projects=&template=1.bug.yml&title=MUI+X+Telemetry+failed+to+make+initialization 302
 
 # Legacy redirection
 # Added in chronological order (the last line is the most recent one)

packages/x-license/package.json

@@ -36,6 +36,7 @@
   "dependencies": {
     "@babel/runtime": "^7.26.9",
     "@mui/utils": "^5.16.6 || ^6.0.0 || ^7.0.0-alpha",
+    "@mui/x-telemetry": "workspace:*",
     "@mui/x-internals": "workspace:*"
   },
   "peerDependencies": {

packages/x-license/src/index.ts

@@ -4,3 +4,4 @@ export * from './verifyLicense';
 export * from './useLicenseVerifier';
 export * from './Watermark';
 export * from './Unstable_LicenseInfoProvider';
+export { muiXTelemetrySettings } from '@mui/x-telemetry';

packages/x-license/src/useLicenseVerifier/useLicenseVerifier.ts

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import { sendMuiXTelemetryEvent, muiXTelemetryEvents } from '@mui/x-telemetry';
 import { verifyLicense } from '../verifyLicense/verifyLicense';
 import { LicenseInfo } from '../utils/licenseInfo';
 import {
@@ -50,6 +51,17 @@ export function useLicenseVerifier(
 
     const fullPackageName = `@mui/${packageName}`;
 
+    sendMuiXTelemetryEvent(
+      muiXTelemetryEvents.licenseVerification(
+        { licenseKey },
+        {
+          packageName,
+          packageReleaseInfo: releaseInfo,
+          licenseStatus: licenseStatus?.status,
+        },
+      ),
+    );
+
     if (licenseStatus.status === LICENSE_STATUS.Valid) {
       // Skip
     } else if (licenseStatus.status === LICENSE_STATUS.Invalid) {

packages/x-license/tsconfig.build.json

@@ -10,7 +10,10 @@
     "outDir": "build/esm",
     "rootDir": "./src"
   },
-  "references": [{ "path": "../x-internals/tsconfig.build.json" }],
+  "references": [
+    { "path": "../x-internals/tsconfig.build.json" },
+    { "path": "../x-telemetry/tsconfig.build.json" }
+  ],
   "include": ["src/**/*.ts*"],
   "exclude": ["src/**/*.spec.ts*", "src/**/*.test.ts*"]
 }

packages/x-telemetry/LICENSE

@@ -0,0 +1,11 @@
+Commercial License
+
+Copyright (c) 2020 Material-UI SAS
+
+MUI X Pro (https://mui.com/pricing/) is commercial software. You MUST agree to the
+End User License Agreement (EULA: https://mui.com/r/x-license-eula) to be able to
+use the software.
+
+This means that you either need to purchase a commercial license at
+https://mui.com/r/x-get-license?scope=pro or be eligible for the Evaluation (trial)
+licenses detailed at https://mui.com/r/x-license-trial.

packages/x-telemetry/README.md

@@ -0,0 +1,51 @@
+# @mui/x-telemetry
+
+Package used by some of MUI X to collects **anonymous** telemetry data about general usage. Participation in this anonymous program is optional, and you may opt-out if you'd not like to share any information.
+
+## How to opt-in
+
+Currently, **it's disabled by default,** and you could opt-in to it in 3 ways:
+
+1. By setting it directly to package settings on the application start (e.g. in main file).
+
+```js
+import { muiXTelemetrySettings } from '@mui/x-telemetry';
+// or
+import { muiXTelemetrySettings } from '@mui/x-license';
+
+muiXTelemetrySettings.enableTelemetry(); // to enable telemetry collection and sending
+// or
+muiXTelemetrySettings.disableTelemetry(); // to disable telemetry collection and sending
+```
+
+2. By setting the environment variable.
+
+```dotenv
+MUI_X_TELEMETRY_DISABLED=false # Enable telemetry
+# or
+MUI_X_TELEMETRY_DISABLED=true # Enable telemetry
+```
+
+> ⚠️ Note that some frameworks requires to prefix the variable with `REACT_APP_`, `NEXT_PUBLIC_`, etc.
+
+3. By setting the flag to global object on the application start (e.g. in main file).
+
+```js
+import { ponyfillGlobal } from '@mui/utils';
+
+ponyfillGlobal.__MUI_X_TELEMETRY_DISABLED__ = false; // enabled
+// or
+ponyfillGlobal.__MUI_X_TELEMETRY_DISABLED__ = true; // disabled
+```
+
+OR
+
+```js
+if (typeof window !== 'undefined') {
+  window.__MUI_X_TELEMETRY_DISABLED__ = false; // enabled
+}
+// or
+if (typeof window !== 'undefined') {
+  window.__MUI_X_TELEMETRY_DISABLED__ = true; // disabled
+}
+```

packages/x-telemetry/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@mui/x-telemetry",
+  "version": "8.0.0-alpha.12",
+  "description": "MUI X Telemetry",
+  "author": "MUI Team",
+  "main": "src/index.ts",
+  "license": "SEE LICENSE IN LICENSE",
+  "bugs": {
+    "url": "https://github.com/mui/mui-x/issues"
+  },
+  "homepage": "https://mui.com/x/guides/telemetry/",
+  "publishConfig": {
+    "access": "public",
+    "directory": "build"
+  },
+  "scripts": {
+    "typescript": "tsc -p tsconfig.json",
+    "build": "pnpm build:modern && pnpm build:node && pnpm build:stable && pnpm build:types && pnpm build:copy-files ",
+    "build:modern": "node ../../scripts/build.mjs modern",
+    "build:node": "node ../../scripts/build.mjs node",
+    "build:stable": "node ../../scripts/build.mjs stable",
+    "build:copy-files": "node ../../scripts/copyFiles.mjs && node ./scripts/addPackageScripts.js",
+    "build:types": "tsx ../../scripts/buildTypes.mts",
+    "prebuild": "rimraf build tsconfig.build.tsbuildinfo"
+  },
+  "sideEffects": false,
+  "packageScripts": {
+    "postinstall": "node ./postinstall/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mui/mui-x.git",
+    "directory": "packages/x-telemetry"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.26.9",
+    "@fingerprintjs/fingerprintjs": "^4.6.0",
+    "@mui/utils": "^5.16.6 || ^6.0.0",
+    "ci-info": "^4.0.0",
+    "conf": "^5.0.0",
+    "is-docker": "^2.2.1",
+    "node-machine-id": "^1.1.12"
+  },
+  "devDependencies": {
+    "@mui/internal-test-utils": "^2.0.2",
+    "@types/device-uuid": "^1.0.3",
+    "rimraf": "^6.0.1"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

packages/x-telemetry/scripts/addPackageScripts.js

@@ -0,0 +1,19 @@
+const fs = require('fs');
+const path = require('path');
+
+const packageDir = process.cwd();
+
+const packageJsonPath = path.join(packageDir, 'package.json');
+const packageJsonFileContent = fs.readFileSync(packageJsonPath, 'utf8');
+const packageJson = JSON.parse(packageJsonFileContent);
+
+if (packageJson.packageScripts) {
+  const buildPackageJsonPath = path.join(packageDir, 'build/package.json');
+  const buildPackageJsonFileContent = fs.readFileSync(buildPackageJsonPath, 'utf8');
+  const buildPackageJson = JSON.parse(buildPackageJsonFileContent);
+
+  buildPackageJson.scripts = packageJson.packageScripts;
+  delete buildPackageJson.packageScripts;
+
+  fs.writeFileSync(buildPackageJsonPath, JSON.stringify(buildPackageJson, null, 2));
+}

packages/x-telemetry/src/context.ts

@@ -0,0 +1,25 @@
+// This file will be modified by the `postinstall` script.
+// See postinstall/index.ts for more information.
+
+export interface TelemetryContextType {
+  config: {
+    isInitialized: boolean;
+  };
+  traits: Record<string, any> & {
+    machineId?: string | null;
+    projectId?: string | null;
+    sessionId?: string | null;
+    anonymousId?: string | null;
+    isDocker?: boolean;
+    isCI?: boolean;
+  };
+}
+
+const defaultValue: TelemetryContextType = {
+  config: {
+    isInitialized: false,
+  },
+  traits: {},
+};
+
+export default defaultValue;

packages/x-telemetry/src/index.ts

@@ -0,0 +1,21 @@
+import muiXTelemetryEvents from './runtime/events';
+import sendMuiXTelemetryEventOriginal from './runtime/sender';
+import muiXTelemetrySettingsOriginal from './runtime/settings';
+
+const noop = () => {};
+
+// To cut unused imports in production as early as possible
+const sendMuiXTelemetryEvent =
+  process.env.NODE_ENV === 'production' ? noop : sendMuiXTelemetryEventOriginal;
+
+// To cut unused imports in production as early as possible
+const muiXTelemetrySettings =
+  process.env.NODE_ENV === 'production'
+    ? {
+        enableDebug: noop,
+        enableTelemetry: noop,
+        disableTelemetry: noop,
+      }
+    : muiXTelemetrySettingsOriginal;
+
+export { muiXTelemetryEvents, sendMuiXTelemetryEvent, muiXTelemetrySettings };