Using Superwall Deep Links

A Superwall Deep Link is a URL hosted at https://<subdomain>.superwall.app/app-link/... that opens your app to trigger a paywall as configured on the Superwall dashboard, or custom in-app behavior via the Superwall delegate.

Prerequisites

2. Create a Web Checkout app, even if you do not plan to charge through Web Checkout, this provisions the *.superwall.app domain that powers Superwall Deep Links.

Handling incoming links

• Always call handleDeepLink first. It returns true when the SDK recognizes the URL and plans to take over presentation, or false when you should continue routing inside your own app.
• When a recognized link arrives before Superwall.configure(...) finishes, the SDK caches it and replays it immediately after configuration completes, so it is safe to forward links during cold launch.
• If the return value is false, continue with your normal router—those links are not associated with any Superwall experience.

Future<void> _handleIncomingLink(Uri uri) async {
  final handled = await Superwall.shared.handleDeepLink(uri);
  if (!handled) {
    _routeInternally(uri);
  }
}

void _listenForLinks() {
  uriLinkStream.listen((uri) {
    if (uri != null) {
      _handleIncomingLink(uri);
    }
  });
}

Link formats and campaigns

Deep link URLs are hosted at https://<subdomain>.superwall.app/app-link/..., you can have anything after the /app-link/ path, including query parameters. These values will be availble to you in audience filters on the Superwall dashboard, or in the handleSuperwallDeepLink delegate method.

class PaywallDelegate extends SuperwallDelegate {
  @override
  void handleSuperwallDeepLink(
    Uri fullURL,
    List<String> pathComponents,
    Map<String, String> queryParameters,
  ) {
    if (pathComponents.isEmpty) {
      return;
    }

    switch (pathComponents.first) {
      case 'campaign':
        final placementId =
            pathComponents.length > 1 ? pathComponents[1] : null;
        if (placementId != null) {
          _routeToPlacement(placementId, queryParameters);
        }
        break;
      default:
        break;
    }
  }
}

Keep your own routing logic in place for non-Superwall URLs and for any additional behaviors you want to stack on top of Superwall’s default presentation flow.