Experience SDK

npm install @ninetailed/experience.js-react
# OR
yarn add @ninetailed/experience.js-react

npm install @ninetailed/experience.js-next
# OR
yarn add @ninetailed/experience.js-next

npm install @ninetailed/experience.js-gatsby
# OR
yarn add @ninetailed/experience.js-gatsby

npm install @ninetailed/experience.js
# OR
yarn add @ninetailed/experience.js

Add the <NinetailedProvider> component to the top level of the application, so that the Ninetailed profile can be consumed from any child component.

import React from 'react';
import MyAppCode from '../myAppCode.jsx';
import { NinetailedProvider } from '@ninetailed/experience.js-react';

export const App = () => {
  return (
    <div id="my-app">
      <NinetailedProvider 
        // REQUIRED. An API key uniquely identifying your Ninetailed account.
        clientId="NINETAILED_API_KEY"

        // === ALL OF THE FOLLOWING PROPS ARE OPTIONAL ===
        // === DEFAULT VALUES ARE SHOWN ===

        // Your Ninetailed environment, typically either "main" or "development"
        environment="main"

        // Add any plugin instances
        plugins=[]

        // Specify an amount of time (ms) that an <Experience /> component must be present in the viewport to register a component view
        componentViewTrackingThreshold={2000}

        // Specify a maximum amount of time (ms) to wait for an Experience API response before falling back to baseline content
        requestTimeout={5000}

        // Specify a locale to localize profile location information
        locale="en-US"

        // Specify an alternative Experience API base URL
        url="https://experience.ninetailed.co"

        // Set to to true ONLY if using an unindexed CMS
        useSDKEvaluation=true
      >
        <MyAppCode />
      </NinetailedProvider>
    </div>
  );   
}

Add the <NinetailedProvider> component to the top level of the application, so that the Ninetailed profile can be consumed from any child component.

The Next.js <NinetailedProvider> also hooks into the Next's page router to automatically call ninetailed.page() on every route change. Do not additionally call this method on your own, otherwise you will duplicate events.

import { NinetailedProvider } from '@ninetailed/experience.js-next';

export const App = ({component, pageProps}) => {
  return (
    <div id="my-app">
      <NinetailedProvider 
        // REQUIRED. An API key uniquely identifying your Ninetailed account.
        clientId="NINETAILED_API_KEY"

        // === ALL OF THE FOLLOWING PROPS ARE OPTIONAL ===
        // === DEFAULT VALUES ARE SHOWN ===

        // Your Ninetailed environment, typically either "main" or "development"
        environment="main"

        // Add any plugin instances
        plugins=[]

        // Specify an amount of time (ms) that an <Experience /> component must be present in the viewport to register a component view
        componentViewTrackingThreshold={2000}

        // Specify a maximum amount of time (ms) to wait for an Experience API response before falling back to baseline content
        requestTimeout={5000}

        // Specify a locale to localize profile location information
        locale="en-US"

        // Specify an alternative Experience API base URL
        url="https://experience.ninetailed.co"

        // Set to to true ONLY if using an unindexed CMS
        useSDKEvaluation=true
      >
        <Component {...pageProps} />
      </NinetailedProvider>
    </div>
  );   
}
}

Add the plugin to your plugins array in your gatsby-config.js|ts file. By using the Gatsby JS plugin there's no need to configure the NinetailedProvider as described for the React and Next.js SDKs.

The plugin automatically calls ninetailed.page() on every route change. Do not additionally call this method on your own, otherwise you will duplicate events.

... // Your Other Gatsby configuration
plugins: [
  ... // Your existing Gatsby plugins
  {
    resolve: `@ninetailed/experience.js-gatsby`,
    options: {
      // REQUIRED. An API key uniquely identifying your Ninetailed account.
      clientId: "NINETAILED_API_KEY", 

      // === ALL OF FOLLOWING PROPERTIRES ARE OPTIONAL ===
      // === DEFAULT VALUES ARE SHOWN ===

      // Your Ninetailed environment, typically either "main" or "development"
      environment: "main",

      // Add any plugin instances
      ninetailedPlugins: [],

      // Specify an amount of time (ms) that a component must be present in the viewport to register a component view
      componentViewTrackingThreshold: 2000,

      // Specify a maximum amount of time (ms) to wait for an Experience API response before falling back to baseline content
      requestTimeout: 5000,

      // Specify a locale to localize profile location information
      locale: "en-US",

      // Specify an alternative Experience API base URL
      url: "https://experience.ninetailed.co",

      // Set to to true ONLY if using an unindexed CMS
      useSDKEvaluation: true
    }
  }
]

import { Ninetailed } from '@ninetailed/experience.js';

export const ninetailed = new Ninetailed(
   { 
        // REQUIRED. An API key uniquely identifying your Ninetailed account.
        clientId: "NINETAILED_API_KEY", 
        // OPTIONAL. Your Ninetailed environment, typically either "main" or "development"
        environment: "main" // Default
    }, 
    // === THE FOLLOWING ARGUMENT AND ALL OF ITS PROPERTIRES ARE OPTIONAL ===
    // === DEFAULT VALUES ARE SHOWN ===
    { 
        // Add any plugin instances
        plugins: [],

        // Specify an amount of time (ms) that a component must be present in the viewport to register a component view
        componentViewTrackingThreshold: 2000,

        // Specify a maximum amount of time (ms) to wait for an Experience API response before falling back to baseline content
        requestTimeout: 5000,

        // Specify a locale to localize profile location information
        locale: "en-US",

        // Specify an alternative Experience API base URL
        url: "https://experience.ninetailed.co"

        // Set to to true ONLY if using an unindexed
        useSDKEvaluation: true
    }
);

The useNinetailed hook provides the tracking functions page, track, and identify. These methods will call the Experience API using the configuration parameters supplied to a <NinetailedProvider>.

import React from 'react';

import { useNinetailed } from '@ninetailed/experience.js-react';
// or import { useNinetailed } from '@ninetailed/experience.js-next';
// or import { useNinetailed } from '@ninetailed/experience.js-gatsby';

export const myComponent = () => {
  const { page, track, identify } = useNinetailed();

  page();
  identify('anAlias', {someTrait: "value"});

  return (
    <button 
      type="button" 
      onClick={() => { track('add_to_cart'); }}
    >
      Add to Cart
    </button>
  );
}

The page, track, and identify methods are available directly on a Ninetailed class instance.

import { Ninetailed } from '@ninetailed/experience.js';

const ninetailed = new Ninetailed({ clientId: "NINETAILED_API_KEY"})

ninetailed.page();
ninetailed.track('myEvent')
ninetailed.identify('alias', {traitName: "traitValue"})

See the Ninetailed Instance documentation for a full list of configuration options and methods available from the JS SDK.

import { ExperienceMapper } from '@ninetailed/experience.js-utils';

const mappedExperiences = (myEntry.nt_experiences || [])
  .map((experience) => {
    return {
      id: experience.id,
      name: experience.name
      type: experience.nt_type as 'nt_personalization' | 'nt_experiment'
      config: experience.nt_config,
      audience: {
        id: experience.nt_audience.nt_audience_id
        // If mapping for the Preview Plugin, this displays audience names
        name: experience.nt_audience.nt_name
      },
      variants: experience.variants.map((variant) => {
        return {
          id: variant.id, // Required
          // Map any other fields required by your components
          ...variant,
          someComponentProp: variant.foo
        }
      })
    }
  })
  .filter((experience) => ExperienceMapper.isExperienceEntry(experience))
  .map((experience) => ExperienceMapper.mapExperience(experience));

Your exact query and mapping will vary depending on both your content model and the props required by the component you use to render your content. This example assumes a content model using a content type of page that contains a field called sections that can reference entries of type hero.

It also shows using a lightweight GraphQL client library graphql-request to make the API request, but any GraphQL client is suitable.

import { request, gql } from "graphql-request";
import { filterAndMapExperiences, mapAudiences } from "../lib/helpers";

const CONTENTFUL_HERO_QUERY = gql`
  fragment SysId on Entry {
    sys {
      id
    }
  }

  fragment HeroEntry on Hero {
    ...SysId
    internalName
  }

  fragment NtExperienceFields on NtExperience {
    ...SysId
    ntExperienceId
    ntName
    ntType
    ntConfig
    ntAudience {
      ntAudienceId
    }
  }

  fragment NinetailedHero on Hero {
    ...HeroEntry
    ntExperiencesCollection(limit: 10) {
      items {
        ...NtExperienceFields
        ntVariantsCollection(limit: 10) {
          items {
            ...HeroEntry
          }
        }
      }
    }
  }


  query NinetailedHeroQuery($heroEntryid: String!) {
    page(id: $heroEntryid) {
      ...SysId
      sectionsCollection(limit: 10) {
        items {
          ...NinetailedHero
        }
      }
    }
  }
`;


export async function getHeroData(heroId) {
  const data = await request(
    `https://graphql.contentful.com/content/v1/spaces/${process.env.CTFL_SPACE_ID}`,
    CONTENTFUL_HERO_QUERY,
    heroId,
    {
      Authorization: `Bearer ${process.env.CTFL_API_KEY}`,
      "Content-Type": "application/json",
    }
  );
  return data;
}

import { ExperienceMapper } from '@ninetailed/experience.js-utils';
import { getHeroData } from 'api/yourDataFetcher';

const hero = await getHeroData('aHeroEntryId')

const mappedExperiences = (hero.ntExperiencesCollection?.items || [])
  .map((experience) => {
    return {
      id: experience.ntExperienceId,
      name: experience.ntName,
      type: experience.ntType,
      config: experience.ntConfig,
      // This syntax accounts for the possibility of an audience not being set on an experiment
      ...(experience.ntAudience
        ? { 
            audience: {
              id: experience.ntAudience.ntAudienceId
              // If mapping for the Preview Plugin, this displays audience names
              name: experience.ntAudience.ntName
            },
          }
        } : {})
      variants: experience.ntVariantsCollection.items.map((variant) => {
        return {
          id: variant.sys.id, // Required
          // Map any other fields required by your rendering component
          ...variant
        }
      })
    }
  })
  .filter((experience) => ExperienceMapper.isExperienceEntry(experience))
  .map((experience) => ExperienceMapper.mapExperience(experience));

Notice the use of fragments to capture the sys.id, since this is required on the Ninetailed Experience (NtExperience) entry as well as all variants referenced by the entry. Additionally, note the use of a fragment to isolate the fields of the Experience entry so that the base HeroEntry fragment can be used to query both the baseline and the variant content without introducing a circular reference.

// or '@ninetailed/experience.js-next', '@ninetailed/experience.js-gatsby'
import { Experience } from '@ninetailed/experience.js-react';
import { ExperienceMapper } from '@ninetailed/experience.js-utils'

// This function is assumed to return a single entry and all its supporting data, including referenced content, in their entirety
import { getCmsEntry } from '../api/yourEntryGetter'
import { YourComponent } from './YourComponent'

export const YourExperience = (cmsBaselineEntry) => {
  const baselineEntry = getCmsEntry(cmsBaselineEntry);
  const experiences = baselineEntry['nt_experiences']

  const mappedExperiences = (experiences || [])
  .map((experience) => {
    return {
      id: experience.id,
      name: experience.name
      type: experience.nt_type as 'nt_personalization' | 'nt_experiment'
      config: experience.nt_config,
      audience: {
        id: experience.nt_audience.nt_audience_id
      },
      variants: experience.variants.map((variant) => {
        return {
          id: variant.id, // Required
          // Map any other data from the variant required by your component
          ...variant,
          someComponentProp: variant.foo
        }
      })
    }
  })
  .filter((experience) => ExperienceMapper.isExperienceEntry(experience))
  .map((experience) => ExperienceMapper.mapExperience(experience));

  return (
    <Experience
      {...baselineEntry} // Any props your `component` above needs
      id={entry.id} // Required. The id of the BASELINE entry
      component={YourComponent} // Required. What to use to render the selected variant
      experiences={mappedExperiences} // Array of mapped experiences
  />);
};

// or '@ninetailed/experience.js-next', '@ninetailed/experience.js-gatsby'
import { Experience } from '@ninetailed/experience.js-react';

// For use with Contentful REST APIs only
import { ExperienceMapper } from '@ninetailed/experience.js-utils-contentful'

// This function is assumed to return a single entry and all its nested references from the REST Contentful CDA in their entirety
import { getContentfulEntry } from '../api/yourEntryGetter'
import { YourComponent } from './YourComponent'

export const YourExperience = (cmsBaselineEntry) => {
  const baselineEntry = getContentfulEntry(cmsBaselineEntry);
  const experiences = baselineEntry.fields.nt_experiences;
  const mappedExperiences = experiences
    .filter((experience) => ExperienceMapper.isExperienceEntry(experience))
    .map((experience) => ExperienceMapper.mapExperience(experience))

  return (
    <Experience
      {...baselineEntry} // Any props your `component` above needs
      id={baselineEntry.sys.id} // Required. The sys.id of the BASELINE entry
      component={YourComponent} // Required. What to use to render the selected variant
      experiences={mappedExperiences} // Array of mapped experiences
  />);
};

import React from 'react';
import { INLINES } from '@contentful/rich-text-types';
import { documentToReactComponents} from '@contentful/rich-text-react-renderer';
// or `@ninetailed/experience.js-next', @ninetailed/experience.js-gatsby'
import { MergeTag } from '@ninetailed/experience.js-react';

export const renderRichText = (richTextDocument) => {
  return documentToReactComponents(richTextDocument, {
    renderNode: {
      [INLINES.EMBEDDED_ENTRY]: (node) => {
        if (node.data.target.sys.contentType.sys.id === 'nt_mergetag')) {
          return (
            <MergeTag 
              id={node.data.target.fields.nt_mergetag_id}
              fallback={node.data.target.fields.nt_fallback}
            />
          );
        }
      }
    },
  });
};

import React from 'react';
// or `@ninetailed/experience.js-next', @ninetailed/experience.js-gatsby'
import { MergeTag } from '@ninetailed/experience.js-react';

const Greeting = () => {
  return (
  <> 
    <p>Welcome back, <MergeTag id="traits.firstName" fallback="you" />
    <p>How is <MergeTag id="location.city" fallback="your city" /> this time of year?</p>
  </>
};

const SomeAsyncConditionalComponent = () => {
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // ... Do something like get async data
    setLoading(false);
  }, []);

  // This component conditionally renders a top-level element, so tracking might be lost
  return loading ? (
    <div>Some loading markup</div>
  ) : (
    <div>Some markup after loading</div>
  );
};

const YourExperience = (cmsBaselineEntry) => {
  // ... Filter and map as above

  return (
    <Experience
      id={entry.id}
      component={SomeAsyncConditionalComponent}
      {...baselineEntry}
      experiences={mappedExperiences}
  />);
};

const SomeAsyncConditionalComponent = () => {
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // ... Do something like get async data
    setLoading(false);
  }, []);

// Wrapping an element around the conditional rendering to preserve tracking
return (
    <div> 
      (loading ? (<div>Some loading markup</div>) : (
      <div>Some markup after loading</div>) )
    </div>
  );
};

const YourExperience = (cmsBaselineEntry) => {
  // ... Filter and map as above

  return (
    <Experience
      id={entry.id}
      component={SomeAsyncConditionalComponent}
      {...baselineEntry}
      experiences={mappedExperiences}
  />);
};