Skip to content

Embed the Connection Widget

Use this guide when you need to place the Conflux configuration widget on an external merchant site — for example, inside a WooCommerce plugin settings page or a custom onboarding screen.

Prerequisites

  • A SystemConnection exists and has been verified.
  • A widget token (SystemConnectionToken with purpose = access) has been issued for the connection. In the plugin-initiated flow this token is returned by Conflux at the end of the /api/system-connections/register handshake — see Connection Flow. Store it securely; Conflux returns the plaintext value only once.

1. Load the widget script

Add this <script> tag anywhere on the page, before the custom element is used. Point src at the Conflux instance the connection belongs to:

<script src="https://your-conflux-domain.com/widget.js" defer></script>

The script registers the <conflux-config> web component. It has no external runtime dependencies and does not require a framework on the host page. It loads its font files (Inter) from the same Conflux instance, under /widget-assets/. Load the script directly from the Conflux instance with a classic <script src> as shown, because the font URLs are resolved relative to the script's own URL; a copied, self-hosted, inlined or type="module" script cannot find the fonts and the widget falls back to the system font.

If the host page sends a Content Security Policy, allow that origin for fonts, for example font-src https://your-conflux-domain.com. Without it the browser blocks the fonts and the widget falls back to the system font.

2. Place the element

Drop the <conflux-config> element where the configuration form should appear:

<conflux-config
    token="PLAIN_TOKEN_HERE"
    api-base="https://your-conflux-domain.com"
></conflux-config>

Replace PLAIN_TOKEN_HERE with the plaintext token issued for this connection. Replace https://your-conflux-domain.com with the base URL of your Conflux instance (no trailing slash, no path).

Props

Prop Required Description
token Yes The plaintext widget token for the connection. Conflux hashes it on receipt and looks up the connection.
api-base No Base URL of the Conflux instance (e.g. https://conflux.example.com). Defaults to an empty string, which means same-origin requests — only correct when the widget is served from the Conflux domain itself. Always set this when embedding on an external site.

What the widget does

On mount the widget calls GET /api/widget/configuration using the token as a Bearer credential. If the connection's plugin exposes a configuration schema, the widget renders a form. The merchant fills in the settings and clicks Save configuration, which sends a PATCH /api/widget/configuration request. Saved values are stored in system_connections.configuration.

If the plugin does not expose a configuration schema, the widget shows "No configuration available for this connection." — this is expected for plugins that have no user-configurable settings.

PHP example: rendering the element from a plugin

Inside a WooCommerce (or any PHP-based) plugin, you can output the element dynamically using the token your plugin received and stored during registration:

$token = get_option('conflux_widget_token');
$apiBase = 'https://your-conflux-domain.com';

printf(
    '<script src="%s/widget.js" defer></script><conflux-config token="%s" api-base="%s"></conflux-config>',
    esc_attr($apiBase),
    esc_attr($token),
    esc_attr($apiBase),
);

Never expose the token to unauthenticated users

The widget token grants read and write access to a connection's configuration. Render the element only on pages that require merchant authentication. Do not include the token in public HTML.

Troubleshooting

The widget shows "Failed to load configuration (HTTP 401)." The token is missing, empty, or does not match any stored hash. Confirm the plaintext token was saved correctly after the registration handshake.

The widget shows "Could not reach the Conflux server." A network or CORS error prevented the fetch. Confirm api-base is correct and that the Conflux instance allows cross-origin requests from the merchant domain.

The widget renders but shows "No configuration available for this connection." The plugin does not implement HasConnectionConfiguration. See Implement Connection Config to add configuration fields to the plugin.

The widget renders in the system font instead of Inter. The font files under /widget-assets/ could not be used. Open the browser's Network tab and check the status of the font request first. A 404 means the font files are missing from public/widget-assets/: the widgets were not built or deployed, or a cached older widget script asks for a hash that no longer exists. A 200 without an Access-Control-Allow-Origin header means the server does not send that header for /widget-assets/ (see ADR-0040). A Content Security Policy error means the host page's font-src does not allow the Conflux origin.

See also