Split content reference

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.

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-splits
import { 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:

Data structure

Below you are able to find the properties that are available to you when working with Split content in the code:

Split

Split slice

Split slice content

Allows user to enforce a global variant when a slice is activated.

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 a Record<string, string> (See variation object), which describes what should be the activated variation for the UI. It uses json-logic-js to evaluate the cond 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 either exp (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 adapted getActiveVariation 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.