Custom snippets

  • Updated
  • Optimizely Web Experimentation
  • Optimizely Personalization

To run an experiment or campaign, include a snippet of code inside the <head> tags on any pages where your experiment runs. Without this snippet, Optimizely Web Experimentation cannot know what to track or even where to find your experiment in the first place.

Each experiment you run is contained within a project. A project can have multiple experiments, but all of those experiments share the same snippet. This is the default behavior, and for most, this model works well. However, larger organizations can also use a custom snippet to avoid certain potential issues they may experience as they start using Optimizely Web Experimentation or Optimizely Personalization at scale.

How custom snippets work

Each project starts with a single basic snippet that automatically includes all the entities from that project (and only that project). This is a 1:1 relationship between projects and basic snippets.

basic snippet diagram

You can change this setup by creating a custom snippet. Custom snippets can have a many-to-many relationship with projects. This lets teams use projects as organizers, each with their workspaces and permissions, that can touch the same URLs. (You cannot do this with basic snippets because no page on your site may reference more than one snippet.)

diagram of custom snippets and their relationships to projects and experiments

In other words, you can deliver a project with many snippets on different parts of a site, and a single snippet can pull in experiments from many projects. In this way, Optimizely Web Experimentation and Optimizely Personalization separate performance and implementation concerns from those of permissions and governance.

Custom snippets are only available in projects that use the standalone Optimizely Web Experimentation or Optimizely Personalization snippet.

If you want to include more than one project in a custom snippet, make sure the projects you want to include are linked projects before you create the custom snippet (you can still add projects to a custom snippet after the snippet was initially created, but they need to be linked before you can do that). 

Use case: Boost site performance

Attic & Button’s ecommerce site includes a home page, several category pages, and many product description pages. The storefront is owned by the company’s ecommerce team, which runs a large number of experiments across all these pages. Because Attic & Button needs to keep all these experiments in the same project, the snippet has grown large enough to have a negative impact on the site’s performance.

Attic & Button can solve this problem by using multiple snippets to reduce the size of each. With custom snippets, the team can use a unique snippet for each of three experiments: one for the home page, one for product category pages, and one for product description pages. The team runs all the same experiments, but because each snippet is smaller, site performance is restored. 

For the best performance, use prefetch in your code to speed up fetching of custom snippets implemented on the next page that you expect visitors to navigate to.

Prefetch hints to your visitor's browser that a resource might be needed, but does not necessarily load it right away. Instead, the prefetch hint can be used to tell the browser to fetch a resource required in the next navigational step. If Page A initiates a prefetch request for key resources for Page B, the navigation and resource loading requests can be done in parallel.

For example, if you are on the homepage and you have a custom snippet implemented for category pages, you can add a hint:

<link rel="prefetch" href="cdn.optimizely.com/public/12322/s/category.js" as="script">

Since prefetch resources are fetched by the browser with low priority when possible, this does not impact the rendering of the current page (the homepage).

Use case: Separate swimlanes for different teams

MondoMedia is a large online media company with an editorial team and a marketing team that both regularly run experiments with Optimizely Web Experimentation. The editors use Optimizely Web Experimentation to test headlines, while the marketers use it to test the effectiveness of different types of ads. By their nature, both of these activities often have to run on the same pages.

Previously, both teams had to share one crowded project that contained both teams' experiments. There was a concern about whether one team would accidentally interfere with the other team's work. But with custom snippets, each team can work within a separate project with its own permissions, both of which touch the same URL. This is achieved by building a single custom snippet that contains both the editorial and marketing teams' projects.

Use case: Run experiments across properties

Attic & Button’s navigation team is responsible for the performance of the site’s header. They want to run an experiment on the header and track how a change to the header’s copy affects sales for their canvas backpack product. This experiment encompasses the backpack’s landing page and its description page on the ecommerce site. Because these two pages are the responsibility of different teams, in the past they each had their own snippet, and no experiments could be conducted across both.

However, the navigation team can include their experiment in custom snippets for the landing page and the product description page. The header appears consistently throughout any user’s experience (either the test version or the original version), and actions taken on both of these pages are tracked by the new experiment.

In this way, different teams can set up experiments that cross boundaries and touch pages owned by other teams. You can have two teams, each with ownership of a single page, running tests that incorporate both pages.

In this use case, the Attic & Button site has only two separate custom snippets: one for the landing page and one for the PDP. Both of these snippets also include the navigation team's header project.

Custom snippet matching criteria

When you create a custom snippet, the default setting includes all pages from the selected project. But if you only want to include specific pages, you can specify pages to explicitly include or exclude, or specify custom rules to match all pages that follow a certain pattern.

You have the following options for matching criteria:

  • Match to URL – Enter a single URL you want to target. The snippet pulls in any experiments on pages that match the URL. For example, if you have a page that uses a regular expression (regex) pattern like www.website.com/products/.*, you would enter a URL like www.website.com/products/123. Matching to URL offers more precise filtering.
  • Match to Substring – Enter a string to check against each of the URL conditions. The snippet pulls in any pages where any of the targeting conditions match the substring. Matching to substring is less precise, but captures a broader set of pages. For example, you could enter the pattern /products/.* to capture a page targeting www.website.com/products/.*.

Your custom snippet can include and exclude multiple URLs and URL patterns. You can also mix and match the criteria options to make sure your custom snippet includes exactly the experiments and pages you want.

For example, if you want to exclude experiments on certain individual product pages, you can enter the exact URLs for those product pages and choose the Match to URL matching criteria. Or, suppose you want to include only products for Winter 2022, and those product pages all have one URL pattern in common: www.examplecompany.com/products/winter22. You can enter the Winter 2022 URL pattern and choose the Match to Substring matching criteria to include only those pages in your snippet.

If you include pages, this only includes that specific page and the experiments targeted to it directly. It does not include other pages with overlapping conditions or experiments that run on the same URLs. To match all experiments that run on a certain URL, use the URL rules above.

Custom snippet logic

When you generate a custom snippet, the following logic is used to decide which properties are included:

  1. The new custom snippet first finds all the projects you specified above. All project-level properties—custom events, project JS, and attributes—are wrapped into the snippet here.
  2. Within those projects, find all the pages that match the snippet’s rules. Click events and tags on those pages are added to the snippet here.
  3. Find all the campaigns and experiments targeted to these pages. The snippet adds the audiences for each of these campaigns or experiments and any changes for the pages that match.

Custom snippet permissions

Custom snippet permissions work for Administrator and Project Owner roles as follows:

  • Administrators can see all snippets for an account from Account Settings; create, edit, and delete snippets for any projects; and link any projects.
  • Project Owners can see snippets that pull from a specific project from the project’s Project Settings; create and edit snippets (as long as they own all of the projects included in the snippet); and link projects they own.

Custom snippet availability

Custom snippets are an advanced feature designed for large teams and performance-conscious customers. 

If you want to include more than one project in a custom snippet, link the projects you want to include before you create the custom snippet.

Linked projects

Even without custom snippets, you can use events in one project that originated in another. This is called referencing. Selecting it from All projects in the metric picker. Custom snippets are not required for referencing, and linked projects are not required for cross-project events or single-project custom snippets.

If you want to use cross-project behavioral targeting or combine multiple projects into one snippet, use linked projects, which requires you to change the state of these projects from Unlinked to Linked:

  • Unlinked projects are completely separated from each other. This is the default project state.
  • Linked projects can share behavior targeting, overlap with each other in a snippet, and use account-level namespacing and attribution.
You should pause any running experiments when you link projects.

Linking projects has a couple of important effects:

  • Linking "resets" the behavioral targeting for a project. When you link a project, it stops reading and writing events in the project-level store and starts reading and writing events in an account-level store instead. The events in the project-level behavior store are still there, but the project reads from a different place (the account-level store). That is why we say the behavior store resets.
  • When you link multiple projects into a single snippet, Optimizely automatically checks each project for any conflicts, like events that share an API name with any events in the other projects you are trying to link. You can resolve the conflict by renaming the conflicting events.

This table summarizes the differences between how isolated and linked projects work.

  Unlinked Linked
Namespace: At what level do namespace uniqueness checks happen? Project-level uniqueness.

Visitor attributes and behavioral store are scoped to a single project.

 Account-level uniqueness; Optimizely only checks other linked projects.

Visitor attributes and behavioral store are scoped to the account level.
Overlaps: Can two projects touch the same page? No, because of the potential for namespace conflicts. Yes. Projects are safe to run with other linked projects in one custom snippet.
Attribution: can experiments in one project reference events from another project? Yes. Cross-project events do not require linking. Yes. Cross-project events do not require linking.

You can use a custom snippet with both unlinked and linked projects. However, unlinked projects can only use single-project custom snippets. This means you cannot group projects together when they are unlinked.

If you do have to change any API names, you will probably need to do so in both the Optimizely Web Experimentation or Optimizely Personalization UI and any code running on your site that references those API names.

Conflicts also apply to integrations across linked projects. Optimizely Web Experimentation or Optimizely Personalization will not let you link two projects with conflicting integration settings. You have to switch one project to the same integration account as the other before you can proceed with linking the projects.

Optimizely requires you to resolve any conflicts in these elements before you can link projects:

  • Event API names
  • Page API names
  • Attribute API names
  • Extension API names
  • Integration settings

Link a project

You should link your projects—even if you are not sure you will need the features that linking enables—because you might want to use behavioral targeting and multi-project custom snippets. You should link projects during an experimentation pause, like onboarding or transition to Optimizely Web Experimentation or Optimizely Personalization, to avoid any impact on running experiments or personalization campaigns.

To link a project:

  1. In the project you want to link, go to Settings > Advanced.
  2. Select Link Project > Linked.
  3. Click Check for Conflicts.

As long as there are no conflicts, your project is now linked.

Related articles