[x-license] Introduce usage telemetry (#13530)

Signed-off-by: Vadym Raksha <[email protected]>

Author: hasdfa

.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) {