Initialization

To integrate Wingify Feature Experimentation (FE) into your React application, you must wrap your application code with the VWOProvider component.

The VWOProvider is a React context provider that initializes the Wingify Feature Experimentation (FE) SDK and makes the client instance and user context available to child components through React Context.

It is essential for enabling feature flag evaluation, A/B testing, and user tracking using hooks like useVWOClient or useGetFlag.

Usage

import React from 'react';
import { VWOProvider, IVWOOptions, IVWOContextModel } from 'vwo-fme-react-sdk';

const vwoConfig: IVWOOptions = {
  sdkKey: '32-alpha-numeric-sdk-key', // Your VWO SDK Key
  accountId: '123456', // Your VWO Account ID
  logger: {
    level: 'debug', // Optional log level for debugging
  },
};

const userContext: IVWOContextModel = {
  id: 'unique_user_id', // Required: Unique identifier for the user
  customVariables: { planId: 2, plan: 'premium' }, // Optional
};

// Optional: Provide a fallback UI component that will be displayed while VWOProvider initializes.
// This is useful for showing a loading state or placeholder content during SDK initialization.
const fallbackComponent = <div>Initializing VWO...</div>;

const App = () => (
  <VWOProvider config={vwoConfig} userContext={ userContext } fallbackComponent={fallbackComponent}>
    <YourComponent />
  </VWOProvider>
);

export default App;

Parameter Types (`IVWOProvider`)

Type	Prop	Required	Description
`IVWOClient`	client	No	Pre-initialized Wingify client. If provided, it overrides the `config`.
`IVWOOptions`	config	No	SDK configuration for initializing the Wingify client. Required if the `client` is not passed.
`IVWOContextModel`	userContext	No	Initial user context to evaluate flags and experiments.
`ReactNode`	children	Yes	Child components that require access to the Wingify context.
`ReactNode`	fallbackComponent	No	Component shown while the client is initializing.

📘
Note
⚠️ Either client or config must be provided. If both are provided, client takes precedence and a warning is logged.

Usage (Using Pre-initialized Wingify Client)

If you have already initialized a Wingify client in your application, you can pass it directly to the VWOProvider:

import React, { useEffect, useState } from 'react';
import { VWOProvider, IVWOOptions, IVWOClient, IVWOContextModel, init } from 'vwo-fme-react-sdk';

const vwoConfig: IVWOOptions = {
  sdkKey: '32-alpha-numeric-sdk-key', // Replace with your real SDK key
  accountId: '123456', // Replace with your real account ID
  logger: {
    level: 'debug',
  },
};

const userContext: IVWOContextModel = {
  id: 'unique_user_id',
  customVariables: { planId: 2, plan: 'premium' }
};

const fallbackComponent = <div>Initializing VWO...</div>;

const App = () => {
  const [vwoClient, setVwoClient] = useState<IVWOClient | null>(null);

  useEffect(() => {
    const initializeVWO = async () => {
      const client = await init(vwoConfig);
      setVwoClient(client);
    };

    initializeVWO();
  }, []);

  if (!vwoClient) return fallbackComponent;

  return (
    <VWOProvider client={vwoClient} userContext={ userContext }>
      <YourComponent />
    </VWOProvider>
  );
};

export default App;

Basic Implementation without User Context

If you don't have user details available while initialising the VWOProvider, you can pass it later in the useGetFlag hook.

import React from 'react';
import { VWOProvider, IVWOOptions, IVWOContextModel } from 'vwo-fme-react-sdk';

const vwoConfig: IVWOOptions = {
  sdkKey: '32-alpha-numeric-sdk-key', // Your VWO SDK Key
  accountId: '123456', // Your VWO Account ID
  logger: {
    level: 'debug', // Optional log level for debugging
  },
};

// Optional: Provide a fallback UI component that will be displayed while VWOProvider initializes.
// This is useful for showing a loading state or placeholder content during SDK initialization.
const fallbackComponent = <div>Initializing VWO...</div>;

const App = () => (
  <VWOProvider config={vwoConfig} fallbackComponent={fallbackComponent}>
    <YourComponent />
  </VWOProvider>
);

export default App;

Using the React SDK Without the `VWOProvider`

In some cases, you might prefer not to wrap your application with the VWOProvider component. For example, you may want finer control over when and how the SDK is initialized, or you might need to integrate it into an existing setup where using a provider is not feasible.

Wingify FE React SDK allows you to bypass the provider and directly work with its methods. This gives you the flexibility to manually initialize the SDK and manage feature flag evaluations, user targeting, and other SDK operations programmatically.

You can implement this approach using the example below:

import React, { useEffect, useState } from 'react';
import { init } from 'vwo-fme-react-sdk';

const MyComponent = () => {
  const [isFeatureEnabled, setIsFeatureEnabled] = useState<Boolean>(false);

  useEffect(() => {
    // Initialize the VWO client using vwo-fme-node-sdk
    const initializeVWO = async () => {
      const vwoClient = await init({
        accountId: '123456', // Replace with your actual account ID
        sdkKey: '32-alpha-numeric-sdk-key', // Replace with your actual SDK key
      });

      // Set up user context
      const userContext = { id: 'unique_user_id' };

      // Check if a feature is enabled for the user
      const feature = await vwoClient.getFlag('feature_key', userContext);

      if (feature.isEnabled()) {
        setIsFeatureEnabled(true);

        // You can also fetch the feature variables
        const value = feature.getVariable('feature_variable', 'default_value');
        console.log('Feature variable:', value);
      } else {
        setIsFeatureEnabled(false).
      }

      // Track custom events
      vwoClient.trackEvent('custom_event_name', userContext);
    };

    initializeVWO();
  }, []);

  return (
    <div>
      <h1>Feature Status: {isFeatureEnabled ? 'Enabled' : 'Disabled'}</h1>
    </div>
  );
};

export default MyComponent;

Wingify Provider Config Parameter Definitions

To customize the SDK further, additional parameters can be passed to the VWOProvider component using config parameter. Here’s a table describing each option:

Parameter	Type	Description
accountId Required	Integer	Your Wingify application's Account ID.
sdkKey Required	String	A unique environment key is provided to you inside the Websites & Apps section in the Wingify application, under Default Project.
pollInterval Optional	Number	Time (in milliseconds) at which Wingify should check with the server for any updates to the feature flag or rules in the Wingify Dashboard. Useful to keep your Wingify Client instance up-to-date with any changes made in the Wingify Application. For more details, please check -Polling
logger Optional	object	An optional logger object that defines the logging behavior. For more details, please check - Logger
storage Optional	object	Storage Service, if required, can be implemented using this parameter. For more details, please check - Storage Service
integrations Optional	object	A callback function that receives data which can be pushed to any external tool that you need to integrate with. For more details, please check - Integrations

Poll Interval (Keeping Wingify client up-to-date)

When you initialize the vwoClient using VWOProvider, it pulls the latest configurations you've done in the Wingify application.
If/when you make any changes to the feature flags or rules within Wingify after the vwoClient has been initialized in your server, there needs to be some way to update your vwoClient with the latest settings from Wingify. This can be done via polling.

The poll interval is an optional parameter that allows the SDK to automatically fetch and update settings from the Wingify server at specified intervals. Setting this parameter ensures your application always uses the latest configuration.

import { VWOProvider, IVWOOptions, IVWOContextModel } from 'vwo-fme-react-sdk';
const vwoConfig: IVWOOptions = {
  sdkKey: '32-alpha-numeric-sdk-key', // Your VWO SDK Key
  accountId: '123456', // Your VWO Account ID
  pollInterval: 60000, // Time interval for fetching updates from VWO servers (in milliseconds)
};

const userContext: IVWOContextModel = { id: 'unique_user_id' };

const App = () => (
  <VWOProvider config={vwoConfig} userContext={ userContext }>
    <YourComponent />
  </VWOProvider>
);

Logger

Wingify by default logs all ERROR level messages to your console. To gain more control over Wingify's logging behavior, you can use the logger parameter in the init configuration.

import { VWOProvider, IVWOOptions, IVWOContextModel } from 'vwo-fme-react-sdk';
const vwoConfig: IVWOOptions = {
  sdkKey: '32-alpha-numeric-sdk-key', // SDK Key
  accountId: '123456', // VWO Account ID
  logger: {
    level: 'debug',
  },
};

const userContext: IVWOContextModel = {id: 'unique_user_id'};

const App = () => (
  <VWOProvider config={vwoConfig} userContext=USERCONTEXT>
    <YourComponent />
  </VWOProvider>
);

export default App;

Please click here for more advanced logger options.

Storage

By default, the SDK operates in stateless mode, evaluating flags on each useGetFlag hook. To improve performance and consistency, you can use a custom storage mechanism to cache decisions, ensuring stable user experiences and reducing application load.

import { VWOProvider, IVWOOptions, IVWOContextModel } from 'vwo-fme-react-sdk';

// implementation of class StorageConnector - check storage Service page

const vwoConfig: IVWOOptions = {
  sdkKey: '32-alpha-numeric-sdk-key', // Your VWO SDK Key
  accountId: '123456', // Your VWO Account ID
  storage: StorageConnector,
};

const userContext: IVWOContextModel = {id: 'unique_user_id'};

const App = () => (
  <VWOProvider config={vwoConfig} userContext=USERCONTEXT>
    <YourComponent />
  </VWOProvider>
);

export default App;

Please click here to learn more about storage implementation.

Integrations

Wingify FE SDKs provide seamless integration with third-party tools like analytics platforms, monitoring services, customer data platforms (CDPs), and messaging systems. This is achieved through a simple yet powerful callback mechanism that receives Wingify-specific properties and can forward them to any third-party tool of your choice.

import { VWOProvider, IVWOOptions, IVWOContextModel } from 'vwo-fme-react-sdk';
const vwoConfig: IVWOOptions = {
  sdkKey: '32-alpha-numeric-sdk-key', // SDK Key
  accountId: '123456', // VWO Account ID
  integrations: {
    callback (properties) {
      console.log('Integrations callback', properties); // list of keys
    }
  }
};

const userContext: IVWOContextModel = {id: 'unique_user_id'};

const App = () => (
  <VWOProvider config={vwoConfig} userContext=USERCONTEXT>
    <YourComponent />
  </VWOProvider>
);

export default App;

Please click here to learn more about Integrations.

Usage

Parameter Types (IVWOProvider)

Note

Usage (Using Pre-initialized Wingify Client)

Basic Implementation without User Context

Using the React SDK Without the VWOProvider

Wingify Provider Config Parameter Definitions

Poll Interval (Keeping Wingify client up-to-date)

Logger

Storage

Integrations

Parameter Types (`IVWOProvider`)

Using the React SDK Without the `VWOProvider`