URL integration Specification

This mode of integration enables third-party developers/ integrating parties to add OneStudyTeam's Study Module(s) directly to their website in an iFrame.

Note: This mode is only available for module(s) that have the following form flow

Prescreener form
Site Map
- This module type displays a list of participating sites along side a map showing their location.
Demographics form.

The images and snippets used for this guide are all for demonstration purposes only.

Prescreener form

This form will allow the user to answer questions about themselves and proceed to the next screen in the form flow, which is the Site Map Screen

Site Map

This screen displays a list of participating sites along side a map showing their location

Demographics/ Contact Info form

This form enables the user to submit their contact information to the participating site that has been selected in the form Site Map.

Installation

The installation for direct integration through URL is very easy 🚀. The third-party/integration party will be provided with a URL, which they need to add to their website with some required query parameters using an iframe (this is discussed in the section code-example).

URL structure

https://{study-module-url}/{locale}/?{queryparams}

URL attribute Name	Provided By	Required?	Comment(s)
locale	Integrating party	Yes	If the locale is not provided the StudyModule won't load. Alpha-2 language and country code to specify localization language for module to display in. Codes come from ISO-639-1 and ISO-3166-1 and are of the form: "en-US" - US English "es-US" - US Spanish "es-ES" - Spain Spanish
required queryparams - micrositeId - trialId	Integrating party	Yes	If the required queryparams are not provided the StudyModule won't load. - Example micrositeId: 550e8400-e29b-41d4-a716-446655440000 - Example trialId: 832c08e-c3dc-46f2-9745-0b3ed985eee5
Optional queryparams - utm paramters	Integrating party	No	Example utm params - utm_source - utm_medium - utm_campaign - utm_content - utm_term

Example URL

URL structure with required parameter(s)

This is how the url structure should be and look like with the required query parameters provided.

https://example-url.com/en-US?micrositeId=550e8400-e29b-41d4-a716-446655440000&trialId=2832c08e-c3dc-46f2-9745-0b3ed985eee5

URL structure with required & optional parameter(s)

https://example-url.com/en-US?micrositeId=550e8400-e29b-41d4-a716-446655440000&trialId=2832c08e-c3dc-46f2-9745-0b3ed985eee5&utm_source=meta&utm_medium=paid-social&utm_campaign=202501&utm_content=content

Code example

This code snippet is just an example.

<!DOCTYPE html>

  <body style="height: 80vh;" background-color="#f5f5f5">
    <iframe
      src="https://example-url.com/en-US?micrositeId=550e8400-e29b-41d4-a716-446655440000&trialId=2832c08e-c3dc-46f2-9745-0b3ed985eee5"
      style="width: 100%; height: 100%; border: none; background-color: #f5f5f5"></iframe>
  </body>

</html>

In the above code snippet, we have a html webpage, which is displaying the OST StudyModule loaded in an iframe at Line 4

What happens if any of the REQUIRED attributes are not provided to the iframe. Section below covers it in the detail.

Tests 🧪

Test case 1 → If the correct Studyteam URL is used for the iFrame.

Test case 2 → If parameters in the Studyteam URL are incorrect.

Test case 3 → If the correct Studyteam URL is used and there are UTM parameters appended to the URL.

Test case 1

Test Setup	Add the Studyteam URL as the src to a generic iFrame.
Required Attributes	The URL should have the following: - Locale - micrositeId - trialId
Example of Studyteam URL	`https://example-url.com/en-US?micrositeId=550e8400-e29b-41d4-a716-446655440000&trialId=2832c08e-c3dc-46f2-9745-0b3ed985eee5`

Outcome

Prescreener form should be displayed.

Test case 2 (If parameters in the Studyteam URL are incorrect)

Test Setup	Add the Studyteam URL as the src to a generic iFrame.
Required Attributes	The URL should have the following: - Locale - micrositeId - trialId This test is in the event that one of these parameters is missing.
Example of Studyteam URL	Example of Studyteam URL with incorrect parameters:`https://example-url.com/en-US?micrositeId=550e8400-e29b-41d4-a716-446655440000`

Outcome

Error message should be displayed.

Test case 3 (If the correct Studyteam URL is used and there are UTM parameters appended to the URL)

Test Setup	Add the Studyteam URL as the src to a generic iFrame.
Required & Optional Attributes	The URL should have the following required attributes - Locale - micrositeId - trialIdOptional parameters The UTM parameter could be any number of these parameters: - utm_source - utm_medium - utm_campaign - utm_content - utm_term
Example of Studyteam URL	Example of Studyteam URL with UTM values: `https://example-url.com/en-US?micrositeId=550e8400-e29b-41d4-a716-446655440000&trialId=2832c08e-c3dc-46f2-9745-0b3ed985eee5&utm_source=meta&utm_medium=paid-social&utm_campaign=202501&utm_content=content`

Outcome

Prescreener form should be displayed.

That's it, you have integrated the Study Module using the URL approach successfully 🥳 🚀