TesterBuddy › Docs › Web SDK

Web SDK Reference

One script tag. Automatic error capture, network monitoring, performance tracking — and a direct link to every tester who triggered it.

v1.0 — latest 🌐 Browser-only ⚡ ~4 KB gzipped
⚡ Getting Started

Quick Start #

Add a single <script> tag to your site and TesterBuddy starts capturing events immediately. No npm install, no build step.

HTML 
<script src="https://testerbuddy.app/sdk/testerbuddy.js"
        data-app-key="YOUR_API_KEY"
        data-mode="all">
</script>

Paste this snippet just before the closing </body> tag. Replace YOUR_API_KEY with the key found in the Web SDK tab of your app in TesterBuddy.

  1. 1
    Create a Web App in TesterBuddy
    Open TesterBuddy → tap + → choose platform Web → enter your site URL and app name.
  2. 2
    Copy your API Key
    Go to the Web SDK tab inside your app. Copy the Web API Key shown at the top.
  3. 3
    Add the script to your site
    Paste the snippet above into every HTML page (or your base template / <head> partial). Works with React, Vue, Nuxt, plain HTML — anything that serves HTML.
  4. 4
    Trigger an event and verify
    Load your site, open the console and deliberately trigger a JS error (undeclaredVar.foo). Within seconds it appears in the Web Events list in TesterBuddy.
💡
Send setup instructions by email In the Web SDK tab, tap Send Setup Email. TesterBuddy will mail a ready-to-paste code snippet with step-by-step instructions to you or a developer on your team.
🔑 Authentication

API Key #

Each web app in TesterBuddy has a unique Web API Key. This key is used by the SDK to authenticate your events. It is safe to include in your front-end HTML — it can only be used to write events, never to read them or access your account.

⚠️
Treat it like a public write-only token Anyone who has the key can send events to your app, but they cannot read data or impersonate your account. Do not confuse it with your account password or profile token.
Where to find it
  • Open TesterBuddy on iOS
  • Tap your web app to open the detail view
  • Tap Web SDK (the code icon in the toolbar)
  • The Web API Key is displayed at the top — tap to copy
Rotating your key

If you accidentally expose your key, contact support via Settings → Contact Support inside TesterBuddy to request a rotation. After rotation, update the data-app-key attribute in your HTML.

⚙️ Configuration

Tracking Modes #

The data-mode attribute controls which visitors the SDK tracks. Choose the mode that fits your testing workflow.

Mode Who is tracked Best for
all (default) Every visitor to your site Public beta or staging sites where you want maximum coverage
testers Only visitors who are enrolled TesterBuddy testers Production sites — limits noise from real users
HTML — testers-only mode 
<script src="https://testerbuddy.app/sdk/testerbuddy.js"
        data-app-key="YOUR_API_KEY"
        data-mode="testers">
</script>
ℹ️
How tester detection works In testers mode the SDK checks for a TesterBuddy session cookie set when the tester opened your test URL from the iOS app. No login popup is shown — unrecognised visitors are simply ignored silently.
📊 Events

Automatic Tracking #

As soon as the script loads, TesterBuddy passively monitors four categories of events. Nothing extra to configure.

🔴
JavaScript Errors
error
Uncaught exceptions and unhandled promise rejections, including the full stack trace and originating URL.
🌐
Network Failures
network_error
Failed fetch() and XMLHttpRequest calls — captures the URL, HTTP status, and response time.
⚡
Performance Metrics
performance
Page load time, Time to First Byte (TTFB), and DOM ready timing via the Navigation Timing API.
👁
Page Views
pageview
Every navigation, including SPA route changes via History API. Captures the full URL and session.
What is NOT collected

TesterBuddy never captures form values, passwords, credit card fields, or any DOM content. It never uses fingerprinting. Events contain: URL, error message, stack trace, user agent string, and a randomly generated session ID.

✨ API

Custom Events — track() #

Log any user action with TesterBuddy.track(name, metadata). Custom events appear in the dashboard with type custom and are grouped by their event name.

JavaScript 
// Basic event
TesterBuddy.track('button_clicked', { label: 'Sign Up' });

// With rich metadata
TesterBuddy.track('checkout_started', {
  plan: 'pro',
  price: 29.99,
  currency: 'USD',
  items: 3
});

// React — on user interaction
<button onClick={() =>
  TesterBuddy.track('hero_cta', { variant: 'A' })
}>
  Get Started
</button>
Parameters
Parameter Type Required Description
name string required Event name. Use snake_case for consistency. Max 200 chars.
metadata object optional Any JSON-serializable key/value pairs. Shown in the event detail view. Max depth 3.
ℹ️
Script not yet loaded? The SDK queues track() calls made before it initialises, so it's safe to call TesterBuddy.track() anywhere in your JS — even at the top of <head>.
👤 Identity

Identified Testers #

When a tester is signed into TesterBuddy and visits your site, their identity is attached to every event they generate — automatically. You'll see their name and avatar next to each error in the dashboard.

You can also explicitly identify a tester from your own app using TesterBuddy.identify(). This links your internal user ID or email to the session:

JavaScript 
// Identify by email (must match TesterBuddy account)
TesterBuddy.identify('tester@example.com');

// Or by TesterBuddy user ID
TesterBuddy.identify(42);

// Call after your own login flow completes
async function onSignIn(user) {
  await yourAuthFlow(user);
  TesterBuddy.identify(user.email);
}
⚠️
Identification is advisory If the email or ID passed to identify() doesn't match a TesterBuddy account enrolled in your app, the event is still recorded — it will just appear without a name in the dashboard.
📄 Reference

Script Attributes #

All configuration is done via data-* attributes on the script tag — no JavaScript setup required.

Attribute Required Default Description
data-app-key required — Your Web API Key. Found in the Web SDK tab of your app.
data-mode optional "all" "all" or "testers". See Tracking Modes.
data-session-id optional auto Override the auto-generated session ID. Useful if you have your own session management.
Full example with all attributes
HTML 
<script
  src="https://testerbuddy.app/sdk/testerbuddy.js"
  data-app-key="tb_live_abc123xyz"
  data-mode="testers"
  data-session-id="your-own-session-id"
></script>
🌍 Compatibility

Browser Support #

TesterBuddy uses modern Web APIs. All evergreen browsers are fully supported. For older environments the SDK degrades gracefully — it will still capture JS errors but some metrics may be unavailable.

Browser Support Notes
Chrome / Edge 90+ ✓ Full All features including performance metrics
Firefox 88+ ✓ Full All features
Safari 14+ ✓ Full All features; sendBeacon used for exit events
Safari 12–13 ◑ Partial Errors + page views; no performance timing
IE 11 ◑ Partial Errors only; custom events not available
IE <11 — SDK loads silently and does nothing
💡
The SDK is loaded asynchronously and never blocks your page render. In unsupported browsers it exits silently — your site works normally.
📱 iOS App

Web Events View #

In TesterBuddy, open any web app and tap the Web Events tab (globe icon). You'll see all events captured from your site in real time.

Filter by type

Tap the segmented control at the top to filter by event type: All, Errors, Network, Performance, Page Views, or Custom.

Event detail

Tap any event to see the full detail view: error message, stack trace (formatted), page URL, user agent, session ID, and the tester's name and avatar if they were identified.

Grouped vs. Individual view

Toggle between Grouped (deduplicated by message) and Individual (chronological stream) using the control at the top right. Grouped view is the default — it's the most useful for spotting patterns.

🗂️ Analytics

Grouped Errors #

The grouped view deduplicates events by message. Instead of seeing 47 identical "Cannot read properties of undefined" entries, you see one row with ×47. Each row shows:

  • Occurrence count — total times this event was captured
  • Unique sessions — how many independent visits triggered it
  • Affected testers — identified testers who hit this issue
  • Last seen — relative time (e.g. "3h ago")
  • Fixed badge — shown in green when the error hasn't recurred in 24 hours

Tap any row to see the full timeline: first occurrence, last occurrence, the most recent individual event, and an explanation of whether it's considered fixed.

✅ Status

Fixed Status Indicator #

TesterBuddy automatically marks an error group as Fixed when it has not been seen in the last 24 hours. This gives you a quick signal that a bug is likely resolved — without requiring you to manually close tickets.

ℹ️
How it works The Fixed badge appears when now − last_occurrence ≥ 24 hours. If the same error recurs after that window, the badge disappears and the occurrence count increments. There is no permanent "close" action — the system self-heals based on activity.
Interpreting Fixed
  • Fixed (green badge) — No recurrence in 24h. Likely resolved by a recent deploy or no longer triggered.
  • No badge — Error is still occurring or occurred within the last 24h. Needs attention.

The 24-hour window is the current default. Future versions may allow this threshold to be configured per app.

🤖 AI

AI Summary #

Tap AI Summary on any app to generate an AI-powered analysis. For web apps, the summary incorporates three sources of signal:

  • Tester chat messages and direct feedback
  • Survey responses from testers
  • Web SDK events — top recurring errors, network failures, and performance issues from the last 30 days

The AI correlates these sources and produces a structured report with a sentiment overview, key issues raised by testers, a technical incidents section (from SDK events), and actionable next steps.

💡
Best results Run AI Summary after your testers have submitted at least 3–4 feedback messages and your SDK has been active for a day or more. The AI needs signal from both sources to correlate UI feedback with technical errors.
🔧 Help

Troubleshooting #

Events not appearing in TesterBuddy Common
  • Check the browser console for a 401 Unauthorized response from /api/sdk/ingest. This means your data-app-key is wrong or your app is not set to "active".
  • Make sure you're using the Web API Key, not your account token or TestFlight URL.
  • Check that the script tag is present in the rendered HTML. Some frameworks (Next.js, etc.) require placing scripts in specific locations.
  • If you're on a staging environment with CSP headers, add https://testerbuddy.app to your connect-src directive.
Script is blocked by Content Security Policy (CSP)
Add the following to your Content-Security-Policy header:
HTTP Header 
Content-Security-Policy:
  script-src 'self' https://testerbuddy.app;
  connect-src 'self' https://testerbuddy.app;
SPA route changes not tracked as page views
  • The SDK listens to popstate and patches history.pushState / replaceState to detect SPA navigation.
  • If your framework uses hash routing (#/path), page views may not be captured. Use TesterBuddy.track('pageview', { path: location.hash }) manually in your router's navigation hook.
App icon not fetching automatically
  • TesterBuddy tries to scrape your site's apple-touch-icon, og:image, then falls back to Google's favicon service.
  • If your site has a strict CORS or CSP policy, the backend scraper may be blocked. Use the Custom Icon URL option in Edit App to paste a direct image URL.
  • The icon fetch is triggered when the app is created or when you tap Refresh Icon in the app detail menu.
❓ FAQ

Frequently Asked Questions #

The script is loaded asynchronously and is approximately 4 KB gzipped. It does not block rendering. Network requests are batched and sent using navigator.sendBeacon where available, so they don't block page unload. In all our testing the SDK adds <1 ms to page load time.
TesterBuddy does not collect personally identifiable information unless you explicitly call TesterBuddy.identify(). It never reads form values, DOM content, or fingerprints users. Session IDs are randomly generated per browser session and are not linked to any real identity. Events are associated with testers only when the tester is signed in to TesterBuddy and has opted into testing your app.
Yes. The SDK is a plain JavaScript file — it works with any framework that renders HTML. For Next.js, add the script tag inside <Script strategy="afterInteractive"> in your _app.tsx or layout.tsx. For Vue, add it to your index.html. For React, use react-helmet or add it to public/index.html.
Yes — the SDK will capture events even from localhost. This is useful for testing your integration. To avoid polluting your production event stream, use a separate TesterBuddy app (with its own API key) for your development environment.
The ingest endpoint accepts up to 50 events per batch request. There is no hard daily limit during the beta period. The SDK automatically batches events to stay within this limit.
The SDK is browser-only. For server-side event ingestion, you can call the POST /api/sdk/ingest endpoint directly with a JSON body and your API key in the X-TB-Key header. See the API reference for the full payload schema.