Writing organisation scripts

This guide is the developer companion to the admin script configuration article. Use it when you are writing or reviewing the JavaScript that runs in OmniLab Pages.

Where the script runs

Organisation scripts run in the consumer-facing Pages runtime, not inside Studio. Before active scripts run, OmniLab initialises window.omnilab and can expose both group data and basic contact data to the page.

window.omnilab?.contact?.externalId
window.omnilab?.contact?.email
window.omnilab?.group
window.omnilab?.group?.configuration?.variables
window.omnilab?.group?.uniqueKey
window.location.pathname

Contact values are available only when the participant is already known in that flow.

Your code must contain real script tags

OmniLab expects the script code field to contain one or more valid <script>...</script> blocks. Inline scripts and external script loaders are both supported.

<script>
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: "omnilab_view",
  organisation_key: window.omnilab?.group?.uniqueKey,
  page: window.location.pathname,
});
</script>

<script async src="https://www.googletagmanager.com/gtm.js?id=GTM-AB12C3D"></script>

Context and trigger behavior

If the current trigger is REGISTRATION, OmniLab still keeps the other active scripts available and adds the registration-targeted scripts for that stage. In practice, use a separate REGISTRATION script for conversion events instead of overloading the base page-view script.

Safe use cases

• Analytics loaders such as GTM, a pixel base tag, or a dataLayer bootstrap
• Per-organisation behaviour based on window.omnilab.group.configuration.variables
• Lightweight event pushes on visit or registration
• Minor DOM enhancements that do not depend on fragile selectors or block interaction

<script>
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: "omnilab_view",
  organisation_key: window.omnilab?.group?.uniqueKey,
  country: window.omnilab?.group?.configuration?.variables?.country,
  locale: window.omnilab?.group?.configuration?.variables?.locale || "en_US",
  page: window.location.pathname,
  surface: "Pages",
});
</script>

<script>
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: "registration_complete",
  external_id: window.omnilab?.contact?.externalId,
  email: window.omnilab?.contact?.email,
  organisation_key: window.omnilab?.group?.uniqueKey,
});
</script>

What to avoid

• Replacing or overriding OmniLab business logic
• Blocking synchronous work that delays page load or prevents participation
• Fragile DOM rewrites that depend on unstable class names or layout details
• Collecting extra personal data without a clear legal basis and review
• Large client-side libraries that are not essential to the participant journey

Local testing workflow

1. Build and review the script in a staging environment.
2. Test both iframe and non-iframe delivery if the script depends on the container.
3. If the trigger is REGISTRATION, complete a full registration flow and inspect the browser console and network panel.
4. After admins save the script, publish the affected campaign again before you validate the live experience.

Handoff to admins

When you hand a script to an admin, provide:

• the script name
• the intended context (ALL, IFRAME_ONLY, or NON_IFRAME_ONLY)
• the intended trigger (VISIT or REGISTRATION)
• whether the script should start active or inactive
• a rollback instruction and a staging test result

Related