Experience SDK

Overview

Contentful Personalization provides SDKs and plugins for modern web frameworks to enable you to harness the power of real-time personalization. All SDKs are written in Typescript to maximize your efficiency through code completion and compile-time analysis.

The Contentful Personalization SDKs provide abstracted means to communicate with the Contentful Personalization Experience API and the browser. It shortens integration times into JavaScript codebases. The SDKs handle:

• creating page, track, and identify events and sending them to the Experience API
• errors, retries and queuing
• caching the profile client-side via localStorage.

Composed JavaScript SDKs

Contentful Personalization’s lowest-level SDK is the Shared SDK, @ninetailed/experience.js-shared, whose primary function is to create an API Client that handles the details of working with the endpoints of the Experience API. It also exposes data objects, types, and methods applicable across development environments

Contentful Personalization’s JavaScript SDK, @ninetailed/experience.js, is composed from the Shared SDK. The principal function of the JavaScript SDK is to create an instance that stores and updates a profile in response to events. The JavaScript and Shared SDK form the foundations on top of which all other JavaScript-based SDKs are built.

Supported frameworks

For declarative front-end implementations, Contentful Personalization provides SDKs for:

• React
• Next.js
• Gatsby.

Additionally, Contentful Personalization provides a Node.js SDK for interacting with the Experience API in server or edge runtimes.

Choose an SDK

We strongly recommend using the SDK available for your framework ,if one is available, for the fastest, most declarative implementation.

For most Contentful Personalization users, it’s enough to install the appropriate React-based SDK, send page, track, and identify events to enhance user profiles, and use the <Experience> component to render personalization and experiment content client-side.

However, you may need to arbitrarily access profile data or exercise more control over how experiences are rendered and tracked.

These needs usually arise when:

1. you need more control within a React-based web application, like if you’re edge- or server-side rendering experiences and/or using React Server Components; or
2. you’re not implementing Contentful Personalization within a web-based React project (e.g., Vue/Nuxt, Svelte or React Native).

In such scenarios, the API Client created by the Shared SDK serves as the best starting place for upserting profiles in server and edge runtimes, while the JavaScript SDK provides declarative tracking behaviour to use in client-side code.

For any front-end integration that is not based on JavaScript, explore our Experience API for complete freedom on where to integrate.

Install the SDK

Dependency installation

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

Create an instance

The core responsibility of the Experience SDKs is to define a Ninetailed class instance based on your input configuration. The created instance is then responsible for:

• keeping track of the current profile and providing a hook into when the profile changes
• exposing declarative methods to interact with the Experience API
• providing extensibility to the instance through plugins.

When working with the React, Next.js or Gatsby SDK, an instance will be created and made available to your application globally using a React context provider.

1
import React from 'react';
2
import MyAppCode from '../myAppCode.jsx';
3
import { NinetailedProvider } from '@ninetailed/experience.js-react';
4
5
export const App = () => {
6
  return (
7
    <div id="my-app">
8
      <NinetailedProvider 
9
        // REQUIRED. An API key uniquely identifying your Ninetailed account.
10
        clientId="NINETAILED_API_KEY"
11
        
12
        // === ALL OF THE FOLLOWING PROPS ARE OPTIONAL ===
13
        // === DEFAULT VALUES ARE SHOWN ===
14
        
15
        // Your Ninetailed environment, typically either "main" or "development"
16
        environment="main"
17
        
18
        // Add any plugin instances
19
        plugins=[]
20
        
21
        // Specify an amount of time (ms) that an <Experience /> component must be present in the viewport to register a component view
22
        componentViewTrackingThreshold={2000}
23
        
24
        // Specify a maximum amount of time (ms) to wait for an Experience API response before falling back to baseline content
25
        requestTimeout={5000}
26
        
27
        // Specify a locale to localize profile location information
28
        locale="en-US"
29
        
30
        // Specify an alternative Experience API base URL
31
        url="https://experience.ninetailed.co"
32
        
33
        // Set to true ONLY if using an unindexed CMS
34
        useSDKEvaluation=true
35
      >
36
        <MyAppCode />
37
      </NinetailedProvider>
38
    </div>
39
  );   
40
}

Browser instance access

Installing the Experience SDK exposes several Contentful Personalization properties and methods on a window.ninetailed object to facilitate testing and debugging.

For a full description of instance properties and methods available to your application, consult the JavaScript SDK documentation.

Send events

Contentful Personalization profiles are created and updated by sending events about that profile to the Experience API. Rather than interacting with the Experience API endpoints directly, the principal way to send events is to use the methods made available from the JavaScript SDK.

A class instance created by any of Contentful Personalization’s SDKs composed from the JavaScript SDK provides three methods for sending events: page, track and identify.

page

1
type Page = (properties?: Object) => Promise<void>;

A page event indicates a user has viewed the current page. The SDK provides a context object describing the parameters of the page that has been viewed including the referrer, url, path, user-agent and other properties to be consumed by the API.

While most of the time you will call this page method with no arguments, you may optionally specify any properties you would like to associate with the page view event. This can be useful when creating Audiences. For example, if the category to which viewed blog posts belong is not contained within the URL of the blog posts but you’d like to create an Audience of visitors who have viewed blog posts of a certain category a certain number of times, you can pass the category along in the argument:

1
page({'category': 'YOUR_BLOG_CATEGORY'})

track

1
type Track = (event: string, properties?: Object) => Promise<void>;

track events are used to log specific named actions a user takes, like signup or registered_for_newsletter. Events can be named anything you like.

Track events may also accept a properties argument detailing additional information. For example, you might include the SKU and quantity of items on an add_to_cart event.

1
track('add_to_cart', {sku: '9T41L', quantity: 1})

In addition to serving as an Audience rule, track events are used to indicate the conversion events you want to measure in Experience Insights.

identify

1
type Identify = (uid: string, traits?: Traits) => Promise<void>;

Identify events serve two purposes:

First, identify allows you to add custom information, called traits, to a profile. Traits can be any attribute of interest about a customer. Any valid JSON is a valid trait. You can store any information of interest on profiles that you may want to use to segment users. For example, you might store a user’s responses from a sign up form, a list of products they recently visited, or data from an upstream source of your customer data like a CRM or CDP.

1
identify('', { favoriteColor: "red" })

Second, identify allows you to name or “alias” a profile such that it can be referenced by that same alias in the future. IDs stored within an analytics system, customer data platform, or e-commerce platform make ideal aliases.

1
identify('customer12345')

After aliasing a profile, you can reinstate the aliased profile on a different device or browser by calling identify again using the same supplied alias. This merges the latest activity of the current profile with the profile at that alias. For personalizations and experiments served to logged in users, you will likely want to call identify after each successful authentication.

Access event methods

1
import React from 'react';
2
3
import { useNinetailed } from '@ninetailed/experience.js-react';
4
// or import { useNinetailed } from '@ninetailed/experience.js-next';
5
// or import { useNinetailed } from '@ninetailed/experience.js-gatsby';
6
7
export const myComponent = () => {
8
  const { page, track, identify } = useNinetailed();
9
  
10
  page();
11
  identify('anAlias', {someTrait: "value"});
12
    
13
  return (
14
    <button 
15
      type="button" 
16
      onClick={() => { track('add_to_cart'); }}
17
    >
18
      Add to Cart
19
    </button>
20
  );
21
}

Custom flag change types

Custom flag change types provide an alternative way to manage changes within a personalization or experiment, using an ID in your code paired with plain text (string) or JSON (structured format) to make the change.

Using the <useFlag()> hook, you can fetch the changes from a profileState. We are accepting the changes that may come with the profile that is returned from the Experience API and handle that in the hook.

Parameters

Returns:

• value: The current flag value.
• status: ‘loading’ | ‘success’ | ‘error’.
• error: Error object or null.

Example

1
import { useFlag } from '@ninetailed/experience.js-react';
2
3
function MyComponent() {
4
  const { value, status } = useFlag('my-feature-flag', false);
5
6
  if (status === 'loading') {
7
    return <div>Loading...</div>;
8
  }
9
10
  return (
11
    <div>
12
      {value ? (
13
        <div>New Feature Enabled!</div>
14
      ) : (
15
        <div>Standard Experience</div>
16
      )}
17
    </div>
18
  );
19
}

Track views for custom flags

You can track the performance of your custom flag views by passing the shouldAutoTrack option to the useFlag hook, so you can analyze the impact of the dynamic content managed through the variable flags. It accepts a boolean or a function returning a boolean.

Example 1: Always track when resolved

1
const { value, status } = useFlag('theme-variable', {
2
  padding: '12px',
3
  color: 'black',
4
}, {
5
  shouldAutoTrack: true
6
});

Example 2: Conditionally track based on state

1
const { value, status } = useFlag('theme-variable', {
2
  padding: '12px',
3
  color: 'black',
4
}, {
5
  shouldAutoTrack: () => isUserLoggedIn() && hasCompletedOnboarding()
6
});

Manual tracking

If your personalization only becomes visible after a user interaction, for example, a modal shown on button click, you likely want to track the “view” of a custom flag at a later, custom point in time. For this purpose, you can use the following option: useFlagWithManualTracking. This ensures tracking is sent only when the user is actually affected by the flag.

Example:

1
const [flag, track] = useFlagWithManualTracking('modal-variant', 'default');
2
3
const handleSaveClick = () => {
4
  openModal(flag);
5
  track(); // Only now the user has seen the personalization
6
};

Tracked metadata

When a view is tracked for a Variable, the SDK sends a componentView event with:

Validate values at runtime

When providing JSON values for a custom flag, you must make sure the defined values are valid. For that, we can use runtime validation packages like zod.

Example: Button colors

In this example, we want to test button colors. To do so, we create a new Experiment in Contentful Personalization and use Custom flags with a JSON type. We then define the values as needed:

In code, we need to use these values and validate them at runtime to ensure that our visitors don’t encounter any errors in production:

1
import * as z from "zod";
2
3
// Zod schema for runtime validation (making sure it's a HEX value like #ABC123)
4
const ButtonStyleSchema = z.object({
5
  backgroundColor: z.string().regex(/^#[0-9a-f]{6}$/i),
6
  color: z.string().regex(/^#[0-9a-f]{6}$/i),
7
});
8
const ButtonMapSchema = z.object({
9
  primary: ButtonStyleSchema,
10
  secondary: ButtonStyleSchema,
11
});
12
type ButtonMap = z.infer<typeof ButtonMapSchema>;
13
14
// define the default values (you could also do that within useFlag)
15
const defaultButtonMap: ButtonMap = {
16
  primary: { backgroundColor: '#4f46e5', color: '#ffffff' },
17
  secondary: { backgroundColor: '#e0e7ff', color: '#4338ca' },
18
};
19
20
// capturing the real value
21
const { value: rawButtonMapValue } = useFlag<ButtonMap>(
22
  'buttonColors',
23
  defaultButtonMap,
24
);
25
26
// Validate the variant map and fall back to default if invalid
27
const validationResult = ButtonMapSchema.safeParse(rawButtonMapValue);
28
const buttonMap: ButtonMap = validationResult.success
29
  ? validationResult.data
30
  : defaultButtonMap;

Utility libraries

Our Experience API utility libraries provide methods to map experience content to the format required by the <Experience> component exported by our React, Next.js, and Gatsby SDKs.

Use the Contentful Utility SDK if you are are retrieving content and experiences using Contentful’s client libraries that interface with the Contentful REST APIs, including:

• the Contentful Content Delivery API
• the Contentful Content Preview API

For all other sources, including the Contentful GraphQL API or your own internal content APIs, middleware, use the JavaScript Utility SDK and map your experiences to the type required by the ExperienceMapper class methods.

JavaScript library usage

1
npm install @ninetailed/experience.js-utils
2
# OR
3
yarn add @ninetailed/experience.js-utils

You must map your fetched CMS Experience entries to a particular shape prior to transforming them with the ExperienceMapper methods. The following examples show the format required in a .map step prior to calling .filter to remove ill-formatted entries.

1
import { ExperienceMapper } from '@ninetailed/experience.js-utils';
2
3
const mappedExperiences = (myEntry.nt_experiences || [])
4
  .map((experience) => {
5
    return {
6
      id: experience.id,
7
      name: experience.name
8
      type: experience.nt_type as 'nt_personalization' | 'nt_experiment'
9
      config: experience.nt_config,
10
      audience: {
11
        id: experience.nt_audience.nt_audience_id
12
        // If mapping for the Preview Plugin, this displays audience names
13
        name: experience.nt_audience.nt_name
14
      },
15
      variants: experience.variants.map((variant) => {
16
        return {
17
          id: variant.id, // Required
18
          // Map any other fields required by your components
19
          ...variant,
20
          someComponentProp: variant.foo
21
        }
22
      })
23
    }
24
  })
25
  .filter((experience) => ExperienceMapper.isExperienceEntry(experience))
26
  .map((experience) => ExperienceMapper.mapExperience(experience));

Contentful library usage

$
npm install @ninetailed/experience.js-utils-contentful
$
# OR
$
yarn add @ninetailed/experience.js-utils-contentful

1
import { ExperienceMapper } from '@ninetailed/experience.js-utils-contentful'
2
import { createClient } from 'contentful';
3
4
const client = createClient({
5
  accessToken: 'youtAccessToken',
6
  space: 'yourSpaceId'
7
})
8
9
// Specify what entries with Ninetailed Experience references to get from Contentful
10
const query = {...}
11
12
const rawEntries = await client.getEntries(query);
13
// Extract one entry, as an example
14
const [yourEntry] = rawEntries.items
15
16
// Filter and map with ExperienceMapper methods
17
const experiences = (yourEntry.fields.nt_experiences || [])
18
    .filter(ExperienceMapper.isExperienceEntry)
19
    .map(ExperienceMapper.mapExperience)

See also our Contentful + Next.js example project for context.

ExperienceMapper class methods

isExperienceEntry

Determines if a provided entry is of valid type to be consumed by mapExperience. Use with .filter to remove any invalidly typed experiences.

mapExperience

Transform an experience to the type required by the <Experience> component.

isExperimentEntry

Determines if a provided entry is of valid type to be consumed by mapExperiment. Use with .filter to remove any invalidly typed experiments.

mapExperiment

Transform an experiment to the type required by the React and Next.js <NinetailedProvider> experiments prop.

mapCustomExperience

This class method is for the Contentful library only. If you need to modify how the variants referenced by an experience entry retrieved from Contentful are mapped, use this method to pass a custom variant mapping function. Example usage:

1
const experiences = myExperience.fields.nt_experiences
2
  .filter(ExperienceMapper.isExperienceEntry)
3
  .map((experience) => {
4
    ExperienceMapper.mapCustomExperience(experience, (variant) => {
5
      id: variant.sys.id // required
6
      // Add any data required by your `component` prop on the <Experience> component
7
      ...variant.fields,
8
      someComponentProp: variant.foo
9
    });
10
  })

mapCustomExperienceAsync

This class method is for the Contentful library only, SDK >= 7.7.x. Similar to mapCustomExperience, but allows asynchronous operations to be executed in the variant mapping step.

1
const experiences = myExperience.fields.nt_experiences
2
  .filter(ExperienceMapper.isExperienceEntry)
3
  .map((experience) => {
4
    ExperienceMapper.mapCustomExperienceAsync(experience, async (variant) => {
5
      await new Promise ((resolve) => setTimeout(resolve, 1000)); // Simulated delay supported by async handler
6
      return {
7
        id: variant.sys.id // required
8
        // Add any data required by your `component` prop on the <Experience> component
9
        ...variant.fields,
10
        someComponentProp: variant.foo
11
      }
12
    });
13
  })

mapBaselineWithExperiences

This class method is for the Contentful library only. Supply an object representing a baseline entry and its attached experiences and return an array of filtered and mapped experiences.

Render Experiences

The <Experience> component

The React-based SDKs provide an <Experience> component to wrap your existing React components you use to render your content. This is the most declarative way to render personalization and experiment content, and therefore the methodology that most users should adopt when possible.

The <Experience> component functions wraps your existing React component. It automatically detects the properties needed from the wrapped component. The experiences prop accepts Experience content that has been appropriately transformed by the ExperienceMapper available from our Utility libraries.

<Experience> component props

Example use

These examples show working CMS data, our Utility Libraries, and the <Experience> component together in demonstrative examples. Your implementation will vary according to your existing React components and your data source. Consult the Utility libraries documentation to know what data to fetch from your content source and how to transform the returned Experience entries to the format required by the <Experience> component.

These examples show fetching CMS data from within potentially deeply nested React components. In practice, you will likely fetch that data from higher within your rendering tree and pass it to components, especially when statically pre-rendering. However, the mapping exercises and use of the <Experience> component demonstrated remain the same no matter what rendering strategy you adopt.

1
// or '@ninetailed/experience.js-next', '@ninetailed/experience.js-gatsby'
2
import { Experience } from '@ninetailed/experience.js-react';
3
import { ExperienceMapper } from '@ninetailed/experience.js-utils'
4
5
// This function is assumed to return a single entry and all its supporting data, including referenced content, in their entirety
6
import { getCmsEntry } from '../api/yourEntryGetter'
7
import { YourComponent } from './YourComponent'
8
9
export const YourExperience = (cmsBaselineEntry) => {
10
  const baselineEntry = getCmsEntry(cmsBaselineEntry);
11
  const experiences = baselineEntry['nt_experiences']
12
  
13
  const mappedExperiences = (experiences || [])
14
  .map((experience) => {
15
    return {
16
      id: experience.id,
17
      name: experience.name
18
      type: experience.nt_type as 'nt_personalization' | 'nt_experiment'
19
      config: experience.nt_config,
20
      audience: {
21
        id: experience.nt_audience.nt_audience_id
22
      },
23
      variants: experience.variants.map((variant) => {
24
        return {
25
          id: variant.id, // Required
26
          // Map any other data from the variant required by your component
27
          ...variant,
28
          someComponentProp: variant.foo
29
        }
30
      })
31
    }
32
  })
33
  .filter((experience) => ExperienceMapper.isExperienceEntry(experience))
34
  .map((experience) => ExperienceMapper.mapExperience(experience));
35
  
36
  return (
37
    <Experience
38
      {...baselineEntry} // Any props your `component` above needs
39
      id={baselineEntry.sys.id} // Required. The sys.id of the BASELINE entry
40
      component={YourComponent} // Required. What to use to render the selected variant
41
      experiences={mappedExperiences} // Array of mapped experiences
42
      trackClicks // Whether clicks should be tracked for the rendered component
43
      trackHovers // Whether hovers should be tracked for the rendered component
44
  />);
45
};

Inline Personalization with merge tags

Contentful Personalization allows you to embed content placeholders into Rich Text Fields that can then be rendered client-side using information from the current visitor’s profile. These dynamic placeholder entries are called Merge Tags, which can then be used as inline entries within a rich text field of your CMS entries.

The React-based SDKs provide a corresponding <MergeTag /> component that allow you to declaratively render the inlined Merge Tag entries.

While rendering Merge Tag entries embedded within Rich Text Fields is the most common use for merge tags, you simply pass the property accessor (using dot notation) of any Contentful Personalization profile property as the id of the MergeTag component.

1
import React from 'react';
2
import { INLINES } from '@contentful/rich-text-types';
3
import { documentToReactComponents} from '@contentful/rich-text-react-renderer';
4
// or `@ninetailed/experience.js-next', @ninetailed/experience.js-gatsby'
5
import { MergeTag } from '@ninetailed/experience.js-react';
6
7
export const renderRichText = (richTextDocument) => {
8
  return documentToReactComponents(richTextDocument, {
9
    renderNode: {
10
      [INLINES.EMBEDDED_ENTRY]: (node) => {
11
        if (node.data.target.sys.contentType.sys.id === 'nt_mergetag')) {
12
          return (
13
            <MergeTag 
14
              id={node.data.target.fields.nt_mergetag_id}
15
              fallback={node.data.target.fields.nt_fallback}
16
            />
17
          );
18
        }
19
      }
20
    },
21
  });
22
};

Tracking impressions of Experiences

The <Experience> component needs to track when the markup it renders is present within the visitor’s viewport. This is the criteria used to fire impression events to any connected Contentful Personalization plugins.

Unless the component prop being passed to <Experience> is defined as a React forwardRef, the <Experience> component will insert an empty non-displaying <div> of class nt-cmp-marker immediately prior to the rendered component. It is this inserted element’s intersection with the viewport that then tracked.

1
// Returned markup from the <Experience> component when passing a regular component
2
<div className="nt-cmp-marker" style="display: none !important">
3
<!-- Your rendered component content -->
4
<div>
5
    <!-- ... -->
6
</div>

Under the hood, the tracking component uses React’s useRef to store the DOM node to track. See the React forwardRef documentation for more details.

Because of the use of useRef, it is important that the components you pass have some consistent parent element between re-renders. Conditionally rendering top-level elements in a component may cause tracking to become decoupled.

1
const SomeAsyncConditionalComponent = () => {
2
  const [loading, setLoading] = useState(true);
3
4
  useEffect(() => {
5
    // ... Do something like get async data
6
    setLoading(false);
7
  }, []);
8
9
  // This component conditionally renders a top-level element, so tracking might be lost
10
  return loading ? (
11
    <div>Some loading markup</div>
12
  ) : (
13
    <div>Some markup after loading</div>
14
  );
15
};
16
17
const YourExperience = (cmsBaselineEntry) => {
18
  // ... Filter and map as above
19
  
20
  return (
21
    <Experience
22
      id={entry.id}
23
      component={SomeAsyncConditionalComponent}
24
      {...baselineEntry}
25
      experiences={mappedExperiences}
26
  />);
27
};