Présentation

Cette page décrit comment instrumenter votre application React Native avec le Datadog Feature Flags SDK. 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 Datadog Feature Flags SDK pour React Native 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 Feature Flags dans vos composants React Native.

Prérequis

• React Native version 0.65 ou ultérieure
• iOS version 13 ou ultérieure
• Android niveau d’API 23 ou ultérieur Le - Datadog React Native SDK (@datadog/mobile-react-native) doit être initialisé en premier.

Installation

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

npm install @datadog/mobile-react-native @datadog/mobile-react-native-openfeature @openfeature/react-sdk @openfeature/web-sdk @openfeature/core

yarn add @datadog/mobile-react-native @datadog/mobile-react-native-openfeature @openfeature/react-sdk @openfeature/web-sdk @openfeature/core

Configuration iOS

Installez le pod ajouté :

(cd ios && pod install)

Configuration Android

Si vous utilisez React Native version 0.68 ou supérieure, utilisez Java 17. Si vous utilisez React Native version 0.67 ou inférieure, utilisez Java version 11.

Dans votre fichier android/build.gradle, spécifiez kotlinVersion pour éviter les conflits entre les dépendances Kotlin :

buildscript {
    ext {
        kotlinVersion = "1.8.21"
    }
}

Initialiser le SDK

Le fournisseur Datadog OpenFeature pour React Native nécessite que le Datadog React Native SDK principal soit initialisé en premier, suivi de l’activation de Feature Flags. Pour créer un jeton client, consultez Jetons client.

Option 1 : Utilisation du composant DatadogProvider

Si vous utilisez le composant DatadogProvider pour l’initialisation du SDK, activez les Feature Flags dans le rappel onInitialized :

import { DatadogProvider, DatadogProviderConfiguration, DdFlags } from '@datadog/mobile-react-native';
import { DatadogOpenFeatureProvider } from '@datadog/mobile-react-native-openfeature';
import { OpenFeature, OpenFeatureProvider } from '@openfeature/react-sdk';

const config = new DatadogProviderConfiguration(
    '<CLIENT_TOKEN>',
    '<ENVIRONMENT_NAME>',
    trackingConsent,
    {
      rumConfiguration: {
        applicationId: '<APPLICATION_ID>',
      },
      // ...
    },
);
config.site = '';

export default function App() {
    return (
        <DatadogProvider
            configuration={config}
            onInitialized={async () => {
                await DdFlags.enable();

                const provider = new DatadogOpenFeatureProvider();
                OpenFeature.setProvider(provider);
            }}
        >
            <OpenFeatureProvider>
                <Navigation />
            </OpenFeatureProvider>
        </DatadogProvider>
    );
}

Option 2 : Utilisation de l’initialisation impérative

Si vous initialisez le SDK de manière impérative, activez les Feature Flags une fois l’initialisation terminée :

import { DdSdkReactNative, DdFlags, CoreConfiguration } from '@datadog/mobile-react-native';
import { DatadogOpenFeatureProvider } from '@datadog/mobile-react-native-openfeature';
import { OpenFeature } from '@openfeature/react-sdk';

(async () => {
    const config = new CoreConfiguration(
        '<CLIENT_TOKEN>',
        '<ENVIRONMENT_NAME>',
        '<APPLICATION_ID>'
    );
    config.site = '';

    await DdSdkReactNative.initialize(config);

    // Enable Feature Flags after core SDK initialization
    await DdFlags.enable();

    // Set the Datadog provider with OpenFeature
    const provider = new DatadogOpenFeatureProvider();
    OpenFeature.setProvider(provider);
})();

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.

import { OpenFeature } from '@openfeature/react-sdk';

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

OpenFeature.setContext(evaluationContext);

Enveloppez votre application

Enveloppez votre application avec le composant OpenFeatureProvider. Cela rend les Feature Flags disponibles pour tous les composants enfants via le contexte React.

import { OpenFeatureProvider } from '@openfeature/react-sdk';

function App() {
    return (
        <OpenFeatureProvider>
            <YourApp />
        </OpenFeatureProvider>
    );
}

Évaluer les Feature Flags

Le SDK OpenFeature React fournit des hooks pour évaluer les Feature Flags au sein de vos composants. Chaque hook renvoie la valeur du Feature Flag en fonction du contexte d’évaluation que vous avez configuré. 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.

Feature Flags booléens

Utilisez useBooleanFlagValue(key, defaultValue) pour les Feature Flags qui représentent des conditions activées/désactivées ou vrai/faux :

import { useBooleanFlagValue } from '@openfeature/react-sdk';

function CheckoutButton() {
  const isNewCheckoutEnabled = useBooleanFlagValue('new_checkout_button', false);

  if (isNewCheckoutEnabled) {
    return <NewCheckoutButton />;
  }

  return <LegacyCheckoutButton />;
}

Feature Flags de chaîne

Utilisez useStringFlagValue(key, defaultValue) pour les Feature Flags qui permettent de choisir entre plusieurs variantes ou chaînes de configuration :

import { useStringFlagValue } from '@openfeature/react-sdk';

function ThemedComponent() {
  const theme = useStringFlagValue('ui_theme', 'light');

  switch (theme) {
    case 'dark':
      return <DarkTheme />;
    case 'light':
    default:
      return <LightTheme />;
  }
}

Indicateurs numériques

Utilisez useNumberFlagValue(key, defaultValue) pour les Feature Flags numériques tels que les limites, les pourcentages ou les multiplicateurs :

import { useNumberFlagValue } from '@openfeature/react-sdk';

function CartDisplay() {
  const maxItems = useNumberFlagValue('max_cart_items', 20);

  return <Cart maxItems={maxItems} />;
}

Indicateurs d’objet

Utilisez useObjectFlagValue(key, defaultValue) pour les données de configuration structurées :

import { useObjectFlagValue } from '@openfeature/react-sdk';

function Banner() {
  const config = useObjectFlagValue('promo_banner', {
    color: '#00A3FF',
    message: 'Welcome!',
  });

  return <PromoBanner color={config.color} message={config.message} />;
}

Prise en charge de Suspense

La prise en charge intégrée de suspense vous permet d’éviter d’afficher les composants avec des indicateurs de fonctionnalité jusqu’à ce que l’initialisation du fournisseur soit terminée, ou lorsque le contexte change. Passez { suspend: true } dans les options du hook pour utiliser cette fonctionnalité.

Exemple :

import { useBooleanFlagValue } from '@openfeature/react-sdk';
import { Suspense } from 'react';

function Content() {
  // Display a loading message if the component uses feature flags and the provider is not ready
  return (
    <Suspense fallback={"Loading..."}>
      <WelcomeMessage />
    </Suspense>
  );
}

function WelcomeMessage() {
  const showNewMessage = useBooleanFlagValue('show-new-welcome-message', false, { suspend: true });

  return (
    <>
      {showNewMessage ? (
        <p>Welcome! You're seeing the new experience.</p>
      ) : (
        <p>Welcome back!</p>
      )}
    </>
  );
}

Détails de l’évaluation des Feature Flags

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

• useBooleanFlagDetails(key, defaultValue)
• useStringFlagDetails(key, defaultValue)
• useNumberFlagDetails(key, defaultValue)
• useObjectFlagDetails(key, defaultValue)

Exemple :

import { useStringFlagDetails } from '@openfeature/react-sdk';

function PaywallLayout() {
  const details = useStringFlagDetails('paywall_layout', 'control');

  console.log(details.value);   // Evaluated value (for example: "A", "B", or "control")
  console.log(details.variant); // Variant name, if applicable
  console.log(details.reason);  // Description of why this value was chosen

  return <Layout variant={details.value} />;
}

Les détails des indicateurs vous aident à déboguer le comportement d’évaluation et à comprendre pourquoi un utilisateur a reçu une valeur donnée.

Exemple complet

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

import { Suspense } from 'react';
import { View } from 'react-native';
import { DatadogProvider, DatadogProviderConfiguration, DdFlags } from '@datadog/mobile-react-native';
import { DatadogOpenFeatureProvider } from '@datadog/mobile-react-native-openfeature';
import { OpenFeature, OpenFeatureProvider, useBooleanFlagValue } from '@openfeature/react-sdk';

const config = new DatadogProviderConfiguration(
    '<CLIENT_TOKEN>',
    '<ENVIRONMENT_NAME>',
    trackingConsent,
    {
      rumConfiguration: {
        applicationId: '<APPLICATION_ID>',
      },
      // ...
    },
);

// Wrap your app with the DatadogProvider and OpenFeatureProvider.
export default function AppWithProviders() {
    // Based on your auth state.
    const user = getCurrentUser();

    return (
        <DatadogProvider
            configuration={config}
            onInitialized={async () => {
                await DdFlags.enable();

                const provider = new DatadogOpenFeatureProvider();

                const evaluationContext = {
                    targetingKey: user.id,
                    region: user.country,
                };

                OpenFeature.setProvider(provider, evaluationContext);
            }}
        >
          <Suspense fallback={<Loading />}>
            <OpenFeatureProvider suspendUntilReady>
                <App />
            </OpenFeatureProvider>
          </Suspense>
        </DatadogProvider>
    );
}

// Use feature flags in your components
function App() {
    const showNewFeature = useBooleanFlagValue('new_feature', false);

    return (
        <View>
            {showNewFeature ? <NewFeature /> : <ExistingFeature />}
        </View>
    );
}

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() :

import { OpenFeature } from '@openfeature/react-sdk';

// When a user logs in
function onUserLogin(user) {
    OpenFeature.setContext({
        targetingKey: user.id,
        email: user.email,
        plan: user.plan,
    });
}

Configurer les options de Feature Flags

Passez les options de configuration à DdFlags.enable() pour personnaliser le comportement de Feature Flags :

await DdFlags.enable({
    // Send flag evaluation data to RUM for session analysis (default: true)
    rumIntegrationEnabled: true,
    // Track flag exposures for analytics (default: true)
    trackExposures: true,
});

rumIntegrationEnabled

Lorsque true (par défaut), les évaluations des Feature Flags sont suivies dans RUM, ce qui permet de les corréler avec les sessions utilisateur. Cela permet des analyses telles que « Les utilisateurs de la variante B rencontrent-ils plus d’erreurs ? ».

trackExposures

Lorsque true (par défaut), le SDK enregistre automatiquement un événement d’exposition lorsqu’un Feature Flag est évalué. Ces événements contiennent des métadonnées sur le Feature Flag auquel il a été accédé, la variante qui a été servie et dans quel contexte : Ils sont envoyés à Datadog afin que vous puissiez analyser l’adoption des fonctionnalités.

Exigences relatives aux attributs de contexte

Utilisez des attributs plats dans votre contexte d’évaluation :

OpenFeature.setContext({
    targetingKey: 'user-123',
    userId: 'user-123',
    tier: 'premium',
    age: 25
});

Évitez les objets et les tableaux imbriqués :

// These attributes will be dropped from the evaluation context with a console warning.
OpenFeature.setContext({
    targetingKey: 'user-123',
    user: { id: 'user-123' },        // nested object - NOT SUPPORTED
    features: ['beta', 'analytics']  // array - NOT SUPPORTED
});

Tests

Vous pouvez effectuer des tests sur un environnement de test Datadog dédié avec le DatadogOpenFeatureProvider réel, ou le remplacer par le TypedInMemoryProvider d’OpenFeature pour contrôler directement les valeurs des Feature Flags 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. TypedInMemoryProvider est exporté depuis @openfeature/web-sdk, qui est déjà installé pour React Native Feature Flags.

import { render, screen } from '@testing-library/react-native';
import { Text } from 'react-native';
import { OpenFeature, OpenFeatureProvider, useBooleanFlagValue } from '@openfeature/react-sdk';
import { TypedInMemoryProvider } from '@openfeature/web-sdk';

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

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

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

function CheckoutButton() {
    const enabled = useBooleanFlagValue('new_checkout_button', false);
    return <Text>{enabled ? 'New checkout' : 'Legacy checkout'}</Text>;
}

test('new checkout button is enabled', () => {
    render(
        <OpenFeatureProvider>
            <CheckoutButton />
        </OpenFeatureProvider>
    );

    expect(screen.getByText('New checkout')).toBeTruthy();
});

La structure des indicateurs du SDK Web nécessite variants, defaultVariant et disabled. Utilisez setProviderAndWait avant de rendre les composants afin que les hooks ne s’évaluent pas par rapport au fournisseur par défaut.

Dépannage

Aucun Feature Flag renvoyé

Si les évaluations de Feature Flags renvoient des valeurs par défaut :

1. Vérifiez que le SDK Datadog React Native est initialisé avant d’appeler DdFlags.enable().
2. Confirmez que DdFlags.enable() est terminé avant de définir le fournisseur OpenFeature.
3. Vérifiez que le contexte d’évaluation est défini avant d’évaluer les Feature Flags.
4. Confirmez que le Feature Flag existe et est activé dans votre dashboard Datadog Feature Flags.

Erreurs d’installation de pod iOS

Si use_frameworks! est activé dans votre Podfile, vous pourriez rencontrer des erreurs lors de pod install. Modifiez votre Podfile pour installer le pod du SDK en tant que bibliothèque statique :

static_libraries = ['DatadogSDKReactNative']

pre_install do |installer|
  installer.pod_targets.each do |pod|
    if static_libraries.include?(pod.name)
      def pod.static_framework?;
        true
      end
      def pod.build_type;
        Pod::BuildType.static_library
      end
    end
  end
end

Erreur de Feature Flags non initialisés

Si vous voyez une erreur indiquant que les Feature Flags ne sont pas initialisés, vérifiez l’ordre d’initialisation :

1. Initialisez d’abord le Datadog React Native SDK principal (DdSdkReactNative.initialize() ou DatadogProvider).
2. Appelez DdFlags.enable() après l’initialisation du SDK.
3. Créez et définissez le DatadogOpenFeatureProvider après avoir activé les Feature Flags.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

OpenFeature React SDKOPENFEATURE Feature Flags côté clientDOCUMENTATION Surveillance React NativeDOCUMENTATION Proxy du trafic du SDK Feature FlagGUIDE