Integration

suprsend_flutter_sdk is used to integrate SuprSend into your Flutter application. v3 currently ships user identification and Mobile Push; event tracking, user channel methods, and the other features of the native SDKs are not yet available in Flutter. It wraps the native SuprSend Android and iOS SDKs.

This is v3 of suprsend_flutter_sdk. Documentation for v2 of this SDK is available here. If you are upgrading from v2, refer the migration guide.

Installation

Add the SDK to your pubspec.yaml:

pubspec.yaml

dependencies:
  suprsend_flutter_sdk: ^3.0.0

shell

flutter pub get

Requirements: iOS 15.0+, Android minSdk 19.

For iOS, set the deployment target in ios/Podfile and then run pod install from the ios/ directory.

ios/Podfile

platform :ios, '15.0'

Integration steps

Step 1: Create client instance

Initialize the SuprSend client inside main. All the methods of SuprSend SDK can be accessed only after creating the instance.

Dart

import 'package:suprsend_flutter_sdk/suprsend_flutter_sdk.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  SuprSend('YOUR_PUBLIC_KEY');

  runApp(const MyApp());
}

Parameter	Description
publicKey*	Required. Your workspace public key from the SuprSend dashboard (ApiKeys → Public Keys).
host	Optional. Custom SuprSend API host; only needed for self-hosted or region-specific setups.

Step 2: Authenticate user

Authenticate the user so that all the actions performed after authenticating will be w.r.t that user. This is a mandatory step and needs to be called before using any other method. This is usually performed after successful login and on reload of the app to re-authenticate the user (can be changed based on your requirement).

Dart

await SuprSend.identify(
  'user-distinct-id',
  userToken: jwt, // only needed in production environments for security
  tenantId: 'tenant-id', // only needed in multi-tenant workspaces
  refreshUserToken: (oldUserToken, tokenPayload) async {
    return await myBackend.fetchSuprSendToken();
  },
);

Properties	Description
distinctId*	Unique identifier to identify a user across platform.
userToken	Mandatory when enhanced security mode is on. This is an ES256 JWT token generated on your server-side. Refer docs to create userToken.
tenantId	Needed only when your workspace has multiple tenants/brands. Scopes the identified user’s activity to that tenant. Its value must match scope.tenant_id in the userToken payload, else it raises a scoping error.
refreshUserToken	This function is called by the SDK internally to get a new userToken when the existing user token is expired. The returned string is used as the new userToken.

Step 3: Reset user

This will remove user data from the SuprSend instance, similar to a logout action.

Dart

await SuprSend.reset();

Change active tenant

Use the below method to switch the active tenant of the identified user.

Dart

await SuprSend.changeTenant('tenant-id');

Logging

Add the below code in main below the SuprSend instance creation to see logs for debugging.

Dart

await SuprSend.enableLogging();

API response

identify and reset return SSResponse. Use it to check whether a call succeeded and to read error details when it didn’t.

Dart

final response = await SuprSend.identify('user-distinct-id');
if (response.isSuccess) {
  // handle success
} else {
  print('${response.errorType}: ${response.errorMessage}');
}

Property	Description
status	"success" or "error".
isSuccess	true when the call succeeded (convenience getter over status).
statusCode	HTTP status code, when available.
errorType	Error category, e.g. VALIDATION_ERROR, NETWORK_ERROR.
errorMessage	Human-readable error message.