AlgorithmX
Integrations11 min read

Integrations

Start here: what the AlgorithmX SDK does in your app, what to prepare, and which guide to follow for Android, iOS, Flutter, or React Native.

SDK 1.1.0: these APIs use SDK-generated anonymous/device IDs and API-based in-app delivery. Existing 1.0.x integrations should follow the updated identity and profile instructions below.

These guides cover native Android and iOS SDK 1.1.0, Flutter 1.1.1, and React Native 1.1.1. Their identity, customer ingestion, and general event requests match the AlgorithmX Ingress backend. Push sending uses Firebase Cloud Messaging (FCM) for both iOS and Android.

The AlgorithmX SDK connects your mobile app to AlgorithmX. Once it is in your app, your marketing team can send push notifications and in-app campaigns to your customers, and see how customers respond.

You add the SDK to the app you already have. You keep your login, your push notification setup, and your navigation. You only add a few lines of code in places your app already has.

Start with one small test

Your first goal is to recognize one test customer and see one event arrive in AlgorithmX. Once that works, connect push delivery and test a campaign. This gives you a clear result at each stage, instead of adding everything and wondering which part needs attention.

There are two sides to prepare: your app configures Firebase and supplies its FCM token, and AlgorithmX needs permission to send through that Firebase project. Upload one service-account JSON for its iOS and Android apps in the dashboard. For iOS, configure Apple's APNs credentials in Firebase. Follow Connect Firebase and Send a Test for the files and dashboard steps.

What the SDK does

  • Knows who the customer is. You tell it when a customer logs in or out.
  • Records what customers do. You send events such as "product viewed" or "purchase".
  • Shows push notifications that your team creates in AlgorithmX, with images and buttons.
  • Shows in-app campaigns: an API-delivered message fetched and displayed when the customer opens or returns to the app.
  • Opens the right screen when a customer taps a notification or a campaign button.
  • Reports results: deliveries, views, clicks, and closes.

Words used in these guides

WordMeaning
Customer IDThe ID your own backend uses, for example customer_123. AlgorithmX stores it as ExternalId and manages a separate internal profile ID.
EventSomething the customer did, such as addToCart or purchase, with optional details.
FCM registration tokenFirebase's address for one app installation on iOS or Android. Pass the current and refreshed token to AlgorithmX; it can change and is separate from a customer ID.
In-app campaignA message that appears inside your app, over the current screen.
Deep linkA link that opens a screen in your app, for example myapp://open/product?id=SKU-123.
Custom actionA named action your app knows, for example viewCart, that a campaign can trigger.
API base URLThe address of the AlgorithmX server for your company. AlgorithmX gives it to you.
Partner IDYour company's ID at AlgorithmX. AlgorithmX gives it to you. The SDK sends it in the x-partner-id header of every SDK API request.

The steps, on every platform

Every platform guide follows the same steps. Most take only a few lines of code.

  1. Install the SDK from your platform's package manager.
  2. Start the SDK when your app starts.
  3. Tell AlgorithmX who the customer is at login and logout.
  4. Send events when customers do important things.
  5. Connect push notifications: pass the push token and AlgorithmX notifications to the SDK.
  6. Open the right screen when a customer taps a notification.
  7. Check in-app campaigns: they need no code, only a few checks.
  8. Test on real phones before you release.

Choose your platform

Your app is built withPackage to installGuide
Android (Kotlin or Java)cloud.algorithmx:android-sdk from Maven CentralAndroid guide
iOS (Swift)AlgorithmXSDK with Swift Package Manager or CocoaPodsiOS guide
Flutteralgorithmx_flutter from pub.devFlutter guide
Expo SDK 55 with Expo Notifications@algorithmxcloud/react-native-sdk from npmExpo guide
React Native@algorithmxcloud/react-native-sdk from npmReact Native guide

All packages are public and free to install. The iOS SDK source is at github.com/algorithmx-cloud/algorithmx-ios-sdk.

Expo users can configure SDK startup and API-based in-app campaigns through the plugin. Its automatic iOS token path still registers an APNs token and does not complete the current FCM push integration. For iOS push, follow the React Native Firebase/native Firebase path and preserve native changes through your app's configuration. Both routes use the same JavaScript API for customers, events, and navigation.

Before you start

What AlgorithmX gives you

  • The API base URL for each environment, for example one for testing and one for production.
  • Your partner ID. You pass it to the SDK together with the API base URL.

What you give AlgorithmX

Upload one Firebase service-account JSON in Settings → In-App Integration. It covers the iOS and Android apps in the connected Firebase project. Your app sends its FCM registration tokens through the SDK.

Keep the mobile Firebase configuration files in their matching app targets: google-services.json for Android and GoogleService-Info.plist for iOS. Upload the Apple APNs key, Key ID, and Team ID to Firebase, where iOS delivery is configured. These files and identifiers are explained in Connect Firebase and Send a Test.

What to agree on with your AlgorithmX contact

Write these down before you start coding. Your developers and your campaign team both need them.

  • Customer ID: which ID you send. Use the same one your backend uses.
  • Events: the list of event names and their details, for example purchase with orderId and total.
  • Deep links: the links your app can already open, for example myapp://open/cart.
  • Custom actions: the action names your app supports, for example viewCart, and their details.

Campaigns can only use links and actions that your released app supports. Your campaign team uses this list when they create campaigns.

SDK endpoints

The SDK sends these requests for you when you use its APIs. Keep this reference handy when checking your server logs or discussing the integration with your backend team.

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 example, trackEvent("productView", { productId: "SKU-123" }) sends this JSON body:

json
[
  {
    "eventType": "productView",
    "data": { "productId": "SKU-123" },
    "timestamp": "2026-10-07T12:00:00.000Z"
  }
]

This records the supplied custom event. Agree separately on event names and data required for backend cart, order, search, or listing processing.

Native Android, iOS, and Flutter integrations can optionally override the campaign interaction endpoint.

Identity and profile request bodies

The SDK makes these requests; clients do not generate anonymous or device IDs. Startup sends /api/v1/Identity/Bootstrap with { anonymousId, deviceId, userAgent }, where both IDs are UUIDs and userAgent contains operating system/device information.

For a signed-in customer, /api/v1/Identity receives:

json
{
  "anonymousId": "a781ba16-c6fb-469d-83fb-2d2cc0eb0057",
  "trustedIdentifiers": {
    "ExternalId": "customer_123",
    "Email": "[email protected]",
    "Phone": "+905315013673"
  }
}

/api/v1/Customer/Ingest receives supported profile fields directly:

json
{
  "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.

Bootstrap and identify require X-Partner-Id. Customer ingestion and event logging also require X-Anonymous-Id; customer ingestion includes the UUID in X-Device-Id. The SDK keeps the anonymous UUID on login and generates a fresh one on logout/account switch. The backend returns 202 Accepted for asynchronous processing, which does not confirm that data is stored. Bootstrap/identity and profile ingestion use separate backend queues, so the SDK's HTTP ordering does not guarantee consumer processing order; verify persistence and resend a complete profile if it was not stored.

Automatic API-based in-app views

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:

ts
AlgorithmX.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.

After the integration

Use a test account you can recognize in AlgorithmX, and keep the phone nearby. Work through this sequence with your campaign team:

  1. Log in, so the SDK knows the customer.
  2. Do something that sends an event.
  3. Ask your campaign team to send a test notification and a test in-app campaign.
  4. Tap the notification and its buttons, and check that the right screen opens.
  5. Check that your existing notifications and screens still work as before.

Then continue with In-App Push Campaigns and In-App View Campaigns to create your first campaigns.