Contentful Integration Guide

{
  traffic: number;           // Traffic percentage (0-1) allocated to this experience
  distribution: number[];    // Variant distribution weights, e.g., [0.5, 0.5]
  components: Array<{
    baseline: { id: string };
    variants: Array<{ id: string; hidden?: boolean }>;
  }>;
  sticky?: boolean;          // Whether assignment persists across sessions
}

import { createClient } from 'contentful';

const contentfulClient = createClient({
  space: process.env.NEXT_PUBLIC_CONTENTFUL_SPACE_ID ?? '',
  accessToken: process.env.NEXT_PUBLIC_CONTENTFUL_TOKEN ?? '',
  environment: process.env.NEXT_PUBLIC_CONTENTFUL_ENVIRONMENT ?? 'master',
}).withoutUnresolvableLinks;

const previewClient = createClient({
  space: process.env.NEXT_PUBLIC_CONTENTFUL_SPACE_ID ?? '',
  accessToken: process.env.NEXT_PUBLIC_CONTENTFUL_PREVIEW_TOKEN ?? '',
  host: 'preview.contentful.com',
}).withoutUnresolvableLinks;

const getClient = (preview: boolean) => {
  return preview ? previewClient : contentfulClient;
};

const entries = await client.getEntries<IPageSkeleton>({
  limit: 1,
  include: 10,
  'fields.slug': slug,
  content_type: 'page',
});
const [page] = entries.items;

const entries = await contentfulClient.getEntries<INtExperienceSkeleton>({
  content_type: 'nt_experience',
  include: 1,
});
return (entries.items as unknown as ExperienceEntryLike[])
  .filter(ExperienceMapper.isExperienceEntry)
  .map(ExperienceMapper.mapExperience);

const entries = await contentfulClient.getEntries<INtAudienceSkeleton>({
  content_type: 'nt_audience',
  include: 1,
});
return entries.items
  .filter(AudienceMapper.isAudienceEntry)
  .map(AudienceMapper.mapAudience);

const entries = await client.getEntries<INtExperienceSkeleton>({
  content_type: 'nt_experience',
  'fields.nt_type': 'nt_experiment',
  include: 1,
});
return (entries.items as unknown as ExperienceEntryLike[])
  .filter(ExperienceMapper.isExperienceEntry)
  .map(ExperienceMapper.mapExperiment);

static isExperienceEntry(entry): entry is ExperienceEntry {
  return ExperienceEntry.safeParse(entry).success;
}

static mapExperience(ctfEntry) {
  const { fields } = validateExperienceEntry(ctfEntry);
  const variants = fields.nt_variants.map((variant) => ({
    ...variant,
    id: variant.sys.id,
  }));
  const experience = createExperience(fields, variants);
  return DefaultExperienceMapper.mapExperience(experience);
}

const experiences = entry.fields.nt_experiences
  .filter(ExperienceMapper.isExperienceEntry)
  .map((experience) =>
    ExperienceMapper.mapCustomExperience(experience, (variant) => ({
      id: variant.sys.id,
      ...variant.fields,
    }))
  );

const experiences = ExperienceMapper.mapBaselineWithExperiences(heroEntry);

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

const experiences = (entry.fields.nt_experiences || [])
  .filter(ExperienceMapper.isExperienceEntry)
  .map(ExperienceMapper.mapExperience);

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

const mappedExperiences = (myEntry.nt_experiences || [])
  .map((experience) => ({
    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) => ({
      id: variant.id,
      ...variant,
    })),
  }))
  .filter(ExperienceMapper.isExperienceEntry)
  .map(ExperienceMapper.mapExperience);

Contentful API -> Fetch entries (include depth >= 2) ->
  For each entry:
    -> Resolve content type ID via entry.sys.contentType.sys.id
    -> Look up React component in ContentTypeMap
    -> Extract nt_experiences field
    -> Filter with ExperienceMapper.isExperienceEntry()
    -> Map with ExperienceMapper.mapExperience()
    -> Wrap with <Experience> component
    -> Render with resolved variant or baseline

const ContentTypeMap = {
  hero: Hero,
  cta: CTA,
  feature: Feature,
  banner: Banner,
  navigation: Navigation,
  footer: Footer,
  pricingPlan: PricingPlan,
  pricingTable: PricingTable,
};

const ComponentRenderer: React.FC<ComponentRendererProps> = (props) => {
  const contentTypeId = get(props, 'sys.contentType.sys.id') as string;
  const Component = ContentTypeMap[contentTypeId];
  if (!Component) {
    console.warn(`${contentTypeId} can not be handled`);
    return null;
  }
  return <Component {...props} />;
};

const BlockRenderer = ({ block }: BlockRendererProps) => {
  if (Array.isArray(block)) {
    return (
      <>
        {block.map((b) => (
          <BlockRenderer key={`block-${b.sys.id}`} block={b} />
        ))}
      </>
    );
  }

  const contentTypeId = get(block, 'sys.contentType.sys.id') as string;
  const { id } = block.sys;

  const experiences = (
    (block.fields.nt_experiences || []) as ExperienceEntryLike[]
  )
    .filter((experience) => ExperienceMapper.isExperienceEntry(experience))
    .map((experience) => ExperienceMapper.mapExperience(experience));

  return (
    <div key={`${contentTypeId}-${id}`}>
      <Experience
        {...block}
        id={id}
        component={ComponentRenderer}
        trackClicks
        experiences={experiences}
      />
    </div>
  );
};

import { documentToReactComponents } from '@contentful/rich-text-react-renderer';
import { BLOCKS, INLINES } from '@contentful/rich-text-types';

const options = {
  renderNode: {
    [BLOCKS.EMBEDDED_ENTRY]: (node) => {
      return <BlockRenderer block={node.data.target} />;
    },
  },
};

import { INLINES } from '@contentful/rich-text-types';
import { MergeTag } from '@ninetailed/experience.js-react';

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 { MergeTag } from '@ninetailed/experience.js-react';

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

<NinetailedProvider
  clientId="NINETAILED_API_KEY"          // REQUIRED
  environment="main"                      // "main" or "development", default: "main"
  plugins={[]}                            // Array of plugin instances
  componentViewTrackingThreshold={2000}   // ms in viewport before tracking fires
  requestTimeout={5000}                   // ms to wait for API before fallback to baseline
  locale="en-US"                          // Locale for profile location info
  url="https://experience.ninetailed.co"  // Experience API base URL
>
  <MyAppCode />
</NinetailedProvider>

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

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

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

// React/Next.js/Gatsby
const { page, track, identify } = useNinetailed();

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

const { value, status, error } = useFlag('flagKey', defaultValue, options?);

const [flag, track] = useFlagWithManualTracking('modal-variant', 'default');

const handleClick = () => {
  openModal(flag);
  track(); // Track only when user actually sees the personalization
};