Skip to Content
Publisher WidgetIntegration Guide

Integration Guide

Add the Publisher Widget to your site in three steps:

  1. Install or include the loader
  2. Generate an init token on your server
  3. Initialise the widget

Step 1 — Add the loader

npm install @palactix/publisher-widget
import { init } from '@palactix/publisher-widget';
 
document.getElementById('open-publisher')!.addEventListener('click', async () => {
  // Fetch a fresh init token from YOUR backend endpoint
  const { token } = await fetch('/api/publisher-token').then(r => r.json());
 
  const widget = init({
    token,
    appUrl: 'https://app.palactix.com',
    onReady: () => console.log('Widget ready'),
    onClose: () => console.log('Widget closed'),
  });
 
  widget.publish();
});

Step 2 — Generate an init token on your server

Init tokens must be generated server-side. Never call the Palactix API directly from the browser — your widget_secret would be exposed.

Call the Palactix API from your backend whenever a user is about to open the widget. The public token issuance endpoint is POST /widget/tokens and is authenticated using the widget credentials (Basic auth).

Example (high level):

POST https://api.palactix.com/widget/tokens
Authorization: Basic BASE64(widgetId:widgetSecret)
Content-Type: application/json
 
{
  "external_user_id": "usr_abc123",
  "ttl": 300,
  "meta": {
    "name": "Jane Doe",
    "email": "[email protected]"
  }
}

Response from the Palactix API contains init_token. Your server should extract that value and return a simple JSON object to your frontend, for example { "token": "<init_token>" }.

See Generating Init Tokens for language-specific server examples.

Step 3 — Initialise the widget

Pass the token you received from your server to the loader:

import { init } from '@palactix/publisher-widget';
 
document.getElementById('open-publisher')!.addEventListener('click', async () => {
  const { token } = await fetch('/api/publisher-token').then(r => r.json());
 
  const widget = init({
    token,
    appUrl: 'https://app.palactix.com',
    onReady: () => console.log('Widget ready'),
    onClose: () => console.log('Widget closed'),
    onPublished: (post) => console.log('Published', post),
  });
 
  widget.publish();
});

Auto-initialise via data attributes

If you prefer zero-JS integration the loader can auto-initialise elements marked with data-palactix-widget.

<div
  data-palactix-widget
  data-token="<token-from-server>"
  data-app-url="https://app.palactix.com"
></div>
 
<script src="https://widgets.palactix.com/publisher/v1/loader.min.js"></script>

When using data attributes the init token must be rendered server-side into the HTML. Make sure your page is not cached at a CDN layer or the token will not be usable when loaded by the browser.

Widget API reference

MethodDescription
init(config)Initialises the widget. Returns a PublisherWidget handle.
widget.publish(preFill?)Opens the publisher panel and optionally pre-fills caption/media.
widget.destroy()Closes and removes all DOM nodes. Revokes the widget session.

Config options:

OptionTypeRequiredDescription
tokenstring✓Short-lived signed token your server returns to the frontend. Pass this directly to init() as token.
appUrlstring—Override the publisher iframe URL (useful for local dev).
primarystring—CSS color hex used to theme the widget.
modestring—'modal' (default) or 'drawer'.
onReady() => void—Fired when the iframe is ready.
onClose() => void—Fired when the user dismisses the widget.

Allowed origins

Your widget will only load on domains you have explicitly whitelisted. Add origins in your developer portal under Widgets → Allowed Origins.

Example allowed origins:

https://yoursite.com
https://app.yoursite.com
http://localhost:3000
Last updated on
OverviewGenerating Init Tokens