suggestly_flutter 0.2.2

suggestly_flutter: ^0.2.2 copied to clipboard

suggestly_flutter #

Reusable, fully themeable Material 3 dialogs that capture text input, feature requests, bug reports (including environment metadata and screenshots), and star ratings. Every popup respects accessibility, null safety, and text scaling and can be themed globally or per instance.

Features #

• SuggestlyFeatureRequestPopup - reproduces the Suggestly feature form with priority and version inputs.
• SuggestlyBugReportPopup - mirrors the Suggestly web bug report, collecting environment details and up to five validated screenshots via the built-in file picker.
• SuggestlyRatingPopup - star-based selector with optional comment and custom labels.
• Shared action model, barrier configuration, autofocus, and semantic labels for all popups.

Getting started #

Add the dependency to your pubspec.yaml (path assumes the monorepo layout):

dependencies:
  suggestly_flutter:
    path: ../suggestly.packages/suggestly_flutter

Then import the package:

import 'package:suggestly_flutter/suggestly_flutter.dart';

Before showing any Suggestly dialogs, initialise the shared client with your API key:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Suggestly.initialize(apiKey: 'YOUR-API-KEY-HERE');
  runApp(const MyApp());
}

Initialisation now validates the API key by fetching your application details. If the key is invalid, a SuggestlyApiException is thrown.

If you do not already store a Suggestly user ID for the signed-in customer, call Suggestly.ensureUserExists to create or retrieve one when starting a session:

final String userId = await Suggestly.ensureUserExists(
  email: currentUser.email,
  name: currentUser.displayName, // Optional; saved as an empty string when omitted.
);

Provide the current user's identity by passing their Suggestly userId whenever you present a popup. The service now looks up the name and email on demand using the stored profile; if a user record is missing a name, the dialogs will prompt for it and synchronise the update with Suggestly before submitting feedback.

Usage #

Feature requests #

final String userId = await Suggestly.ensureUserExists(
  email: currentUser.email,
  name: currentUser.displayName,
);

final SuggestlyPopupResult<FeedbackSubmissionResult> featureResult =
    await SuggestlyFeatureRequestPopup.show(
  context,
  title: 'Request a feature',
  message: 'Share what would make Suggestly more helpful.',
  userId: userId,
  submitLabel: 'Submit request',
);

if (featureResult.didSubmit) {
  debugPrint('We logged the feature request.');
} else if (featureResult.hasError) {
  debugPrint('Feature request failed: ${featureResult.errorMessage}');
}

Bug reports (with attachments) #

final SuggestlyPopupResult<FeedbackSubmissionResult> bugResult =
    await SuggestlyBugReportPopup.show(
  context,
  title: 'Report a bug',
  message: 'Screenshots are optional but recommended.',
  submitLabel: 'Send report',
  userId: userId,
);

if (bugResult.didSubmit) {
  debugPrint('Thanks for the report!');
} else if (bugResult.hasError) {
  debugPrint('Bug report failed: ${bugResult.errorMessage}');
}

The popup guides users through adding up to five screenshots using the built-in file_selector integration. Attachments are validated for file type and size, renamed deterministically, and uploaded alongside the report.

Ratings #

final SuggestlyPopupResult<FeedbackSubmissionResult> ratingResult =
    await SuggestlyRatingPopup.show(
  context,
  title: 'Rate your experience',
  message: 'Stars help us prioritise improvements.',
  userId: userId,
  ratingLabelBuilder: (value) => '$value / 5',
  submitLabel: 'Submit rating',
);

if (ratingResult.didSubmit) {
  debugPrint('Thanks for the feedback!');
} else if (ratingResult.hasError) {
  debugPrint('Rating failed: ${ratingResult.errorMessage}');
}

Collaborators can submit internal ratings while an application remains in Draft. Once it is live, the popups automatically prevent team members from rating their own product.

Example host app #

An interactive host application lives under example/ so you can exercise the dialogs without wiring them into your product first. Launch it with:

cd suggestly.packages/suggestly_flutter/example
flutter run

Demo mode boots instantly using the bundled in-memory client, and you can toggle eligibility for each popup to validate error paths. Switch to Live mode, paste a real Suggestly API key, and press Initialise to talk to your own backend.

Theming #

Wrap a subtree with TextInputPopupTheme to provide defaults that apply to every popup, or pass themeOverrides to individual dialogs:

TextInputPopupTheme(
  data: TextInputPopupThemeData(
    backgroundColor: Theme.of(context).colorScheme.surface,
    shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(24)),
    contentPadding: const EdgeInsets.fromLTRB(28, 28, 28, 20),
  ),
  child: Builder(
    builder: (context) => FilledButton(
      onPressed: () {
        SuggestlyFeatureRequestPopup.show(
          context,
          title: 'Request a feature',
          message: 'Tell us what would make Suggestly better.',
          userId: userId,
          themeOverrides: const TextInputPopupThemeData(
            primaryButtonStyle: FilledButton.styleFrom(
              minimumSize: Size(140, 40),
            ),
          ),
        );
      },
      child: const Text('Request feature'),
    ),
  ),
);

Additional information #

• flutter analyze and flutter test run clean.
• SuggestlyBugReportPopup owns the attachment workflow with file_selector, enforcing the same limits as the Suggestly web app (image formats only, up to five files, 5 MB each).
• Popups automatically prompt for a missing user name and update the stored Suggestly profile before sending feedback, ensuring submissions include the captured name.
• Contributions, issues, and suggestions are welcome.

Direct API access #

If you need to interact with the Suggestly service outside the prebuilt dialogs, the Suggestly class exposes the underlying client:

• Suggestly.ensureUserExists normalises email/name input and creates the user on-demand, returning the canonical user ID for use across dialogs.
• Suggestly.fetchFeedbackEligibility reads cached eligibility for one or more submission kinds, while Suggestly.ensureFeedbackEligibility refreshes it on demand, both keyed solely by the Suggestly userId.
• Suggestly.getApplicationSummary returns the branding metadata used across popups (name, logo, status).
• Suggestly.submitBugReport, Suggestly.submitFeatureRequest, and Suggestly.submitRating let you send feedback from fully custom flows using only the Suggestly userId.
• Suggestly.dispose clears in-memory caches and closes the internal HTTP client; call it when tearing down long-lived isolates or cleaning up tests.
• Suggestly.debugOverrideClient accepts a SuggestlyTestingClient (or your own fake) to intercept outbound traffic during automated testing.