Usertour logo

Usertour v0.9.9: Introducing Embeds—Onboarding Inside Your App's Layout

Meet Usertour Embeds: inline cards, surveys, and multi-step guides inside your app's layout. v0.9.9 also improves small-screen layouts, button analytics, and SDK behavior.

Last updated on November 22, 20267 min read
Usertour v0.9.9: Introducing Embeds—Onboarding Inside Your App's Layout

An empty state is a useful place to help someone get started. A gated feature is a natural place to explain an upgrade. A newly updated section is a good place to introduce what changed.

Usertour v0.9.9 introduces Embeds, a new content type for these moments: cards that live inside your application's layout. An embed can hold a welcome message, an inline survey, or a small multi-step guide. Several can appear on the same page, each in the place where it is useful.

This release also keeps floating onboarding content within small screens, adds a clear result to usertour.start(), and improves runtime behavior across tooltips, checklists, launchers, and analytics.

Meet Embeds#

An embed attaches to a target on your page. You can place it at the top or bottom of a container, before or after an element, or over an element with cover placement.

That makes it useful for experiences such as:

  • Getting started in an empty state: explain the first action beside the area it will populate.
  • Feature discovery: introduce an update within the section where someone will use it.
  • Upgrade prompts: place a card on a gated feature with a next step.
  • Inline feedback: ask a question in the context of the work the user just completed.
  • Small guides: walk through several steps within one container.

Multiple embeds can show at once, including several on the same target. They keep a stable order and do not wait for another piece of content to finish.

Build a card that can do more than display text#

An embed can contain inline and hidden steps. Buttons can move to a named step, dismiss the card, start a flow, navigate to another page, or evaluate JavaScript. Question blocks work inside embed steps too.

For example, a getting-started card could introduce a task, move to a second step with a short question, then offer a button that starts a product tour. The card stays in its own container while the user moves through the steps.

The theme editor includes an Embed section for background, text color, padding, and the shared border, with a preview inside a small page layout. You can make the card blend into the surrounding interface or give it enough contrast to attract attention.

An optional close button appears in the top-right corner when dismissal is enabled.

Choose how the card appears#

Animate on appear is off by default. When enabled, an embed in the document flow expands to its height while fading in; a cover placement fades in over its target.

The animation runs once per appearance, rather than on each step change. It also respects visitors who request reduced motion. Duration and style are controlled by the theme.

Show it when it belongs#

An embed appears while the user matches its Show embed if… rules and its target is present and visible. It disappears when either stops being true. If your application re-renders the target, the embed follows the replacement element.

A hidden target does not start the embed, so it does not count as a view. Frequency settings—once by default, multiple, or unlimited—control whether a new session can start after the previous one ends.

Republishing updates a live embed in place. It stays on the current step unless that step was removed, in which case it returns to the first step. Updated button rules on the visible step take effect immediately.

Embed targets resolve on the page itself, like banner targets. They do not target elements inside iframes. The same-origin iframe targeting added in v0.9.8 continues to apply to tooltips, launchers, and element conditions.

Measure views, clicks, and dismissals#

Embed analytics show unique views, unique clickers, and dismissals for the selected date range. Multi-step embeds include a steps table, and a buttons table breaks down the buttons on each step.

Embeds also appear in sessions, session detail, the activity feed, user session history, and CSV exports. New events record when an embed starts, when a step is shown, and why an embed is dismissed. The new built-in button_clicked event records the step, button identifier, and button text.

Button tracking has a specific scope in this release: only embeds report button presses. Newly inserted editor buttons receive a cvid identifier across all content types, but buttons authored before this change have no such identifier and are not reported. The new embed events are not sent to CRM timelines.

This gives you a way to compare how many people saw an inline card with how many chose an action inside it.

Create and diagnose Embeds through API v2 and MCP#

Embeds are supported in API v2 and MCP. They can be read, written, validated, and analyzed, while diagnose_content and diagnose_user can explain their delivery behavior. The MCP authoring guide now includes an Embeds section.

For teams already building onboarding with AI assistants, that extends the available content types to experiences placed directly in the page. You can use an assistant to help author an embed, validate its configuration, and investigate why it is not appearing for a particular user.

See the Embeds guide for the authoring workflow.

Floating steps now fit small screens#

An authored step width should not push important content or controls outside a phone's screen. v0.9.9 adjusts modals, bubbles, tooltips, and Resource Center announcements to the available viewport.

Floating content keeps its authored width when it fits. On narrower screens, width is capped with 16 pixels of space on each side. Long content scrolls inside its frame instead of extending beyond the bottom of the screen.

Tooltips also account for the space available beside their target. An auto-aligned tooltip can move back over the target when neither side has enough room. Offsets are constrained so they cannot push the step outside the available space.

These changes apply automatically. A step that already fits keeps its size and position, and you do not need to create a separate mobile version to get the viewport limits.

A clearer result from usertour.start()#

usertour.start() now resolves with a boolean indicating whether the server started the content.

It returns true when the server starts it, and false when it cannot—for example, if the content is missing, unpublished, already seen once, or the server could not be reached. A call queued before the SDK bundle loads also receives the server's result.

If your integration used a rejected promise to mean “not started,” update it to check the returned value. A true result confirms the server started the content; it does not guarantee that a tooltip target is already visible or that the visitor completed the experience.

More predictable behavior across the SDK#

The SDK runtime suite now covers 143 listed behaviors across 388 tests. That work also fixed several interactions users encounter during normal onboarding:

  • A tooltip waiting for a missing target uses the theme's timeout, which defaults to three seconds.
  • Scrolling a target out of view hides its tooltip without ending the flow on a timeout. Scrolling back can reveal it again.
  • A checklist collapses when a flow actually appears, instead of collapsing while a tooltip is still searching for its target.
  • Hidden launchers no longer leave an invisible box that intercepts clicks beside the target.
  • Open widgets update their colors when a different theme variation starts matching.

Analytics also handle day boundaries more reliably around daylight-saving changes. API v2 rejects impossible calendar dates with a 400 response, and session details and exports now use the same one-based version and step numbers as the dashboard.

Upgrading to v0.9.9#

Usertour Cloud was already running this version when it was released. For self-hosted installations:

  • No database migration or new environment variable is required. The startup seed adds embed events and attributes to each project.
  • The served SDK bundle moves from 0.8.4 to 0.8.7. Pages receive it on their next load after the instance is upgraded. The usertour.js npm package remains at 0.0.26.
  • Embeds require SDK bundle 0.8.6 or later. Older bundles receive no embeds; their other content continues to work.
  • Review custom button_clicked events. This name is now reserved for the built-in event. Existing project definitions are retained with a warning during seeding.
  • Review API-authored steps. Inline and hidden steps no longer accept a step-level target; an embed's data.target determines placement.

Check integrations that consume the result of usertour.start(), and review any floating layouts that previously depended on overflowing the viewport. Rollback is a revert of the image; embed content remains in the database but is not delivered by the older build.

Read the full v0.9.9 release notes, follow the Embeds guide, or open Usertour Cloud to create an inline experience for your application.

Put this into practice

Build your first product tour with Usertour in minutes — free plan, no credit card, open source.

Related reading

More ideas from the Usertour blog.