@sanity/personalization-plugin

Previously know as @sanity/personalisation-plugin

This plugin allows users to add a/b/n testing experiments to individual fields.

For this plugin you need to defined the experiments you are running and the variations those experiments have. Each experiment needs to have an id, a label, and an array of variants that have an id and a label. You can either pass an array of experiments in the plugin config, or you can use and async function to retrieve the experiments and variants from an external service like growthbook, Amplitude, LaunchDarkly... You could even store the experiments in your sanity dataset.

Once configured you can query the values using the ids of the experiment and variant

• @sanity/personalization-plugin
  • Installation
  • Usage
  • Loading Experiments
  • Using complex field configurations
  • Validation of individual array items
  • Shape of stored data
  • Querying data
  • Split testing
  • Using experiment fields in an array
  • License
  • Develop & test
    • Release new version
  • License

For Specific information about the growthbookFieldLevel export see its readme

Installation

npm install @sanity/personalization-plugin

Usage

Add it as a plugin in sanity.config.ts (or .js):

import {defineConfig} from 'sanity'
import {fieldLevelExperiments} from '@sanity/personalization-plugin'

const experiment1 = {
  id: '123',
  label: 'experiment 1',
  variants: [
    {
      id: '123-a',
      label: 'first var',
    },
    {
      id: '123-b',
      label: 'second var',
    },
  ],
}
const experiment2 = {
  id: '456',
  label: 'experiment 2',
  variants: [
    {
      id: '456-a',
      label: 'b first var',
    },
    {
      id: '456-b',
      label: 'b second var',
    },
  ],
}

export default defineConfig({
  //...
  plugins: [
    //...
    fieldLevelExperiments({
      fields: ['string'],

      experiments: [experiment1, experiment2],
    }),
  ],
})

This will register two new fields to the schema., based on the setting passed intto fields:

• experimentString an Object field with string field called default, a string field called experimentId and an array field called variants of type:
• variantString an object field with a string field called value, a string field called variantId, a string field called experimentId.

Use the experiment field in your schema like this:

//for Example in post.ts

fields: [
  defineField({
    name: 'title',
    type: 'experimentString',
  }),
]

Loading Experiments

Experiments must be an array of objects with an id and label and an array of variants objects with an id and label.

experiments: [
  {
    id: '123',
    label: 'experiment 1',
    variants: [
      {
        id: '123-a',
        label: 'first var',
      },
      {
        id: '123-b',
        label: 'second var',
      },
    ],
  },
  {
    id: '456',
    label: 'experiment 2',
    variants: [
      {
        id: '456-a',
        label: 'b first var',
      },
      {
        id: '456-b',
        label: 'b second var',
      },
    ],
  },
]

Or an asynchronous function that returns an array of objects with an id and label and an array of variants objects with an id and label.

experiments: async () => {
  const response = await fetch('https://example.com/experiments')
  const {externalExperiments} = await response.json()

  const experiments: ExperimentType[] = externalExperiments?.map((experiment) => {
    const experimentId = experiment.id
    const experimentLabel = experiment.name
    const variants = experiment.variations?.map((variant) => {
      return {
        id: variant.variationId,
        label: variant.name,
      }
    })
    return {
      id: experimentId,
      label: experimentLabel,
      variants,
    }
  })
  return experiments
}

The async function contains a configured Sanity Client in the first parameter, allowing you to store Language options as documents. Your query should return an array of objects with an id and title.

experiments: async (client) => {
    const experiments = await client.fetch(`*[_type == 'experiment']`)
    return experiments
  },

Using complex field configurations

For more control over the value field, you can pass a schema definition into the fields array.

import {defineConfig} from 'sanity'
import {fieldLevelExperiments} from '@sanity/personalization-plugin'

export default defineConfig({
  //...
  plugins: [
    //...
    fieldLevelExperiments({
      fields: [
        defineField({
          name: 'featuredProduct',
          type: 'reference',
          to: [{type: 'product'}],
          hidden: ({document}) => !document?.title,
        }),
      ],
      experiments: [experiment1, experiment2],
    }),
  ],
})

This would also create two new fields in your schema.

• experimentFeaturedProduct an Object field with reference field called default, a string field called experimentId and an array field called variants of type:
• variantFeaturedProduct an object field with a reference field called value, a string field called variandId, a string field called experimentId.

Note that the name key in the field gets rewritten to value and is instead used to name the object field.

Validation of individual array items

You may wish to validate individual fields for various reasons. From the variant array field, add a validation rule that can look through all the array items, and return item-specific validation messages at the path of that array item.

defineField({
  name: 'title',
  title: 'Title',
  type: 'experimentString',
  validation: (rule) =>
    rule.custom((experiment: ExperimentGeneric<string>) => {
      if (!experiment.default) {
        return 'Default value is required'
      }

      const invalidVariants = experiment.variants?.filter((variant) => !variant.value)

      if (invalidVariants?.length) {
        return invalidVariants.map((item) => ({
          message: `Variant is missing a value`,
          path: ['variants', {_key: item._key}, 'value'],
        }))
      }
      return true
    }),
}),

Shape of stored data

The custom input contains buttons which will add new array items with the experiment and variant already populated. Data returned from this array will look like this:

"title": {
  "default": "asdf",
  "experimentId": "test-1",
  "variants": [
    {
      "experimentId": "test-1",
      "value": "asdf",
      "variantId": "test-1-a"
    },
    {
      "experimentId": "test-1",
      "variantId": "test-1-b",
      "value": "asdf"
    }
  ]
}

Querying data

Using GROQ filters you can query for a specific experiment, with a fallback to default value like so:

*[_type == "post"] {
"title":coalesce(title.variants[experimentId == $experiment && variantId == $variant][0].value, title.default),
}

Split testing

Split testing involves splitting traffic for one url over 2+ pages, this is used when you want to test more than just a single field in an experiment.

Studio Setup

To do split testing using this plugin define a type that can store a url path

export const path = defineType({
  name: 'path',
  type: 'string',
  validation: (Rule) =>
    Rule.required().custom(async (value: string | undefined, context) => {
      if (!value) return true
      if (!value.startsWith('/')) return 'Must start with "/"'
      return true
    }),
})

add the type to the studio schema.types and the plugin config fields:

 fieldLevelExperiments({
        fields: ['path', ...otherFields],
        experiments: getExperiments,
      }),

and then create a document type that stores the routing information:

export const routing = defineType({
  name: 'routing',
  type: 'document',
  title: 'Routing Experiments',
  fields: [
    {
      name: 'pathExperiment',
      type: 'experimentPath',
      initialValue: {active: true},
    },
  ],
  preview: {
    select: {
      path: 'pathExperiment.default',
      experiment: 'pathExperiment.experimentId',
    },
    prepare({path, experiment}) {
      return {
        title: `${path} - ${experiment}`,
      }
    },
  },
})

Frontend usage

In your frontend you will need some middleware that can intercept the request for the page and check if the route is included in your split page testing and if so decide which page the user should see.

In Next.js Middleware it could be something like

const ROUTING_QUERY = defineQuery(`*[
  _type == "routing" &&
  pathExperiment.default == $path
][0]{
  "route": coalesce(pathExperiment.variants[experimentId == $experimentId && variantId == $variantId][0].value, pathExperiment.default)
}`)

export async function middleware(request: NextRequest) {
  let response = NextResponse.next()
  const path = request.nextUrl.pathname
  // getExperimentValue is a function that will determine a variant based on some user properties
  const {variant} = await getExperimentValue(path)

  const queryParams = {
    path,
    experimentId: 'homepage',
    variantId: variant?.id || '',
  }

  // Instead of doing a query for every page this could be queried at build time and stored in a file.
  const data = await client.fetch(ROUTING_QUERY, queryParams)
  if (data?.route) {
    const url = request.nextUrl.clone()
    url.pathname = data.route
    const rewrite = NextResponse.rewrite(url)
    return rewrite
  }

  return response
}

export const config = {
  //only run the middleware on pages
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)'],
}

Using experiment fields in an array

You may want to add experiment fields as a type with in an array in oder to do this you would need to set an initial value for the experiment to active the schema would be something like:

defineField({
      name: 'components',
      type: 'array',
      of: [
        defineArrayMember({type: 'cta', name: 'cta'}),
        defineArrayMember({type: 'experimentCta', name: 'expCta', initialValue: {active: true}}),
        defineArrayMember({type: 'hero', name: 'hero'}),
        defineArrayMember({type: 'experimentHero', name: 'expHero', initialValue: {active: true}}),
      ],
      group: 'editorial',
    }),

You can then use a groq filter to return the base version of you array member so you don't have to create an experiment specific version

*[
  _type == "event" &&
  slug.current == $slug
][0]{
  ...,
  components[]{
    _key,
    ...,
    string::startsWith(_type, "exp") => {
      ...coalesce(@.variants[experimentId == $experiment && variantId == $variant][0].value, @.default),
    },
  }
}`);

Overwriting the experiment and variant field names

If your use case does not match exactly with experiments you can overwrite the name field names for experiment and variant in the config.

import {defineConfig} from 'sanity'
import {fieldLevelExperiments} from '@sanity/personalization-plugin'

export default defineConfig({
  //...
  plugins: [
    //...
    fieldLevelExperiments({
      fields: ['string'],
      experiments: [experiment1, experiment2],
      experimentNameOverride: 'audience',
      variantNameOverride: 'segment',
    }),
  ],
})

This would also create two new fields in your schema.

• audienceString an Object field with string field called default, a string field called audienceId and an array field called segments of type:
• segmentString an object field with a string field called value, a string field called segmentId, a string field called audienceId.

the data will be stored as

"title": {
  "default": "asdf",
  "audienceId": "test-1",
  "segments": [
    {
      "audienceId": "test-1",
      "value": "asdf",
      "segmentId": "test-1-a"
    },
    {
      "audienceId": "test-1",
      "segmentId": "test-1-b",
      "value": "qwer"
    }
  ]
}

This will also affect the query you write to fetch data to be:

*[_type == "post"] {
"title":coalesce(title.segments[audienceId == $audience && segmentId == $segment][0].value, title.default),
}

License

MIT © Jon Burbridge

Develop & test

This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.

See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.

Release new version

Run "CI & Release" workflow. Make sure to select the main branch and check "Release new version".

Semantic release will only release on configured branches, so it is safe to run release on any branch.