Forms

Embed a Promotion Hub form

Add one permanent script to your website. Promotion Hub keeps the form current, forwards enabled form events, and can securely stitch host analytics identities without extra publisher code.

1Allow your website origin

2Paste the permanent script

3Test the form and events

Before you start

Install analytics on your website using that provider's normal instructions. For Usermaven or DataFast identity stitching, connect the workspace integration in Promotion Hub, allowlist this exact origin, and enable Identify submitters at workspace and form level. No API key or bridge code belongs on the publisher site.

The embed bridge only forwards form activity to adapters you enable. If a tracker is absent or blocked, the form continues working normally.

1. Allow the host website

In the form's settings, add every exact production website origin that may embed it. Use only the scheme and hostname.

Allowed origins

https://www.example.com
https://staging.example.com

Do not add paths, credentials, or wildcard domains. An unlisted origin cannot exchange trusted resize, redirect, or analytics messages with the form.

2. Install the form once

Copy your form's generated snippet from Promotion Hub. It already contains your form ID, Promotion Hub origin, and mount ID.

HTML and website builders

Paste this into a custom HTML block where the form should appear.

HTML

<script type="text/javascript" src="https://hub.indieshortsmag.com/jsform/FORM_ID"></script>

Next.js

Copy the complete component from your dashboard, then import and render PromotionHubForm where the form should appear. The example shows the same component structure.

app/components/PromotionHubForm.tsx

import Script from "next/script"

export function PromotionHubForm() {
  const mountId = "promotion-hub-form-FORM_ID"

  return (
    <>
      <div id={mountId} />
      <Script
        id={`${mountId}-script`}
        src="https://hub.indieshortsmag.com/jsform/FORM_ID"
        data-ph-container={mountId}
        strategy="afterInteractive"
      />
    </>
  )
}

You do not need to replace the snippet when fields, packages, styling, allowed origins, or tracking settings change. The script loads the latest published configuration.

Advanced: local Promotion Hub development

When running Promotion Hub locally, its non-production runtime can allow http://localhost:3000 without changing saved form settings. Set PROMOTION_HUB_DEV_PARENT_ORIGINS only when you need additional exact local origins. Production always uses the form's saved allowlist.

3. Enable host-owned analytics

Choose the adapters that match analytics already installed on the host: dataLayer/GTM, gtag, fbq, Usermaven, or DataFast. Each adapter is optional and isolated from form submission.

The generated loader responds only to its exact Promotion Hub iframe and only on allowlisted origins. It sends a provider-neutral v3 message containing available anonymous Usermaven and/or DataFast identifiers plus sanitized attribution. Credentials are encrypted in Promotion Hub and never cross postMessage.

The bridge also dispatches a promotionhub:event CustomEvent so other tools can subscribe without changing the iframe.

Optional dataLayer listener

window.dataLayer = window.dataLayer || []

window.addEventListener("promotionhub:event", (event) => {
  window.dataLayer.push({
    event: "promotion_hub_form_event",
    promotionHub: event.detail,
  })
})

Supported events

embed_loadedform_startedstep_viewedvalidation_errorsubmit_startedsubmit_succeededsubmit_failedpayment_startedpayment_completedpayment_failed

Submission success is sent only after durable server creation. Payment completion is sent only after server confirmation. Event IDs are deduplicated across retries and reloads.

For payment events on a custom thank-you page, keep the permanent Promotion Hub script installed on that page and use a return URL whose origin is in Allowed Parent Origins. The loader removes the signed return token from the address bar, polls webhook-backed confirmation, and forwards one terminal event with a stable event ID.

Troubleshooting

The form does not resize or redirect: Confirm the page's exact origin is saved in Allowed Parent Origins, including the correct HTTPS scheme and port.
Analytics events are missing: Confirm the adapter is enabled, the provider is installed on the host page, and consent or an ad blocker is not preventing the tracker from loading.
Events appear twice: Remove duplicate embed scripts and ensure the same conversion is not also sent by a direct form pixel or a second GTM listener.

Forms documentationOpen Promotion Hub