Add app insights (#23303)

## Description

This PR adds user telemetry to the website through the integration of
AppInsights

Changes include:
- Added AppInsights config
- Set essential cookie with uuid to track usage analytics

docs/.env.template

@@ -5,3 +5,6 @@
 # Flag that determines whether or not repo-local API documentation should be generated and included in the site build.
 # Only used in local development.
 LOCAL_API_DOCS=<boolean>
+
+# Key used to authenticate with the Azure Application Insights API. Refer to README.md for more information.
+INSTRUMENTATION_KEY=<instrumentation_key>

docs/README.md

@@ -86,6 +86,32 @@ To include repo-local API documentation when building the site locally, you will
 So long as the `LOCAL_API_DOCS` environment variable is set to `true`, local API documentation will be included when building the site.
 To remove the local API docs, simply remove the above variable or set it to `false`, `npm run clean` and rebuild as needed.
 
+## User Telemetry
+
+The Fluid Framework website collects basic user telemetry to help improve the experience for our users.
+The telemetry data includes anonymous information such as:
+
+-   Daily / Monthly users
+-   Pages visited
+-   User flow
+
+This data is collected in compliance with relevant privacy standards.
+For more information, please refer to our [privacy policy.](https://www.microsoft.com/privacy/privacystatement).
+If you have any concerns about telemetry, please reach out to our team via [GitHub Issues](https://github.com/microsoft/FluidFramework/issues).
+
+To test this telemetry locally add the following key to the .env file.
+This key is used to instantiate Application Insights so that usage events can be tracked.
+The key can be requested from internal Microsoft Fluid Framework engineers.
+
+```
+INSTRUMENTATION_KEY=<key>
+```
+
+## Deployment
+
+The Fluid Framework website is deployed using the build-docs pipeline. `INSTRUMENTATION_KEY`
+is set as a pipeline variable here.
+
 ## Writing site documentation
 
 For details about authoring documentation content in Docusaurus, see [here](https://docusaurus.io/docs/create-doc).

docs/docusaurus.config.ts

@@ -3,13 +3,15 @@
  * Licensed under the MIT License.
  */
 
+import dotenv from "dotenv";
 import type { VersionOptions } from "@docusaurus/plugin-content-docs";
 import * as Preset from "@docusaurus/preset-classic";
 import type { Config } from "@docusaurus/types";
 import { themes as prismThemes } from "prism-react-renderer";
 
 import DocsVersions from "./config/docs-versions.mjs";
 
+dotenv.config();
 const includeLocalApiDocs = process.env.LOCAL_API_DOCS === "true";
 
 const githubUrl = "https://github.com/microsoft/FluidFramework";
@@ -165,6 +167,9 @@ const config: Config = {
 			},
 		],
 	],
+	customFields: {
+		INSTRUMENTATION_KEY: process.env.INSTRUMENTATION_KEY,
+	},
 };
 
 export default config;

docs/package.json

@@ -74,6 +74,8 @@
 		"@fluid-tools/markdown-magic": "file:../tools/markdown-magic",
 		"@fluidframework/build-common": "^2.0.3",
 		"@fluidframework/eslint-config-fluid": "^5.5.1",
+		"@microsoft/applicationinsights-react-js": "^17.3.4",
+		"@microsoft/applicationinsights-web": "^3.3.4",
 		"@playwright/test": "^1.49.0",
 		"@rushstack/node-core-library": "^5.9.0",
 		"@types/node": "^22.9.1",
@@ -83,6 +85,7 @@
 		"cross-env": "^7.0.3",
 		"dill-cli": "^0.1.3",
 		"docusaurus-plugin-sass": "^0.2.5",
+		"dotenv": "^16.4.7",
 		"dotenv-cli": "^7.4.3",
 		"eslint": "~8.55.0",
 		"eslint-config-prettier": "~9.1.0",
@@ -99,7 +102,8 @@
 		"rimraf": "^5.0.10",
 		"simple-git": "^3.27.0",
 		"start-server-and-test": "^2.0.8",
-		"typescript": "~5.5.4"
+		"typescript": "~5.5.4",
+		"uuid": "^11.0.3"
 	},
 	"packageManager": "pnpm@8.15.8+sha512.d1a029e1a447ad90bc96cd58b0fad486d2993d531856396f7babf2d83eb1823bb83c5a3d0fc18f675b2d10321d49eb161fece36fe8134aa5823ecd215feed392",
 	"engines": {

docs/src/appInsights.ts

@@ -0,0 +1,32 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// eslint-disable-next-line import/no-unresolved
+import siteConfig from "@generated/docusaurus.config";
+import { ReactPlugin } from "@microsoft/applicationinsights-react-js";
+import { ApplicationInsights } from "@microsoft/applicationinsights-web";
+
+const reactPlugin = new ReactPlugin();
+let appInsights: ApplicationInsights | undefined;
+
+if (siteConfig?.customFields?.INSTRUMENTATION_KEY === undefined) {
+	console.warn("Instrumentation Key is missing. App Insights will not be initialized.");
+}
+
+// Only initialize Application Insights if not in local development.
+// Remove the condition if you want to run Application Insights locally.
+if (typeof window !== "undefined" && window.location.hostname !== "localhost") {
+	appInsights = new ApplicationInsights({
+		config: {
+			connectionString: `InstrumentationKey=${siteConfig?.customFields?.INSTRUMENTATION_KEY}`,
+			enableAutoRouteTracking: true,
+			enableDebug: true,
+			extensions: [reactPlugin],
+		},
+	});
+	appInsights.loadAppInsights();
+}
+
+export default appInsights;