Embed SDK

The Movement Embed SDK is a lightweight JavaScript library that enables external websites to integrate with Movement's share content testing system. The script is loaded once on every page and automatically looks up share variants by matching the current page URL against flows configured with a share_url.

Installation

Add the embed script to your website by including it from your Movement public domain:

<script src="https://your-movement-domain.com/embed.js"></script>

The script automatically detects its API base URL from its own <script> src attribute, so no additional configuration is needed. Note that the SDK is served from your Movement public domain (e.g. your-movement-domain.com), which is different from your website's own domain where the script runs.

API Reference

The SDK exposes a global window.Movement object with the following methods:

Movement.getVariant(options, callback)

Fetches a share content variant for the current page URL.

Parameters:

Callback data shape:

When a matching flow is found, the callback receives an object with:

{
  tid: "1709123456abcd",          // Tracking ID for this share event, used internally for tracking
  flowSlug: "save-the-whales",    // Flow slug (used in share URLs)
  channels: [
    {
      channel: "whatsapp",        // Channel name
      variant: {
        id: 42,                   // Variant ID
        title: "Share Title",
        description: "Share description text",
        imageUrl: "https://example.com/image.png",
        shareText: "Pre-written share message",
        sharedUrl: "https://your-movement-domain.com/p/save-the-whales/shared?t=1709123456abcd&v=42"
      }
    },
    // ... more channels
  ]
}

The sharedUrl is a tracking URL served from the Movement public domain. When a user clicks this link, Movement records the click and redirects them to the flow's configured share URL (your external website). This means the sharedUrl host will be different from the page where the SDK runs — this is expected behavior.

For example, for a flow with a share URL of external-domain.com/petition and a call of Movement.getVariant({ url: 'https://external-domain.com/petition' }, callback), the callback receives an object where:

• sharedUrl is https://your-movement-domain.com/p/save-the-whales/shared?t=1709123456abcd&v=42
• Clicking that URL redirects to https://external-domain.com/petition?rtid=123

The rtid query parameter appended to the redirect URL is the referring trial ID — it identifies the specific share event that brought the user to the page.

When no matching flow is found, the callback receives null.

Example:

<script src="https://your-movement-domain.com/embed.js"></script>
<script>
  Movement.getVariant({ url: window.location.href }, function(data) {
    if (data) {
      var variant = data.channels[0].variant;
      document.getElementById('share-title').textContent = variant.title;
      document.getElementById('share-link').href = variant.sharedUrl;
    }
  });
</script>

Movement.recordObjective(options)

Records an objective conversion for a share trial. This increments the objective count on the corresponding content trial, which feeds into the A/B testing statistics. An objective represents a desired user action (e.g. signing a petition, completing a form) that was achieved after being referred via a shared link.

Parameters:

The rtid (referring trial ID) identifies the specific share event that brought the user to the page. It is appended to the redirect URL when a user clicks a shared link (as ?rtid=123). This allows objective tracking to be linked back to the original share event.

Call this when a referred user completes a desired action (e.g. submitting a form, signing a petition). This is typically called on a page that the user landed on after clicking a shared link — the rtid parameter in the URL identifies which share trial to attribute the objective to.

Example:

// On a page that the user landed on via a shared link (URL contains ?rtid=123):
Movement.recordObjective();

// Or with an explicit referring trial ID:
Movement.recordObjective({ rtid: 123 });

Movement.getData()

Returns the variant data from the most recent getVariant call, or null if no variant has been fetched yet.

Example:

var data = Movement.getData();
if (data) {
  console.log('Current variant TID:', data.tid);
}

How URL Matching Works

When getVariant is called, the SDK sends the provided URL to the Movement API. The API normalizes the URL by:

1. Stripping the protocol (http:// or https://)
2. Removing query parameters and fragments
3. Removing trailing slashes
4. Converting to lowercase

It then matches this normalized URL against the share_url field on the client's flows. If a match is found, the API selects a variant using the configured content test algorithm (random during warmup, then Thompson Sampling bandit) and returns the variant data.

Full Integration Example

This example shows a page where users can sign a petition and share it. Users who arrive via a shared link will have rtid in their URL, allowing objective tracking.

<!DOCTYPE html>
<html>
<head>
  <title>Petition Page</title>
</head>
<body>
  <div id="share-section" style="display: none;">
    <h2 id="share-title"></h2>
    <p id="share-description"></p>
    <a id="share-link" target="_blank">Share now</a>
  </div>

  <form id="petition-form">
    <!-- petition form fields -->
    <button type="submit">Sign the Petition</button>
  </form>

  <script src="https://your-movement-domain.com/embed.js"></script>
  <script>
    // Fetch the share variant for this page
    Movement.getVariant({ url: window.location.href }, function(data) {
      if (data && data.channels.length > 0) {
        var variant = data.channels[0].variant;

        document.getElementById('share-title').textContent = variant.title;
        document.getElementById('share-description').textContent = variant.description;
        document.getElementById('share-link').href = variant.sharedUrl;
        document.getElementById('share-section').style.display = 'block';
      }
    });

    // Record an objective when the petition form is submitted.
    // This only fires if the user arrived via a shared link (rtid in URL).
    document.getElementById('petition-form').addEventListener('submit', function() {
      try {
        Movement.recordObjective();
      } catch (e) {
        // No rtid in URL — user didn't arrive via a shared link, ignore
      }
    });
  </script>
</body>
</html>

CORS

The embed SDK endpoints support cross-origin requests from any domain. The following endpoints have permissive CORS headers:

• GET /embed.js — the SDK script itself
• GET /api/target/share/external_variant — variant lookup
• POST /api/target/share/record_objective — objective recording

No authentication is required for any of these endpoints.