flawsnap 0.0.1

In-app bug reporting for Flutter with annotated screenshots, device information, logs, and network request summaries.

flawsnap

In-app bug reporting for Flutter apps. Users shake the phone or tap a floating button, mark up a screenshot of the app, and send. Reports land in the same Snaplog inbox as your website's, tagged ios or android.

Requirements

• Flutter with Dart >=3.13.3 <4.0.0, as currently required by pubspec.yaml. Flutter must also be at least 3.38.1. Local release checks were run with Flutter 3.47.5 and Dart 3.13.4; older supported combinations need validation. Dependencies may impose additional native platform requirements.
• A running Snaplog backend and a project key for your own project.
• For production, an HTTPS API URL reachable from your users' devices. Installing this package does not deploy a backend or create a Snaplog account.
• The SDK targets Android and iOS. The existing project notes record iOS simulator testing. The Android example builds successfully in release mode with Flutter 3.47.5; end-to-end testing on physical Android and iOS devices is still needed. Other platforms are not claimed.

Installation

From pub.dev (after publication)

These commands require the maintainer to publish this package first; this README does not confirm that a release is already available.

Run inside the consuming Flutter app:

flutter pub add flawsnap

Or, once version 0.0.1 is published, add to the app's pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  flawsnap: ^0.0.1

Then run flutter pub get. Choose one installation source for this package.

From GitHub (before publication)

dependencies:
  flawsnap:
    git:
      url: https://github.com/RazyeshPersonal/snaplog-flutter-sdk.git

Run flutter pub get. Private repositories require Git access. For reproducible installs, add a ref under git pointing to an existing release tag or commit.

From a local checkout

dependencies:
  flawsnap:
    path: ../snaplog-flutter-sdk

Adjust the path relative to your app's pubspec.yaml, then run flutter pub get. See the official dependency source guide.

Setup

1. In the Snaplog portal, open your project's Security settings and turn on Accept reports from mobile apps. Copy the project key.

2. Install the package using one of the sources above.

3. Initialise and wrap your app:

   import 'package:flutter/material.dart';
   import 'package:flawsnap/flawsnap.dart';
   
   Future<void> main() async {
     WidgetsFlutterBinding.ensureInitialized();
     await Snaplog.init(apiUrl: 'https://api.example.com/api/v1', projectKey: 'pk_...');
     runApp(Snaplog.wrap(const MyApp()));
   }
   
   class MyApp extends StatelessWidget {
     const MyApp({super.key});
   
     @override
     Widget build(BuildContext context) {
       return MaterialApp(
         navigatorObservers: [Snaplog.navigatorObserver],
         home: Scaffold(
           appBar: AppBar(title: const Text('Snaplog example')),
           body: Center(
             child: ElevatedButton(
               onPressed: Snaplog.show,
               child: const Text('Report a problem'),
             ),
           ),
         ),
       );
     }
   }
   

   Replace the example API URL and key with your project's values. The API URL is the backend base URL, including /api/v1 for the deployment shown here. Use a mobile reporting project key, never an administrator credential.

4. Optional extras:

   MaterialApp(navigatorObservers: [Snaplog.navigatorObserver])  // report the current screen
   final client = Snaplog.httpClient();                           // record network calls
   Snaplog.identify(name: user.name, email: user.email);          // prefill the reporter
   Snaplog.log('Payment failed', level: 'error');                 // custom log lines
   Snaplog.setMetadata({'plan': 'pro'});                          // extra details
   Snaplog.show();                                                // open the reporter yourself
   

   Choose triggers with Snaplog.init(..., triggers: {SnaplogTrigger.button}) (default: shake and button). Shake needs a physical device.

   Admins can hide the floating button from the project's settings in the portal, or set its position (left/right) and colour; the label set there is used as the button's accessibility label. Shake and Snaplog.show() keep working when the button is hidden.

Native app configuration

Android

In your app's android/app/src/main/AndroidManifest.xml, add this directly inside <manifest> so release builds can reach the backend:

<uses-permission android:name="android.permission.INTERNET" />

Use HTTPS in production. Debug-only internet permissions do not cover release builds. The included example declares this permission in its main manifest.

iOS

Add this inside the root dictionary of ios/Runner/Info.plist:

<key>NSMotionUsageDescription</key>
<string>Motion data lets you shake your device to report a problem.</string>

This follows the sensors_plus setup requirements. The example already includes it. Match your native build settings to dependency requirements; device_info_plus currently requires iOS 13 or later, Java 17, and recent Android and Xcode toolchains.

Team sign-in

When the project allows it (portal: project settings, "Let team members sign in from the widget and app"), the report screen shows Team member? Sign in. The SDK shows a code like ABCD-EFGH and opens Snaplog's approval page in the browser. The member signs in there (or on another device, with the code) and presses Allow. From then on their reports go in under their Snaplog account ("Reporting as Jane · Sign out"), without the name and email fields. Everyone else reports anonymously as before.

• Snaplog.signIn() / Snaplog.signOut() do the same from your own UI.
• The app gets a reporter token, not a Snaplog session. It can only send reports to this project and lasts 30 days. If the API rejects it (expired, revoked, or the setting turned off), the name and email fields come back.
• The token is kept in shared_preferences. To keep it encrypted at rest, implement ReporterTokenStore with flutter_secure_storage and pass it as Snaplog.init(..., tokenStore: MyStore()).
• On Android, auto backup copies shared_preferences to the user's cloud backup by default. To keep the token out of it, exclude FlutterSharedPreferences.xml in your backup rules (android:fullBackupContent / android:dataExtractionRules), set android:allowBackup="false", or use the secure-storage option above.

What a report includes

• Screenshot of the app with the user's marks (box, draw, five colours).
• Title, description, priority, and "Who should look?" from your project's categories.
• Device model, OS and version, app name, version and build, screen size, pixel ratio, locale, light/dark mode.
• The current route (with navigatorObserver).
• The last 100 log lines: Flutter errors, uncaught exceptions, debugPrint output and Snaplog.log calls.
• The last 100 requests made with Snaplog.httpClient() (method, URL, status, timing; bodies are never recorded).

If the key is wrong or mobile reporting is off for the project, init logs why and the SDK stays hidden; your app is unaffected.

Local development

The example app talks to a local API:

cd example
cp dart_defines.example.env dart_defines.env   # then put in your project key
flutter run --dart-define-from-file=dart_defines.env

The iOS example allows plain HTTP to local addresses (NSAllowsLocalNetworking) for development. Production apps should use an https API URL. The Android emulator reaches your machine at http://10.0.2.2:8080, and needs a cleartext network-security exception for HTTP.

Verify the integration

1. Launch the app with your backend reachable and mobile reporting enabled.
2. Tap Report a problem, use the floating button, or shake a physical device.
3. Annotate the screenshot, enter a title and details, and submit a test report.
4. Open your project's Snaplog inbox and confirm the report and device details.
5. Repeat on Android and iOS release builds before distributing your app.

Troubleshooting

Problem	What to check
Package not found on pub.dev	Confirm a release exists under the exact package name, or use Git/path installation.
SDK version solving fails	Run flutter --version; the current package requires Dart 3.13.3 or later below 4.0.0. Check dependency constraints too.
Reporter stays hidden	Look for [snaplog] reporting disabled in logs; check the API URL, project key, backend reachability, and mobile reporting setting.
Floating button is missing	Check the selected triggers and the project's portal button setting.
Shake does not work	Use a physical device with the shake trigger enabled; use the button on simulators.
Local backend cannot be reached	Android emulator uses 10.0.2.2; a physical phone needs a reachable LAN address. localhost on a phone refers to that phone.
Requests are missing from reports	Send those requests through Snaplog.httpClient(); unrelated clients are not automatically intercepted.
Team sign-in is unavailable	Enable team sign-in in the project's settings.

Publishing for everyone (maintainers)

For the complete interactive release procedure, see the manual publishing guide.

Publication makes the SDK downloadable worldwide. Each consuming app still needs its own project configuration and access to a running Snaplog backend.

1. Prepare the release

• Check availability of flawsnap on pub.dev before the first release. If another publisher owns it, select an available name and update imports and examples accordingly.

• Review the release metadata in pubspec.yaml (already configured in this repo):

  name: flawsnap
  description: In-app bug reporting for Flutter with annotated screenshots, device information, logs, and network request summaries.
  version: 0.0.1
  repository: https://github.com/RazyeshPersonal/snaplog-flutter-sdk
  

• The package uses the MIT License. Keep the license and copyright notice included when distributing the package.

• Update CHANGELOG.md for the version being released.

• Validate SDK and platform constraints against the versions you actually test. Do not lower them just to make dependency resolution succeed.

2. Run checks from the package root

flutter pub get
flutter analyze
flutter test
dart pub publish --dry-run

Resolve failures and review the upload file list, including example configuration. Keep credentials and local environment files out of the published archive. This repository includes .pubignore to exclude local configuration, credentials, and repository tooling. It overrides .gitignore for publication, so keep the exclusions in sync. A dry run does not upload the package.

3. Publish

dart pub publish

Follow authentication and confirmation prompts with the Google account that will own the package. A verified publisher can be used for an organization. Published versions generally remain available; review the archive before confirming.

Official reference: Publishing Dart packages.

4. Verify public installation

After publication, open https://pub.dev/packages/flawsnap and check the version and README. In a separate Flutter app, run:

flutter pub add flawsnap

Follow the setup example above and send a test report. Share the pub.dev package page with users; they do not need access to your Git repository for this installation.

5. Release updates

Increment version in pubspec.yaml for each release, record changes in CHANGELOG.md, repeat validation, and publish the new version. Existing versions cannot be overwritten. For example, use 0.0.2 for the next appropriate release. Consumers may need to update their version constraint before running flutter pub get; ^0.0.1 does not include 0.0.2.

Tests

flutter test