HTML Custom Element Embed

What you can do

You already published Maya's homepage hero. Her marketing site is WordPress — or a plain HTML page — not Next.js. This page is how that snapshot lands there: a script tag and <rulecms-widget> with a token and a published key.

Two everyday jobs:

• Put the published hero on her WordPress homepage. Open the Integration tab on the published widget, pin the versioned script, and drop the custom element where the hero should appear.
• Preview the Development draft the same way. Same two attributes — a dev. token and the draft widget-… key — from the Integrate tab. That walkthrough lives on Development Integration.
• Let a ruleset pick which hero shows. Same script. Swap published-key for ruleset-published-key and put the visitor's facts in a params JSON attribute. The resolve walkthrough lives on Resolve from your app.

She can use the ten built-in cards — Text, Image, Video, Icon, Button, Divider, Embed, List, Accordion, Custom. A Custom slot still renders as a dashed box here. This embed cannot receive mounts. A team library still needs @rulecms/widget-react in a React host.

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

How it thinks

The script registers <rulecms-widget>. The token chooses the host. You do not set an API origin yourself.

A Staging or Production token — no dev. prefix — plus a published key {envId}---widget-… loads the snapshot from https://widget-cache.rulecms.com. That response is cached until she republishes. A dev. token plus a draft widget-… key loads the live composer from https://rulecms.com. There is no publish step on that path.

Here is the case that surprises people. Maya pastes a Production published key next to a dev. token, or a draft widget-… key next to a Production token. The request goes to the wrong host. Pair them. The Default Widget is Production-only. Promote copies the draft to the next environment; it does not publish. Copy To is only for extra environments she named herself.

If her site is already React, prefer the Development Integration / React SDK path. Use this page when the host is not a React app.

The element is light DOM, not a shadow tree. Host CSS — her WordPress theme, her fonts, her variables — can reach the widget. This widget's catalogs travel on the same GET as the React embed.

Omit endpoint except in tests. The script chooses the host from the token. Pin the versioned script in production. The /latest/ URL is optional and caches for a few minutes.

Put Maya's published hero on the page

You do this on the published widget page in Staging or Production. The tab is labeled Integration, not Integrate. If the hero still lives only in Development, promote the draft and publish first — then come back here.

1. Open the organization → team → project → environment where she published the hero. Staging is the QA stop. Production is the live marketing site.
2. Open Maya's homepage hero — the published widget, not the composer.
3. Open the Integration tab.
4. Copy the PublishedKey. It looks like {environmentId}---widget-….
5. Copy (or create) an enabled client token for that same environment. It must not start with dev.. Tokens live on Projects, Environments & Tokens.
6. On her page, pin the versioned script once — a site-wide footer is fine. Current shipped version: 0.4.0.

<!-- Recommended: pin a version -->
<script src="https://rulecms.com/embed/widget-custom-element@0.4.0/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> -->

7. Place the custom element where the hero should appear. The Integration tab already has this snippet with her published key filled in.

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

8. Open the page. You should see the hero — or a short loading state, then the hero. That is a safe stop.

A complete plain HTML page looks like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Homepage</title>
    <script src="https://rulecms.com/embed/widget-custom-element@0.4.0/widget-custom-element.iife.js"></script>
  </head>
  <body>
    <rulecms-widget
      token="YOUR_STAGING_OR_PRODUCTION_TOKEN"
      published-key="ENVIRONMENT_ID---widget-…"
    ></rulecms-widget>
  </body>
</html>

WordPress enqueue, Angular, and RuleCMS.mount live on Hosts and troubleshooting.

When a ruleset should pick the hero, keep the same script and token. Use the ruleset published key from View published and send the facts as JSON. Do not set both keys.

<rulecms-widget
  token="YOUR_STAGING_OR_PRODUCTION_TOKEN"
  ruleset-published-key="ENVIRONMENT_ID---ruleset-…"
  params='{"locale":"de-DE","user":{"plan":"pro"}}'
></rulecms-widget>

Needs 0.4.0 or later. The same pair works on RuleCMS.mount. Full resolve story — Development draft, anonId, fallback — is on Resolve from your app.

What to read next

This page is the story and the first two tags. WordPress, other hosts, and what a blank embed usually means live on the page below.

• Hosts and troubleshooting — WordPress Custom HTML, Angular CUSTOM_ELEMENTS_SCHEMA, RuleCMS.mount, CSP, tokens in page source, and the troubleshooting table.
• Development Integration — The same two attributes from the Integrate tab: a dev. token and the draft widget-… key. No publish step.
• Publishing — How the hero became the snapshot a Staging or Production token fetches.
• Projects, Environments & Tokens — Copy the token. Pair a Staging or Production token with the published key.
• API Reference — Fetch the same snapshot yourself. Same GET fields; this page renders them.
• Mount Your Own Components — A Custom slot that should render a component from her app. This embed cannot. Use @rulecms/widget-react.
• Component Libraries — A first-class palette card. Needs a React host that maps the Library ID.
• Widget Edit Links — The R badge on a published HTML embed. Not on a Development draft.
• Resolve from your app — ruleset-published-key and params on this embed, or the React helper, or a raw POST.

How this fits

This page does not replace the React SDK. It is how Maya puts a published widget on a page that is not React. Widgets is how she creates the hero. Publishing is how the site gets a snapshot. Tokens live on Projects, Environments & Tokens.

The Default Widget is in Production. She published this hero. Promote copies the draft; it does not publish. When she wants the live draft instead, Development Integration is the Integrate tab — a dev. token and the draft widget-… key on the same two attributes.