Quick Start

The Evolv AI platform offers SDKs for React-based frameworks like React (for web) and NextJS. The SDKs allow you to embed Evolv directly into your application for a more seamless experience.

note

The following guide is written in TypeScript, but you can apply it to a JavaScript project as well.

Requirements

The Evolv SDK requires a web-based React or NextJS application.

• React v18 or higher
• NextJS v13 or higher (for NextJS applications only)

1. Install the appropriate SDK for your framework.

React

npm install @evolv/react

NextJS

npm install @evolv/nextjs

2. Add the <EvolvProvider />.

You are responsible for providing the User ID: uid

Replace the environment ID with your own, or use the existing ID for the demo.

React

src/index.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { EvolvProvider, EvolvClientOptions } from "@evolv/react";


const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);

const options: EvolvClientOptions = {
  environment: "a925240014"
};

const uid = '1234.567';

root.render(
  <React.StrictMode>
    <EvolvProvider options={options} uid={uid}>
      <App/>
    </EvolvProvider>
  </React.StrictMode>
);

See also

• User Ids
• Provider/React

NextJS

pages/index.tsx

import type { NextPage } from 'next';
import { EvolvClientOptions } from "@evolv/client";
import { EvolvProvider, EvolvServerSideProps } from "@evolv/nextjs";
import Button from "../components/button";


const options: EvolvClientOptions = {
  environment: "a925240014"
};

const Home: NextPage<EvolvServerSideProps & { uid: string }> = (props) => {
  return (
    <EvolvProvider
      options={options}
      uid={props.uid}
      hydratedState={props.hydratedState}
      remoteContext={props.remoteContext}
    >
      <Button/>
    </EvolvProvider>
  );
};

export default Home;

See also

• User Ids
• Provider/NextJS

info

Once implemented, you should see requests to participants.evolv.ai in the browser's network tab.

3. Set the Evolv context.

• Setting the Evolv context values let you match the desired conditions for your variants to show.
• This example sets the context value of customizeButton to true, which satisfies the context requirements and renders the variants.

React

src/App.tsx

import React from 'react';
import { useContextState } from '@evolv/react';


function App() {
  const [, setEnabled] = useContextState<boolean>('customizeButton');

  setEnabled(true);

  return (
    <div className="App">
      ...
    </div>
  );
}

export default App;

NextJS

pages/index.tsx

import type { GetServerSidePropsContext, NextPage } from 'next';
import { EvolvClientOptions, LocalContext, RemoteContext } from "@evolv/client";
import { EvolvProvider, EvolvServerSideProps, getEvolvServerSideProps } from "@evolv/nextjs";
import Button from "../components/button";


const options: EvolvClientOptions = {
  environment: "a925240014"
};

const Home: NextPage<EvolvServerSideProps & { uid: string }> = (props) => {
  return (
    <EvolvProvider
      options={options}
      uid={props.uid}
      hydratedState={props.hydratedState}
      remoteContext={props.remoteContext}
    >
      <Button/>
    </EvolvProvider>
  );
};

export async function getServerSideProps(ctx: GetServerSidePropsContext) {
  const remoteContext: Partial<RemoteContext> = {
    customizeButton: true
  };
  const localContext: LocalContext = {};

  const { props: { uid } } = '123.456';
  const { props: evolvProps } = await getEvolvServerSideProps({
    client: options,
    uid,
    remoteContext,
  }, ctx);

  return {
    props: {
      ...evolvProps,
      uid
    }
  };
}

export default Home;

See also

• Context

4. Add the useVariable() hook to a component.

The useVariable() hook returns the variant allocated to the current user for the given variable.

React

src/App.tsx

import React from 'react';
import { useVariable } from "@evolv/react";


function App() {
  const buttonText: string = useVariable('cta-button.text', 'Control Button Text');
  const buttonColor: string = useVariable('cta-button.color', 'grey');

  return (
    <div className="App">
      <button
        type="button"
        className="btn btn-light"
        style={{ backgroundColor: buttonColor }}
      >
        {buttonText}
      </button>
    </div>
  );
}

export default App;

NextJS

components/Button.tsx

import { useVariable } from '@evolv/nextjs';

export default function Button() {
  const buttonText: string = useVariable('cta-button.text', 'Control Button Text');
  const buttonColor: string = useVariable('cta-button.color', 'grey');

  return (
    <button
      style={{ backgroundColor: buttonColor }}
    >
      {buttonText}
    </button>
  );
}

See also

• Hooks/useVariable()

5. Emit an event.

• Emit an event using the Evolv Client.
• Events are used as primary and secondary optimization metrics and are considered conversions.

React

const { client } = useEvolv();

client.emit('react.sdk.conversion');

NextJS

const { client } = useEvolv();

client.emit('react.sdk.conversion');

See also

• Events

6. Start the app.

When the page loads, your uid is allocated one of the active combinations of variants. The button text and background color will appear with a combination of these values.

• Button text:
  • Control: Control Button Text
  • Variant: Variant Button Text
• Button color:
  • Control: grey
  • Variant: green

Each variable has a default value in the event Evolv cannot be reached. Usually, this value is the control value.

info

For enhanced debug messages with NextJS, set the DEBUG environment variable when running your application.

Example:

DEBUG=evolv:* npm start