Quick Start for Developers (Next.js)

Overview
This guideline walks you through setting up and integrating Contentful, Ninetailed, and Next.js. In this guide, you'll find:
How to set up Ninetailed App on Contentful
How to install the SDK for Next.js
How to use Ninetailed Profiles in Next.js
Steps you need to follow to personalize components in Next.js
How to integrate Google Analytics with Ninetailed
Next steps and further integrations
Step 1: Set Up the Ninetailed App on Contentful
1.Install the Ninetailed App from the Contentful marketplace.
2.Select the organization and space you want to install the app.
3.Authorize the app access and continue installing Ninetailed.
4.Connect your Contentful account to Ninetailed App and then:
1.create an organization
2.confirm your settings
3.complete installation
5.Get your API Key. You can find your API Key in the Ninetailed App configuration (You will need your API Key in the next steps):
Find more information about the install process in the Contentful section.
Step 2: Frontend Integration for Next.js
In this step, you'll find the steps you need to follow to add Ninetailed to Next.js. With the Next.js SDK, you can add dynamic content for personalization to any component.
1. Install Next.js SDK
Install the @ninetailed/experience-sdk-nextjs module via npm or yarn.
Install module via npm:
1
npm install @ninetailed/experience-sdk-nextjs
Copied!
Install module via yarn:
1
yarn add @ninetailed/experience-sdk-nextjs
Copied!
How to Use
This is what the configuration of @ninetailed/experience-sdk-nextjs looks like:
1
import React from 'react';
2
import {
3
  PersonalizationProvider
4
} from '@ninetailed/experience-sdk-nextjs';
5
​
6
export const App = () => {
7
    return (<>
8
        <PersonalizationProvider apiKey={YOUR_API_KEY}>
9
            <YourAppCode />
10
        </ProfileProvider>    
11
    </>);   
12
}
Copied!
Your API Key can be found in the Ninetailed App configuration.
2. Profile
Ninetailed manages visitor profiles automatically, which gets updated via page(), track(), identify() events. Ninetailed uses profiles internally to calculate your personalizations and render merge tags in your rich text components.
1
type Profile = {
2
  /**
3
   * An id which can get set by you - e.x. CRM id.
4
   */
5
  id?: string;
6
  /**
7
   * This is an internal identifier to find the visitor in our system.
8
   */
9
  anonymousId: string;
10
  /**
11
   * The calculated audiences the visitor is in.
12
   */
13
  audiences: string[];
14
  /**
15
   * Tratits you have set via identify(id: string, traits: Traits) calls.
16
   */
17
  traits: Traits;
18
  /**
19
   * The current location of the user.
20
   */
21
  location: Location;
22
};
Copied!
Traits is a JSON dataset that can be set by you through identify calls. Whenever you send new traits to our system we deeply merge the traits of the user. "Traits" are commonly used in merge tags to build inline personalization like const headline = Hey ${profile.traits.firstname}👋.
1
type Traits = {
2
  [key: string]: string | number | boolean | Traits;
3
};
4
​
5
// example
6
const traits: Traits = {
7
  "firstname": "Max",
8
  "address": {
9
    "street": "Allee 33"
10
  },
11
  "company": "Big fat Company"
12
}
Copied!
Location is the last seen location of the user. You would normally use this to merge it into Richtext.
1
type Location = {
2
  coordinates?: {
3
    latitude: number;
4
    longitude: number;
5
  };
6
  city?: string;
7
  postalCode?: string;
8
  region?: string;
9
  regionCode?: string;
10
  country?: string;
11
  continent?: string;
12
  timezone?: string;
13
};
Copied!
useProfile
The useProfile hook makes it really easy for you to access the profile of the visitor.
1
import { useProfile } from '@ninetailed/experience-sdk-nextjs';
Copied!
The hook delivers the profile and the loading and error state.
1
const Greeting = () => {
2
    const [loading, profile, error] = useProfile();
3
    
4
    return <p>Hey {profile.traits.firstname}, nice weather in {profile.location.city}!</p>
5
}
Copied!
3. Analytics & Events
As a Ninetailed App, we need to know about the visitor currently viewing the website to personalize the content. Our customer data platform is in charge of this information. In any case, you need to provide events about the user to our API to generate a profile over time.
In order to make this process as simple as possible, Ninetailed provides the page(), track(), and identify() methods which can be used via the useAnalytics hook or the window object of the browser, for example, in a Tag Manager.
useAnalytics
The useAnalytics hook provides the event tracking functions inside your React components. This is very handy if you want to send events from your code.
1
import React from 'react';
2
import { useAnalytics } from '@ninetailed/experience-sdk-nextjs';
3
​
4
const CallToAction = () => {
5
    const { track, page, identify } = useAnalytics();
6
    
7
    return (<button 
8
        type="button" 
9
        onClick={() => { track('built new Rick'); }}
10
    >
11
        build new Rick
12
    </button>);
13
}
Copied!
Events
Page View
Page views should be sent on every page change. Our SDK populates all data needed as, referrer, url, user-agent and other properties to be consumed by the API.
1
type Page = () => Promise<void>;
Copied!
Track
Track events are used to describe special actions the user did, like signup or registered_for_newsletter.
1
type Track = (event: string) => Promise<void>;
Copied!
Identify
By identifying a user you add a custom id to the profile, like a Hubspot id or an id from your internal database. Even more important, you can set traits about this customer, like the firstname, age or anything you want to personalize the content even more.
1
type Identify = (uid: string, traits: Traits) => Promise<void>;
Copied!
Tag Manager
The Analytics SDK also add the page(), track() and identify() functions to the window object. That way you can also access them from a Tag Manager. We recommend sending page views directly from the code as soon as the SDK is initialized so the personalizations are not delayed.
4. Personalization Components
Personalize Component
To make personalizing your components as seamless as possible Ninetailed provides a <Personalize /> component that wraps the component you'd like to personalize. It automatically detects the properties needed from the wrapped component and also applies a variants property.
1
import React from 'react';
2
import { Personalize } from '@ninetailed/experience-sdk-nextjs';
3
​
4
type HeadlineProps = {
5
  text: string;
6
}
7
​
8
const Headline: React.FC<HeadlineProps> = ({ text }) => {
9
  return <h1>{text}</h1>
10
};
11
​
12
export const Page = () => {
13
  // These variants normally come from Contentful, just inlined here to see the structure
14
  const variants = [
15
    {
16
      text: "We build super nice websites for enterprise companies!", 
17
      audience: "enterprise-audience-id" // variants have a audience id
18
    }
19
  ]
20
  
21
  return (<Personalize 
22
    component={Headline} 
23
    variants={variants} 
24
    text="We build websites for everbody" // this is the baseline for user which are not in a audience. 
25
  />);
26
};
Copied!
Inline Personalization
The Ninetailed Contentful App allows your content creators to use inline personalization in Richtext fields. Inline personalization is done by adding embedded entries into the text. Also, using merge tags makes it very easy to use inline personalization.
1
import React from 'react';
2
import { documentToReactComponents, Options } from '@contentful/rich-text-react-renderer';
3
import { INLINES } from "@contentful/rich-text-types";
4
import { MergeTag } from '@ninetailed/experience-sdk-nextjs';
5
​
6
const richTextOptions = (links: HeroHeadlineLinks): Options => {
7
    const entryMap = new Map();
8
    for (const entry of links.entries.inline) {
9
        entryMap.set(entry?.sys.id, entry);
10
    }
11
​
12
    return {
13
        renderNode: {
14
            [INLINES.EMBEDDED_ENTRY]: (node) => {
15
                const id = node.data.target.sys.id;
16
                if (id) {
17
                    const mergeTag = entryMap.get(id);
18
                    return <MergeTag id={mergeTag.id}/>;
19
                }
20
                return <>{`${node.nodeType} ${id}`}</>;
21
            }
22
        }
23
    };
24
};
25
​
26
const Greeting = ({ text }) => {
27
  return documentToReactComponents(text.json, headlineOptions(text.links))
28
};
Copied!
5. Server Side Rendering
You can use Next.js to fetch personalized content from the server and serve a fully updated page via server side rendering.
1
import {
2
  PersonalizationProvider,
3
  getServerSideProfile,
4
} from '@ninetailed/experience-sdk-nextjs';
5
import { Hero } from './Hero';
6
​
7
const Page = ({ ninetailed, data }) => {
8
  <PersonalizationProvider profile={ninetailed.profile} apiKey={API_KEY}>
9
    <Personalize component={Hero} headline={data.headline} variants={data.variants}/>
10
  </PersonalizationProvider>
11
}
12
​
13
export async function getServerSideProps() {
14
  const profile = await getServerSideProfile(ctx, {
15
    apiKey: API_KEY,
16
  });
17
  
18
  const data = await getPageData();
19
​
20
  return { props: { ninetailed: { profile }, data } };
21
}
22
​
23
export default Page
Copied!
Step 3: Connect with Google Analytics
By integrating Google Analytics with the Ninetailed, you can send Ninetailed events to Google Analytics for analysis.‌
How to Use
To use, install the package, include it in your project, and initialize the plugin with AnalyticsProvider
1
import { AnalyticsProvider } from '@ninetailed/experience-sdk-nextjs';
2
​
3
<AnalyticsProvider plugins={
4
  [
5
    googleAnalytics({
6
      trackingId: 'UA-1234567'
7
    })
8
  ]
9
}
10
>
Copied!
Find more information about how to integrate Google Analytics with Ninetailed.
What's Next
After following these steps, you'll have Ninetailed integrated with Contentful that is ready to start creating personalized content for your audiences.
Find more information about how to create personalized content for your audiences in the Personalized Content and Audience Builder documents.
Getting started - Previous
Quick Start for Developers (React)
Next - Content Management Systems
Getting started
Last modified 6mo ago
Copy link
Contents
Overview
Step 1: Set Up the Ninetailed App on Contentful
Step 2: Frontend Integration for Next.js
1. Install Next.js SDK
2. Profile
3. Analytics & Events
4. Personalization Components
5. Server Side Rendering
Step 3: Connect with Google Analytics
What's Next