UserLoop SDK

The UserLoop JavaScript SDK lets you embed a survey or quiz in any website, including custom storefronts, landing pages, account areas, and post-purchase experiences. It has no framework dependency and renders a responsive survey inside an element you choose.

Quick Start

Add this snippet where you want the survey to appear. Replace YOUR_SURVEY_ID with the survey ID from your UserLoop dashboard.

<div id="userloop_survey"></div>

<script>
  (function () {
    var SURVEY_ID = 'YOUR_SURVEY_ID';
    var TARGET_ID = 'userloop_survey';

    function start() {
      var target = document.getElementById(TARGET_ID);
      if (!target) return;
      UserLoop(SURVEY_ID, target).init();
    }

    if (window.UserLoop) {
      start();
      return;
    }

    var script = document.createElement('script');
    script.src = 'https://cdn.userloop.io/sdk-2/userloop.js';
    script.async = true;
    script.onload = start;
    document.head.appendChild(script);
  })();
</script>

The SDK loads the published survey, applies its colours and settings, and handles navigation and response submission.

Initialising the SDK

If your site manages script loading itself, include the SDK and create an instance directly:

<script src="https://cdn.userloop.io/sdk-2/userloop.js"></script>

<div id="userloop_survey"></div>

<script>
  const survey = UserLoop(
    'YOUR_SURVEY_ID',
    document.getElementById('userloop_survey'),
    {
      email_collection: true,
      expanded_mode: false,
    },
    {
      customer: {},
      transaction: {},
    }
  );

  survey.init();
</script>

The initializer is:

UserLoop(surveyId, targetElement, config, context)

Call init() after the target element exists in the page.

Common Configuration Options

Branding, colours, progress bars, button text, thank-you content, rewards, and most presentation settings come from the published survey configuration rather than the embed code.

Instance Methods

UserLoop(...) returns an instance with these methods:

Supported Question Types

The SDK renders the question types configured in UserLoop, including Single Select, Multi Select, Open Ended, Email, Date, Phone, Number Score and NPS, CSAT, Video, and Info Screen. Follow-up questions, optional questions, custom button text, auto-proceed, redirect links, progress indicators, and thank-you rewards are driven by the survey configuration.

See Question Types for guidance on choosing and configuring questions.

Info Screens

An Info Screen is a content-only step. Use one to introduce a survey, explain what will happen next, divide a longer survey into sections, or describe a reward before asking a question.

An Info Screen can contain:

• A heading
• Multi-line supporting text
• An optional image
• The survey's normal Continue button

It is placed in the survey like any other question, so you can position it at the beginning, end, or between questions. The same product and customer targeting rules also apply.

For API-driven survey configurations, an Info Screen has type: "Info Screen":

{
  "question_id": "intro-screen",
  "type": "Info Screen",
  "question": "Before you start",
  "question_subheading": "This takes about two minutes.\n\nYou'll receive 10% off at the end.",
  "info_image": "https://example.com/survey-intro.jpg",
  "required": false,
  "answers": []
}

Info Screen behaviour:

• It collects and submits no answer, so it creates no response row and does not appear in response exports.
• It advances the progress bar as a survey step, but is not numbered as a question.
• Supporting text keeps its line breaks.
• A broken optional image is removed without preventing the rest of the screen from loading.
• The Continue button is always available. Required and skip settings do not apply.
• An Info Screen cannot be used as a conditional follow-up question.
• If email collection is enabled, the email field appears on the first answerable question rather than on the Info Screen.
• A live survey containing only Info Screens is not shown because there is no response to collect. Preview mode can still render it for design review.

Info Screens are supported by the JavaScript SDK and by UserLoop's Shopify Checkout, Popup Survey, and App Block survey experiences.

Passing Customer and Transaction Data

Pass customer and order context as the fourth argument. All fields are optional; send only the data your site has.

const customer = {
  id: 'customer_123',
  email: '[email protected]',
  firstName: 'Alex',
  lastName: 'Morgan',
  order_count: 3,
};

const transaction = {
  transaction_id: 'order_456',
  order_creation_date: '2026-08-07T09:30:00.000Z',
  total: 89.95,
  currency: 'GBP',
  coupon_code: 'WELCOME10',
  platform: 'Custom Storefront',
  source: 'website',
  utm_source: 'newsletter',
  products: [
    {
      id: 'shopify-product-id',
      name: 'Example product',
      product_url: 'https://example.com/products/example-product',
    },
  ],
};

const survey = UserLoop(
  'YOUR_SURVEY_ID',
  document.getElementById('userloop_survey'),
  { email_collection: true },
  { customer, transaction }
);

await survey.init();

This context enriches the response data and lets UserLoop decide whether targeted questions apply.

Question Targeting

Questions, including Info Screens, can be limited by product or customer status in the survey configuration:

• Product targeting matches against product IDs in the transaction. For Shopify, pass product IDs rather than variant IDs.
• New-customer and returning-customer targeting uses customer.order_count or transaction.order_count.
• Live embeds hide questions whose targeting rules do not match.
• Preview mode intentionally ignores targeting and renders every configured question so the complete design can be reviewed.

If targeting removes every answerable question, the live survey container is hidden instead of displaying an empty survey.

Refreshing or Switching Surveys

Use refresh() when your page gains updated order data or when you want to reload the published survey configuration:

await survey.refresh();

To switch the same embed to another survey:

await survey.refresh('ANOTHER_SURVEY_ID');

// Equivalent:
await survey.setSurveyId('ANOTHER_SURVEY_ID');

Video Responses

Video questions let respondents record with their camera or choose an existing file. The SDK handles permission prompts, upload progress, retry messaging, and the normal response submission flow. Whether Video is available and its maximum duration are controlled by the survey configuration.

Because camera and microphone access require a secure browser context, serve pages containing Video questions over HTTPS. If a respondent declines camera access, the file-upload option can still be used where supported.

Integrations

When the survey is connected to integrations such as Shopify, Klaviyo, Slack, gift cards, webhooks, or response notifications, the published survey includes the necessary integration flags. The SDK copies those flags into response payloads automatically; you do not need to duplicate them in your embed configuration.

Testing and Troubleshooting

Before publishing your integration:

1. Confirm the survey is published and the survey ID is correct.
2. Confirm https://cdn.userloop.io/sdk-2/userloop.js is allowed by your site's Content Security Policy.
3. Make sure the target element exists before calling UserLoop(...).
4. Test at mobile and desktop widths.
5. Pass representative product IDs and order counts when testing targeted questions.
6. Use preview_mode: true to review all questions, including those whose live targeting would not match your test customer.
7. Check the browser console and Network panel if the survey does not load.

Do not place private credentials or API keys in browser-side SDK configuration. The survey ID is intended to be used by the browser; secret server-side keys are not.

Need Help?

If you have questions about an SDK integration, contact us through live chat. Include the page URL, survey ID, browser-console error, and a description of the behaviour you expected so we can investigate quickly.