Skip to main content

Integration

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​

The following code will install the widget. You can choose to install the widget anywhere, but you must not open the widget before it has been loaded (see below).

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

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>
  </head>
  <body>
    <a class="selfAssessmentTrigger" href="#">
      Open Trialbee Self-assessment Widget
    </a>
    <br><br>
    <button class="selfAssessmentTrigger">
      Open Trialbee Self-assessment Widget
    </button>
    <br><br>
    <a href="javascript:openTrialbeeSelfAssessment();">
      Open Trialbee Self-assessment Widget (no class!)
    </a>

    <!-- Trialbee Self-assessment -->
    <script defer
      id="trialbee-script"
      src="https://widget.trialbee.com/prescreener.js">
    </script>
    <script>
      var trialbeeWidget;

      // This script opens the widget with pre-selected configuration
      function openTrialbeeSelfAssessment() {
        try {
          trialbeeWidget.open({
            baseURI: "https://widget.trialbee.com/api/osa",
            studyId: "TBX1",
            locale: "en_US",
            landingPage: window.location.href,
          });
        } catch (error) {
          alert("Self-assessment not yet available. Try again in a few seconds");
        }
      }

      // Make all elements with class "selfAssessmentTrigger" open the widget
      document.addEventListener("DOMContentLoaded", function(event) {
        trialbeeWidget = new window.TrialbeeRecruitmentWidget();
        const triggers = document.querySelectorAll('.selfAssessmentTrigger');
        triggers.forEach(element => {
          element.onclick = function () {
            openTrialbeeSelfAssessment();
          };
        });
      });
    </script>
    <!-- Trialbee Self-assessment -->
  </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 an 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.

Configuration​

The widget configuration has the following fields:

baseURI (required)​

The Honey backend URL, should be set to https://widget.trialbee.com/api/osa unless otherwise instructed.

studyId (required)​

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

locale (required)​

Provided by Trialbee Project Manager, example: en_US

referrerToken​

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 referrer-tracking guide for more information.

referrer (deprecated)​

This field can be set to the URL for how the user entered into a website with internal navigation. Most often, this value will require you to add cookies to the webpage to track entrypoint.

landingPage​

This field can be set to where the user was when they opened the widget. Currently, this field also holds information about UTM-data. Example: https://my-study.com/?utm_src=facebook&utm_medium=social. For single study landing pages, you might be able to just extract current browser URL using window.location.href.

Examples​

Minimal​

trialbeeWidget.open({
  baseURI: "https://widget.trialbee.com/api/osa",
  studyId: "TBX1",
  locale: "en_US",
});

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
});