Widget Integration

Nomenclature

• Widget loading script: A script that enables the Self-assessment Widget to be triggered.
• Widget: A single-page application that runs widget.trialbee.com inside an <iframe>.
• Widget-configuration object: The object that configures each invocation of the Widget.

Prerequisites

In order to trigger the Widget for your specific study, you need:

• A studyId
• A supported locale

Both these variables are provided by the project manager at Trialbee.

Install the Widget Loading Script

The following code will install the widget loading script into the webpage.

index.html

<!DOCTYPE html>
<html>
  <head>
    <script defer
      id="trialbee-script"
      src="https://widget.trialbee.com/prescreener.js">
    </script>
  </head>
  <body>...</body>
</html>

Widget-configuration object

The widget configuration has the following fields:

studyId (required)

Provided by Trialbee Project Manager, example: ABC123 or 5531ea31.

locale (required)

Provided by Trialbee Project Manager, example: en_US

landingPage (optional)

This field can be set to the URL where the user was when they opened the widget. This field should also pass UTM parameter information if available. Example: https://my-study.com/?utm_src=facebook&utm_medium=social.

Please note that you might want to take special consideration as to how

referrerToken (optional)

If the study used multiple recruitment vendors, via Trialbee Omnichannel Ecosystem, or just want to trace how the user entered the webpage, set this field. Example: my-referrer-token.

See source tracking guide for more information.

Examples

Minimal

trialbeeWidget.open({
  studyId: "TBX1",
  locale: "en_US",
});

Full example opening the widget

The widget must be opened using javascript. In the following example, we make every element having the class selfAssessmentTrigger a trigger to open the self-assessment widget.

index.html

<!DOCTYPE html>
  <head>
    <script defer
      id="trialbee-script"
      src="https://widget.trialbee.com/prescreener.js">
    </script>
    <script>
      var trialbeeWidget;

      // Create a click-trigger on any element that has the class "selfAssessmentTrigger"
      document.addEventListener("DOMContentLoaded", function(event) {
        const triggers = document.querySelectorAll('.selfAssessmentTrigger');
        triggers.forEach(element => {
          element.onclick = function () {
            openTrialbeeSelfAssessment()
          };
        });
      });

      // This script opens the Widget with a predefined configuration.
      function openTrialbeeSelfAssessment() {
        try {
          trialbeeWidget.open({
            studyId: "TBX1",
            locale: "en_US",
            referrerToken: "my-referrer-token",
            landingPage: window.location.href,
          });
        } catch (error) {
          alert("Self-assessment not yet available. Try again in a few seconds");
        }
      }

      // Wait for the script's load-event, then change the text of the link
      const trialbeeScript = document.getElementById('trialbee-script');
      trialbeeScript.addEventListener('load', () => {
        trialbeeWidget = new window.TrialbeeRecruitmentWidget();
      });
    </script>
  </head>
  <body>
    <a class="selfAssessmentTrigger" href="#">
      Open Trialbee Self-assessment Widget
    </a>
    <br><br>
    <button class="selfAssessmentTrigger">
      Open Trialbee Self-assessment Widget
    </button>
  </body>
</html>

The example file is overly verbose but contains a safe way to download the script, initialize the widget and finally open it. The core pieces

• new window.TrialbeeRecruitmentWidget(),
• trialbeeWidget.open({...})

are there, but the remaining code is still required to ensure that the script has been properly downloaded, initialized and will execute by clicking a URL.

tip

Most of the example code can be used directly on your webpage. Remove comments, and update the configuration object to work with your configuration.

UTM-tracking

const landingPage = window.location.href || "https://my-study.com/?utm_src=facebook";

trialbeeWidget.open({
  ...minimalConfiguration,
  landingPage: landingPage,
});

Referrer token

In the following example we assume that the URL will contain the token in final part of the path.

const currentPageUrl = 'https://my-studies.com/study/anna?utm_src=facebook';
const url = new URL(currentPageUrl);
const referrerToken = url.location.pathname.split('/').slice(-1); // anna

trialbeeWidget.open({
  ...minimalConfiguration,
  referrerToken: referrerToken, // anna
});

Landing page

We will store the URL on the users first entry for the next 7 days.

// check if we have a cookie already
const firstEntryUrl = document.cookie
  .split('; ')
  .find((row) => row.startsWith('firstEntryUrl='))
  ?.split('=')[1];

// at first visit, set cookie if not already set
if (!firstEntryUrl)
  document.cookie = `firstEntryUrl=${window.location.href}; max-age=${
    7 * 24 * 3600
  }`;

trialbeeWidget.open({
  ...minimalConfiguration,
  landingPage: cookieValue, // or url.href
});