Web Experiment actions

Actions define how variants modify your site. Actions relate to variants rather than a specific page, and apply to specific Pages to control where they take effect.

Experiment applies variant actions during evaluation. Evaluation runs on the initial page load and any time state pushes to or pops from the session history. On a history state change, the SDK first reverts all applied element change and custom code actions, then reevaluates and reapplies actions for the updated page.

Element changes

Element changes modify existing elements on your site. Web Experiment applies these changes by editing the inner text of an element or appending style to the element based on the change you make in the visual editor.

The visual editor supports the following element changes:

Display: Show or remove the element from the DOM.
Visibility: Show or hide the element.
Text: Update an element's inner text, color, and size.
Background: Update a background image or color.
Move: Move the position of an element.

URL redirect

URL redirects load a new URL when a targeted user lands on a targeted page in your experiment. URL redirects happen on the client, and aren't the same as a server redirect with a 3xx response. Use URL redirect when your variants are different URLs or pages. For example, use it to test landing pages or different versions of a page built in a CMS. URL redirect works with standard A/B tests and multi-armed bandits.

URL redirects retain any query parameters on the original page URL. For example, you create a variant to redirect users from https://example.com to https://example.com/get-started. If a user clicks a link https://example.com?utm_source=facebook, Web Experiment redirects that user to https://example.com/get-started?utm_source=facebook.

Set up a URL redirect

Set up URL redirect through the Visual Editor as a variant action. To add a URL redirect to a treatment variant, follow these steps:

Create a Web Experiment and open the Visual Editor.
Click the Treatment three-dot menu, select Edit, then under Action select URL Redirect.
In the URL Redirect panel, add each URL you want to test as a separate variant and click Apply.

Configuration limits

Visual experimentation and Amplitude's low-code implementation apply the following limits when you use URL redirect:

Setting	Limit	Reason
Evaluation mode	`local`	Optimizes test performance and minimizes latency impact to end users.
Bucketing unit	`User`	Evaluation mode is `local`.
Keys	`deviceID`	Evaluation mode is `local`.
Audience	`all users`	URL redirect logic uses local evaluation mode.
Deployment	Project API key	Simplifies setup requirements.

It's possible for the URL redirect test to have a Sample Ratio Mismatch (SRM). Redirect tests work by loading the redirected page, ideally as fast as possible. The sequence for this is:

Control flow:

Load control page HTML.
Browser parses and loads dependencies (including the experiment script).
Experiment script initializes, evaluates the user, and logs an impression if the user is in control.

Treatment flow:

Load control page HTML.
Browser parses and loads dependencies (including the experiment script).
Experiment script evaluates the user, assigns the user to treatment, and triggers a redirect.
Load treatment page HTML.
Browser parses and loads dependencies (including the experiment script again).
Experiment script initializes and logs the impression for treatment.

Because the treatment flow involves more steps before logging the impression, users who bounce quickly (for example, after clicking an ad by mistake) are more likely to count in control than in treatment. This imbalance can appear as Sample Ratio Mismatch (SRM).

Researchers report similar effects: if treatment slows performance, more users leave before impressions log, which reduces recorded impressions. Faster performance has the opposite effect, producing more recorded users in treatment than in control.

To resolve SRM, follow these guidelines:

Reduce latency in evaluation. The longer the delay before logging impressions, the more pronounced the SRM effect.
Use local evaluation where possible. For example, target only on browser properties instead of slower remote attributes like Country. Local evaluation reduces the chance that users drop off before logging. The following configuration example shows local evaluation in Amplitude Experiment.

SEO best practices for redirects

Client-side redirects in experiments can affect how search engines index and rank your pages. Follow these best practices to minimize SEO impact.

Use temporary redirects during tests

Web Experiment uses client-side redirects that simulate a 302 temporary redirect through window.location.replace. The 302 signal tells search engines to keep the original URL indexed during the experiment. Don't use noindex tags on your control page, because noindex removes the page from search results.

After you pick a winner, implement a permanent server-side 301 or 308 redirect to consolidate link equity to the winning URL.

Add canonical tags on variant pages

Add a canonical tag on your experiment variant page that points back to the original (control) URL. The canonical tag prevents search engines from indexing the variant as a separate page.

html

<!-- On the variant/redirect destination page -->
<link rel="canonical" href="https://example.com/original-page" />

Prefer server-side redirects for SEO-critical pages

For pages where SEO is critical, consider using server-side assignment and redirects at the edge (CDN) or server level. Server-side redirects execute before the page renders, which:

Ensures search engine crawlers interpret redirects reliably.
Minimizes page flicker for users.
Provides proper HTTP status codes to crawlers.

If you must use client-side redirects, make sure the redirect logic runs in the <head> to reduce layout shift.

Keep tests short and avoid cloaking

Don't show different content or URLs to users compared to what Googlebot sees. Search engines consider this practice cloaking and may penalize your site. End experiments promptly and remove test logic after concluding to avoid SEO drift.

Ensure goals cover both URLs

Define conversion goals that include both control and variant URLs. Web Experiment preserves query parameters through redirects, so attribution and session continuity stay intact.

Use Search Console if issues arise

If a search engine indexes your experiment variant page unexpectedly, use Google Search Console's URL removal tool as a temporary fix while you address the underlying issue.

Custom code

Custom code requires a Growth or Enterprise plan.

Web Experiment applies custom code actions as an optional part of the element changes action. Use the custom code action to write JavaScript, CSS, and HTML that adds elements or customizes your site in ways the visual editor doesn't support.

Apply custom code to specific Pages using the Apply to dropdown. The dropdown lets you run different code depending on which Page is active.

You can use custom code together with the element changes. For example, an engineer can build a custom code component with placeholder text. A non-technical user can then use the visual editor to edit the placeholder text without touching the custom code.

Web Experiment applies custom code to your site in the following order:

Adds CSS in a <style> tag in the page's <head>.
Parses HTML into a DOM element.
Wraps JavaScript in a function, and adds it to a <script> tag in the page's <head>.
Calls the wrapped JavaScript function and passes parsed HTML and utilities as arguments.

JavaScript

Web Experiment wraps any custom JavaScript in a function, and calls the function when the variant action applies. The function has two parameters you can use with your custom JavaScript code.

html: The custom HTML code parsed as a DOM element object.
utils: An object that contains utility functions you can use in your custom code.

Utilities

Web Experiment provides the following utilities:

waitForElement(selector: string): Promise<Element>: Returns a promise that resolves when waitForElement finds an element matching the selector in the DOM. Uses MutationObserver to listen for elements.
remove: (()=> void) | undefined: A function that you can set inside the JavaScript you inject. Web Experiment calls the remove function on page change, when Amplitude reevaluates experiments and reapplies variants.
The remove function is useful for cleaning up changes to the page in single page apps, where the page doesn't fully reload. For example, if you inject an HTML element on a specific page, set the remove function to remove that element when the page changes.

HTML

Web Experiment parses custom HTML as a DOM element, and passes the element to the custom JavaScript code for insertion. The custom HTML can use existing CSS styles and classes, or new CSS that you define.

CSS

Use custom CSS styles to manipulate existing CSS classes and styles, or add new styles for elements you add with custom HTML. Web Experiment adds custom CSS to a <style> tag in the page's <head> element.

Examples

Generative AI like ChatGPT or equivalents can create HTML and CSS for simple elements. ChatGPT generated the initial modal and banner examples that follow, and Amplitude then modified them.

Insert an element

To insert an element onto your page, follow this pattern:

Write the HTML and CSS for the element you want to add to the page.
Identify the selector of the parent element you want to insert your new element into. The parent is often the body.

Paste the following JavaScript code, and update PARENT_SELECTOR with the parent element selector from step 2.

utils.waitForElement("PARENT_SELECTOR").then(function (e) {
  e.appendChild(html);
  utils.remove = function () {
    html.remove();
  };
});

If you want to insert your element into the parent element at a specific position, use insertBefore() instead of appendChild().

This example adds a discount code banner to the top of the page.

utils.waitForElement("body").then(function (e) {
  e.insertBefore(html, e.firstChild);
  utils.remove = function () {
    html.remove();
  };
});

This example adds a modal to the page after a 1 second delay.

var modal = html;
utils.waitForElement("body").then(function (body) {
  // Append the modal element to the body.
  body.appendChild(modal);

  // Get the close button element
  var closeBtn = document.getElementsByClassName("close")[0];

  // When the user clicks on the close button (x), close the modal
  closeBtn.onclick = function () {
    modal.style.display = "none";
  };

  // When the user clicks anywhere outside of the modal, close it
  window.onclick = function (event) {
    if (event.target == modal) {
      modal.style.display = "none";
    }
  };

  // Show the modal after a 1 second delay.
  window.setTimeout(function () {
    modal.style.display = "block";
  }, 1000);

  // Remove the modal on teardown.
  utils.remove = function () {
    modal.remove();
  };
});

Was this helpful?