update readme

Author: zhiyuanliang-ms

examples/quote-of-the-day/.env.temlate

@@ -2,4 +2,5 @@
 # This is a template of related environment variables in examples.
 # To use this file directly, please rename it to .env
 APPCONFIG_CONNECTION_STRING=<app-configuration-connection-string>
-APPLICATIONINSIGHTS_CONNECTION_STRING=<application-insights-connection-string>
+APPLICATIONINSIGHTS_CONNECTION_STRING=<application-insights-connection-string>
+USE_APP_CONFIG=true

examples/quote-of-the-day/README.md

@@ -14,4 +14,142 @@ npm run build
 
 ```cmd
 npm run start
+```
+
+## Telemetry
+
+The Quote of the Day example implements telemetry using Azure Application Insights to track feature flag evaluations. This helps monitor and analyze how feature flags are being used in your application.
+
+### Application Insights Integration
+
+The application uses the `@microsoft/feature-management-applicationinsights-node` package to integrate Feature Management with Application Insights:
+
+```javascript
+const { createTelemetryPublisher } = require("@microsoft/feature-management-applicationinsights-node");
+
+// When initializing Feature Management
+const publishTelemetry = createTelemetryPublisher(appInsightsClient);
+featureManager = new FeatureManager(featureFlagProvider, {
+    onFeatureEvaluated: publishTelemetry,
+    targetingContextAccessor: targetingContextAccessor
+});
+```
+
+The `onFeatureEvaluated` option registers a callback that automatically sends telemetry events to Application Insights whenever a feature flag is evaluated.
+
+### Targeting Context in Telemetry
+
+The telemetry implementation also captures the targeting context, which includes user ID and groups, in the telemetry data:
+
+```javascript
+// Initialize Application Insights with targeting context
+applicationInsights.defaultClient.addTelemetryProcessor(
+    createTargetingTelemetryProcessor(targetingContextAccessor)
+);
+```
+
+This ensures that every telemetry event sent to Application Insights includes the targeting identity information, allowing you to correlate feature flag usage with specific users or groups in your analytics.
+
+### Experimentation and A/B Testing
+
+Telemetry is particularly valuable for running experiments like A/B tests. Here's how you can use telemetry to track whether different variants of a feature influence user behavior.
+
+In this example, a variant feature flag is used to track the like button click rate of a web application:
+
+```json
+{
+    "id": "Greeting",
+    "enabled": true,
+    "variants": [
+        {
+            "name": "Default"
+        },
+        {
+            "name": "Simple",
+            "configuration_value": "Hello!"
+        },
+        {
+            "name": "Long",
+            "configuration_value": "I hope this makes your day!"
+        }
+    ],
+    "allocation": {
+        "percentile": [
+        {
+            "variant": "Default",
+            "from": 0,
+            "to": 50
+        },
+        {
+            "variant": "Simple",
+            "from": 50,
+            "to": 75
+        },
+        {
+            "variant": "Long",
+            "from": 75,
+            "to": 100
+        }
+        ],
+        "default_when_enabled": "Default",
+        "default_when_disabled": "Default"
+    },
+    "telemetry": {
+        "enabled": true
+    }
+}
+```
+
+## Targeting
+
+The targeting mechanism uses the `exampleTargetingContextAccessor` to extract the targeting context from the request. This function retrieves the userId and groups from the query parameters of the request.
+
+```javascript
+const targetingContextAccessor = {
+    getTargetingContext: () => {
+        const req = requestAccessor.getStore();
+        if (req === undefined) {
+            return undefined;
+        }
+        // read user and groups from request
+        const userId = req.query.userId ?? req.body.userId;
+        const groups = req.query.groups ?? req.body.groups;
+        // return an ITargetingContext with the appropriate user info
+        return { userId: userId, groups: groups ? groups.split(",") : [] };
+    }
+};
+```
+
+The `FeatureManager` is configured with this targeting context accessor:
+
+```javascript
+const featureManager = new FeatureManager(
+    featureProvider, 
+    { 
+        targetingContextAccessor: exampleTargetingContextAccessor 
+    }
+);
+```
+
+This allows you to get ambient targeting context while doing feature flag evaluation and variant allocation.
+
+### Request Accessor
+
+The `requestAccessor` is an instance of `AsyncLocalStorage` from the `async_hooks` module. It is used to store the request object in asynchronous local storage, allowing it to be accessed throughout the lifetime of the request. This is particularly useful for accessing request-specific data in asynchronous operations. For more information, please go to https://nodejs.org/api/async_context.html
+
+```javascript
+import { AsyncLocalStorage } from "async_hooks";
+const requestAccessor = new AsyncLocalStorage();
+```
+
+Middleware is used to store the request object in the AsyncLocalStorage:
+
+```javascript
+const requestStorageMiddleware = (req, res, next) => {
+    requestAccessor.run(req, next);
+};
+
+...
+
+server.use(requestStorageMiddleware);
 ```

examples/quote-of-the-day/config.js

@@ -3,8 +3,12 @@
 
 require("dotenv").config();
 
+const fs = require('fs/promises');
+const localFeatureFlags = JSON.parse(await fs.readFile("localFeatureFlags.json"));
+
 // Export configuration variables
 module.exports = {
+    localFeatureFlags,
     appConfigConnectionString: process.env.APPCONFIG_CONNECTION_STRING,
     appInsightsConnectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
     port: process.env.PORT || "8080"

examples/quote-of-the-day/featureManagement.js

@@ -2,7 +2,7 @@
 // Licensed under the MIT license.
 
 const { load } = require("@azure/app-configuration-provider");
-const { FeatureManager, ConfigurationMapFeatureFlagProvider } = require("@microsoft/feature-management");
+const { FeatureManager, ConfigurationMapFeatureFlagProvider, ConfigurationObjectFeatureFlagProvider } = require("@microsoft/feature-management");
 const { createTelemetryPublisher } = require("@microsoft/feature-management-applicationinsights-node");
 const config = require("./config");
 
@@ -27,8 +27,11 @@ async function initializeFeatureManagement(appInsightsClient, targetingContextAc
             }
         }
     });
-
     const featureFlagProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
+
+    // You can also alternatively use local feature flag source.
+    // const featureFlagProvider = new ConfigurationObjectFeatureFlagProvider(config.localFeatureFlags);
+
     const publishTelemetry = createTelemetryPublisher(appInsightsClient);
     featureManager = new FeatureManager(featureFlagProvider, {
         onFeatureEvaluated: publishTelemetry,
@@ -39,7 +42,7 @@ async function initializeFeatureManagement(appInsightsClient, targetingContextAc
 }
 
 // Middleware to refresh configuration before each request
-const configRefreshMiddleware = (req, res, next) => {
+const featureFlagRefreshMiddleware = (req, res, next) => {
     // The configuration refresh happens asynchronously to the processing of your app's incoming requests.
     // It will not block or slow down the incoming request that triggered the refresh. 
     // The request that triggered the refresh may not get the updated configuration values, but later requests will get new configuration values.
@@ -49,5 +52,5 @@ const configRefreshMiddleware = (req, res, next) => {
 
 module.exports = {
     initializeFeatureManagement,
-    configRefreshMiddleware
+    featureFlagRefreshMiddleware
 };

examples/quote-of-the-day/config.json renamed to examples/quote-of-the-day/localFeatureFlags.json

@@ -2,15 +2,13 @@
   "name": "quoteoftheday",
   "scripts": {
     "build-client": "cd client && npm install && npm run build",
-    "build-fm": "cd ../../src/feature-management && npm install && npm run build",
-    "build-fmai": "cd ../../src/feature-management-applicationinsights-node && npm install && npm run build",
-    "build": "npm run build-fm && npm run build-fmai && npm install && npm run build-client",
+    "build": "npm install && npm run build-client",
     "start": "node server.js"
   },
   "dependencies": {
     "@azure/app-configuration-provider": "latest",
-    "@microsoft/feature-management": "../../src/feature-management",
-    "@microsoft/feature-management-applicationinsights-node": "../../src/feature-management-applicationinsights-node",
+    "@microsoft/feature-management": "2.1.0-preview.1",
+    "@microsoft/feature-management-applicationinsights-node": "2.1.0-preview.1",
     "applicationinsights": "^2.9.6",
     "dotenv": "^16.5.0",
     "express": "^4.19.2"

examples/quote-of-the-day/package.json

@@ -6,7 +6,7 @@ const config = require("./config");
 const express = require("express");
 const { targetingContextAccessor, requestStorageMiddleware } = require("./targetingContextAccessor");
 const { initializeAppInsights } = require("./telemetry");
-const { initializeFeatureManagement, configRefreshMiddleware } = require("./featureManagement");
+const { initializeFeatureManagement, featureFlagRefreshMiddleware } = require("./featureManagement");
 const { initializeRoutes } = require("./routes");
 
 // Initialize Express server
@@ -32,7 +32,7 @@ async function startApp() {
 
         // Set up middleware
         server.use(requestStorageMiddleware);
-        server.use(configRefreshMiddleware);
+        server.use(featureFlagRefreshMiddleware);
         server.use(express.json());
         server.use(express.static("public"));