Split content reference
This page is for developers who want to set up split content for their project.
If you would like to learn how to use split content in Plasmic Studio, please see this page.
Also feel free to skip doc this and jump right into the Split content setup guide if want to learn the fundamentals later.
Concepts
Split
Split is a basic concept that allows you to create multiple versions of a component or a page. These version are called Slices. You can then target these slices to different users based on conditions you define. There are three main ways to create Splits - via A/B Testing, Segmentation, and Scheduling. Split data is saved in our database and versioned similarly to any other editable elements in Studio. Split content requires specific developer instrumentation for consumption and an additional setup process which involves codebase changes.
Split slice
Slices is what define the content splits — think of it as a variation of a page that gets served to different users. When we have an A/B test split there will be two Slices created - base Split Slice which represents the original version of the website, and override Split Slice — which contains the version you want to test. Slices created via A/B testing, scheduling, segment are stored as a Split Slice array.
Split slice content
Split slice content contains the information about the content that should be shown when the slice is active. It contains the global variant group and variant that should be activated when the slice is active.
The variation
object
The getActiveVariation
function returns an object that identifies the content that should be activated based on internal IDs defined by Plasmic, as well as by external IDs defined by the user.
But in some cases, you may want to get a more detailed object that explains what is the content that is being activated.
For this, you can use the describeVariation
function.
// It can also be imported from `@plasmicapp/loader-splitsimport { describeVariation } from '@plasmicapp/loader-nextjs/edge';...const variation = getActiveVariation({splits: PLASMIC.getActiveSplits(),traits,path: plasmicPath});const detailedVariation = describeVariation(PLASMIC.getActiveSplits(),variation);
The detailed variation is an object with the same keys as the variation object, but the value is an object with the following keys:
Field | Optional | Description |
---|---|---|
name | No | The name of the split defined in Studio. |
description | Yes | The description of the split defined in Studio. |
pagesPaths | No | An array of strings listing the Plasmic page paths that directly use the specific split. This does not account for changes activated through components. |
type | No | If the variation is an original value or an override. |
chosenValue | No | The value that was chosen for the split. It’s equal to the original value in the variation object. |
externalIdGroup | Yes | The external id group specified in the Studio. |
externalIdValue | Yes | The external id specified to this variation in the Studio. |
Data structure
Below you are able to find the properties that are available to you when working with Split content in the code:
Split
Property | Type | Description |
---|---|---|
id | String | ID of the Split |
projectId | String | ID of the project that the Split belongs to |
externalId | String? | External ID used for integrating analytics or providing specific context for the tests, see more here. |
name | String | Name of the Split |
type | ‘experiment’, ‘segment’ | Split type |
description | String? | Description |
slices | ExperimentSlice[] or SegmentSlice[] | Slices that this Split has |
pagesPaths | String[] | Pages affected by the Split |
Split slice
Property | Type | Description |
---|---|---|
id | String | ID of the slice |
name | String | Name of the slice |
externalId | String? | External ID used for integrating analytics or providing specific context for the tests, see more here. |
contents | GlobalVariantSplitContent[] | Content to be shown if the slice is active |
prob | Number? | Only present in ExperimentSlice. The probability that this slice is going to get active if the Split is of type ‘experiment’ |
cond | String? | Only present in SegmentSlice. A json blob using JSONLogic. Contains condition which determines whether the split should be shown to a user. Refer to this link for more info. |
Split slice content
Allows user to enforce a global variant when a slice is activated.
Property | Type | Description |
---|---|---|
group | String | Global variant group to be actived |
variant | String | Global variants to be activated |
projectId | String | ID of the project that the variant belongs to |
API overview
You are able to fetch active splits using PLASMIC.getActiveSplits()
function. This function returns an array of splits (see more above) that are currently active.
@plasmicapp/loader-splits
This is the package that contains logic to process splits.
It exports the following functions:
getActiveVariation
(GitHub): Converts a split array and the current value of the traits into aRecord<string, string>
(See variation object), which describes what should be the activated variation for the UI. It uses json-logic-js to evaluate thecond
that the split has, and includes two different algorithms to pick the random slice for static setup (better explained below). The keys of the returned object are formatted as{type}.{id}
where type is eitherexp
(experimentation, A/B testing),seg (segmentation), or
ext` (to indicate that those are external ids). This is the main function for all different splits setup. Function definition:
function getActiveVariation(opts: {splits: Split[];traits: Record<string, string | number | boolean>;getKnownValue?: (key: string) => string | undefined;updateKnownValue?: (key: string, value: string) => void;getRandomValue?: (key: string) => number;enableUnseededExperiments?: boolean;useSeedBucketing?: boolean;seedRange?: number;});
getExternalIds
(GitHub): Given the set of splits and the current active variation, it’s able to filter out splits and return an object of external ids in both keys and values. This function is more of a nice-to-have than a necessity, just to make it easier for users to integrate with their tracking platforms.describeVariationForKey
/describeVariation
(GitHub): Both functions allow the user to exchange the variation object for a richer object which includes more information about the split. This is useful for debugging and to allow users to better instrument their applications.
@plasmicapp/loader-edge
This package is largely inspired by Next.js and provides a framework for implementing split content with static pages (for more info follow this guide).
It exports the following functions:
generateAllPaths
(GitHub): Given a path and the number of seeds the application uses, this function generates all necessary paths for handling instrumented pages in A/B testing scenarios.generateAllPathsWithTraits
(GitHub): Given a path, an object describing all possible trait values, and the number of seeds, this function generates all necessary paths for instrumented pages.rewriteWithTraits
: Given a path and the set of traits for the current path, this function creates a new path with the traits encoded. It serves as the inverse of rewriteWithoutTraits.rewriteWithoutTraits
: Given a path, this function decodes the path into its original form and extracts the set of traits. It is the inverse of rewriteWithTraits.getMiddlewareResponse
: Given a path, traits, and cookies, this function composes a new path and indicates necessary cookie updates.getActiveVariation
: An adaptedgetActiveVariation
from@plasmicapp/loader-splits
to simplify usage in static setup.
@plasmicapp/loader-react
The React loader receives the variation object in the PlasmicRootProvider
, and then Provider transforms the variation object in the global variants activation array. Check the GitHub definition to see how this is implemented.
@plasmicapp/loader-nextjs
The Next.js loader is re-exporting the @plasmicapp/loader-edge
package under the @plasmicapp/loader-nextjs/edge
path.
It also includes a modified getActiveVariation
function as part of the NextJsPlasmicComponentLoader
which is specific to the SSR setup. This function is an adapted usage of getActiveVariation
from @plasmicapp/loader-splits
to simplify the SSR setup.
Check GitHub to see how this is implemented.
@plasmicapp/react-web/lib/splits
To extend the support of the split content in the CodeGen mode @plasmicapp/loader-splits
has been reexported into react-web/lib/splits
.
This way users don’t need to install any additional packages, and we also include an additional PlasmicSplitsProvider
which contains the splits data serialized in this file.
PlasmicSplitsProvider
receives all the parameters as props from getActiveVariation
which allows the developer to set up the additional behaviors that they want to save picked variations.
PlasmicSplitsProvider
is also responsible for wrapping the elements with the necessary global contexts providers.
Next steps
Follow our Split content setup guide to learn how to set up split content in your project.
Have feedback on this page? Let us know on our forum.