#Variants

Today, users expect personalized content tailored to their preferences. Generic content is less effective because users prefer relevant content that appeals to them. With the introduction of Variants, Hygraph empowers content teams to deliver tailored content experiences that resonate with specific user Segments. This level of personalization not only enhances user engagement but also drives conversion rates.

#Key terms

Segments - A named reference used to target a group of users based on shared characteristics or behaviors. The actual user lists for these groups are defined and managed in an external system. You use Segments to deliver specific content, that is, Variants to these external user groups. Examples of shared characteristics for segmentation are:

• Demographics: Age, gender, location, language
• Behavioral data: Pages visited, products viewed, time on site
• Engagement: Frequency of visits, previous purchases, email interactions

Variants - Personalized versions of content entries that are served depending on the defined Segment. Variants define what version of the content a Segment sees.

A base content entry can have many Variants, each tailored to a specific Segment. These Variants are not separate entries but linked to the base entry. They inherit structure or layout from the base entry while allowing customization of certain fields.

#Benefits

With Variants, you can create different pieces of content for different audiences. Here are a few benefits of Variants:

• Enables personalization and A/B testing use cases
• Provides support for targeted content without duplicating entries
• Helps manage multi-regional or multi-brand strategies efficiently

#Use cases

Hygraph doesn’t decide which content Variant is shown to your end-users, and we don’t collect or process any end-user data to drive Segment creation. While it is possible to build personalized experiences without an additional tool, we recommend using a personalization engine for more complex setups.

Here are a few use cases that Variants support:

• Show different homepage banners to users in Germany vs. the US.
• Highlight specific content to users based on their browsing history, or the platform they come from.
• Display metric units for Europe and imperial units for the US on a product page.
• Present different introductions or visuals depending on whether the reader is a developer or a marketer.

#Get started

Prerequisites

• You have already set up a content model.
• You have created at least one content entry based on the content model.

Permissions

Variants inherit permissions from their content model. So if a user can read, create, and update a model, they have the same permissions for Variants of entries based on the model.

Limits

• You can create a maximum of 30 Variants per entry.
• Segments and Variants count toward the Content entries limits of your billing plan.

Steps

1. Enable Variant support for fields.
2. (Optional) Modify your Segment system model.
3. Add Segments.
4. Add Variants for the base entry and link the Variant to one or more Segments.

#Enable Variant support for fields

First, you need to enable Variant support on a per-field basis in your schema.

1. Go to the Schema Editor, and choose your content model.
2. On the Fields tab, click Edit field for the field that you want to add Variants.
   • Variants are not supported for modular components, union type references, custom fields or conditionally visible fields in the Preview version.
3. Under Settings, select the Enable variants check box.
   • You cannot enable Variant support for unique fields.
4. Click Update.

Repeat these steps for as many fields in the schema, as required.

If you disable Variant support for a field or delete a field that has Variant support enabled, the field and its associated content is removed from all Variants.

#(Optional) Modify your Segment system model

The Segment system model includes certain fields, by default. You can add more fields to the Segment model from the Field Types sidebar. Variants are not supported for modular components, union type references, custom fields or conditionally visible fields in the Preview version. You cannot localize the fields of the Segment model.

#Add a Segment

Next, add Segments to display content from different Variants.

1. In the Content Editor, under Variants, go to Segments.
2. Select Add entry.
3. Provide the name of the Segment and optionally, add a description.
4. Click Save or Save & publish.

Repeat the above steps to add multiple Segments.

#Add a Variant and link it to a Segment

1. Go to the Content Editor, and open your content entry. This is the base version of your content entry.
2. In the right sidebar, under Variants, select Add. A new version of the content entry is displayed. The values from the base entry for the default locale are copied into the Variant entry. This makes it easier to make adjustments, especially when the Variant only differs slightly from the base entry.
   • To add a new locale to the Variant, in the right sidebar, under Localizations, click the + icon next to the locale. The empty localized fields appear and you can enter the localized text for the Variant in these fields.
3. Only the fields that have Variant support enabled are available for editing. Make changes to the available fields, as required.
   • Turn on the Show all fields toggle to view the rest of the fields in the content model in read-only mode. If you want to edit the read-only fields, you need to go back to the content entry.
4. Now, click Select segment.
5. Choose one or more Segments that this Variant applies, and click Add selected entries.
6. Click Save or Save & publish.

#Modify a Variant

After you save a Variant, you can modify the values in different fields of the Variant. You can also modify the Segments that you linked to this Variant.

• Link more Segments - Select the Segment that you added, and click Add segment.
• Unlink a Segment - Hover over the context menu next to a Segment, and click Remove.

#Set up live preview

With Live Preview, you can preview content from the base entry and variant entries in your frontend before publishing.

Ensure that you've added the live preview widget and set up the preview URL template for your content entry. To configure live preview for your variants, do the following:

1. Navigate to the Schema builder.

2. Select the model for which you've enabled variants.

3. Click the Sidebar tab, and for the Preview widget, select Edit widget.

4. Under Variant preview settings, complete the Preview name and the URL template fields. You can use the following preview URL template options:

   • https://preview.your-domain.com/post/${id}?variant=${variant.id}
   • https://preview.your-domain.com/post/${id}?segment={variant.segments[0].id}
   • https://preview.your-domain.com/post/${id}?segments={variant.segments[*].id}

5. Click Update to save.

#Example URL template for variants

Use the Variant ID, the Segment ID, or multiple Segment IDs to set up the URL template. As a developer, you need to interpret the query parameter, and show the right variant by querying the API. For example:

{variant.segments[*].id} returns a comma separated list of all segments. Commas are encoded as %2C in the URL.

#Next steps

Integrate a personalization engine to identify user Segments in real time, and then dynamically deliver content based on the Variants that you set up in Hygraph.

#Behavior of Variant fields

Each variant maintains its own values independently. If the same content is needed across entries, you need to manually update it in each entry. When working with variant fields, note the following points:

• Base entry updates: Updating a variant-enabled field in the base entry does not update the same field in its variants.
• Variant Entry updates: Changes made to variant fields do not affect the corresponding fields in the base entry.

Publishing the base entry doesn’t auto-publish its variants. You need to publish each variant separately. To be able to publish a variant, you must have already published the base entry.

#Query Segments and Variants

After you add a Segment or a Variant, it is added to the Hygraph schema and is immediately queryable through the API. You need to access the API Playground section of your Hygraph project, select Content API at the top of the screen, and then run the query.

#Fetch Variants

You can fetch all the Variants associated with a specific content entry.

#Fetch a Variant and its linked Segments

#Fetch a Variant from a Segment

#Fetch all Segments

#Fetch a Segment

You can fetch a specific Segment by providing its ID.