Skip to main content

Flutter SDK Reference

This page is a comprehensive API reference for the OpenLynk Flutter SDK. For a step-by-step integration walkthrough, see the Flutter Integration Tutorial.

Installation​

Add the SDK to your pubspec.yaml:

dependencies:
  openlynk_sdk:
    git:
      url: https://github.com/openlynk-sdk/openlynk-flutter.git
      ref: main

Run flutter pub get after adding the dependency.

The SDK depends on the following packages (resolved automatically):

  • http
  • shared_preferences
  • device_info_plus
  • app_links

OpenlynkSDK Constructor​

OpenlynkSDK({
  required String appId,
  required String apiKey,
  String baseURL = 'https://openlynk.io',
  OpenlynkSDKConfig config = const OpenlynkSDKConfig(),
})
ParameterTypeRequiredDefaultDescription
appIdStringYes—Your app ID from the OpenLynk dashboard
apiKeyStringYes—Your API key (format: ol_...)
baseURLStringNohttps://openlynk.ioAPI base URL
configOpenlynkSDKConfigNoOpenlynkSDKConfig()SDK configuration options

Methods​

MethodReturnsDescription
init()Future<void>Start listeners, restore pending links, process cold-start link
dispose()voidStop the deep link listener
createLink({destination, metadata})Future<CreatedLink>Create a shareable deep link
parseDeepLink(Uri uri)Future<ParsedDeepLink?>Parse a deep link URL manually
getLinkBySlug({slug, hostname})Future<LinkDetails>Fetch link details by slug
restorePendingLinks({userEmail})Future<List<RestoredLink>>Restore deferred links by email
restorePendingLinksForAnonymous()Future<List<RestoredLink>>Restore deferred links using device fingerprint
registerPushToken(token, {userEmail})Future<void>Register an FCM token for push notifications
handlePushPayload(data)Future<void>Process push notification payload data

OpenlynkSDKConfig​

const OpenlynkSDKConfig({
  bool autoRestoreOnInit = true,
  Future<String?> Function()? userEmailProvider,
  void Function(List<RestoredLink>)? onRestoredLinks,
  void Function(ParsedDeepLink)? onDeepLink,
})
PropertyTypeDefaultDescription
autoRestoreOnInitbooltrueAutomatically restore pending links when init() is called
userEmailProviderFuture<String?> Function()?nullAsync function that returns the current user's email for deferred deep linking
onRestoredLinksvoid Function(List<RestoredLink>)?nullCallback invoked when deferred links are restored
onDeepLinkvoid Function(ParsedDeepLink)?nullCallback invoked when a deep link opens the app

What init() Does​

Calling init() performs the following steps in order:

  1. Install heartbeat — sends a heartbeat to the OpenLynk API, reporting that the SDK is installed on this device. Throttled server-side to once per 24 hours.
  2. Restore pending links — if autoRestoreOnInit is true, calls restorePendingLinks() or restorePendingLinksForAnonymous() depending on whether userEmailProvider returns an email. Fires the onRestoredLinks callback with any matches.
  3. Start link listener — begins listening for incoming deep links using the app_links package. When a link arrives, it is parsed and the onDeepLink callback fires.
  4. Process cold-start link — checks if the app was launched via a deep link (cold start). If so, parses the link and fires onDeepLink.
tip

Call init() as early as possible in your app lifecycle, typically in your root widget's initState().

Callback-Based Alternatives​

For cases where you prefer callbacks over async/await, the SDK provides callback-based versions of key methods:

Async MethodCallback Alternative
createLink()createLinkWithCallback(destination, metadata, callback)
restorePendingLinks()restorePendingLinksWithCallback(userEmail, callback)
restorePendingLinksForAnonymous()restorePendingLinksForAnonymousWithCallback(callback)

Error Handling​

All async methods throw exceptions on failure. Wrap calls in try-catch:

try {
  final link = await sdk.createLink(
    destination: '/product/123',
    metadata: {'campaign': 'summer'},
  );
} catch (e) {
  print('Failed to create link: $e');
}

Common errors:

ErrorCause
Network errorDevice is offline or API is unreachable
Invalid app IDThe appId does not match any app in OpenLynk
Invalid destinationThe destination parameter is empty or malformed
Rate limit exceededToo many API calls in a short period (HTTP 429)

Platform Setup​

The Flutter SDK uses Universal Links on iOS and App Links on Android. You must configure these in your native project:

warning

Deep links will not work without completing platform-specific setup. The SDK can create and restore links without it, but incoming link handling requires Universal Links or App Links to be configured.

What's Next?​