HTML Custom Element Embed

Embed a RuleCMS widget in any HTML page with a script tag and <rulecms-widget> — WordPress, Angular, PHP, and more. No React host required.

What this is for

Use this when your site is not a React app — for example WordPress, plain HTML, PHP, Angular, Rails, Webflow custom code, or any CMS that can load a script tag — and you want to show a RuleCMS widget you already composed and published.

You load one JavaScript file from RuleCMS, drop a <rulecms-widget> tag where the content should appear, and pass your token and published key. RuleCMS fetches the config and renders text, images, and video for you.

You need three things: (1) the embed script URL from RuleCMS, (2) a client token for Staging, Production, or Development, and (3) the widget's published key (or draft widget key when using a dev. token).

A public teaching page with the same two tags is the HTML sample lab. Live demo: use-rulecms-example-html-project.vercel.app.

When to use this vs the React SDK

	HTML custom element	`@rulecms/widget-react`
Best for	WordPress, PHP, Angular, static HTML, any non-React host	React, Next.js, Remix, CRA
Install	`<script src="…">` — no npm	`npm install @rulecms/widget-react`
Host needs React?	No (bundled inside the script)	Yes
Custom component libraries	Default text / image / video only (v0.3.2)	Full library registration — see Component Libraries

If you already have a React app, prefer the Development Integration / React SDK path. Use this tutorial when the host page is plain HTML (or another framework that can host a custom element).

Prerequisites

A RuleCMS team, app, and environment (Development, Staging, or Production).
A widget composed with the built-in components (text, image, video).
For Staging / Production: the widget is published and you have its published key.
An enabled client token for that same app + environment (see Projects, Environments & Tokens).
Permission to add a script tag and custom HTML to the page where the widget should appear.

Step 1 — Publish (Staging / Production) or use Development

Staging or Production

Open the widget in RuleCMS and publish to Staging or Production.
On the published widget page, open the Integration tab.
Copy the PublishedKey. It looks like {environmentId}---widget-….
Copy (or create) an enabled app token for that environment. It must not start with dev..

Development (live drafts, no publish)

Create or regenerate a Development token that starts with dev..
Use the draft widget key itself (for example widget-9a31b6c8-…) — not a published key.
Details: Development Integration.

Step 2 — Load the RuleCMS embed script

Add this script once on the page (or in your site-wide footer). Prefer the versioned URL in production so your site does not pick up breaking changes unexpectedly:

<!-- Recommended: pin a version -->
<script src="https://rulecms.com/embed/widget-custom-element@0.3.2/widget-custom-element.iife.js"></script>

<!-- Optional: always track the newest release (short cache) -->
<!-- <script src="https://rulecms.com/embed/widget-custom-element/latest/widget-custom-element.iife.js"></script> -->

Current shipped version: 0.3.2. Loading the script registers the <rulecms-widget> custom element automatically.

Content Security Policy: If your site uses CSP, allow scripts from https://rulecms.com (and your own origin). The widget also calls https://widget-cache.rulecms.com (published) or https://rulecms.com (Development) over fetch, and may load images/videos from your media host (Cloudinary).

Step 3 — Place the custom element

Put the tag wherever the widget should appear. Replace the placeholders with your real values:

<rulecms-widget
  token="YOUR_CLIENT_TOKEN"
  published-key="ENVIRONMENT_ID---widget-…"
></rulecms-widget>

Attributes

Attribute	Required	Description
`token`	Yes	Client token from RuleCMS. Use a `dev.` token only for Development drafts.
`published-key`	Yes	Staging/Production published key, or the draft `widget-…` key with a `dev.` token.
`endpoint`	No	Optional API origin override for tests. Omit in production — the script chooses the correct host from the token.

Complete minimal page

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>RuleCMS widget</title>
    <script src="https://rulecms.com/embed/widget-custom-element@0.3.2/widget-custom-element.iife.js"></script>
  </head>
  <body>
    <h1>Welcome</h1>

    <rulecms-widget
      token="YOUR_CLIENT_TOKEN"
      published-key="ENVIRONMENT_ID---widget-…"
    ></rulecms-widget>
  </body>
</html>

Step 4 — Verify

Open the page in a browser.
You should see the widget content (or a short loading state, then the content).
If something fails, open DevTools → Network and confirm:
- The embed script returns 200 from rulecms.com/embed/…
- A request to /api/v1/c/widget/get (published) or /api/v1/c/dev/widget/get (Development) succeeds

WordPress

Typical approach without a dedicated plugin yet:

In Appearance → Theme File Editor (or your child theme / a site-wide header plugin), enqueue the script, or paste the <script src=…> in your theme footer / a "Header and Footer Scripts" plugin.
In a page or post, add a Custom HTML block (Gutenberg) or a shortcode that outputs the <rulecms-widget> tag with your token and published key.
Prefer storing the token in wp-config / environment and printing it from PHP rather than hard-coding it in every post.

<?php
// Example theme / plugin output (escape your values!)
$token = esc_attr( getenv('RULECMS_TOKEN') ?: '' );
$key   = esc_attr( 'ENVIRONMENT_ID---widget-…' );
?>
<script src="https://rulecms.com/embed/widget-custom-element@0.3.2/widget-custom-element.iife.js"></script>
<rulecms-widget token="<?php echo $token; ?>" published-key="<?php echo $key; ?>"></rulecms-widget>

Angular (or other SPA shells)

Add the script in angular.json scripts / index.html, then place the element in a template. Tell Angular to leave the tag alone:

<!-- app.component.html -->
<rulecms-widget
  token="YOUR_CLIENT_TOKEN"
  published-key="ENVIRONMENT_ID---widget-…"
></rulecms-widget>

If the framework strips unknown elements, register CUSTOM_ELEMENTS_SCHEMA on the declaring NgModule (Angular), or use the programmatic API below.

Optional: mount with JavaScript

After the script loads, window.RuleCMS exposes helpers:

<div id="hero-slot"></div>
<script src="https://rulecms.com/embed/widget-custom-element@0.3.2/widget-custom-element.iife.js"></script>
<script>
  RuleCMS.mount(document.getElementById('hero-slot'), {
    token: 'YOUR_CLIENT_TOKEN',
    publishedKey: 'ENVIRONMENT_ID---widget-…',
    // endpoint: 'https://rulecms.com', // only for tests
  });

  // Later:
  // RuleCMS.unmount(document.getElementById('hero-slot'));
</script>

How Staging / Production vs Development routing works

	Staging / Production	Development
Token	No prefix	Starts with `dev.`
`published-key` value	`{envId}---widget-…`	Draft key `widget-…`
API host (automatic)	`https://widget-cache.rulecms.com`	`https://rulecms.com`
Caching	Cached until you republish	Always fresh (no publish)

You do not set the API host yourself unless you are writing automated tests against a non-production origin.

Security notes

Treat client tokens like passwords. Prefer injecting them from a server template / secret store, not committing them to a public git repo.
Anyone who can view your page source can see the token. Scope tokens per environment and rotate them if they leak. Use Staging tokens on Staging sites; Production tokens only where needed.
The embed script is served with CORS enabled so customer sites can load it cross-origin from https://rulecms.com.

Troubleshooting

Symptom	Likely cause / fix
Blank area / "set both token and published-key"	Missing attributes, or the script ran before attributes were set. Confirm both attributes are non-empty.
Error loading widget / 401	Wrong or disabled token, or token environment does not match the published key's environment. Regenerate/copy from the Integration tab.
404 Widget not found	Wrong published key, unpublished widget, or using a draft key with a non-`dev.` token (or the reverse).
Script 404	Typo in the URL, or the pinned version is not deployed yet. Try the `/latest/` URL temporarily, then pin the version from the Integration tab.
CSP blocked	Allow `script-src` / `connect-src` for `https://rulecms.com` and `https://widget-cache.rulecms.com`, plus your media CDN if images/videos fail.
Custom team components missing	The HTML embed ships the default text / image / video library. For custom libraries, use `@rulecms/widget-react` in a React host (see Component Libraries).
Custom slot shows a dashed box	The HTML embed cannot receive host React components. Register them with `mounts` on `@rulecms/widget-react` instead (see Mount Your Own Components).
Staging content looks stale	Published path is cached until republish. Publish again after edits, or use a `dev.` token + draft key for live preview.

Related docs

Publishing
Projects, Environments & Tokens
Development Integration (React + live drafts)
API Reference (raw HTTP fetch)
Mount Your Own Components (React host only — the script embed cannot fill a Custom slot)
Component Libraries
RuleCMS Components (text, image, video)