Présentation

Cette page décrit comment instrumenter votre application JavaScript de navigateur avec le SDK Datadog Feature Flags. Les Datadog Feature Flags offrent un moyen unifié de contrôler à distance la disponibilité des fonctionnalités dans votre application, d’expérimenter en toute sécurité et de proposer de nouvelles expériences en toute confiance.

Le SDK Datadog Feature Flags pour JavaScript est basé sur OpenFeature, un standard ouvert pour la gestion des Feature Flags. Ce guide explique comment installer le SDK, configurer le fournisseur Datadog et évaluer les indicateurs dans votre application.

Installation

Installez le fournisseur OpenFeature de Datadog et le SDK Web OpenFeature à l’aide de votre gestionnaire de paquets préféré :

npm install @datadog/openfeature-browser @openfeature/web-sdk @openfeature/core

yarn add @datadog/openfeature-browser @openfeature/web-sdk @openfeature/core

pnpm add @datadog/openfeature-browser @openfeature/web-sdk @openfeature/core

Initialiser le fournisseur

Créez une instance DatadogProvider avec vos identifiants Datadog. Pour la configuration en direct des Feature Flags de navigateur, applicationId, clientToken, site et env sont requis. Pour créer un jeton client, consultez Jetons client.

import { DatadogProvider } from '@datadog/openfeature-browser';
import { OpenFeature } from '@openfeature/web-sdk';

const provider = new DatadogProvider({
  // Required
  // applicationId is a unique identifier to distinguish multiple frontend applications.
  // This should match the app ID you provide to your RUM SDK.
  applicationId: '<APPLICATION_ID>',
  // Required
  clientToken: '<CLIENT_TOKEN>',
  site: '',
  env: '<ENV_NAME>',
});

Définir le contexte d’évaluation

Définissez à qui ou à quoi l’évaluation de l’indicateur s’applique en utilisant un contexte d’évaluation. Le contexte d’évaluation inclut des informations sur l’utilisateur ou la session utilisées pour déterminer quelles variantes d’indicateur doivent être renvoyées. Référencez ces attributs dans vos règles de ciblage pour contrôler qui voit chaque variante.

const evaluationContext = {
  targetingKey: 'user-123',
  user_id: '123',
  user_role: 'admin',
  email: 'user@example.com',
};

await OpenFeature.setProviderAndWait(provider, evaluationContext);

La plupart des applications exécutent plusieurs tâches asynchrones au démarrage, comme la récupération de données depuis un autre service ou le chargement de la configuration. Cet exemple montre uniquement l’initialisation des Feature Flags. En guise de bonne pratique, lancez toutes vos promesses de démarrage ensemble et attendez-les en groupe (par exemple, avec Promise.all) juste avant que les résultats ne soient nécessaires, plutôt que d’attendre chacune d’elles séquentiellement. Cela permet de maintenir le temps de démarrage total proche de celui de la tâche la plus lente au lieu de la somme de toutes les tâches.

Évaluer les Feature Flags

Une fois le fournisseur initialisé, vous pouvez évaluer les flags n’importe où dans votre application. L’évaluation des flags est locale et instantanée : le SDK utilise des données mises en cache localement, donc aucune requête réseau n’est effectuée lors de l’évaluation des flags.

Obtenez un client

Récupérez le client OpenFeature pour évaluer les indicateurs :

const client = OpenFeature.getClient();

Feature Flags booléens

Utilisez getBooleanValue(key, defaultValue) pour les indicateurs qui repre9sentent des conditions active9/de9sactive9 ou vrai/faux :

const isNewCheckoutEnabled = client.getBooleanValue('checkout_new', false);

if (isNewCheckoutEnabled) {
  showNewCheckoutFlow();
} else {
  showLegacyCheckout();
}

Feature Flags de chaîne

Utilisez getStringValue(key, defaultValue) pour les indicateurs qui permettent de choisir entre plusieurs variantes ou chaeenes de configuration :

const theme = client.getStringValue('ui_theme', 'light');

switch (theme) {
  case 'dark':
    setDarkTheme();
    break;
  case 'light':
  default:
    setLightTheme();
}

Indicateurs numériques

Utilisez getNumberValue(key, defaultValue) pour les indicateurs nume9riques tels que les limites, les pourcentages ou les multiplicateurs :

const maxItems = client.getNumberValue('cart_items_max', 20);
const priceMultiplier = client.getNumberValue('pricing_multiplier', 1.0);

Indicateurs d’objet

Utilisez getObjectValue(key, defaultValue) pour les donne9es de configuration structure9es :

const config = client.getObjectValue('promo_banner_config', {
  color: '#00A3FF',
  message: 'Welcome!',
});

Détails de l’évaluation des Feature Flags

Lorsque vous avez besoin de plus que la simple valeur de l’indicateur, utilisez les méthodes de détail. Celles-ci renvoient à la fois la valeur évaluée et les métadonnées expliquant l’évaluation :

const details = client.getBooleanDetails('checkout_new', false);

console.log(details.value);       // Evaluated value (true or false)
console.log(details.variant);     // Variant name, if applicable
console.log(details.reason);      // Why this value was chosen
console.log(details.errorCode);   // Error code, if evaluation failed

Exemple complet

Voici un exemple complet montrant comment configurer et utiliser les Datadog Feature Flags dans une application JavaScript :

import { DatadogProvider } from '@datadog/openfeature-browser';
import { OpenFeature } from '@openfeature/web-sdk';

// Initialize the Datadog provider
const provider = new DatadogProvider({
  applicationId: '<APPLICATION_ID>',
  clientToken: '<CLIENT_TOKEN>',
  site: '',
  env: '<ENV_NAME>',
});

// Set the evaluation context
const evaluationContext = {
  targetingKey: 'user-123',
  user_id: '123',
  user_role: 'admin',
};

await OpenFeature.setProviderAndWait(provider, evaluationContext);

// Get the client and evaluate flags
const client = OpenFeature.getClient();
const showNewFeature = client.getBooleanValue('new_feature', false);

if (showNewFeature) {
  console.log('New feature is enabled!');
}

Mettre à jour le contexte d’évaluation

Pour mettre e0 jour le contexte d’e9valuation apre8s l’initialisation (par exemple, lorsqu’un utilisateur se connecte), utilisez OpenFeature.setContext() :

await OpenFeature.setContext({
  targetingKey: user.id,
  user_id: user.id,
  email: user.email,
  plan: user.plan,
});

Configurer les options du fournisseur de navigateur

Le fournisseur web prend e9galement en charge ces parame8tres optionnels :

Remplacer les indicateurs dans votre navigateur

Pour parcourir les indicateurs de votre organisation et les remplacer localement pendant votre développement, intégrez le wrapper DatadogDevtools dans votre pile de fournisseurs et utilisez l’onglet Feature Flags dans l’extension développeur du SDK Browser Datadog.

Tests

Vous pouvez effectuer des tests sur un environnement de test Datadog dédié avec le DatadogProvider réel, ou le remplacer par le InMemoryProvider d’OpenFeature pour contrôler directement les valeurs des indicateurs dans le code de test. Cette section présente l’approche en mémoire, qui permet de garder les tests hermétiques et hors ligne. InMemoryProvider est exporté directement depuis @openfeature/web-sdk, aucune dépendance supplémentaire n’est donc requise.

Contrairement au SDK côté serveur, le SDK Web évalue les indicateurs de manière synchrone après l’initialisation. Toujours await setProviderAndWait une fois dans beforeEach pour vous assurer que le fournisseur est prêt.

import { beforeEach, afterAll, expect, test } from 'vitest';
import { OpenFeature, TypedInMemoryProvider } from '@openfeature/web-sdk';

const flags = {
  new_checkout_button: {
    variants: { on: true, off: false },
    defaultVariant: 'on',
    disabled: false,
  },
  ui_theme: {
    variants: { dark: 'dark', light: 'light' },
    defaultVariant: 'light',
    disabled: false,
  },
};

beforeEach(async () => {
  await OpenFeature.setProviderAndWait(new TypedInMemoryProvider(flags));
});

afterAll(async () => {
  await OpenFeature.close();
});

test('new checkout button is enabled by default', () => {
  const client = OpenFeature.getClient();
  expect(client.getBooleanValue('new_checkout_button', false)).toBe(true);
});

test('missing flag returns default', () => {
  const client = OpenFeature.getClient();
  expect(client.getBooleanValue('does-not-exist', false)).toBe(false);
});

La structure des indicateurs du SDK Web nécessite variants, defaultVariant et disabled. L’omission de l’un de ces éléments entraîne l’échec de la compilation TypeScript ; au moment de l’exécution, l’évaluation d’une clé de drapeau inconnue renvoie la valeur par défaut fournie. Privilégiez TypedInMemoryProvider à InMemoryProvider , obsolète, pour des configurations d’indicateurs vérifiées par type. Le même modèle de test fonctionne avec Jest + jsdom ; remplacez les importations vitest par @jest/globals et ajoutez jest-environment-jsdom à votre projet.

Lectures complémentaires

Documentation, liens et articles supplémentaires utiles:

Feature Flags côté clientDOCUMENTATION SDK Web OpenFeatureOPENFEATURE Surveillance BrowserDOCUMENTATION Extension de développement pour navigateurDOCUMENTATION Trafic du SDK Proxy Feature FlagGUIDE