@whitebeardnl/messaging-loader

npm distribution of the WhiteBeard on-site messaging embed loader — banners, modals, inline article prompts, and registration walls, managed from the CMS with no frontend deployments required. This is the same runtime shipped as the classic <script data-*> embed; use whichever integration fits your stack.

Install

npm install @whitebeardnl/messaging-loader

Quick start

import { init } from '@whitebeardnl/messaging-loader';

init({
  siteId: 1,
  apiBase: 'https://messaging.domain.com/',
  assetBase: 'https://api.domain.com/',
});

init(config) returns a Promise that resolves with the raw API payload, or null if the request failed or config was invalid (e.g. missing siteId) — in both cases a wb:loader:error event is dispatched on window with details.

Config options

| Field | Maps to data-* attribute | Description | | ---------------- | --------------------------- | -------------------------------------------------------------------------- | | siteId | data-site-id | Publication ID for the site, as configured in the CMS. Required. | | apiBase | data-api-base | Base URL of the Messaging API. | | assetBase | data-asset-base | Base URL for CMS API. | | endpoint | data-endpoint | Messaging embed endpoint path. Defaults to /messaging/embed. | | zoneSelector | data-zone-selector | CSS selector used to specify the attribute to look for when finding zones. Defaults to [data-wb-zone-key]. | | inlineSelector | data-inline-selector | CSS selector used to inject inline article messages into the page content. | | context | data-context | Extra targeting context, forwarded to the API. Accepts a plain object here (no JSON stringifying needed). |

Avoiding a paywall-teaser flash

If your page uses the .article-paywall convention (see the full docs), call detachArticlePaywallMarker() synchronously before init() to remove the teaser from the DOM immediately, avoiding a flash of it before messages resolve:

import { init, detachArticlePaywallMarker } from '@whitebeardnl/messaging-loader';

detachArticlePaywallMarker();
init({ siteId: 1, apiBase: '...', assetBase: '...' });

This is optional — init() does not call it automatically, since doing so on every call (rather than once per page) could re-hide a paywall marker a message has already claimed.

Events

The loader dispatches the same wb:message:*, wb:loader:error, and wb:message:conversion* events on window regardless of distribution — see messaging_tool_frontend.mdx in the main repo for the full event contracts, zone/inline targeting behavior, and template-specific integrations (e.g. the registration wall).

Prefer a plain <script> tag instead?

The classic script-tag integration still exists and is the right choice for sites that don't run a JS bundler:

<script
  data-api-base="https://messaging.domain.com/"
  data-asset-base="https://api.domain.com/"
  data-site-id="1"
  type="text/javascript"
  src="https://api.domain.com/js/messaging_loader.js"
  async="true"
></script>

See messaging_tool_frontend.mdx for the complete reference.

License

ISC