# Tugboat — Full Documentation

> Tugboat is an embeddable beta-feedback widget for developer and product teams. A floating, draggable JavaScript button embeds into any web app; testers use it to send annotated screenshots, screen recordings with voice narration, voice notes and text notes — each carrying console/network logs, environment metadata and a session replay automatically. Teams triage feedback in a dashboard (organized per project = client deployment), publish a two-way "What's New" changelog and a votable roadmap back into the widget, target announcements to user cohorts, and push feedback into Jira.

---

## Getting started

Tugboat is a floating feedback button you embed in your web app. Testers tap it to send screenshots, screen recordings, voice notes and text — with technical context attached automatically.

1. Create a project — in the dashboard, Projects → New project. Each project gets a unique project_key (looks like `pk_...`). Use one project per app or client deployment.

2. Embed the widget — drop this one line before your closing </body> tag:

    <script src="https://tugboatapp.com/widget.js" data-project-key="pk_your_key"></script>

   Works with React, Vue, Angular, Svelte, Next.js and plain HTML — any web app, plus mobile web and PWAs. No npm install.

3. Collect feedback — a draggable button appears (bottom-right by default). Testers click it, pick a capture type, and feedback lands in your dashboard tagged by project. They can also press Ctrl/⌘ + Shift + K to open it instantly.

Lightweight: the core widget is ~22KB gzipped and renders entirely inside its own Shadow DOM, so its styles never leak into your app and your CSS can't break it. Session replay (rrweb, ~119KB) only loads for projects on a plan with replay enabled.

### Install with AI

Paste this prompt into Cursor, Copilot, Claude or ChatGPT:

    Install the Tugboat feedback widget into my web app.
    1. Add this before </body> (any framework, no npm install):
       <script src="https://tugboatapp.com/widget.js" data-project-key="pk_your_key"></script>
       Replace pk_your_key with my project key from the Tugboat dashboard (Projects → Settings).
    Optional:
    - Keyboard shortcut: data-hotkey="mod+shift+k" (mod = Ctrl/⌘); "none" to disable.
    - Manual trigger: set project to "manual" mode, call Tugboat.open() from my UI.
    - Audience targeting: Tugboat.identify({ plan, role, segments }) or window.tugboatUser before load.
    - Privacy: replays auto-redact PII; mark regions with data-tugboat-block or data-tugboat-mask.

---

## Keyboard shortcut

Testers and teammates can open Tugboat instantly without hunting for the button. Default: Ctrl + Shift + K (Windows/Linux) or ⌘ + Shift + K (Mac). Works even while focused in a form field. Press Esc to close.

- Customize per project in Settings → Keyboard shortcut (toggle on/off, record a custom combo).
- Or pin it per-embed with a data-hotkey attribute on the script tag: use `mod` for Ctrl/⌘, combined with `shift`, `alt` and a key, e.g. `data-hotkey="ctrl+shift+f"`. Set `data-hotkey="none"` to turn it off.

---

## Sentiment ratings

Every feedback form includes an optional emoji sentiment scale — 😠 🙁 😐 🙂 😍 (rating 1–5) — so testers tell you how they feel in one tap, not just what they typed. It becomes a lightweight NPS-style signal. Shown on the text-note form and after any screenshot/recording/voice capture. The chosen sentiment appears on the feedback row and detail in the dashboard. Available on every plan; no setup.

---

## Capture types

- Screenshot — captures the screen, opens an annotation editor (box/arrow/pen) so the tester marks the issue, and allows an optional attached voice note. The widget hides itself during capture so it never appears in the image.
- Screen recording — records the screen with microphone narration mixed in, up to the plan's limit. The browser's share dialog lets the tester pick the current tab, another tab, a window, or the whole screen.
- Voice note — a quick audio explanation.
- Text note — written context.

Recording limits by plan: Solo 30s · Team 3 min · Business 10 min · Enterprise custom.

---

## Session replay

A lightweight DVR for the page using rrweb: the widget continuously records the DOM and interactions, keeping roughly the last 30 seconds in memory. When a tester submits feedback, that buffer is attached, so you can replay exactly what led up to the bug. Open a feedback item and click "▶ Replay session" to load the player. Available on Team, Business and Enterprise plans.

---

## Privacy & PII redaction

Protection applies to session replays, where rendered text would otherwise be recorded.

Automatic:
- All form inputs are masked — passwords and typed values are never captured.
- Auto PII redaction (on by default) — emails, phone numbers and card-like number sequences in rendered text are replaced with [redacted] before the replay leaves the browser.

Toggle auto-redaction per project in Settings → Privacy & PII redaction (on by default, every plan).

Block or mask specific regions with one attribute:
- data-tugboat-block (or class tugboat-block) — the element and its contents are not recorded at all.
- data-tugboat-mask (or class tugboat-mask) — the element's text is masked but layout is preserved.

Example:

    <section data-tugboat-block> ...sensitive account details... </section>
    <p data-tugboat-mask>Order total: $4,208.55</p>

Redaction happens client-side, before any data is sent. Combined with Shadow DOM isolation, the widget stays a good citizen inside regulated apps.

---

## Console, network & environment

Every submission carries technical context automatically:
- Console logs — recent console errors and warnings, uncaught exceptions and unhandled promise rejections.
- Network errors — failed requests (HTTP status ≥ 400 or network errors) from fetch and XHR, with method, URL, status and duration.
- Environment metadata — OS, browser and version, viewport, screen size, device pixel ratio, language, timezone and online status.
- Device tag — each submission shows the OS/device it came from, read from the capture: Android or iOS (phone icon, mobile), Windows/macOS/Linux (desktop icon), or the native platform (iOS/Android app) when sent from a mobile SDK. Shown on the feedback list, the detail view and next to the session replay so the capture platform is obvious.

Reports carrying console errors or failed requests are flagged in your inbox so you can filter to the highest-signal bugs.

---

## Annotated screenshots

Testers draw boxes, arrows and freehand pen marks directly on the capture before sending, in four colors, with undo/clear and an expand-to-fullscreen editor. Available on all plans.

---

## Roadmap & upvotes

The widget includes a Roadmap panel showing Planned, In progress and Released items, and lets users upvote what they want most.

- Manage it in a project's Roadmap tab: add items with a title, optional description and status; move items between statuses; see live vote totals.
- Upvoting is anonymous and frictionless (no login/email), de-duplicated to one vote per browser; tapping again removes the vote.
- Available on every plan, including free Solo. Roadmap items can be scoped to specific audiences (see Audience targeting).

---

## Audience targeting

Both Changelog ("What's new") and Roadmap posts can be targeted to a cohort based on the user context you pass to the widget.

1. Identify the user — pass a user object with any of plan, role and segments:

    <script>window.tugboatUser = { plan: "pro", role: "admin", segments: ["beta"] };</script>
    <script src="https://tugboatapp.com/widget.js" data-project-key="pk_your_key"></script>

   Or after login: `Tugboat.identify({ plan: "pro", role: "admin", segments: ["beta"] });`

2. Target a post — fill the optional Audience fields (Plans, Roles, Segments, comma-separated) when creating a changelog or roadmap item. Blank = everyone. Plans/Roles: user must match one listed value. Segments: user must hold at least one listed segment. Fields combine with AND. If no user context is passed, targeted posts stay hidden and only untargeted posts show.

---

## Triage & filters

Feedback has a status (New, In progress, Resolved), priority and tags. An independent view control switches between Inbox (active), Archived, and All — so you can filter archived items by status too (e.g. archived items still marked New). Filter by view, status, subject/topic and signal (e.g. has errors, has replay); the filters stack. Status is editable on any row, including archived ones. Each project defines its own subjects/topics that testers choose from.

---

## Canonical numbers, activity log & PDF reports

Every submission is assigned a canonical, per-project sequential number (e.g. #42) for easy reference. Tugboat keeps a full activity/audit trail: status and priority changes, tags added/removed, archive/restore, Jira links, internal comments and public replies — each recorded with the actor's name and timestamp. The trail is shown inside each submission (an "Activity & replies" timeline) and in a project-wide "Activity" tab that aggregates every change across all submissions; every entry is labelled with the submission it belongs to (number + subject or note snippet) and shows note/reply text inline, so entries like "Archived" always have context. Teams can add internal (team-only) comments on a submission. Managers can export a branded PDF audit report of all activity over any date range from the Activity tab — with columns Date, Ref, Submission (subject/note), Change (including the full text of notes and replies) and By.

---

## Tester updates & two-way replies

Every tester gets a private status link the moment they submit: the widget's "Thank you" screen shows a bookmarkable link to their report's public status page (/s/<token>) with a one-tap Copy button — no email or account required. Testers who leave an email can additionally opt in ("Email me when there's an update"); on a public reply or a status change, opted-in testers are emailed (via Resend) with the same secure link. The public status page shows the submission's status and the public conversation only (internal notes are never exposed) and lets the tester reply back — their reply lands in the dashboard timeline and notifies the team. Public replies are distinct from internal notes: only public replies are shared with the tester, and reports submitted without any contact info allow internal notes only. Optionally, "Auto-publish resolved fixes" posts a "Fixed:" entry to the widget's What's New feed whenever a submission is marked Resolved (using the public reply text when available).

---

## Guided submissions

An optional per-project mode that helps non-technical testers give useful context. Instead of a single free-text note, the widget shows short structured prompts (defaults: "What were you trying to do?", "What did you expect to happen?", "What actually happened?"; fully customizable, up to six) and an optional "I'm reporting as…" persona dropdown (e.g. End user, Admin, Developer, QA). The answers are assembled into one clean, structured note. Off by default; enable in Settings → Guided submissions.

---

## Custom branding (Business)

White-label the widget per project: your own logo or a preset button icon (ship, bug, lightbulb, megaphone and more), accent color (optionally themed across all capture tiles), button text and shape (pill/circle/rounded-square), a custom panel headline, and fully editable widget copy (brand name, capture labels, send/sending/thank-you/consent text) to remove every trace of Tugboat. Optionally hide the "What's new" panel and offer a dismiss (×) control.

---

## Jira integration

Connect a project to Jira (site URL, email, API token, project key, issue type). One click turns a tester's report into a ticket with screenshots, video and voice attached. Credentials are encrypted at rest. More integrations (Linear, GitHub, Asana, Trello, ClickUp) are on the roadmap.

---

## Team & roles

Roles: Owner, Admin, Member, Viewer. Owners/Admins manage team, billing and deletion; Members create projects and triage feedback; Viewers are read-only. Members and Viewers can be restricted to specific projects. Invite teammates by email.

---

## Plans & billing

- Solo — free: 1 project, 100 feedback/mo, all capture types, 7-day history.
- Team — $39/mo: unlimited projects, 5 teammates, Jira + integrations, unlimited history, changelog publishing, session replay.
- Business — $149/mo: everything in Team, unlimited teammates, custom branding & white-label, Member & Viewer roles, priority support.
- Enterprise — custom: everything in Business, AI feedback intelligence (soon), SSO/SAML/SCIM (soon), audit logs & SLA, dedicated support.

Roadmap & upvotes, sentiment ratings, PII redaction, Shadow DOM isolation and audience targeting are available on all plans.

---

## Getting support

Reach the team from the in-app support page or Contact form. Business and Enterprise plans include priority and dedicated support.