@dataships/elements

Drop-in consent widget for custom storefronts. The customer adds one script tag and one mount() call; the widget renders the Dataships consent checkbox, description and marketing-information modal inside a shadow root, styled through a small set of appearance tokens.

<script src="https://sdk.dataships.io/elements/v2/elements.js"></script>
<script>
  DatashipsElements.mount({
    publicKey: "ds_pk_live_…",
    token: "<short-lived JWT>",    // minted per page render by the merchant's server (ES256, { iss: publicKey, iat, exp })
    env: "production",             // any other env also needs the baseUrl Dataships gives you
    // baseUrl: "https://…",       // with env "staging" or "local"
    page: "checkout",              // or "confirmation" | "signup"
    mount: "#email-field",         // CSS selector; widget is inserted AFTER it
    emailInput: "#email",          // checkout only: the host's email input
    // email: "[email protected]", // confirmation only
    // order: { id: "ORD-1001", total: 149.9, billingCountryCode: "IE" }, // confirmation only: completes the checkout
    // user: { firstName: "Jane", lastName: "Doe" },                        // required with order
    appearance: {
      colorPrimary: "#0a6", colorText: "#111", colorTextSecondary: "#666",
      colorBackground: "#fff", colorBorder: "#ddd", fontFamily: "inherit",
      fontSize: "14px", borderRadius: "6px", spacing: "12px",
    },
  });
</script>

Install

From the CDN, as above, or from npm for a bundled app:

npm install @dataships/elements

import { mount } from "@dataships/elements";

The npm package depends on @dataships/sdk; the CDN script bundles it.

Versions and CDN URLs

| URL | Serves | |---|---| | https://sdk.dataships.io/elements/<version>/elements.js | that exact release, cached forever | | https://sdk.dataships.io/elements/v<major>/elements.js | latest stable release of that major (5 min cache) | | https://sdk.dataships.io/elements/next/elements.js | latest release candidate | | https://sdk.dataships.io/elements/<version>/integrity.json | SHA-384 of each script |

On npm, stable releases are tagged latest and release candidates (X.Y.Z-rc.N) are tagged next.

Pin an exact version with Subresource Integrity:

<script
  src="https://sdk.dataships.io/elements/2.0.0/elements.js"
  integrity="sha384-…"
  crossorigin="anonymous"></script>

How it works

The widget drives the Dataships CUSTOM_PLATFORM_CHECKOUT consent-session flow through @dataships/sdk and its CustomPlatformCheckoutAdapter (@dataships/sdk/adapters/custom-platform-checkout):

• mount() builds a DatashipsClient with auth: { publicKey, token } and posts POST /v1/consent-session with integration: { type: "CUSTOM_PLATFORM_CHECKOUT", collectionStep, datashipsSessionId, isFastCheckout }. page: "checkout" is CHECKOUT_INFORMATION, page: "confirmation" is THANK_YOU.

• The adapter mints the per-checkout datashipsSessionId on the checkout page and carries it to the confirmation page through localStorage (keyed by the public key). A confirmation upsert for a checkout that already showed the widget answers 204, which renders nothing.

• Consent is saved on click (/v1/consent-session/consent); the checkout page heartbeats every 210 s for 10 min.

• On the confirmation page, pass the placed order and the checkout is completed: mount({ page: "confirmation", email, order: { id, total, billingCountryCode, submittedAt? }, user: { firstName, lastName } }). After the thank-you upsert, submitSession posts the order under the checkout's beacon (POST /v1/consent-session/submit), which lands it on every session opened during the checkout and queues processing. Exactly once per order id on this browser: a reload of a submitted order renders nothing and sends nothing. Without order the page only renders and logs that the checkout was not completed.

• Signup forms. mount({ page: "signup", mount: ".form-actions", position: "before", emailInput, firstNameInput, lastNameInput, form? }) drives the CUSTOM_PLATFORM_SIGNUP flow on a merchant-built form: anonymous upsert, re-upsert as the email is typed, consent on tick, heartbeat. On the form's native submit the widget holds the form for up to submitHoldMs (3 s) while submitSession completes the sessions with the names read from the form, then lets the form proceed; a failure never blocks the signup. Forms that submit through fetch use submit: "manual" and call handle.submit() from their own handler. A user resolver can replace the two name selectors.

unsafeServerKey: "ds_sk_…" is the accepted-risk escape hatch for a merchant with no server to mint tokens: the server key itself, sent alone as X-Api-Key. Anyone who views the page source can act as that merchant until the key is revoked (ask Dataships support to revoke it); the SDK warns once in the console and tags every request unsafe-server-key so the backend can tell. It replaces token.

preview: true renders the SDK's synthetic email copy with no API calls and no token, so a merchant can style the widget on a sandbox before credentials exist (the SDK adapter's previewMode; consent is never saved). client lets you pass a pre-configured client instead. Without either, token is required.

mount() returns a handle: ready (a promise that settles after the first upsert and, on the confirmation page, the order submit; it never rejects), refresh(), unmount(), submit() (signup) and element. The widget element dispatches bubbling, composed CustomEvents the host page can listen for, on the element or on document (types in ElementsEventMap):

| Event | detail | |---|---| | dataships:upsert | { ok, consentSessionId, consents: ["EMAIL:OPT_IN", …], identifier: "set" \| "anonymous", error? }; ok: false renders nothing | | dataships:consent | { consent, saved } after a checkbox change | | dataships:submit | { ok, page: "confirmation" \| "signup", orderId?, error? } | | dataships:visibility | { visible } whenever the widget shows or hides |

The token is the part that is not "one script tag": the merchant's server holds the signing key, mints a short-lived JWT per page render and injects it into the page. A missing or expired token surfaces as a 401 and the widget stays hidden.

Contributing

See CONTRIBUTING.md in the repository.

License

Apache-2.0