Documentation for PageExperiment

Check out our quickstart guide for a super fast start! The document below is a bit more involved to cover all cases.

Install the pageexperiment package by typing this in your terminal:

      npm install pageexperiment
      

add this middleware.js file to your root directory. Add a list of experiment names, in this case we create just 1 experiment called "experiment1", but you can add multiple experiments at the same time to test out multiple hypotheses.

      import { PageExperimentMiddleware } from 'pageexperiment'

      export default function middleware(req) {
          return PageExperimentMiddleware(req, ["experiment1"]);
      }
      

Ideally you don't want to call the middleware for every request, you just want to call it once when the user visits the site. To do this you can add the following code to the bottom of middleware.js. Either way it's no big deal.

    export const config = {
      matcher: [
        '/((?!api|_next/static|_next/image|favicon.ico).*)',
      ],
    }
      

Wrap our PageExperimentContext around {children} in your app/layout/js file or in your /pages/_app.js file (depending on whether you use /app router or /pages). Add your api key from the dashboard.

      import { PageExperimentContext } from 'pageexperiment'

      <PageExperimentContext apiKey="yourapikey">
          {children}
      </PageExperimentContext>
      

Replace your headline (or any other part of your website) with 2 variants using TestA and TestB components. You can wrap your whole page, or just one line of text, or anything in between. 50% of the visitors will see TestA, and the other 50% will see TestB. Be aware that these are client-side components!

      import { TestA, TestB } from 'pageexperiment';

      <TestA experimentName="experiment1">
          <h1>This is the headline for Variant A</h1>
      </TestA>
      <TestB experimentName="experiment1">
          <h1>This is the headline for Variant B</h1>
      </TestB>
      

There are several types of conversions. For example, you could track whether the visitor clicked a specific button. To do this, wrap your button in our ConversionClick component. Don't forget to add a list of affected experiments (in this case only experiment1). You can also add a name for this conversion event. Be aware that all the conversion components are client-side!

      import { ConversionClick } from 'pageexperiment';

      <ConversionClick affectedExperiments={['experiment1']} conversionName="Buy Button clicked!">
          <Button type="submit">Buy this product</Button>
      </ConversionClick>
      

You can also track whether a user scrolled past a certain element on the page, to see how "deep" the user scrolled in the page. To do this, wrap an element in our ConversionScrollTo component. Again, don't forget to add a list of affected experiments! Optionally you can also add a name for this conversion event.

      import { ConversionScrollTo } from 'pageexperiment';

      <ConversionScrollTo affectedExperiments={['experiment1']} conversionName="User scrolled past this div!">
          <div>
          </div>
      </ConversionScrollTo>

      

Another type of conversion is how long the user stayed on the page. Add a ConversionTimed component and set the number of seconds. Again, don't forget to add a list of affected experiments!

      import { ConversionTimed } from 'pageexperiment';

      <ConversionTimed affectedExperiments={['experiment1']} conversionName="Visitor stayed for 10s!" durationInSeconds="10">
      </ConversionTimed>

      

That's it! You now have some functioning A/B tests! You can check out the results in your dashboard, where you will see something like this:

You can now see if your A/B test works by opening an incognito window in your browser. You will see either variant A or variant B. You can now trigger a conversion event. If you refresh your dashboard, the event should show up under the correct variant. Now close the incognito window and reopen it until you see the other variant (50/50 chance each time you reopen the incognito window). Again trigger a conversion event, and refresh the dashboard and it should show up in the other column!

A quick recap of how it all works: each experiment is a test between variant A and variant B. 50% of your users will see variant A and 50% will see variant B.

You can define these variants however you want. For example you can change only the headline, or you could choose to change the entire page!

You then choose a conversion goal. A goal can be when a user clicks a button, or when a user scrolls past a certain element, or when a user stays on the site for a certain time.

In your dashboard you will see all of those tracked conversions, and you can immediately see which variant is performing best.

After some time, you will typically have a clear winner. At that point it's good practice to stop the experiment, and use the winning variant for 100% of the people visiting the site. You could then start a new experimen to try to improve upon it.

Happy A/B testing! Email us at hello@pageexperiment.com if you have any questions. We will typically answer very fast :)