The Prepr Next.js package

The Prepr Next.js package offers some helper functions and the Adaptive Preview Bar for easier personalization and A/B testing implementation. This guide introduces you to the Prepr Next.js package and shows you how to use it.

Prerequisites

• You need to have a Next.js project connected to Prepr before installing the package.

Introduction

The Prepr Next.js package includes the following features:

• It provides API request headers for the following values:
  • Each visitor's customer ID. You need this API request header, Prepr-Customer-Id, when you query adaptive content and content with A/B testing.
  • Any UTM parameters, if applicable. This is useful to identify customers who enter your website through a social media campaign, for example.
  • HubSpot cookie, if it exists. This is useful for identifying customers who are tracked in HubSpot as a lead, for example.
  • The visitor's IP address. This is useful for localization.

• The Adaptive Preview Bar. This component provides an easy way to test adaptive content and content with A/B test variants.

Installation

To install the Prepr Next.js package, follow the steps below.

1. Run the following command in your Next.js project:

npm install @preprio/prepr-nextjs

2. Add the PREPR_ENV variable to the .env file. You can enable the Adaptive Preview Bar for a staging environment by setting the value to preview.

   Set this variable to production when you deploy your website to production so that the preview bar component doesn't get displayed in your live website.

PREPR_GRAPHQL_URL=<YOUR-PREPR-GRAPHQL-URL>
PREPR_ENV=preview

3. To manage request headers for adaptive and A/B test content you need to implement the PreprMiddleware function. Go to your middleware.ts or the middleware.ts file and add the code below. If you don't have this file, you can create it in the root of your project.

import type { NextRequest } from 'next/server'
import { PreprMiddleware } from '@preprio/prepr-nextjs'
 
export function middleware(request: NextRequest) {
    return PreprMiddleware(request)
}

Behind the scenes

• The PreprMiddleware function accepts a request and optional response property and returns a NextRequest object. It does this so you can chain your own middleware to it.

• The PreprMiddleware function checks every request if the __prepr_uid cookie is set. If it isn't, the function generates a new UUID and sets the cookie with this new value. Then it returns a Prepr-Customer-Id header with the value of the __prepr_uid cookie to simplify your personalization and A/B testing implementation.

• If the PREPR_ENV environment variable is set to preview, the PreprMiddleware function also checks for searchParams segments and a-b-testing in the URL. If these searchParams are set, the PreprMiddleware sets the Prepr-Segments and Prepr-AB-Testing headers with the values of the searchParams, and stores its value in a cookie.

Now that you've successfully installed the package, let's see how to use it.

Usage

Setting your API request headers

When requesting adaptive content or A/B testing content you need to send the Customer ID in the request header. The getPreprHeaders() helper function simplifies this by setting the API request headers for you. Simply call the getPreprHeaders() helper function like in the example code below for a typical web page. It returns an array of headers that you can include in the request.

import { getClient } from '@/lib/client'
import { GetPageBySlugDocument, GetPageBySlugQuery } from '@/gql/graphql'
import { getPreprHeaders } from '@preprio/prepr-nextjs'
 
const getData = async () => {
    // Fetching the data using Apollo Client
    const {data} = await getClient().query < GetPageBySlugQuery > ({
        query: GetPageBySlugDocument,
        variables: {
            slug: '/',
        },
        context: {
            // Call the getPreprHeaders function to get the appropriate headers
            headers: getPreprHeaders(),
        },
        fetchPolicy: 'no-cache',
    })
}

Installing the Adaptive Preview Bar component

The Adaptive Preview Bar is a small component at the top of your preview website that allows editors to quickly switch between A/B testing variants and personalization segments. The instructions below show you how to set it up.

The preview bar component fetches all segments from the Prepr API. So, you need to give it access to do this as follows:

1. In your Prepr environment, go to the Settings → Access tokens page to view all the access tokens.

2. Click the GraphQL preview access token to open it and tick the Enable edit mode checkbox and click the Save button.

Now that you've set up the access for the preview bar, you can display the Adaptive Preview Bar component as follows:

1. Navigate to your root layout file, this is usually layout.tsx. Then add the following code to your layout file.

// Helper function to get all the props for the PreviewBar component (this needs a server component)
import { getPreviewBarProps } from '@preprio/prepr-nextjs'
// Import the PreviewBar component
import { PreprPreviewBar } from '@preprio/prepr-nextjs/components'
// Import the PreviewBar CSS
import '@preprio/prepr-nextjs/dist/components.css'
 
 
export default async function RootLayout({children}: {children: React.ReactNode}) {
    // Get the props for the PreviewBar component, pass the access token as an argument
    const previewBarProps = await getPreviewBarProps(process.env.PREPR_GRAPHQL_URL)
 
    return (
        <html>
            <head>
                {/*...*/}
            </head>
            <body>
                {/* Render the PreviewBar component and include the previewBarProps */}
                <PreprPreviewBar {...previewBarProps} />
                {children}
            </body>    
        </html>
    )
}

Now the Adaptive Preview Bar component is rendered on every page of your website. This component shows the segments in a dropdown list and a switch for A and B variants for an A/B test. By adding the getPreprHeaders() function to your API calls like you did in the previous section, it automatically updates the adaptive content and A/B testing variants when you select a new segment or variant.

Adaptive content example - Electric Car Lovers segment

A/B testing example - B variant

All done

Congratulations! You've successfully simplified personalization and A/B testing, and installed the Adaptive preview bar in your Next.js website. This brings you to the end of the setup guide for the Prepr Next.js package. Don't hesitate to give us feedback on your experience using this guide.

Next steps

To learn more on how to expand your Next.js project, check out the following resources:

• More data collection details
• More about A/B testing
• More about personalization