SnappySnag Documentation
SnappySnag is an in-app visual bug reporting and AI auto-fix suggestion SDK for Flutter. With a single shake or tap, users capture screenshots, drop itemized numbered pins (1–5), and instantly receive AI-powered code fix suggestions and ready-to-use prompts for any AI coding agent (Cursor, Windsurf, Claude, Copilot, etc.) on your dashboard.
Multi-Point Pins
Normalized vector preservation without destructive stamping. Drop 1–5 pins with separate repro notes.
AI Agent Auto-Fix
Widget hierarchy dumps paired with Gemini AI to generate copy-ready prompts for Cursor, Claude, Windsurf, etc.
3-Tier Roles & Safety
Owner, Developer, and Tester. Testers submit reports without consuming your project AI credits.
Quickstart (3 Simple Steps)
Integrate into your existing Flutter application in under 3 minutes.
Add Dependency
flutter pub add snappy_snagGet Your Project API Key
Create a project on the SnappySnag Dashboard (https://snappysnag.com/dashboard) and copy your live API Key (e.g. snag_live_...).
Configure main.dart
Call initialize() in main() and set navigatorKey and builder on MaterialApp.
import 'package:flutter/material.dart';
import 'package:flutter/foundation.dart';
import 'package:snappy_snag/snappy_snag.dart';
void main() {
WidgetsFlutterBinding.ensureInitialized();
// 1. Initialize the SDK (Safe across all environments with a single line)
SnappySnag().initialize(
apiKey: 'snag_live_your_api_key_here',
showTriggerButton: true, // Display floating capture button
);
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
// 2. Attach SnappySnag's default navigator key
navigatorKey: SnappySnag.defaultNavigatorKey,
// 3. Wrap your app with SnappySnagOverlay in builder
builder: (context, child) => SnappySnagOverlay(
child: child ?? const SizedBox.shrink(),
),
home: const MyHomePage(),
);
}
}Ecosystem & Tool Category Comparison
SnappySnag operates independently and can be used alongside existing crash reporting systems, bridging the gap between visual bug reports and AI code fixes.
| Category / Feature | SnappySnag (AI × Visual) | Crash Monitoring SDKs | Legacy Feedback SDKs |
|---|---|---|---|
| Primary Focus | Visual bugs, UI glitches, design inconsistencies & feature requests | Fatal app crashes, unhandled exceptions & stack traces | General user inquiries & basic screenshots |
| AI Agent Integration | Ready-to-use prompts for Cursor, Claude & Copilot | ✕ Raw stack traces only | △ Basic text summarization only |
| Pin Annotations | Up to 5 numbered pins (vector coordinate preservation) | ✕ None (automatic passive dump) | △ Destructive drawing stamps / freeform arrows |
| Widget Tree Dumper | 10-layer widget traversal with auto PII redaction | ✕ None | △ Native UIView hierarchy only |
| Coexistence | - | ○ Works seamlessly together (independent) | ○ Choose based on your workflow |
Multi-Point Pin Annotations
Traditional feedback tools often deface screenshots with rough drawings or require multiple screenshots for separate bugs. SnappySnag allows users to tap anywhere to drop up to 5 numbered pins (①–⑤) with targeted comments.
Pin positions are stored as normalized vector percentages (x, y ratios) rather than burned into the screenshot. Dashboard users can toggle pins on/off and inspect original high-resolution pixels cleanly.
AI-Native Debugging directly inside your IDE
Connect SnappySnag directly to your favorite AI code editors (Cursor, Claude Code, Antigravity, etc.) via the official Model Context Protocol (MCP) server. AI agents can inspect tickets, analyze pin coordinates, write fixes, and resolve bugs directly inside your IDE.
Quick Setup (Under 1 Minute)
Open your project in the Web Dashboard, go to Project Settings > MCP Secret Key, and click 'Copy mcp.json snippet'.
Paste the snippet into your editor's MCP configuration file (e.g., mcp.json) and save.
{
"mcpServers": {
"snappysnag": {
"url": "https://snappysnag.com/api/mcp",
"headers": {
"Authorization": "Bearer snag_mcp_your_secret_key_here"
}
}
}
}Available MCP Tools
Fetches the most recent open feedback ticket with pin details, screen name, and metadata.
Lists tickets filtered by status (open, in_progress, resolved), severity, tags, or search query.
Retrieves normalized pin vector coordinates, screenshot URLs, device specs, and full comment discussion history.
Updates ticket status (e.g. resolved) and automatically posts the AI's explanation into ticket discussions.
Robust Key Isolation & Encryption
The MCP Secret Key (`snag_mcp_...`) is strictly isolated from client-side Write-Only keys (`snag_live_...`). Saved using AES-256-GCM and verified with HMAC-SHA256 hashed lookups. Keys can be instantly rotated from your project settings with a single click.
3-Tier Roles & AI Credit Safety
Strict permission boundaries designed for client work, contractors, and mixed internal/external teams.
Project Owner
- Full project & member management
- Pin inclusion / exclusion triage
- AI auto-fix generation & credit consumption
Developer
- View all pins & technical details
- Triage pins (include/exclude)
- Execute AI fixes & copy agent prompts
Tester
- Submit new feedback & pins from app
- View approved pin feedback
- 🛡️ Cannot consume AI credits (Safe)
Configuration API Reference
| Option | Type | Default | Description |
|---|---|---|---|
| apiKey | String | Required | Project API key starting with snag_live_... |
| mode | SnappySnagMode | user | Operation mode: user (public users: privacy confirmation & user reply AI draft) or dev (internal QA: direct submission & team share AI analysis). |
| showTriggerButton | bool | false | Whether to display the floating overlay capture button. |
| enabled | bool | true | Master switch. When false, suppresses overlay and shake listeners completely. |
| user | SnappySnagUser? | null | User identity (email, id, name). Matches dashboard member permissions. |
| packageName | String? | null | Locks API Key requests to your registered bundle identifier. |
| enableWidgetTree | bool | true | Traverses Flutter UI tree (up to 10 levels) with automatic PII redaction. |
| enableLogging | bool | false | Suppresses verbose console logs during development. |
| theme | SnappySnagTheme | const SnappySnagTheme() | Theme customization: primaryColor, pinColor, borderRadius, and themeMode (system/dark/light). |
| enableHaptics | bool | true | Crisp tactile haptic vibration feedback for pin drops and actions. |
Seamlessly align SnappySnag with your app's brand aesthetic: customize primaryColor, pinColor, borderRadius, and light/dark themeMode. Built-in crisp haptic feedback brings native tactile satisfaction.
SnappySnag().initialize(
apiKey: 'YOUR_API_KEY',
// ⚡️ Native tactile haptic feedback (defaults to true)
enableHaptics: true,
// 🎨 Align UI styling with your product's brand identity
theme: const SnappySnagTheme(
primaryColor: Color(0xFF6366F1), // Brand accent color
pinColor: Color(0xFFF95738), // Marker pin badge color
borderRadius: 16.0, // Corner radius for dialogs & toolbars
themeMode: ThemeMode.system, // ThemeMode.system / dark / light
),
);Built-in localization dictionaries for English and Japanese out of the box. Automatically follows your app locale, supports explicit overrides, and lets you fine-tune specific labels or hints with copyWith().
SnappySnag().initialize(
apiKey: 'YOUR_API_KEY',
// 🌐 Explicit locale override (auto-detects app/device locale if omitted)
locale: const Locale('en'),
// ✍️ Fine-tune specific labels to match your product's tone of voice
localization: SnappySnagLocalization.en().copyWith(
send: 'Submit Feedback 🚀',
pinCommentTitle: 'Noticeable issue',
statusSuccess: 'Feedback submitted! Thank you.',
),
);
// Dynamic runtime switching is also supported
SnappySnag().setLocale(const Locale('ja'));Production & Testing Strategies
SnappySnag supports both in-app public user feedback collection and internal QA testing workflows.
Works out-of-the-box in production releases. Floating buttons default to hidden, and Release mode automatically switches to end-user mode with privacy confirmation. The client API key is strictly Write-Only so internal data can never be fetched, and dashboard Pause/Resume controls plus an Auto-Pause Circuit Breaker protect your quota against spam without requiring app updates. Calling startFeedbackMode from your settings menu is the industry standard.
// Trigger manually from your Settings or Help drawer:
ListTile(
leading: const Icon(Icons.feedback_outlined),
title: const Text('Report a Bug / Feedback'),
onTap: () => SnappySnag.startFeedbackMode(context: context),
)If company policy dictates that the SDK must be completely dormant in public store releases, pass a boolean flag to enabled. The simplest method is !kReleaseMode, or use --dart-define for TestFlight builds.
// Pattern 1: Automatic dormancy in release builds (1-liner)
SnappySnag().initialize(
apiKey: 'YOUR_API_KEY',
enabled: !kReleaseMode,
);
// Pattern 2: Enable specifically for TestFlight / internal testing
// flutter build ipa --dart-define=ENABLE_SNAPPY_SNAG=true
const bool isTestFlight = bool.fromEnvironment('ENABLE_SNAPPY_SNAG', defaultValue: false);
SnappySnag().initialize(
apiKey: 'YOUR_API_KEY',
enabled: isTestFlight,
);Real-time Slack & Discord Notifications
Instantly broadcast feedback reports to your Slack or Discord channels. Interactive cards include direct deep links to open the ticket immediately on the web dashboard.
- Create an Incoming Webhook in your Slack workspace.
- Paste URL into Project Settings > Notifications tab.
- Click 'Send Test' to verify connection (auto-saves on success).
- Create a Webhook under Discord Channel Settings > Integrations.
- Paste URL into Project Settings > Notifications tab.
- Click 'Send Test' to verify connection (auto-saves on success).
Security & Project Language Localization
All Webhook URLs are encrypted with AES-256-GCM. Notification titles, labels, and formats are automatically localized according to your Project Language (Japanese / English) settings.
Frequently Asked Questions
Common questions about integration, safety, ecosystem coexistence, and AI agent usage.
Q.How does SnappySnag differ from other feedback or crash monitoring tools?
Unlike legacy tools focused on raw crash logs or freehand drawing stamps, SnappySnag provides precise multi-point pin annotations (1–5), Flutter widget tree traversal, and Gemini AI auto-fix prompts formatted directly for Cursor, Claude, and Copilot. It operates seamlessly alongside tools like Sentry and Firebase Crashlytics.
Q.Can it be safely deployed in production App Store and Google Play builds?
Yes, absolutely. In release builds, SnappySnag automatically switches to end-user feedback mode with privacy confirmation, and the floating trigger button is hidden by default. The client API key is strictly Write-Only so internal project data can never be queried, and built-in Pause/Resume controls plus an Auto-Pause Circuit Breaker let you instantly halt spam without rebuilding or re-releasing your live store app.
Q.How are submitted data, API keys, and secrets secured?
All network traffic is encrypted via TLS 1.3, and integration secrets (Slack/Discord Webhooks, GitHub PAT, BYOK Gemini Keys) are encrypted at rest with AES-256-GCM. Strict Row Level Security (RLS) and on-device PII masking protect user privacy, while Bundle ID locking, dual IP & device rate limiting, and an Auto-Pause Circuit Breaker safeguard your API key against abuse.
Q.Which AI coding agents support the generated fix prompts?
Cursor, Windsurf, Claude (Artifacts/Projects), GitHub Copilot, and ChatGPT. Any modern LLM or AI coding agent that accepts Markdown prompts can utilize the structured repro guides, widget hierarchies, and pin coordinate data for precise fixes.
Q.Can I start without a credit card? What happens when free tier AI credits run out?
Yes, you can start completely free without a credit card. Even if your free AI credits run out, screenshot capture, multi-pin dropping, feedback submission, GitHub Issue sync, and Slack/Discord alerts remain 100% free and unlimited. To continue AI code suggestions without upgrading, simply bring your own Gemini API key (BYOK).
Q.Can I safely invite external clients and testers without risking project settings?
Yes, completely safe. SnappySnag provides 3-tier team roles: Owner, Developer, and Tester. Tester accounts can view tickets, submit reports, and leave comments, but cannot modify project settings, view encrypted secrets, or consume AI credits. Furthermore, the SDK API key is strictly Write-Only, ensuring internal ticket data can never be fetched from the client app.
Q.What information is included in Slack and Discord alerts?
Upon feedback submission, an instant formatted card alert arrives displaying the screen name, pin count, reporter info, OS/device specs, and comment summaries. Each alert contains a direct authenticated deep link to open the ticket on the web dashboard immediately.
Q.Can feedback be submitted in offline or unstable network environments?
Yes. If network drops occur or the app is accidentally dismissed during submission, unsaved comments, screenshot annotations, and pin coordinates are preserved on-device (SharedPreferences) as drafts, ready to resume and submit once connection is restored.