Activate personalization
note
This following section is only relevant if your are not using Uniform to manage your personalization placement and variations such as when using Uniform apps for headless CMSs like Contentful, Contentstack, Sanity or Kontent.ai.
If you are using Uniform's visual editor to manage layout in your application this section doesn't apply and no additional configuration is required in your front-end application. You should skip this section.
Activating personalization in your application involves adding components that can execute personalization instructions. By default, Uniform executes personalization on the client. However, Uniform also supports edge-side personalization.
Personalization modes#
Uniform supports a variety of personalization modes. Each has its own advantages and disadvantages. The available modes depend on the rendering mode you use.
| Server side (SSR) | Static site (SSG) | |
|---|---|---|
| Description | The application renders on a server in its entirety before it reaches the client. | The application is rendered at build-time. |
| Time to first byte (TTFB) | Affected by time needed to load content. | Optimized by content being fetched at build-time. |
| Scalability | Increased server load requires increased server costs. | Instant and global. |
| Application size | Application size is irrelevant because the application renders on demand. | Very large sites may take a long time to render. |
| Personalization modes |
|
|
Client-side#
warning
Classification must be enabled before you can add personalization to your app. For more information, see the guide on classification activation.
Find the page component where you want to add personalization. To make these instructions easier to follow, the following page component is used:
export async function getStaticProps() { return { props: { fields: { title: "My Title", description: "My Description", }, }, }; } export default function MyPage({ fields }) { const { title, description } = fields; return ( <MyComponent title={title} description={description} /> ); }Add the following code to the page component:
const variants = [ { "id": "personalized-content", "fields": { "title": "Personalized Home", "description": "This is personalized content." }, "pz": { "crit": [ { "l": "someSignal", "op": ">", "r": 0 } ] } }, { "id": "default-content", "fields": { "title": "Default Home", "description": "This is default content." } } ]About this step
This represents the personalized content and the criteria used to determine when to use the content. For more information, see the reference on personalization criteria format.
Add the following code to the page component:
export async function getStaticProps() { return { props: { variations, fields: { title: "My Title", description: "My Description", }, }, }; } export default function MyPage({ fields }) { const { title, description } = fields; return ( <MyComponent title={title} description={description} /> ); }Open the component that you want to personalization. To make these instructions easier to follow, the following component is used as an example:
export const MyComponent = ({fields}) => { const { title, description } = fields; return ( <div> <div>{title}</div> <div>{description}</div> </div> ) };About this step
Personalization can be added to any component.
Add a new component:
import { Personalize } from "@uniformdev/context-react"; import { MyComponent } from "./MyComponent"; export const PersonalizedComponent = ({variations}) => { return ( <Personalize variations={variations} name="my-example" component={MyComponent} /> ) };About this step
The Personalize component determines which variation is the best match and uses the properties on the variation as the props for the component MyComponent.
Add the following code to the page component:
import { PersonalizedComponent } from "../src/components/PersonalizedComponent"; export async function getStaticProps() { return { props: { variations, }, }; } export default function MyPage({ variations }) { return ( <PersonalizedComponent variations={variations} /> ); }
Edge-side#
If you are using a CDN that supports running custom logic, you can move the execution of personalization from the client to the edge.
tip
Instructions on configuration for specific CDNs is available in the CDN integrations section:
The configuration for edge-side personalization is basically the same as client-side personalization. The difference is that the output mode for the Uniform context is changed to edge mode.
Add the following package to your app:
npm install @uniformdev/context-nextOpen the file where you added the Uniform context object.
About this step
This is probably the file
/pages/_app.jsx.Add the following code:
... import { NextCookieTransitionDataStore } from "@uniformdev/context-next"; ... const context = new Context({ manifest, transitionStore: new NextCookieTransitionDataStore({}), });Add the prop
outputTypeto theUniformContextcomponent:... function MyApp({ Component, pageProps }) { return ( <UniformContext context={context} outputType="edge"> <Component {...pageProps} /> </UniformContext> ); }
tip
Next steps: If you haven't already done so, you must configure the component responsible for executing personalization. The steps needed depend on the CDN you deploy your app to.
Server-side#
This is a traditional server-side rendering mode (SSR), where the application renders on the server with all the data and state it has access to at the request time.
tip
Before you start, classification must be enabled before you can add personalization to your app. For more information, see the guide on classification activation.
tip
For more information on server-side rendering with Next.js, see the Next.js docs.
Add the following package to your app:
@uniformdev/context-nextOpen the default document.
About this step
This is probably the file
/pages/_document.js.Add the following code:
... class MyDocument extends Document { static async getInitialProps(ctx) { return await Document.getInitialProps(ctx); } render() { return ( ... ); } export default MyDocument; }Add the following code:
... import { Context } from '@uniformdev/context'; class MyDocument extends Document { static async getInitialProps(ctx) { const context = new Context({ }), return await Document.getInitialProps(ctx); } render() { return ( ... ); } export default MyDocument; }Add the following code:
... import { Context } from '@uniformdev/context'; import manifest from "../lib/uniform/contextManifest.json"; class MyDocument extends Document { static async getInitialProps(ctx) { const context = new Context({ manifest, }), return await Document.getInitialProps(ctx); } render() { return ( ... ); } export default MyDocument; }About this step
You should have downloaded the manifest file before starting this section.
Add the following code:
... import { Context } from '@uniformdev/context'; import manifest from "./contextManifest.json"; import { NextCookieTransitionDataStore } from "@uniformdev/context-next"; class MyDocument extends Document { static async getInitialProps(ctx) { const serverTracker = new Context({ manifest, transitionStore: new NextCookieTransitionDataStore({}), }), return await Document.getInitialProps(ctx); } render() { return ( ... ); } export default MyDocument; }Add the following code:
... import { Context } from '@uniformdev/context'; import manifest from "./contextManifest.json"; import { NextCookieTransitionDataStore } from "@uniformdev/context-next"; import { enableNextSsr } from '@uniformdev/context-next'; class MyDocument extends Document { static async getInitialProps(ctx) { const serverTracker = new Context({ manifest, transitionStore: new NextCookieTransitionDataStore({}), }), enableNextSsr(ctx, serverTracker); return await Document.getInitialProps(ctx); } render() { return ( ... ); } export default MyDocument; }Make the following change:
... function MyApp({ Component, pageProps, serverUniformContext, }) { return ( <UniformContext context={serverUniformContext ?? context}> <Component {...pageProps} /> </UniformContext> ); } export default MyApp;