This is a Sanity Studio v3 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
npm install @sanity/personalisation-plugin
Add it as a plugin in sanity.config.ts
(or .js):
import {defineConfig} from 'sanity'
import {fieldLevelExperiments} from '@sanity/personalisation-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 withstring
field calleddefault
, astring
field calledexperimentId
and an array field of type:varirantsString
an object field with astring
field calledvalue
, a string field calledvariantId
, astring
field calledexperimentId
.
Use the experiment field in your schema like this:
//for Example in post.ts
fields: [
defineField({
name: 'title',
type: 'experimentString',
}),
]
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
},
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/personalisation-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 withreference
field calleddefault
, astring
field calledexperimentId
and an array field of type:variantFeaturedProduct
an object field with areference
field calledvalue
, a string field calledvariandId
, astring
field calledexperimentId
.
Note that the name key in the field gets rewritten to value and is instead used to name the object field.
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
}),
}),
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",
"experimentValue": "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 experitment, with a fallback to default value like so:
*[_type == "post"] {
"title":coalesce(title.variants[experimentId == $experiment && variantId == $variant][0].value, title.default),
}
MIT © Jon Burbridge
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.
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.