AlgorithmX
Integrations22 min read

Flutter Integration

Add AlgorithmX to your Flutter app step by step: install the plugin, start it, identify customers, send events, connect push notifications, and open the right screen from campaigns.

Flutter SDK 1.1.1: uses native SDKs 1.1.0, SDK-generated anonymous/device IDs, and API-based in-app delivery. Push integration uses FCM tokens on both iOS and Android.

This guide adds AlgorithmX to your Flutter app in 8 steps. You keep your app's login, push setup, and navigation. You only add a few lines in places your app already has.

The plugin algorithmx_flutter already contains the Android and iOS SDKs, so it is the only thing you install. The work has two parts:

  • A few native lines in Android and iOS. They start the SDK and pass push notifications to it. This must be native, because a notification can start your app before Dart runs.
  • Everything else in Dart: customers, events, and navigation.

In the examples, names such as appRouter are your own code, not part of the plugin.

Start with one platform and one test customer, then repeat the checks on the other platform. The native sections prepare Android and iOS to receive pushes; the Dart sections connect your customer and screen logic. A successful Dart call is one checkpoint, and seeing its event in AlgorithmX is the next.

Before you start

Check that you have these:

  • Flutter 3.19 or later.
  • Android: minSdk 24 or higher, and Firebase Cloud Messaging set up.
  • iOS: iOS 15 or later, Firebase Cloud Messaging configured, and Apple push signing/capabilities set up.
  • The API base URL from AlgorithmX, for example https://api.example.com.
  • Your partner ID from AlgorithmX, for example your-partner-id. The SDK sends it with every SDK API request.
  • The list of customer ID, events, deep links, and custom actions you agreed on with AlgorithmX. See the overview.

Follow Connect Firebase and Send a Test. Register the Android and iOS apps separately in Firebase, using google-services.json and GoogleService-Info.plist in their respective targets. Upload one service-account JSON to AlgorithmX for the project containing both apps. Configure the iOS APNs key, Key ID, and Team ID in Firebase.

The steps

StepWhat you doWhere
1Install the pluginpubspec.yaml
2Start the SDKAndroid Application, iOS AppDelegate, Dart main()
3Tell AlgorithmX who the customer isLogin, app start, logout
4Send eventsWhere actions happen, such as checkout
5Connect push notificationsYour Firebase code and iOS AppDelegate
6Open the right screenDart main()
7Check in-app campaignsNo code
8TestReal Android and iOS phones

Step 1: Install the plugin

This step adds the Dart API and its native implementation. Finish the build check before changing startup or push handling, so you know the plugin itself is installed correctly.

From your app's folder, run:

bash
flutter pub add algorithmx_flutter

This adds the plugin to your pubspec.yaml:

yaml
dependencies:
  algorithmx_flutter: ^1.1.1

The plugin does not add Firebase; your app keeps its own push setup. To update later, raise the version and run flutter pub get. Release notes are on pub.dev.

Check: flutter pub get finishes, and the app still builds for Android and iOS.

Step 2: Start the SDK

You start the SDK in three places: Android, iOS, and Dart. Use the same URL and partner ID in all three.

2a. Android

In your Application class:

kotlin
import algorithmx.engage.core.AlgorithmX
import algorithmx.engage.flutter.AlgorithmXFlutterPlugin

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        AlgorithmXFlutterPlugin.initializeForBackground(this, "https://api.example.com", "your-partner-id")
        AlgorithmX.setSmallIcon(R.drawable.ic_stat_notification) // Optional: your notification icon.
        // Keep your existing startup code.
    }
}

Flutter apps have no Application class by default. If yours has none, create this file next to MainActivity, and register it in android/app/src/main/AndroidManifest.xml:

xml
<application
    android:name=".MyApplication"
    ...>

2b. iOS

In application(_:didFinishLaunchingWithOptions:) of your AppDelegate, before return super...:

swift
import algorithmx_flutter

AlgorithmXFlutterPlugin.initializeForBackground(apiBaseUrl: "https://api.example.com", partnerId: "your-partner-id")
UNUserNotificationCenter.current().delegate = self // Keep yours if you already set it.
application.registerForRemoteNotifications() // On every launch.

For delivery reports (step 5, optional part), use initializeForBackground(apiBaseUrl: "https://api.example.com", partnerId: "your-partner-id", appGroup: "group.com.example.shop") instead.

2c. Dart

In main(), set your handlers from step 6 first, then connect Dart to the SDK, before runApp:

dart
import 'package:algorithmx_flutter/algorithmx_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final sdk = AlgorithmX.instance;

  // 1. Set your handlers from step 6 here.

  // 2. Connect Dart to the SDK that native code already started.
  await sdk.initialize(apiBaseUrl: 'https://api.example.com', partnerId: 'your-partner-id');

  runApp(const MyApp());
}
  • initialize fails if its URL or partner ID is different from the native one.
  • Handlers before initialize: taps that happen before Dart is ready, such as the tap that started the app, are kept and delivered when initialize runs. If your handlers are not set yet, they miss them.
  • To see each SDK request while testing, call AlgorithmX.setLoggingEnabled(true) (Android) or AlgorithmX.shared.setLoggingEnabled(true) (iOS) in the native code.

Check: the app starts on both platforms without an error from initialize.

Step 3: Tell AlgorithmX who the customer is

The SDK generates and stores an anonymous UUID and a separate installation device UUID during startup. You do not generate either ID or call the bootstrap endpoint yourself. The anonymous UUID stays the same across app restarts and login; events continue to use it in X-Anonymous-Id.

Use the stable account ID from your application's backend when the customer signs in. The SDK sends it as ExternalId, allowing AlgorithmX to resolve the same customer across devices. AlgorithmX manages its own internal profile ID.

Call the identity function after login and when starting with a signed-in customer. Email and phone become trusted identifiers; supported profile fields are sent separately to /Customer/Ingest.

dart
await AlgorithmX.instance.identifyUser('customer_123', attributes: {
  'email': '[email protected]',
  'firstName': 'Amina', 'lastName': 'Hassan',
  'emailOptIn': true, 'smsOptIn': false, 'pushOptIn': true,
  'gdprAccepted': true, 'whatsAppOptIn': false,
});

Supported identifier fields are email, phone, and userName; your application's userId becomes ExternalId. Supported profile fields are firstName, lastName, gender, dateOfBirth, registeredAt, emailOptIn, smsOptIn, pushOptIn, gdprAccepted, and whatsAppOptIn. Send dates as ISO 8601 text and consent fields as booleans.

Send a complete profile. /Customer/Ingest replaces these traits: omitted text/date fields are cleared and omitted consent fields become false. Include all current values whenever you send profile fields through identify / identifyUser or setUserProfile. An identify call containing only identifiers does not send a profile update.

Fields such as plan, language, country, and loyaltyTier are not supported customer traits by these endpoints. The SDK rejects unsupported fields. Send arbitrary business data with trackEvent; that records event data and does not create custom profile fields.

To update profile fields later, pass profile, your application's complete current customer profile object, without email, phone, or userName:

dart
await AlgorithmX.instance.setUserProfile(profile);

On logout:

dart
await AlgorithmX.instance.resetIdentity();

Logout clears waiting campaigns, generates a fresh anonymous UUID and bootstraps a new anonymous profile. The installation's device UUID is retained. Calling identify with a different account ID also rotates the anonymous UUID first, preventing the two accounts from being merged. Close any campaign already on screen as part of your app's logout flow.

To inspect the SDK-generated UUID for diagnostics:

dart
final anonymousId = await AlgorithmX.instance.getAnonymousId();

The SDK remembers the external account ID across restarts. These calls do not replace your application's authentication. API requests are sent in order, but the backend responds with 202 Accepted and processes messages asynchronously; confirm the stored customer data in AlgorithmX. Offline event/profile requests are dropped. Bootstrap and saved account identification are attempted again on startup/foreground; profile updates must be sent again by your app if delivery failed.

Check: the customer can be found using the external ID/email you supplied, and the anonymous UUID is unchanged after login. After logout or switching accounts, it changes.

Step 4: Send events

Choose one action you can easily repeat while testing, such as opening a product. Confirm its event arrives before adding all your business events. The campaign team will use these names and details, so agree on them together.

Send an event right after an action succeeds, for example after an order is confirmed. Put it next to your existing analytics calls.

dart
await AlgorithmX.instance.trackEvent('productView', properties: {'productId': 'SKU-123'});

await AlgorithmX.instance.trackEvent('addToCart', properties: {'productId': 'SKU-123', 'quantity': 2});

await AlgorithmX.instance.trackEvent('purchase', properties: {
  'orderId': 'ORDER-1001',
  'total': 149.90,
  'currency': 'SAR',
  'items': [
    {'productId': 'SKU-123', 'quantity': 2},
  ],
});

Rules for events:

  • Event transport: general events use POST /api/v1/Event/Log, with the event name in eventType, properties in data, and an ISO 8601 UTC timestamp. The SDK sends an array and adds the required partner and anonymous-ID headers automatically. See the request contract.

  • Values: use text, numbers, true/false, lists, and maps. Send dates as a timestamp or an ISO 8601 string. Do not send your own Dart objects.

  • Names and keys: use AlgorithmX's camelCase naming approach, such as addToCart and productId. Custom names and keys are sent as supplied; their casing is not enforced or normalized.

  • Offline: an event sent without internet is lost. It is not sent again later. Keep your own backend as the record of orders and payments.

Check: the event appears for the customer in AlgorithmX.

Step 5: Connect push notifications

This step gives AlgorithmX the phone's push address and a way to process its messages. Treat token registration and message delivery as separate checks: receiving a token does not by itself prove that a push can reach the app.

You keep your push setup. On each platform you send the push token to AlgorithmX and pass AlgorithmX notifications to the SDK.

5a. Firebase messaging in Dart

Choose the case that matches your app.

Case 1: your app uses the firebase_messaging plugin. Initialize Firebase using your app's existing FlutterFire setup before this code, and keep its iOS method swizzling enabled as required by FlutterFire. After AlgorithmX initialization, register FCM tokens on both platforms. Forward received Android messages from Dart; iOS message handling stays in native callbacks from step 5b.

dart
import 'dart:io' show Platform;
import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:algorithmx_flutter/algorithmx_flutter.dart';

bool _isAlgorithmX(RemoteMessage message) =>
    message.data['engageAction'] == 'algoShowNotification' ||
    message.data['engageAction'] == 'algoTriggerWebview';

Future<bool> _forwardToAlgorithmX(RemoteMessage message) async {
  if (!Platform.isAndroid || !_isAlgorithmX(message)) return false;
  await AlgorithmX.instance.handleFcmMessage(
    message.data.map((key, value) => MapEntry(key, value.toString())),
    notificationTitle: message.notification?.title,
    notificationBody: message.notification?.body,
  );
  return true;
}

Future<bool> registerCurrentFcmToken() async {
  // Apple registration must finish before requesting an iOS FCM token.
  if (Platform.isIOS && await FirebaseMessaging.instance.getAPNSToken() == null) {
    return false;
  }
  final token = await FirebaseMessaging.instance.getToken();
  if (token == null || token.isEmpty) return false;
  await AlgorithmX.instance.registerDeviceToken(token);
  return true;
}

@pragma('vm:entry-point')
Future<void> firebaseBackgroundHandler(RemoteMessage message) async {
  if (await _forwardToAlgorithmX(message)) return;
  // Your existing background code.
}

Future<void> wireFirebaseMessaging() async {
  FirebaseMessaging.onBackgroundMessage(firebaseBackgroundHandler);
  FirebaseMessaging.onMessage.listen((message) async {
    if (await _forwardToAlgorithmX(message)) return;
    // Your existing foreground code.
  });

  FirebaseMessaging.instance.onTokenRefresh.listen(AlgorithmX.instance.registerDeviceToken);
  await registerCurrentFcmToken();
}
  • The background handler does not need initialize; step 2a already started the SDK.
  • Do not add your own FirebaseMessagingService next to firebase_messaging. Android gives each message to only one of them.
  • Call wireFirebaseMessaging() once at app startup and handle errors in your existing startup flow. If Apple registration is not ready, registerCurrentFcmToken() returns false; retry that helper after registration/your permission flow and on foreground resume. Do not install the listeners again. See FlutterFire's Apple requirements.
  • Keep one existing background handler and initialize Firebase there if your other background processing uses Firebase services. Do not forward the iOS AlgorithmX message again from Dart.

Case 2: your app has its own native FirebaseMessagingService. Add the AlgorithmX check at the top, exactly as in step 5 of the Android guide:

kotlin
override fun onMessageReceived(message: RemoteMessage) {
    super.onMessageReceived(message)
    if (AlgorithmX.isAlgorithmXPush(message.data)) {
        AlgorithmX.handleFcmMessage(
            applicationContext, message.data,
            message.notification?.title, message.notification?.body
        )
        return
    }
    // Your existing code for other messages.
}

override fun onNewToken(token: String) {
    super.onNewToken(token)
    AlgorithmX.registerDeviceToken(token)
}

Then also send the token on every app start, in Application.onCreate:

kotlin
FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
    AlgorithmX.registerDeviceToken(token)
}

In both cases, keep your own notification permission prompt; the SDK never asks for permission.

Native Firebase alternative on iOS: if your Flutter app uses Firebase directly in Swift instead of FlutterFire, follow the native iOS FCM token setup. Add FirebaseCore/FirebaseMessaging and the matching plist, configure Firebase once after AlgorithmX startup, and add MessagingDelegate to AppDelegate. Use these callbacks in the FlutterAppDelegate subclass:

swift
import FirebaseMessaging
import algorithmx_flutter

override func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    Messaging.messaging().apnsToken = deviceToken
    Messaging.messaging().token { token, error in
        if let error = error { print("FCM token registration failed: \(error.localizedDescription)") }
        if let token = token, !token.isEmpty {
            AlgorithmX.shared.registerDeviceToken(token)
        }
    }
    super.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
}

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
    guard let token = fcmToken, !token.isEmpty else { return }
    AlgorithmX.shared.registerDeviceToken(token)
}

Use one owner for FCM token registration. Do not install this native messaging delegate over FlutterFire's delegate when using the Dart route above.

5b. iOS

In a Flutter app, your AppDelegate extends FlutterAppDelegate. Add these methods (or add the AlgorithmX lines if you already have them). Everything else still goes to super.

swift
// Background notifications. API-based in-app campaigns do not require this callback.
override func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
    if AlgorithmX.shared.isAlgorithmXPush(userInfo: userInfo) {
        AlgorithmX.shared.handleNotification(userInfo: userInfo) { completionHandler(.newData) }
        return
    }
    super.application(application, didReceiveRemoteNotification: userInfo, fetchCompletionHandler: completionHandler)
}

// A notification arrives while the app is open.
override func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    willPresent notification: UNNotification,
    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
) {
    let userInfo = notification.request.content.userInfo
    if AlgorithmX.shared.isAlgorithmXPush(userInfo: userInfo) {
        AlgorithmX.shared.handleNotification(userInfo: userInfo) { completionHandler([.banner, .list, .sound]) }
        return
    }
    super.userNotificationCenter(center, willPresent: notification, withCompletionHandler: completionHandler)
}

// The customer taps a notification or a button.
override func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    let userInfo = response.notification.request.content.userInfo
    if AlgorithmX.shared.isAlgorithmXPush(userInfo: userInfo) {
        AlgorithmX.shared.handleNotificationResponse(
            actionIdentifier: response.actionIdentifier,
            userInfo: userInfo,
            completionHandler: completionHandler
        )
        return
    }
    super.userNotificationCenter(center, didReceive: response, withCompletionHandler: completionHandler)
}
  • AlgorithmX here is the iOS SDK inside the plugin. import algorithmx_flutter gives you access to it.
  • Register the FCM token using the Dart or native route in step 5a. Preserve Flutter/Firebase's Apple registration forwarding; do not send the hexadecimal APNs token to AlgorithmX.
  • Turn on Background Modes, Remote notifications in Xcode. Enable this for background push processing; API-based in-app views work without it.
  • To install on an iPhone without Xcode attached, use a release or profile build. Flutter debug builds only run with the debugger.
  • API-based in-app views: normal SDK startup handles fetching and display. Push callbacks and Remote notifications are only needed for your push/background notification integration.

Check: use the dashboard test form with each app's current FCM token. Then send an AlgorithmX campaign to check native message handling, actions, and reporting on both platforms.

Optional rich notifications on iOS

For AlgorithmX images and action buttons in iOS notifications, create or reuse a Notification Service Extension in your Flutter app's iOS project. The extension can also report delivery and impressions with a shared App Group. Basic notifications, taps, background push callbacks, and API-based in-app campaigns work without it.

The extension is a separate iOS target. This Swift Package Manager example links AlgorithmXSDK; Flutter apps copy the plugin's standalone helper into that target instead.
Xcode showing a separate Notification Service Extension target for rich iOS notifications

The extension is a separate iOS target. This Swift Package Manager example links AlgorithmXSDK; Flutter apps copy the plugin's standalone helper into that target instead.

  1. Open ios/Runner.xcworkspace in Xcode. Create a target with File → New → Target → Notification Service Extension, or reuse an existing extension. Configure its bundle identifier, deployment version, and signing, and confirm the app embeds it.
  2. Get EngageNotificationService.swift from the installed algorithmx_flutter plugin at ios/algorithmx_flutter/Sources/algorithmx_flutter/NativeSDK/Notifications/EngageNotificationService.swift. Find the plugin's installed location in .dart_tool/package_config.json. Flutter SDK 1.1.1 retains the native 1.1.0 helper, so you can also download the same helper directly from AlgorithmX, or open its Flutter 1.1.1 release source.
  3. Add this file in Xcode with Copy items if needed and only the extension target selected. Keep Xcode's NotificationService.swift; the helper is an additional file. Do not add the whole Flutter plugin to the extension.
  4. Follow the extension handler example, omitting import AlgorithmXSDK. It calls EngageNotificationService.isAlgorithmXPush and processNotification, leaving other notifications on their existing path.
  5. For delivery reports, enable the same App Group on the app and extension targets, pass it to AlgorithmXFlutterPlugin.initializeForBackground(apiBaseUrl:partnerId:appGroup:), and use the matching group in the extension helper call. Images and buttons alone can use the overload without an App Group.

Refresh the copied helper from the installed plugin when upgrading it. Test on an iPhone that AlgorithmX image/button notifications and unrelated notifications both work.

Step 6: Open the right screen when a customer taps

Think of a campaign action as a destination request. The SDK tells your app where the customer wants to go, and your existing router decides how to open that screen. Agree on the supported destinations before your campaign team uses them.

When a customer taps an AlgorithmX notification, the plugin calls your Dart handlers. They open your screens and return true when they handled the tap.

HandlerWhen it runsWhat to do
onDeepLinkThe campaign opens a screen with a link.Open the link with your router.
onCustomActionThe campaign runs a custom action.Open the screen for that action.
onActionButtonClickedThe customer taps a notification button.Handle the button and return true.
onNotificationClickEvery tap, before the campaign's action.Optional. Leave it unset so the SDK runs the campaign's action.

"Open a web page" and "open an in-app campaign" need no handler; the SDK does them.

Set the handlers in main(), before initialize (step 2c):

dart
sdk.onDeepLink = (url) => appRouter.openUrl(url);

sdk.onCustomAction = (action, data) {
  final details = data['parsedActionData'];
  if (action == 'viewProduct' && details is Map && details['productId'] is String) {
    return appRouter.openProduct(details['productId'] as String);
  }
  if (action == 'viewCart') return appRouter.openCart();
  return false;
};

sdk.onActionButtonClicked = (event) {
  if (event.actionText == 'viewCart') return appRouter.openCart();
  return event.actionText == 'dismiss';
};
  • Answer fast. The SDK waits up to 5 seconds for each answer. Start the navigation and return; do not wait for network calls.
  • Wait for your navigator. When a tap starts the app, the handlers run before your first frame. Keep the destination and open it when your navigator is ready, for example in a post-frame callback.
  • Handle every button you offer. If the button handler returns false, iOS runs the notification's main action instead, and Android does nothing. Return true for each button your campaigns use.
  • Match buttons on their action text, not their title, because the title can be translated.
  • You do not need new links or screens. Give your campaign team the links and action names your released app supports, for example myapp://open/product?id=SKU-123.
  • Keep your normal login and permission checks before sensitive screens: a campaign only suggests where to go.

Check: send a test notification for each link, action, and button your app supports. The right screen opens once.

Step 7: Check in-app campaigns

Production backend support is pending: the .NET in-app delivery route must be implemented as described in AlgorithmX issue #207. Current device tests use in-app-test-backend; no .NET implementation is included in this SDK update.

In-app campaigns use the API in SDK 1.1.0. Initialise the SDK and identify a signed-in customer; no campaign-fetch code, silent push, push token, or notification permission is needed for this flow.

  1. The SDK bootstraps its anonymous profile and device automatically.
  2. On startup or returning to the foreground, it calls GET /api/v1/inAppViews?language=...&customerId=....
  3. The backend checks the customer's segment, campaign publication/schedule and language, and returns eligible inline HTML, CSS, JavaScript, translations and variation parameters.
  4. The SDK selects a stable variation, applies priority, frequency, expiry and app-enter delay, and displays at most one campaign per visit. The template supplies its close button; Android also supports Back.

The SDK supplies X-Partner-Id, its persistent UUID in X-Anonymous-Id, and the installation UUID in X-Device-Id. Before login, customerId is the anonymous UUID. After identify / identifyUser, it is your application's account ID, stored by AlgorithmX as ExternalId. The backend resolves the internal profile ID; your app does not pass an AlgorithmX profile UUID. Identification, logout and account changes invalidate old campaign requests and content. Signed-in variation selection and local display history use the account ID.

Language defaults to the device/app language. Override it only when your app has its own language selector:

dart
await AlgorithmX.instance.setInAppLanguage('ar');

An empty language override restores the automatic default. Arabic, Hebrew, Persian and Urdu translations use RTL layout; text and placeholder translations are applied from the template's builderState.translations.

First check: publish an active campaign that matches your test customer's segment and language, open the app, and confirm the GET request and impression. Leave the app and return to check another visit. Impressions, clicks, submits, copies and closes are logged through POST /api/v1/Event/Log as inAppViewInteraction; campaign and variation UUIDs remain strings.

The automatic mobile flow supports app-enter campaigns and an optional time delay. Browser URL/scroll/exit/inactivity rules and custom triggers are excluded by the backend from this automatic feed. Display history is stored on the installation; this is not a global cross-device frequency counter.

GET requests follow queued identity/profile POSTs. When identity is still processing (409), the SDK retries up to three times, and it retries again when connectivity returns or the app re-enters the foreground. Normal event/profile requests remain fire-and-forget. The old silent-push algoTriggerWebview is ignored. Visible push notifications retain their separate integration.

Step 8: Test before you release

Keep a test customer and the campaign team ready for this final pass. Check both what the person sees on the phone and what AlgorithmX records. Testing only the screen or only the server leaves half of the journey unchecked.

Use real Android and iOS phones and a test customer. Test release builds, not only debug builds. On iOS, repeat the main checks with a TestFlight build, because store builds use a different Apple push server.

  • Update while logged in: install your current store version, log in, then update to the new build. The customer is recognized without logging in again.
  • Login, restart, logout, second account: events use the right customer each time. No campaign from the first account appears for the second.
  • Your existing notifications and other push plugins still work exactly as before.
  • AlgorithmX notification with the app open, in the background, and closed: a tap opens the right screen once, also when the tap starts the app.
  • Each deep link, custom action, and button opens the right screen.
  • In-app campaign: the SDK fetches it and it appears when the app opens and closes with its close button.
  • Notifications turned off: in-app campaigns still arrive.
  • Events appear for the customer in AlgorithmX.

SDK endpoints

You do not need to write HTTP calls for these endpoints in your app; the SDK sends them when you use its APIs. This reference helps you or your backend team inspect requests during testing.

These paths are relative to your configured apiBaseUrl. SDK API requests include the x-partner-id header.

MethodEndpointPurpose
GET/api/v1/inAppViewsFetch eligible inline campaigns automatically with language, account/anonymous ID and identity headers.
POST/api/v1/Identity/BootstrapCreate or restore the SDK-generated anonymous profile and device.
POST/api/v1/IdentityLink ExternalId and trusted identifiers to the anonymous profile.
POST/api/v1/Customer/IngestReplace supported customer profile fields.
POST/api/v1/Event/LogTrack a custom event or automatic in-app view interaction.
POST/api/v1/tracks/algoViewInteractTrack a manual preview or visible-push interaction.
PUT/api/v1/inAppPushEvents/device/statusUpdate notification status.
POST/api/v1/notificationTokensRegister a push token.

trackEvent posts a one-event array to /api/v1/Event/Log: [{ eventType, data, timestamp }]. data contains the supplied properties or {}; timestamp is ISO 8601 UTC. In SDK 1.1.0, X-Anonymous-Id always contains the SDK-generated anonymous UUID, including after login. Identity requests use anonymousId and trustedIdentifiers, not fingerprintDevice, previousFingerprintDevice, or an attributes object on the wire. The SDK separates profile fields into /Customer/Ingest and adds X-Anonymous-Id and X-Device-Id to that request. All requests include X-Partner-Id.

API-based in-app view interactions use /api/v1/Event/Log with eventType: "inAppViewInteraction". Manual previews, visible-push interactions, token registration and notification status retain their existing transport contracts and need separate backend endpoint support. API templates are inline; manual preview HTML and notification images use GET requests to supplied URLs.

For a custom backend route, trackCampaignInteraction(endpoint: ...) can override the campaign interaction endpoint.

Quick reference

CallWhat it does
AlgorithmXFlutterPlugin.initializeForBackground(this, apiBaseUrl, partnerId) (Android)Starts the SDK in Application.onCreate.
AlgorithmXFlutterPlugin.initializeForBackground(apiBaseUrl:partnerId:appGroup:) (iOS)Starts the SDK in the AppDelegate. The App Group is optional.
AlgorithmX.instance.initialize(apiBaseUrl:, partnerId:)Connects Dart to the SDK. Call it after setting handlers, with the same URL and partner ID.
setUserProfile(profile)Replace supported customer fields with the complete current profile.
setInAppLanguage(language)Optional override of automatic device/app language.
getAnonymousId()Read the SDK-generated anonymous UUID.
identifyUser(userId, attributes:)Sets the customer. Call at login and app start.
resetIdentity()Goes back to an anonymous customer. Call at logout.
trackEvent(name, properties:)Sends an event.
registerDeviceToken(token)Sends an FCM registration token from Dart on Android or iOS.
handleFcmMessage(data, notificationTitle:, notificationBody:)Android: gives an AlgorithmX message received in Dart to the SDK.
onDeepLink, onCustomAction, onActionButtonClicked, onNotificationClick, onCampaignInteractionYour handlers. Set them before initialize.
clearWebViewQueue()Removes waiting in-app campaigns. Call at logout.
getDeviceFingerprint(), getWebViewQueueSize()Show the current customer ID and waiting campaigns, for testing.

The native calls in step 5 are the same as in the Android and iOS guides.

Something not working?

ProblemWhat to check
initialize failsDart and native code use a different URL or partner ID. Use the same values in all three places of step 2.
No events in AlgorithmXThe native code in step 2 runs with the right HTTPS URL and partner ID, and the phone is online.
No AlgorithmX notificationsSee "Something not working?" in the Android or iOS guide: token, sending permission, and passing messages to the SDK.
Android messages stop reaching firebase_messagingA second FirebaseMessagingService was added. Keep only one.
A tap does not reach DartHandlers are set before initialize, and the native code in step 2 starts the SDK.
A tap that starts the app opens nothingYour router keeps the destination until the navigator is ready.
A button does nothing, or opens the main action on iOSYour button handler has no case for that action text and returned false.
In-app campaign never appearsCheck SDK startup, connectivity and the GET response. Publish an active app-enter campaign matching the customer segment and language; check frequency and expiry.
A previous account's campaign appearsCall clearWebViewQueue() at logout and when switching accounts.

Next steps

Create your first campaigns with In-App Push Campaigns and In-App View Campaigns. Go back to the overview for other platforms.