API reference

Grovs() is cheap: every instance talks to the same native SDK. Every method returns a Future that completes once the native SDK has the call, unless noted.

Imports

import 'package:grovs_flutter_plugin/grovs.dart';
import 'package:grovs_flutter_plugin/models/grovs_link.dart';
import 'package:grovs_flutter_plugin/grovs_navigator_observer.dart';

At a glance

Setup

The native SDK is configured before Dart runs, so there's no "not configured" state. See Quick Start.

Native configuration keys

Read once at launch by the native bridges.

setSDK

Future<void> setSDK(bool enabled)

Turns collection on or off at runtime, for example when consent changes. See Privacy & Consent.

• While disabled, the native SDK doesn't authenticate, read the clipboard, or send events, screen views or purchases. The plugin drops deep links.
• Enabling replays the link that launched the app while disabled.
• Setting the current state is a no-op.
• Not persisted. Set the initial state with GrovsEnabled / grovs_enabled.

setDebugLevel

Future<void> setDebugLevel(String level)

Sets the native log level: 'info' for everything, 'error' for errors only.

• Case-insensitive. Any other value means 'error'.

onError

Stream<GrovsError> get onError

Broadcast stream of asynchronous native SDK errors, as GrovsError. See Handling SDK errors.

• iOS only. On Android it never emits.
• iOS buffers the 20 most recent errors before the first listener.
• Unknown error codes are dropped.
• In-app display failures arrive on onInAppMessage as InAppMessageFailed, not here.

getPlatformVersion

Future<String?> getPlatformVersion()

Gets the host OS version, such as "iOS 17.4" or "Android 14". Useful to smoke-test plugin registration.

• The only method that lets the raw PlatformException through instead of GrovsException.

Deep links

onDeeplinkReceived

Stream<DeeplinkDetails> get onDeeplinkReceived

Broadcast stream of DeeplinkDetails for every resolved link, including deferred links matched after install, links passed to handleUrl and taps on Grovs pushes. See Deep Linking.

• Up to 20 events before the first listener are buffered and replayed to it.
• Nothing is emitted while disabled.
• For a push without a link, link is null. See What your app receives.

handleUrl

Future<bool> handleUrl(String url)

Resolves a Grovs link tapped inside your app. The system doesn't hand a universal link or App Link back to the app that opened it. The result arrives on onDeeplinkReceived. See Links tapped inside your app.

Returns true when the link was handed to the native SDK.

• url must be absolute, with a scheme and a host. Otherwise throws INVALID_ARGUMENT.
• Returns false without queuing the link while the SDK is disabled, and on Android when no activity is attached.

Users

setUserIdentifier

Future<void> setUserIdentifier(String identifier)

Sets your identifier for the current user, typically your user_id. Shown in the dashboard and reports.

• Held while the SDK is disabled.

setUserAttributes

Future<void> setUserAttributes(Map<String, dynamic> attributes)

Sets attributes of the current user, shown in the dashboard.

• Values must be platform-channel encodable: null, booleans, numbers, strings, lists, or maps with string keys.
• Held while the SDK is disabled.

Links

generateLink

Future<String> generateLink(GenerateLinkParams params)

Creates a smart link. Fields: GenerateLinkParams. See Link Creation.

Returns the URL. Completes when the native operation finishes.

• Throws GrovsException with GENERATION_ERROR when generation fails, including while disabled or unauthenticated.

linkDetails

Future<GrovsLinkDetails> linkDetails(String path)

Gets the details of a link by its path, the last part of the link (abc123 for https://yourapp.sqd.link/abc123). Pass the path only, not the full URL. See Link details.

Returns a GrovsLinkDetails.

• Throws INVALID_ARGUMENT when path is empty or whitespace, SDK_DISABLED while the SDK is disabled, and LINK_DETAILS_ERROR when the link isn't found or the request fails.

Events

See Events & Screen Tracking.

track

Future<void> track(
  String name, {
  Map<String, dynamic>? properties,
  List<String>? tags,
})

Tracks a custom event.

• The name can't be empty or a reserved system name.
• Rules and limits: Tracking custom events.

trackScreenView

Future<void> trackScreenView(
  String screenName, {
  Map<String, dynamic>? properties,
})

Tracks a screen view manually.

• The native SDK drops a repeat of the same screen within one second.

navigatorObserver

static GrovsNavigatorObserver get navigatorObserver

A shared GrovsNavigatorObserver for automatic screen tracking. See Automatic screen tracking.

MaterialApp(
  navigatorObservers: [Grovs.navigatorObserver],
)

setGlobalTags

Future<void> setGlobalTags(List<String>? tags)

Sets tags merged onto every later event. Pass null to clear them.

setScreenAliases

Future<void> setScreenAliases(Map<String, String> aliases)

Maps raw screen names to dashboard names. See Screen name aliases.

• Stored in Dart for GrovsNavigatorObserver and forwarded to the native SDK, which syncs it.

screenAliases

static Map<String, String> get screenAliases

Unmodifiable view of the aliases last passed to setScreenAliases. GrovsNavigatorObserver applies them to automatic screen views.

Revenue

See Revenue.

logInAppPurchase

Future<void> logInAppPurchase(String transactionId)

Logs a platform store purchase. Completes when the native operation finishes.

• On iOS, a value that isn't an unsigned 64-bit integer throws INVALID_ARGUMENT.
• A purchase the native SDK couldn't log throws PAYMENT_ERROR.

logCustomPurchase

Future<void> logCustomPurchase({
  required TransactionType type,
  required int priceInCents,
  required String currency,
  required String productId,
  DateTime? startDate,
})

Logs a purchase, cancellation or refund made outside the platform store. Completes when the native operation finishes.

Push notifications

setPushToken

Future<void> setPushToken(String token)

Sets the push token for push campaigns: the APNs device token on iOS, the FCM registration token on Android. See Push notifications.

• iOS: not needed. The plugin passes the APNs token once the app registers for remote notifications. Calling it still works, with one extra attributes update.
• Android: the plugin fetches the first FCM token when Firebase is present, and again on setSDK(true). Pass refreshes from onTokenRefresh.
• Held while the SDK is disabled.

isGrovsNotification

Future<bool> isGrovsNotification(Map<String, dynamic> data)

Checks whether Grovs sent a push, without handling it. Pass the push's data, for example RemoteMessage.data from firebase_messaging.

Returns true when the data has a non-empty grovs_campaign_id.

handleNotificationOpen

Future<bool> handleNotificationOpen(Map<String, dynamic> data)

Counts a tap on a Grovs push and opens its link. The push is delivered on onDeeplinkReceived. See Handling taps yourself.

Returns true when the data belongs to a Grovs push and the tap was handled. false for other pushes and while the SDK is disabled.

• Call it only from a tap handler, never when a push is delivered.
• Only when the native path isn't wired. On iOS, setting the notification center delegate and also calling this counts each tap twice.
• On Android, values in data are passed as strings.

In-app messages

See In-app messages.

onInAppMessage

Stream<InAppMessageEvent> get onInAppMessage

Broadcast stream of InAppMessageEvent: shown, clicked, dismissed, answered and failed.

• Up to 20 events before the first listener are buffered and replayed to it.
• On Android, events sent while no Flutter engine is attached are dropped. On iOS they're kept for the next engine.
• Nothing is emitted while disabled.
• Events with an unknown type or a missing required field are dropped.

pauseInAppMessages

Future<void> pauseInAppMessages()

Holds in-app messages back until resumeInAppMessages. The newest highest priority one waits.

resumeInAppMessages

Future<void> resumeInAppMessages()

Lets messages show again after pauseInAppMessages or discardInAppMessages, starting with the one that waited, if it still qualifies.

discardInAppMessages

Future<void> discardInAppMessages({bool dismissCurrent = false})

Drops the waiting message and stays paused. Call resumeInAppMessages to show new ones. With dismissCurrent: true, also closes the message on screen.

setInAppExcludedScreens

Future<void> setInAppExcludedScreens(List<String> screens)

Sets screens where no message shows. Messages wait until the user leaves.

• Matched against the names sent by trackScreenView and GrovsNavigatorObserver, after screen aliases are applied.
• Case is ignored.

setInAppDebugLogging

Future<void> setInAppDebugLogging(bool enabled)

Logs each campaign considered for an event and why it was skipped.

• On iOS, also call setDebugLevel('info') to see the logs.
• On Android, logs go to Logcat under the tag GrovsInApp, whatever the debug level.

Types

DeeplinkDetails

class DeeplinkDetails {
  final String? link;
  final Map<String, dynamic>? data;
  final TrackingParams? tracking;
}

A resolved deep link, emitted on onDeeplinkReceived.

• toMap() returns the same fields as a map, with tracking expanded to its three utm_ keys.

GenerateLinkParams

class GenerateLinkParams {
  GenerateLinkParams({
    required String title,
    String? subtitle,
    String? imageURL,
    Map<String, dynamic>? data,
    List<String>? tags,
    CustomRedirects? customRedirects,
    bool? showPreviewIos,
    bool? showPreviewAndroid,
    bool? copyToClipboardIos,
    bool? copyToClipboardAndroid,
    TrackingParams? tracking,
  });
}

Options for generateLink. See Link Creation.

GrovsLinkDetails

class GrovsLinkDetails {
  final int? id;
  final String? name;
  final String? path;
  final String? title;
  final String? subtitle;
  final String? image;
  final String? accessPath;
  final bool? active;
  final bool? sdkGenerated;
  final Map<String, dynamic>? data;
  final List<String>? tags;
  final DateTime? updatedAt;
  final bool? showPreviewIos;
  final bool? showPreviewAndroid;
  final String? generatedFromPlatform;
  final String? adsPlatform;
  final int? campaignId;
  final TrackingParams? tracking;
  final CustomRedirects? customRedirects;
  final Map<String, dynamic> raw;
}

The result of linkDetails.

• A field whose value has an unexpected type is null. Typed fields are the same on both platforms.

TrackingParams

class TrackingParams {
  TrackingParams({String? utmCampaign, String? utmSource, String? utmMedium});
}

UTM parameters for link generation, and a received link's tracking metadata.

CustomRedirects

class CustomRedirects {
  CustomRedirects({
    CustomLinkRedirect? ios,
    CustomLinkRedirect? android,
    CustomLinkRedirect? desktop,
  });
}

Per-platform redirect overrides for generateLink.

CustomLinkRedirect

class CustomLinkRedirect {
  CustomLinkRedirect({required String url, bool openAppIfInstalled = true});
}

One platform redirect. When openAppIfInstalled is true, the app opens if installed. Otherwise url is always used.

TransactionType

enum TransactionType { buy, cancel, refund }

Used with logCustomPurchase.

InAppMessageEvent

sealed class InAppMessageEvent {
  String? get campaignId;
}
 
final class InAppMessageShown extends InAppMessageEvent {
  final String campaignId;
}
 
final class InAppMessageClicked extends InAppMessageEvent {
  final String campaignId;
  final String? buttonId;
  final Map<String, dynamic>? payload;
}
 
final class InAppMessageDismissed extends InAppMessageEvent {
  final String campaignId;
  final InAppDismissReason reason;
}
 
final class InAppMessageAnswered extends InAppMessageEvent {
  final String campaignId;
  final Object value;
  final String? comment;
}
 
final class InAppMessageFailed extends InAppMessageEvent {
  final String? campaignId;
  final String message;
}

An event on onInAppMessage. Exported from grovs.dart. See React to messages.

InAppDismissReason

enum InAppDismissReason { closeButton, backdrop, swipe, app, orientation, unknown }

Why a message closed, on InAppMessageDismissed.

GrovsError

class GrovsError {
  final GrovsErrorCode code;
  final String message;
}

An SDK error, emitted on onError.

GrovsErrorCode

enum GrovsErrorCode {
  authenticationFailed,   // 'authentication_failed'
  networkRequestFailed,   // 'network_request_failed'
  eventDispatchFailed,    // 'event_dispatch_failed'
  linkGenerationFailed,   // 'link_generation_failed'
}

The category of a GrovsError.

• nativeName is the native snake-case name.
• GrovsErrorCode.fromNativeName maps a name back to a value, or null if unknown.

GrovsException

class GrovsException implements Exception {
  final String message;
  final String? code;
}

Thrown when a native call fails. Every method except getPlatformVersion uses it.

• code is one of the error codes, or null for a Dart-side failure.

Error codes

GrovsException.code values raised by the native bridges:

• On iOS the user, event and consent setters are fire-and-forget and never throw.

GrovsNavigatorObserver

class GrovsNavigatorObserver extends NavigatorObserver {
  GrovsNavigatorObserver({
    String? Function(Route<dynamic> route)? screenNameExtractor,
    Grovs? grovs,
  });
}

Reports a screen view for each route change. Use the shared Grovs.navigatorObserver, or construct one to customize names. See Automatic screen tracking.

• Only PageRoutes are reported.
• The name comes from screenNameExtractor, then RouteSettings.name, then the runtime type. It's translated through Grovs.screenAliases.