Guide authoring, targeting, and publishing

Guide kinds

flow (multi-step tour), modal, tooltip, banner, announcement, checklist, survey. All kinds share the same editor shell, targeting, triggers, frequency controls, publishing pipeline and analytics.

Step types

modal, tooltip, popover, spotlight (overlay with a cut-out), hotspot (pulsing dot that opens a tooltip), banner, slideout, custom (sanitized HTML, no chrome). Every step has title, rich-text body, image, buttons (next, back, dismiss, complete, skip, url, start_guide, event, open_resource_center), placement/offset/width, overlay, progress, close button, auto-advance (button, element_click, element_visible, event, delay), optional URL for multi-page flows, branches (rule → jump to step), and step-level targeting.

Platforms

Each guide lists the platforms that receive it (Trigger → Platforms): Web, iOS and Android (React Native apps count as iOS or Android). Guides created before mobile support are web-only. In mobile apps, URL patterns, URL triggers, multi-page steps and URL-visited tasks match the screen path /<ScreenName> reported by the app. See mobile.md.

Targets and selectors

A target is an ordered list of strategies: guidely-id (the cross-platform id: data-guidely-id on the web, GuidelyTarget / guidelyTarget() in mobile apps), id, data-attr (data-testid, data-tour, …), aria, css, text, xpath. Mobile apps resolve guidely-id and id strategies (and CSS selectors naming a single id). The runtime uses the first strategy resolving to exactly one visible element, waits up to waitMs (MutationObserver + polling) and then applies fallback: skip the step, show_as_modal, end_guide, or wait. Prefer stable attributes (data-tour="primary-action") over generated class names; the editor warns when a selector looks fragile or matched text has changed since it was picked.

Picking elements in your app ("Preview in app")

1. Open a guide in the editor and click Pick element on a step (or Preview in app).
2. Enter your application's URL and environment. Guidely creates a short-lived authoring session and

   opens the app in a new window with ?guidely_authoring=<token>.

3. The installed SDK verifies the token with the public API, enters authoring mode (toolbar + hover

   outlines), and sends each click back to the editor (postMessage to the dashboard origin, plus the authoring-session API as a fallback).

4. The editor fills in the selectors and text snapshot; **Preview in app** renders the current draft

   step or the whole draft guide in your app without publishing.

This works cross-origin and with authenticated apps because the SDK runs inside your page; nothing is loaded in an iframe. Requirements: the SDK must be installed with the same environment key, the dashboard origin must be reachable from the browser, and pop-ups must be allowed for the dashboard. Without the SDK installed, use the built-in simulated preview and manual selectors.

Targeting rules

Rules are AND/OR trees with negation. Fields: user/account attributes (as passed to identify), role, plan, URL path/full/query, device type/browser/OS, first visit/returning, custom events seen in the session, guide completed/dismissed/seen, checklist completed, audience membership, date/time, percentage rollout (deterministic per user), environment, locale. Operators: equals, not equals, contains, does not contain, starts/ends with, exists, gt/gte/lt/lte, in/not in, regex (≤200 chars, invalid patterns never match), before/after, is true/false.

Where rules run: URL, device, attribute, event, time and rollout rules run in the SDK. Audience membership, guide history and checklist completion come from the server at identify() time; the browser only receives the resulting IDs, never audience definitions.

Triggers and frequency

Triggers: page load, URL match, custom event, element click, element visible, manual (startGuide), delay, after another guide completes, when a user enters a segment. Frequency: once per user, once per session, every time, repeat every N hours, maximum impressions, cooldown after dismissal, priority (lower wins), mutual exclusion lists, re-show after dismissal. Only one flow/modal/tooltip guide is active at a time; banners, checklists, hotspots and the resource center may coexist. Remaining eligible guides are queued and shown when the active one ends.

Publishing

• Draft changes autosave and are never shown to end users.
• Validate before publishing; errors (missing targets, empty checklists, invalid URLs) block.
• **Publish** snapshots the draft into an immutable version and points the chosen environment at it.

  Publishing the same draft to several environments reuses the version.

• **Pause / Resume / Unpublish** per environment; **Roll back** to any earlier version; **Restore to

  draft** copies a version back into the draft.

• Every publish, rollback, pause and unpublish is recorded in the guide history and the workspace

  audit log, and bumps the environment's configVersion so SDK caches refresh (ETag). SDKs that are offline keep the last good configuration until they can refresh.

• Permissions: editors publish to development/staging; production needs an admin unless the project

  allows editors (Settings → Privacy & data).