Skip to main content

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.

baseURI (optional)​

The Widget can be reconfigured to load study data from another API-endpoint, including test environments. Note that this will likely cause cross-origin requests and will have an impact on browser compatibility.

Examples​

Minimal​

trialbeeWidget.open({
  baseURI: "https://widget.trialbee.com/api/osa",
  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
});