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 (SystemConnectionAccessToken) 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.

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.

See also