Fetch a Personalize variant

Pass one option on your fetch to show the content of a Personalize variant in a template. You need it when your site shows different content to different audiences and Personalize decides who sees what.

The example on this page is the Blog post template at /blog/{{entry.slug}}, fetched for AI 101 with the variant alias cs_personalize_0_1. That variant belongs to the Returning readers Experience, and AI 101 has an entry variant for it with the title AI 101, next steps.

Prerequisites

• You have a Personalize project with an Experience and a variant. Your stack is connected to that project.
• The entry you fetch has an entry variant for that Personalize variant, and you've published the entry variant.
• You have the variant's alias. The alias in the example is cs_personalize_0_1.
• Your organization has access to entry variants in the Delivery API, an Early Access feature.

What this is and what you get

Studio renders one template for every variant. You don't fork the layout, and you register nothing.

A variant changes the content the layout shows: the connected entry, Pinned Entries and Pinned Queries. The layout stays the same. In the example, the Blog post template shows the title AI 101, next steps for the variant.

Studio takes the alias from you. It doesn't decide which visitor gets which variant. Personalize decides who sees which variant, and its Edge SDK returns the list of aliases for a visitor. See End-to-end personalization delivery in the Personalize docs.

A fetch without a variant returns the base entry. You don't have to author a variant for every audience. Pass nothing for the audiences that use the base entry.

Inside Studio, the variant the canvas is showing wins over the alias you pass.

You can pass locale and variantAlias in the same fetch. For the language option, see Fetch content in a language.

Fetch a Personalize variant

1. Read the alias in your route first. Your route gets it from Personalize, then passes it to the fetch. See End-to-end personalization delivery in the Personalize docs.

2. Pass the alias as variantAlias in the second argument of sdk.fetchCompositionData.

   sdk.fetchCompositionData(
     { url: "/blog/ai-101", searchQuery },
     { variantAlias: "cs_personalize_0_1" }
   );

   The fetch returns the entry variant of AI 101, with the title AI 101, next steps. The layout doesn't change.

3. With the useCompositionData hook, pass variantAlias in the second argument.

   const { specOptions, isLoading, error } = useCompositionData(
     { url: "/blog/ai-101" },
     { variantAlias: "cs_personalize_0_1" }
   );

   When isLoading is false, specOptions has the entry variant of AI 101, with the title AI 101, next steps.

Pass the alias on every fetch. There's no default to fall back on, and the alias isn't an init option. On the server, you don't pass the alias again to <StudioComponent />, because a server fetch puts it in specOptions for the client.

If you cache pages, put the variant in the cache key. See Caching and invalidation.

If it doesn't work

• The base entry shows and the variant never applies. Studio ignores a variantAlias in studioSdk.init and shows no error. Pass it per fetch.
• The variant never applies, and no error shows. Studio ignores a variantAlias in the first argument and a misspelled key in the options. Put variantAlias in the second argument and check its spelling.
• Every visitor sees the same variant. Your cache key has no variant in it. Add the variant to the key.

Next, see Options that change the fetch for every option you can pass. To also pass a language, see Fetch content in a language.