~8 min read

Widgets & embedding

Turn your milestones into a live onboarding widget that sits inside your product. This guide covers building, branding, publishing, API keys, and embedding patterns.

Prerequisite: You need a source with milestones and lifecycles set up. See Milestones & lifecycles first.

Implementation steps

Build the widget from a source

Building generates the widget configuration from your milestones. It does not make the widget public yet.

Open the source detail page
Review your milestones and lifecycles
Click Build widget
Review the preview—it shows exactly what users will see

You can rebuild after changes. Publishing is a separate step.

Configure branding

Customize the widget's visual appearance to match your product.

Pick a color palette or use built-in gradients
Set brand name, welcome message, hub title, and subtitle
Choose light or dark theme

These settings control the wrapper around milestones—change them and rebuild without losing your onboarding structure.

Publish the widget

Publishing makes the widget available to load from your sites.

Click Publish on the source detail page
Confirm the source shows as published
Copy the embed snippet

Two-layer security: An API key at workspace level + published flag at source level. Both required for the widget to load.

Create an API key and allowed origins

Widgets authenticate using a workspace-scoped API key.

Go to workspace settings → API keys
Create a new key or copy an existing one
Add your product's domain to Allowed origins

The widget only loads from allowed origins—this protects you if someone copies your embed snippet.

Embed the widget

Add the script tag to your frontend, typically before the closing body tag.

embed.html

<script
  src="https://your-skene-domain.com/skene-milestones-widget.js"
  data-api-key="YOUR_API_KEY"
  data-source-id="YOUR_SOURCE_ID"
  data-position="bottom-right"
  data-theme="dark"
></script>

Configuration options

data-api-key — Required. Your workspace API key.
data-source-id — Required. The published source ID.
data-position — Optional. bottom-right, bottom-left, top-right, top-left.
data-theme — Optional. light or dark.

Placement patterns

The most effective placements are where users naturally look for guidance:

Floating widget

Bottom-right of your app shell

Inline checklist

Top of dashboard or home page

Contextual

On pricing or upgrade pages

Widget not appearing?

Check that the API key is correct and origin is allowed
Confirm the source is published, not just built
Verify data-source-id matches the source ID in Skene

For more issues, see Troubleshooting.

Product documentation