Embed Widgets — Summary

RxVantage Embed Widgets let third-party applications drop live RxVantage functionality (starting with the rep directory) into their own pages. Integrators get a working, secure UI in minutes without rebuilding it against the raw API.

To see details on each widget we support, please refer to the RxVantage Embed Widgets menu.

How it works

The widget is hosted at embed.rxvantage.com and rendered inside a sandboxed iframe on the host page. Communication between the host and the widget uses the browser's postMessage API with strict origin validation. Authentication is handled by short-lived JWTs that your backend obtains from RxVantage in a server-to-server call, then hands to the widget — credentials never sit in browser code or URLs.

Two integration paths

1. SDK (recommended) — the @rxvantage/api-widgets npm package, available for React, Vue 3, and vanilla JavaScript, plus a UMD CDN bundle for sites without a build pipeline. The SDK manages the iframe lifecycle, the postMessage handshake, token delivery, automatic token refresh, and structured event callbacks (ready, user:select, auth:error, error).
2. Bare iframe fallback — for restricted environments (e.g. CMS platforms with no JS), a plain <iframe> with the token passed as a URL parameter. Trades off token security and event callbacks for maximum compatibility.

Authentication and token lifecycle

The host's backend calls RxVantage's auth endpoint with its client credentials and receives a JWT scoped to the end-user. The SDK delivers that token to the iframe via postMessage with an exact targetOrigin — so the token never appears in URLs, server logs, browser history, or Referer headers. The SDK decodes the JWT's exp claim and proactively refreshes at 75% of remaining lifetime by calling the host's onTokenExpired callback. If refresh fails, the widget surfaces an auth:error event so the host can recover gracefully.

Events the host can listen for

Hosts subscribe via widget.on(event, handler) to react to user actions (rep selection), lifecycle moments (ready), or failure modes (auth or generic errors). Each subscription returns an unsubscribe function for clean teardown.

Event	When it fires
ready	Iframe loaded and auth handshake completed; widget is interactive.
user:select	A user clicked a rep in the directory.
auth:error	Token refresh failed after all retries.
error	An unrecoverable error occurred (network, invalid config, etc.).

Security model

• Tokens are delivered only via postMessage with locked target origins.
• The host validates event.origin and event.source before trusting any message from the iframe.
• The iframe is sandboxed with the minimum permissions it needs.
• The widget stores the JWT only in iframe memory — never in localStorage, cookies, or URLs.

postMessage protocol

For teams that can't use the SDK (native webviews, server-rendered pages with custom JS), RxVantage publishes the underlying postMessage protocol — message envelopes, types, directions, and required targetOrigin values — so a custom integration can replicate what the SDK does.

What the host gets vs. gives up

Host gets: drop-in functionality, automatic updates, no UI or compliance burden, secure token handling out of the box.

Host gives up: deep styling control, direct DOM access to widget internals, and a dependency on RxVantage's uptime and CSP policy.

Quickstart

npm install @rxvantage/api-widgets

import { RepDirectory } from '@rxvantage/api-widgets';

const token = await fetch('/api/rxvantage/token')
  .then(r => r.json())
  .then(d => d.token);

const widget = RepDirectory.init({
  container: '#rep-directory',
  token,
  onTokenExpired: () =>
    fetch('/api/rxvantage/token').then(r => r.json()).then(d => d.token),
  onUserSelect: user => console.log('Selected:', user.name),
});

// Clean up when done.
widget.destroy();

See the full integration guide for framework-specific examples (React, Vue 3, vanilla JS), the bare-iframe fallback, and the postMessage protocol reference.