Web Experiment actions

Actions define how variants modify your site. Actions relate to variants rather than a specific page, and apply to all pages that you target in your experiment.

Experiment applies variant actions during evaluation. This happens on the initial page load and any time state pushes to or pops from the session history. History state changes also cause the SDK to revert all applied element change and custom code actions before reevaluating and reapplying actions with the update page in mind.

Note

See Amplitude's pricing page to find out if this feature is available on your Amplitude plan.

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.

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.

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.

Custom code

Note

Custom code is available on Growth and Enterprise plans only.

Web Experiment applies custom code actions as an optional part of the element changes action. With the custom code action, write custom JavaScript, CSS, and HTML for your site to add elements or customize your site in was the visual editor doesn't support.

Tip

Custom code can be used in tandem with the element changes. For example, An engineer could build a custom code component with placeholder text, then a non-technical user could 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 utils as arguments.

JavaScript

Web Experiment wraps any custom JavaScript in a function, and calls it 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.

Utils

Web Experiment provides the following utilities:

waitForElement(selector: string): Promise<Element>: Returns a promise that resolves when it finds an element that matches 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 this function on page change, when Amplitude reevaluates experiments and reapplies variants.

This function can be 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 this function to remove that element when the page changes.

HTML

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

CSS

Custom CSS styles you can use 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

Tip

Generative AI like ChatGPT or equivalents are quite good at writing HTML and CSS for simple elements. The modal and banner examples below were both initially generated initially by ChatGPT, then modified.

Insert an element

To insert an element onto your page, follow this simple pattern.

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

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

1utils.waitForElement("PARENT_SELECTOR")
2  .then(function (e) {
3    e.appendChild(html);
4    utils.remove = function () {
5        html.remove();
6    }
7  });

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.

1utils.waitForElement("body")
2  .then(function (e) {
3    e.insertBefore(html, e.firstChild);
4    utils.remove = function () {
5      html.remove();
6    }
7  });

 1.announcement-banner {
 2 background-color: #fafafa;
 3 color: #333;
 4 padding: 10px;
 5 text-align: center;
 6 font-family: Arial, sans-serif;
 7 border-bottom: solid #e5e5e5;
 8 border-bottom-width: 1px;
 9}
10 
11.announcement-banner p {
12 margin: 0;
13 font-size: 16px;
14}

1<div class="announcement-banner">
2 <p>🎉 Big Sale: Get 25% off on all items! Use code <strong>SAVE25</strong></p>
3</div>

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

 1var modal = html;
 2utils.waitForElement("body").then(function (body) {
 3 
 4    // Append the modal element to the body.
 5    body.appendChild(modal);
 6 
 7    // Get the close button element
 8    var closeBtn = document.getElementsByClassName("close")[0];
 9 
10    // When the user clicks on the close button (x), close the modal
11    closeBtn.onclick = function() {
12        modal.style.display = "none";
13    }
14 
15    // When the user clicks anywhere outside of the modal, close it
16    window.onclick = function(event) {
17        if (event.target == modal) {
18            modal.style.display = "none";
19        }
20    }
21 
22    // Show the modal after a 1 second delay.
23    window.setTimeout(function () {
24        modal.style.display = "block";
25    }, 1000);
26 
27    // Remove the modal on teardown.
28    utils.remove = function () {
29        modal.remove();
30    }
31});

 1/* TODO: Style the action button */
 2.cta-btn {
 3    color: white;
 4    background-color: #000;
 5    border: #000 solid 1px;
 6}
 7.cta-btn:hover {
 8    color: black;
 9    background-color: #fff;
10    border: #000 solid 1px;
11}
12 
13/*
14 * Modal Boilerplate
15 */
16 
17/* Modal container */
18.modal {
19    display: none; /* Hidden by default */
20    position: fixed;
21    z-index: 1; /* Stay on top */
22    left: 0;
23    top: 0;
24    width: 100%; /* Full width */
25    height: 100%; /* Full height */
26    background-color: rgba(0, 0, 0, 0.5); /* Black background with opacity */
27}
28 
29/* Modal content box */
30.modal-content {
31    background-color: #fff;
32    margin: 15% auto; /* Center the modal */
33    padding: 20px;
34    border-radius: 4px;
35    border: 1px solid #888;
36    width: 40%; /* Width of the modal */
37    max-width: 800px;
38    position: relative;
39}
40 
41/* Close button */
42.close {
43    color: #999;
44    float: right;
45    font-size: 28px;
46    font-weight: bold;
47}
48 
49.close:hover,
50.close:focus {
51    color: #000;
52    text-decoration: none;
53    cursor: pointer;
54}
55 
56/* Modal header */
57.modal-header {
58    margin: 0;
59    padding: 0 0 15px 0;
60    font-size: 24px;
61    font-weight: bold;
62}
63 
64/* Modal body */
65.modal-body {
66    margin: 20px 0;
67    font-size: 16px;
68}
69 
70/* Call to Action container */
71.cta-container {
72    text-align: right;
73}
74 
75/* Call to Action button */
76.cta-btn-base {
77    padding: 10px 20px;
78    font-size: 16px;
79    cursor: pointer;
80    bottom: 20px;
81    right: 20px;
82}

 1<div class="modal">
 2    <div class="modal-content">
 3        <span class="close">&times;</span>
 4        <h2 class="modal-header">
 5            <!-- TODO: Update modal header text -->
 6            Join the mailing list!
 7        </h2>
 8        <p class="modal-body">
 9            <!-- TODO: Update modal body text -->
10            To get updates on new posts to the blog
11            join the exclusive mailing list today!
12        </p>
13        <div class="cta-container">
14            <!-- TODO: Update button link -->
15            <a href="https://example.com">
16                <button class="cta-btn cta-btn-base">
17                    <!-- TODO: Update CTA button text -->
18                    Subscribe
19                </button>
20            </a>
21        </div>
22    </div>
23</div>

Web Experiment actions

Note

Element changes

URL redirect

Custom code

Note

Tip

JavaScript

Utils

HTML

CSS

Examples

Tip

Insert an element

Add a banner

Add a modal