Guidely user guide

This guide is for product managers, customer-success and support teams who create in-app experiences with Guidely, and for the developer who installs it. Developer references live in sdk.md and api.md; operators should read deployment.md or aws-deployment.md.

1. Concepts

A guide goes through Draft → Published → (Paused) → Archived. Drafts are never visible to end users. Publishing creates an immutable version per environment, and you can roll back to any earlier version.

2. Signing in and your workspace

• **Email (or username) and password**, **Continue with Google** or **Continue with GitHub**,

  whichever your administrator enabled. Each workspace can have its own sign-in link (/login?workspace=<slug>, in Settings → Sign-in) that offers only the methods that workspace allows and opens it after signing in.

• A workspace can require particular sign-in methods. If you signed in another way, the workspace

  shows a lock in the switcher and asks you to sign in again with an allowed method.

• The **workspace switcher** (top of the sidebar) lists your workspaces and projects. Create a new

  project from there.

• The **environment selector** (top bar) controls what every page shows: analytics, published

  status, install keys. Always check it before publishing.

• **Settings → Team** invites colleagues by email (copy the invite link), creates **logins**

  (email, optional username and password; you hand the details over) and manages roles. Logins you create belong to this workspace only: admins can reset their password, they can't join other workspaces, and removing one deletes it. Roles:

(Admins can let editors publish to Production in Settings → Privacy & data.)

The Roles and permissions table at the bottom of Settings → Team lists exactly what each role can do. Each member's Access button shows their own permissions; admins can switch individual permissions on or off for that person (for example, let a viewer edit audiences, or hide session replays from an editor, or let a writer edit articles but not publish them) without changing their role. The Invite and Create login dialogs have the same switches under Access, so someone can start with exactly the access they need. Managing members, sign-in and the workspace itself always follow the role, and only owners can adjust an admin's access.

3. Installing Guidely in your product (developer, ~10 minutes)

1. Open **Settings → Environments & Install** and copy the snippet for your framework (React,

   Next.js, Svelte, SvelteKit or a script tag). It already contains the environment's public key.

2. Add the provider / init call to your app, start it, and watch the environment card flip to

   SDK connected.

3. Call `identify(userId, traits, account)` after login so targeting and analytics know who the

   user is, and track("event_name") for things you want to trigger guides or complete checklist tasks with.

4. Optional: restrict **Allowed origins** per environment so only your domains can load the

   configuration.

The Setup wizard (help menu → Setup guide) walks through these steps and verifies each one.

Give important elements stable attributes (data-tour="primary-action", id="invite-button"). Guides anchored to those keep working when your CSS or layout changes.

4. Creating a guide

Guides → New guide. Pick a template (onboarding tour, feature discovery, setup wizard, form helper, workflow walkthrough, announcement, contextual tooltip, product update banner, onboarding checklist, NPS survey) or start from scratch, name it, and the editor opens.

The editor

• **Left – Steps**: the ordered list of steps. Drag to reorder, add with the **+** button (choose a

  step type), duplicate or delete from the row menu. A red dot means the step has a problem that blocks publishing (hover to read it). Below the list, Guide settings opens the Trigger, Targeting, Frequency and Appearance panels.

• **Center – Preview**: a realistic page showing the selected step. Switch desktop / tablet /

  mobile, click Next/Back to walk through the flow, press Reset to start over. Preview in app shows the current draft inside your real application (see §5).

• **Right – Properties** for the selected step:
  • Content: title, rich-text body (bold, italic, links, lists, headings, images), image URL.
  • **Buttons**: up to six buttons with an action (Next, Back, Dismiss, Complete, Skip, Open URL,

    Start another guide, Fire an event, Open Resource Center) and a style.

  • **Target** (tooltip, popover, spotlight, hotspot): the selectors that find the element.

    Use Pick element in app to capture one visually, or type a CSS selector / data-* attribute / id. Test selector shows how many elements match the preview page. Set how long to wait for the element and what to do if it never appears (skip the step, show as a modal, end the guide, or keep waiting).

  • Placement: side and alignment relative to the target, offset, width.
  • **Behaviour**: overlay, progress indicator, close button, click-outside dismissal, spotlight

    padding, banner/slideout position, hotspot size and pulse.

  • **Advance**: go to the next step on a button click, when the user clicks a particular element,

    when an element becomes visible, after an event, or after a delay.

  • Branching: "when these rules match, jump to step X".
  • **URL**: for multi-page flows, the page this step lives on. The guide waits until the user

    navigates there.

Changes autosave (status in the toolbar). ⌘Z / ⌘⇧Z undo and redo.

Checklists and surveys

Checklists have tasks instead of steps. Each task completes manually, when an event fires (contact_created), when a guide is completed, when a URL is visited, or when an element is clicked; it can also launch a guide or open a URL when clicked. Configure the launcher label, position, ordering and the completion message in Checklist settings.

Surveys have questions: NPS, CSAT, thumbs up/down, single or multiple choice, free text and rating scales, with optional follow-up questions shown only when a previous answer matches (for example "What could we do better?" when NPS ≤ 6). Set the thank-you message, position and an active date window in Survey settings.

5. Picking elements and previewing in your app

1. Click Pick element in app on a step (or Preview in app in the toolbar).
2. Enter the URL of a page in your application where the SDK is installed with this

   environment's key, and confirm. Your app opens in a new window in authoring mode (a dark bar at the top).

3. Hover to highlight elements and click the one you want. The editor fills in robust selectors and

   a text snapshot. Click as many elements as you need; press Done when finished.

4. Preview step / Preview guide renders the draft in your app without publishing anything.

Allow pop-ups for the Guidely dashboard if the window does not open. The page must have the SDK installed; otherwise use manual selectors and the built-in preview.

Recording a how-to

How-tos (left navigation) are step-by-step documents with screenshots. Press Record a how-to, pick a page of your app, and click through the task in the tab that opens; Guidely writes each step ("Click “New contact”", "Type “Acme” into “Company”") and takes the screenshot. Press Done in your app, then polish the wording, blur anything private, share a link or embed, export a PDF, Markdown or HTML file, or turn it into an interactive tour or a help article. Details in how-tos.md.

6. Who sees a guide, and when

Trigger (Guide settings): on page load, when the URL matches a pattern (/contacts/*), on a custom event, when an element is clicked or becomes visible, after a delay, after another guide completes, when the user enters an audience, or only when your code calls startGuide("key").

Targeting: rules with AND / OR groups over user attributes, account attributes, role, plan, URL, query parameters, device, browser, first visit vs returning, events seen, guides completed or dismissed, checklists completed, audience membership, date/time, a percentage rollout, environment and locale. Rules marked "evaluated on server" (audiences, history) use data Guidely stores; everything else is evaluated in the browser from the traits your app passed to identify.

Frequency: once per user, once per session, every time, or every N hours; maximum impressions; cooldown after dismissal; re-show after dismissal; priority when several guides qualify at once (lower number wins); guides that must never appear together.

Only one flow, modal or survey is shown at a time. Banners, checklists, hotspots and the Resource Center can coexist with it.

Audiences (left navigation) are reusable rule sets. Build one once, estimate its size with Preview size, and reference it from any guide's targeting. Static audiences are explicit lists of user ids you manage by hand.

7. Publishing, pausing, rolling back

1. Click Validate to see blocking problems (missing targets, empty checklists, invalid URLs).
2. Click **Publish**, choose the environment, optionally add release notes, review the diff against

   the last version, and confirm. The guide is live within a minute for new page loads (the SDK refreshes its configuration every five minutes and on every page load).

3. The guide detail page shows the live version per environment. From there (or the editor menu):

   Pause stops showing it without losing the version; Resume brings it back; Unpublish removes it from that environment; Roll back switches the environment to an earlier version; Restore to draft copies an old version back into the editor.

Every publish, rollback and pause is recorded in the guide's History tab and the workspace audit log (Settings → Audit log). Drafts never affect live users until you publish.

8. Resource Center

Resource Center (left navigation) is the in-app help panel. Create collections and articles (rich text or external links), mark articles published, add FAQs and external links, choose recommended guides and checklists, set the launcher position and label, and preview the widget. Click Publish resource center to push it to every environment. End users search it inside your app.

Writing articles. The body editor has headings, bold/italic/underline/strikethrough, inline code and code blocks, lists, quotes, dividers and links. To add media:

• **Images**: the image button, or paste or drag an image into the article (PNG, JPEG, GIF or

  WebP, up to 10 MB). Select an image and use the T button to give it alt text.

• **Videos**: the video button uploads an MP4 or WebM file (up to 200 MB); it plays with standard

  controls in the web widget.

• YouTube, Vimeo, Loom and Wistia: the embed button, or paste the video's link on its own line.
• **PDFs**: the PDF button, or paste or drag a PDF into the article (up to 50 MB). Readers don't

  download anything: the article shows the document's pages inline, which they swipe through (or page with the arrows), and tapping a page opens a full-screen reader with a link to the original PDF. The editor turns each page into an image while it uploads (the first 40 pages; longer PDFs say so, and readers open the PDF for the rest). Password-protected or damaged PDFs are added as a link instead.

Uploaded files count towards a 5 GB allowance per project (shown under the editor). Uploads that no article, guide or published resource center uses are deleted after 7 days, and all of them go with the project. They are public to anyone with the link (the widget on your site loads them without signing in), so don't upload anything confidential. The iOS and Android SDKs show images and PDF pages inline (with the same full-screen reader) and open videos in the browser or the video app. Scout doesn't read the text inside PDFs yet: summarise the key points in the article text if Scout should answer from them.

Nested collections. Use a collection's ⋯ menu to Add sub-collection, Move to another collection, or reorder it. Collections nest up to three levels; the widget lists them as "Billing › Invoices". Deleting a collection moves its articles and sub-collections up a level.

Audience targeting. Each article has a Shown to setting, and each collection an Audiences… item: pick one or more audiences (see section 6) to list it only for their members (a collection's audiences apply to everything inside it). Use Preview as above the live preview to check what a given audience sees. Targeting changes what the widget lists; it is not access control. Article content can still be read by anyone with your public SDK key, so keep confidential information out of articles. SDKs older than 0.5.0 ignore targeting and nesting and list every published article.

Scout messenger and Inbox

Turn on Scout (left navigation) to replace the help launcher with a chat messenger: end users ask questions, Scout answers from your published articles (with links) and hands off to your team when it can't help. Use Import articles on the Resource Center page to turn Markdown, PDF or Word files into draft articles, and the Scout Playground to test answers before going live. Handed-off conversations land in Inbox, where editors reply, assign and close them. Details: Scout.

9. Measuring

• **Overview**: active guides, unique users reached, guide starts and completions, completion and

  abandonment rate, checklist completion, survey response rate, with a comparison to the previous period, the best-performing guides, recent publishing activity and recent events. Change the date range and environment at the top.

• **Guide → Analytics**: the funnel (viewed → started → completed/dismissed), step-by-step drop-off,

  a daily chart, and audience comparison. Surveys show NPS and answer distributions; checklists show per-task completion. Export CSV on each report.

• Analytics: a sortable table of every guide's performance.
• **Events**: every event the SDK sent (guide lifecycle, checklist, survey, page views, your custom

  events) with filters, live refresh and CSV export.

• **Users**: end-user profiles with traits, accounts, audiences, guide history, checklist progress,

  survey answers, an event timeline, their recordings and the errors they hit. Admins can delete a user's data on request.

• **Insights**: conversion funnels (ordered steps within a time window) and retention cohorts over

  any event; save the ones you check often.

• **Pages**: page views, visitors, time on page, scroll depth, entries, exits and bounce rate for

  every page, with the most-clicked elements and errors per page. Heatmap shows where people click, where they move the mouse and how far they scroll, drawn over the page itself.

• **Replays**: watch recordings of real sessions with page views, clicks, errors, network requests

  and guide events on the timeline. Search recordings by what they logged to the console and jump straight to that moment. Alerts emails people or posts to Slack when a recording matches conditions such as rage clicks, errors, failed requests or a console message, and can open a Linear or Jira ticket for each matching recording. From a guide's analytics, Watch replays shows sessions that saw the guide.

• **Errors**: JavaScript errors grouped into issues with stack traces, affected users and a link to

  the replay. Resolve or ignore issues; a resolved issue that comes back is marked Regressed. Alerts emails people or posts to Slack when a new error appears, a resolved one comes back, or an error spikes, and can open a Linear or Jira ticket for each new issue. Upload source maps from your build (Settings → Source maps) to see original file names and code instead of minified stacks.

Page views, clicks and errors are captured automatically; session replay is off until an admin turns it on in Settings → Privacy & data. See product-analytics.md.

Metric definitions are in analytics.md. All numbers come from stored events; the seeded demo workspace is marked Demo data.

10. Settings

• General: project name and description; delete project.
• **Environments & Install**: public keys (rotate if leaked), allowed origins, SDK status, install

  snippets.

• **Branding**: colors, radius and font used by every guide, with a live preview. Individual guides

  can override these in Appearance. Match your website takes your site's address and fills the form with its brand color, background and text colors, font, corner radius, logo and name; the colors it found are shown as swatches you can click to use as the primary instead. Nothing is saved until you click Save theme. It reads the page's HTML and stylesheets without running JavaScript, so sites styled entirely by scripts may come back with little or nothing.

• **Privacy & data**: analytics on/off, URL collection, masked DOM selectors (never captured during

  authoring, masked in recordings), session timeout, event retention, whether editors may publish to Production, autocapture (page views, page leave, clicks, rage clicks, click and mouse-movement heatmaps), error tracking, and session replay (on/off, sample rate, console and network recording, mask all text, block selectors, recording retention).

• Team: members, roles, invitations, and workspace logins (create, reset password, delete).
• **Sign-in** (workspace-wide): which methods open the workspace (email and password, GitHub,

  Google), GitHub organizations and Google Workspace domains whose people join automatically, the role they get, and the workspace's sign-in link. You can only add organizations and domains you belong to, and you can't turn off the method you are signed in with.

• **Issue trackers** (workspace-wide, admins): connect **Linear** (personal API key + team) or

  Jira Cloud (site, account email, API token + project and issue type). Keys are stored encrypted and never shown again. Editors then get Create ticket on an error issue, a replay and an Inbox conversation: it opens a pre-filled ticket (stack trace, affected users, console errors or the conversation transcript, with links back to Guidely) that can be edited before it's created, and the ticket's key is shown on the page afterwards. Error and replay alert rules can also open tickets automatically (Create a ticket in the rule): one per error issue, or one per matching recording.

• Audit log, Account (name, username, password, active sessions with how each signed in, theme).

Platform admin. Operators of a Guidely instance can be made platform admins. They get a Platform admin entry in the account menu that opens /admin, where they can search every workspace, create one for an existing user, rename or delete it, manage its members, join it to open its projects, and grant admin access to others.

11. Tips

• Keep tours to three or four steps; put the "why" in the first step and let people skip.
• Target stable attributes, not generated class names.
• Test every guide in Development with a test user, then publish to Production.
• Use once frequency for onboarding, interval for surveys, every_time only for manual guides.
• Use checklists for multi-session onboarding; they persist across devices because progress is

  stored on the server.

• Watch step drop-off: a step with high drop-off usually points at a confusing instruction or a

  target that is not always on screen.