Script

Install the script

Copy the script from the widget’s Install dialog (see Install) and paste it inside the <head> tag of every page that should show the widget. It looks like this, with your widget’s UID in place of tool_id:

<script>
  (function () {
    var el = document.createElement("script");
    el.setAttribute("src", "https://cdn.raffle.ai/search-v2/index.js");
    el.setAttribute("id", "raffle-sdk-v2");
    el.setAttribute("type", "module");
    el.setAttribute("defer", "");
    el.setAttribute("data-uid", "tool_id");
    document.head.appendChild(el);
  })();
</script>

• To show the widget on all pages, add the script to a part of your site that every page shares, such as a common header template.
• To show it on some pages only, add the script to those pages, or add it everywhere and list the pages to skip under Hide widget on pages.

If your site sends a Content Security Policy, a strict policy refuses the inline <script> block above. Use the plain tag instead. It does the same thing:

<script id="raffle-sdk-v2" type="module" data-uid="tool_id"
        src="https://cdn.raffle.ai/search-v2/index.js"></script>

See Content Security Policy for the hosts and directives Raffle needs, and Tag Manager to load the script with Google Tag Manager.

The widget runs in its own frames, so your website’s CSS doesn’t change how it looks. Use the settings in Branding instead, including Custom CSS. If you need a fully custom interface, use the Raffle API.

When the widget doesn’t start

The widget doesn’t start, and the browser console says why, when:

• the page has more than one raffle-sdk-v2 script tag, or the tag has no data-uid
• the same UID is listed twice in data-uid
• the script runs inside an <iframe>. Install it on the top-level page.
• the browser is too old (see Supported browsers)

Launcher and pill widgets

Only the script is needed. The widget adds its own button or input to the page.

Overlay widgets

An overlay opens when you call window.raffleApi.open with the widget’s UID, for example from your site’s search button. The Install dialog shows this call for overlay widgets:

<button type="button" onclick="window.raffleApi.open('tool_id')">Search</button>

Embedded widgets

An embedded widget is placed inside an element on your page. Enter that element’s CSS selector as the Element selector on the widget’s General tab, and make sure the element exists on the page, for example:

<div id="target-element"></div>

The widget takes the full width of the element. When visitors search, the results open over the content below it, without pushing the page down. If the element isn’t on the page yet when the widget loads, the widget waits for it to appear.

Multiple widgets

To use more than one widget on a page, list their UIDs in the same script, separated by commas. Don’t add a second script tag.

el.setAttribute("data-uid", "tool1_id,tool2_id");

A page can have:

• at most one launcher, one overlay and one pill
• a launcher or a pill, not both
• several embedded widgets, each in its own element. Two widgets can’t share an element, and each element selector must match only one element on the page.
• one live chat provider. If several widgets use Chat Support, they must use the same provider.

If a page breaks one of these rules, none of the widgets in the script start, and the browser console says which rule.

Different widgets on different pages

To use a specific widget depending on where the visitor is on your website, choose the UID before adding the script:

<script>
  (function () {
    var uid = "tool_id"; // default widget
    var path = window.location.pathname;

    if (path.indexOf("/business") === 0) {
      uid = "tool2_id"; // widget for /business
    } else if (path.indexOf("/private") === 0) {
      uid = "tool3_id"; // widget for /private
    }

    var el = document.createElement("script");
    el.setAttribute("src", "https://cdn.raffle.ai/search-v2/index.js");
    el.setAttribute("id", "raffle-sdk-v2");
    el.setAttribute("type", "module");
    el.setAttribute("data-uid", uid);
    document.head.appendChild(el);
  })();
</script>

JavaScript API

Once the widget has loaded, it adds window.raffleApi to your page. Use it to control the widget from your own code.

The uid is optional when the page has only one widget. With several widgets on the page, pass the UID of the one you mean. A call without a UID, or with a UID that isn’t on the page, throws an error.

window.raffleApi doesn’t exist until the widget has loaded, so check for it before you call it.

Open the widget automatically

To open a widget on your homepage after a few seconds, but not on phones:

<script>
  (function () {
    var delay = 3000; // 3000 milliseconds = 3 seconds
    var tries = 0;

    if (window.location.pathname !== "/") return;
    if (window.matchMedia("(max-width: 480px)").matches) return;

    function openRaffle() {
      if (window.raffleApi) {
        window.raffleApi.open("tool_id");
      } else if (tries++ < 20) {
        setTimeout(openRaffle, 500); // not loaded yet, try again
      }
    }

    setTimeout(openRaffle, delay);
  })();
</script>

Add it after the Raffle script. The widget treats screens up to 480px wide as phones, so the snippet uses the same limit.

Widget events

Listen to these events with window.raffleApi.addEventListener:

client:open  → The widget was opened
client:close → The widget was closed
search:hide  → The launcher was hidden with hide()
search:show  → A hidden launcher was shown again with show()
chat:ready   → Your live chat provider is ready to be used from the widget
chat:start   → A visitor opened your live chat from the widget
chat:end     → The visitor closed the live chat, if your provider reports it
all          → Any of the events above

The callback receives the event name. For chat:start it also receives the visitor’s last question, when Inject first message is on under Chat Support.

window.raffleApi.addEventListener("all", function (eventName, payload) {
  console.log("Raffle event:", eventName, payload);
});

Any other event name throws an Unknown event error. Events aren’t sent while the page is in a background tab.

To send widget events to Google Tag Manager or Tealium, see Tag Manager.

Supported browsers

The widget needs a browser with up-to-date web features. It runs in these browsers and newer versions:

In an older browser, the widget doesn’t load, and the browser console says which feature is missing.