checkpoint static method

void Function() checkpoint(
  1. String identifier,
  2. CheckpointPassed onPassed, {
  3. CheckpointParams params = const CheckpointParams(),
})

Registers that identifier was hit. Depending on the checkpoint's targeting rules, this may present a flow built in the RevenueCat dashboard (often a paywall) with the native SDK's UI.

onPassed is called at most once, only when the app can continue past the checkpoint. It is not called when the user backs out, when a blocking error occurs, or when another checkpoint already owns presentation. Treat a checkpoint as a callback rather than a pending operation to await. The SDK handles error presentation.

Returns a function that removes the callback. Call it when the owning screen is disposed; removing the callback does not dismiss a flow that is already on screen.

Requires iOS 15+ or Android, and Purchases to be configured. Throws an UnsupportedError on other platforms.

Experimental: Checkpoints are an invite-only API and may change or be removed in a future release without a major version bump.

@param identifier The checkpoint identifier, as configured in the RevenueCat dashboard. @param onPassed Called with the CheckpointResult when the checkpoint passes. @param params Optional per-call parameters, such as custom variables and the presentation mode.

Implementation

static void Function() checkpoint(
  String identifier,
  CheckpointPassed onPassed, {
  CheckpointParams params = const CheckpointParams(),
}) {
  if (kIsWeb ||
      (defaultTargetPlatform != TargetPlatform.iOS &&
          defaultTargetPlatform != TargetPlatform.android)) {
    throw UnsupportedError('Checkpoints require iOS 15+ or Android.');
  }

  // Native never replies when the user backs out, so the future below can stay
  // pending for the lifetime of the engine. Dropping the callback on removal
  // keeps that closure from retaining `onPassed` and whatever it captures.
  CheckpointPassed? callback = onPassed;
  _methodChannel.invokeMethod<Object?>('checkpoint', {
    'identifier': identifier,
    'customVariables': convertCustomVariablesToNative(
      params.customVariables,
    ),
    'presentationMode': params.presentationMode.toString(),
  }).then<void>((response) {
    final passed = callback;
    if (passed == null) return;
    callback = null;
    final CheckpointResult result;
    try {
      result = CheckpointResult.fromJson(
        Map<String, dynamic>.from(response as Map),
      );
    } catch (e) {
      debugPrint('RevenueCatUI: Error parsing the checkpoint result: $e');
      return;
    }
    try {
      passed(result);
    } catch (error, stack) {
      FlutterError.reportError(
        FlutterErrorDetails(
          exception: error,
          stack: stack,
          library: 'purchases_ui_flutter',
          context: ErrorDescription('while calling a checkpoint callback'),
        ),
      );
    }
  }).catchError((Object e) {
    debugPrint('RevenueCatUI: Error presenting checkpoint $identifier: $e');
  });
  return () => callback = null;
}