API Reference

Every public API in the Grovs Flutter plugin 3.0.0. The plugin exposes three imports:

import 'package:grovs_flutter_plugin/grovs.dart';                    // Grovs
import 'package:grovs_flutter_plugin/models/grovs_link.dart';        // parameter and result types
import 'package:grovs_flutter_plugin/grovs_navigator_observer.dart'; // GrovsNavigatorObserver

Grovs is a plain class with no state of its own; Grovs() is cheap and every instance talks to the same native SDK. Configuration happens through native config files, not Dart. See Quick Start.

Threading and call order

• Every method returns a Future that completes when the native side has accepted the call. generateLink, logInAppPurchase, and logCustomPurchase complete once the native SDK has finished the operation; the other methods complete as soon as the value is handed to the native SDK.
• A failed native call rejects the Future with a GrovsException, except getPlatformVersion, which lets the raw PlatformException through. See Error codes.
• The native SDK is configured before Dart runs, so there is no "not configured" state to wait for. Calls made while the SDK is disabled are handled as described in Privacy & Consent.

Properties

navigatorObserver

static GrovsNavigatorObserver get navigatorObserver

A shared GrovsNavigatorObserver for automatic screen tracking. Add it to MaterialApp.navigatorObservers. See Events & Screen Tracking.

screenAliases

static Map<String, String> get screenAliases

An unmodifiable view of the aliases last passed to setScreenAliases. Applied by GrovsNavigatorObserver to automatic screen views.

onDeeplinkReceived

Stream<DeeplinkDetails> get onDeeplinkReceived

A broadcast stream that emits a DeeplinkDetails for every resolved link, including deferred links matched after install. Up to 20 events received before the first listener subscribes are buffered and replayed to it. Nothing is emitted while the SDK is disabled. See Deep Linking.

onError

Stream<GrovsError> get onError

A broadcast stream of asynchronous native SDK errors. Fed by the iOS bridge only; on Android it never emits. On iOS the 20 most recent errors raised before the first listener subscribes are buffered. Events with an unknown error code are dropped. See Handling SDK errors.

Configuration

setSDK

Future<void> setSDK(bool enabled)

Turns collection on or off at runtime, for example when the user gives or withdraws consent. While disabled, the native SDK does not authenticate, read the clipboard, or send events, screen views, or purchases, and the plugin drops deep links. Enabling replays the link that launched the app while disabled. Calling it with the current state does nothing. The state is not persisted; set the initial state with GrovsEnabled / grovs_enabled. See Privacy & Consent.

setDebugLevel

Future<void> setDebugLevel(String level)

Sets the native SDK log level. 'info' logs everything; 'error' logs errors only. The value is case-insensitive, and any other value is treated as 'error'.

getPlatformVersion

Future<String?> getPlatformVersion()

The host OS version, such as "iOS 17.4" or "Android 14". Useful for smoke-testing that the plugin is registered.

User

setUserIdentifier

Future<void> setUserIdentifier(String identifier)

Your identifier for the current user, typically your app's user_id. Shown in the Grovs dashboard and reports. Held while the SDK is disabled and sent when it is enabled again.

setUserAttributes

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

Attributes describing the current user, shown in the dashboard. Values must be encodable by the Flutter platform channel (null, bool, num, String, List, string-keyed Map). Held while the SDK is disabled.

setPushToken

Future<void> setPushToken(String token)

The push token used to deliver notifications for messages sent from the dashboard: the APNs device token on iOS, the FCM registration token on Android. See Messages. Held while the SDK is disabled.

Links

generateLink

Future<String> generateLink(GenerateLinkParams params)

Creates a smart link and returns its URL. Throws GrovsException with code GENERATION_ERROR when the native SDK cannot generate the link, including while the SDK is disabled or not yet authenticated. See Link Creation for every parameter.

Revenue

logInAppPurchase

Future<void> logInAppPurchase(String transactionId)

Logs a platform store purchase. On iOS pass the StoreKit 2 transaction ID as a decimal string; a value that does not parse as an unsigned 64-bit integer throws GrovsException with code INVALID_ARGUMENT, and a purchase the native SDK could not log throws with PAYMENT_ERROR. On Android pass the Play Billing purchase's originalJson. See Revenue.

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. currency is an ISO 4217 code. startDate is sent as milliseconds since the epoch and honored on both platforms; when omitted, the native SDK uses the current time.

Events

track

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

Tracks a custom event. The name must not be empty or a reserved system event name. See Events & Screen Tracking for name rules, property rules, and limits.

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.

setGlobalTags

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

Tags merged onto every later event, or null to clear them.

setScreenAliases

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

Maps raw screen names to friendly dashboard names. Stored on the Dart side for GrovsNavigatorObserver and forwarded to the native SDK, which syncs it to the dashboard. See Screen name aliases.

Types

DeeplinkDetails

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

toMap() returns the same fields as a map, with tracking expanded to utm_campaign, utm_source, and utm_medium.

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,
  });
}

Parameters for generateLink. Every optional bool? uses the project default when null. See Link Creation.

TrackingParams

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

UTM parameters for link generation, and the tracking metadata of a received link.

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});
}

When openAppIfInstalled is true, the app opens if installed; otherwise url is always used.

TransactionType

enum TransactionType { buy, cancel, refund }

Used with logCustomPurchase.

GrovsError

class GrovsError {
  final GrovsErrorCode code;
  final String message;
}
 
enum GrovsErrorCode {
  authenticationFailed,   // 'authentication_failed'
  networkRequestFailed,   // 'network_request_failed'
  eventDispatchFailed,    // 'event_dispatch_failed'
  linkGenerationFailed,   // 'link_generation_failed'
}

Emitted on onError. GrovsErrorCode.nativeName is the snake-case name the native SDK reports, and GrovsErrorCode.fromNativeName maps a name back to a value, or null if it is unknown.

GrovsException

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

Thrown by every method when the native call fails. code is one of the error codes below, or null when the failure happened on the Dart side.

GrovsNavigatorObserver

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

Reports a screen view on didPush, didReplace (the new route), and didPop (the route revealed). Only PageRoute routes are reported. The name comes from screenNameExtractor, then RouteSettings.name, then the route's runtime type, and is translated through Grovs.screenAliases. See Automatic screen tracking.

Error codes

GrovsException.code values, as raised by the native bridges:

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

Native configuration keys

Read once at launch by the native bridges. See Quick Start for descriptions.