Skip to main content
The Sequenzy mobile SDKs connect your app to the contact it belongs to. With one SDK in your app you can:
  • Link the installation to a contact when the user signs in.
  • Track custom events that start sequences, like workout_completed.
  • Register the device for push notifications and report opens.
  • Show in-app messages (modal, banner or full screen) and list content cards in your own screens.
The React Native SDK is plain TypeScript, so it runs in Expo Go without a custom build.

How it works

  1. A publishable key identifies your workspace. It ships inside your app, so it is not a secret. You restrict it to your app’s bundle ID and package name.
  2. When a user signs in, your backend mints a short-lived identity token for their email with your secret API key. The app hands that token to the SDK. Only your backend can mint one, so a person can only ever read and write their own contact.
  3. The SDK sends events, registers the push token and fetches in-app items with the publishable key and the identity token.
Never put a secret API key (seq_live_...) in an app.

1. Create an app key

Go to Settings → Integrations → Publishable keys and choose Create key. Under Allowed app IDs, add your iOS bundle ID and your Android package name, for example com.example.app. A key with app IDs and no origins works only from your apps, never from a website. With the CLI:
The SDKs send the app ID in the x-sequenzy-app-id header. Apps cannot prove who they are, so the app ID list keeps your key from being reused by mistake; identity tokens are what protect contact data.

2. Mint identity tokens on your backend

When a user signs in, your backend calls Mint Identity Token with a secret API key (scopes commerce:write, automations:trigger and subscribers:write) and returns identityToken to the app:
Minting also creates the contact if it does not exist yet. Tokens last 24 hours by default (ttlHours, up to 720). Give the SDK an identity token provider, a function that asks your backend for a fresh token, and it renews expired tokens by itself. If your iOS and Android apps use different keys, mint each token for the key that app uses. The provider must not call the SDK itself; it times out after 20 seconds, and after a failure the SDK waits a minute before asking again. On Firebase, a callable Cloud Function can mint the token instead of a backend; see Firebase.

3. Add the SDK

Add the package https://github.com/Sequenzy/sequenzy-swift in Xcode (File → Add Package Dependencies) and link the Sequenzy product to your app.
The app ID defaults to the bundle ID. For push images and delivery reports, add a Notification Service Extension target that links SequenzyNotificationService and contains:

Events

track(name, properties) records a custom event on the signed-in contact. Events start sequences with an Event received trigger, and their properties work in merge tags such as {{event.minutes}}.
  • Names are up to 100 characters: letters, digits, spaces and _ . : - /.
  • Properties are a JSON object: up to 50 keys, nested at most 4 levels, 8 KB in total.
  • Built-in event names (saas.purchase, ecommerce.*, email.*, push.*, in_app.*, contact.*, tag.*, sms.*, web.*, poll.* and the sequence_* events) are rejected, so a device cannot fake a purchase. Send those from your backend with Track Event.
Events tracked before identify wait on the device and are sent once the user signs in. Events with properties that are not JSON (for example NaN or a date object) or larger than 8 KB are dropped when you call track, with an error in the SDK log. Event times come from the device clock, so a device more than 5 minutes fast has its events rejected. The SDK keeps up to 100 events, drops events older than 24 hours, sends them in batches of 20 and retries with backoff when the device is offline. Every event has an ID, so a retry never records it twice.

Screens

screen(name, properties) records the built-in Screen Viewed event (app.screen_viewed) with screen and your properties. Use it for screens you want to segment or start sequences on, such as pricing or checkout. Custom events cannot use the app. prefix.

Products and carts

The same storefront events as the web SDK, so browse and cart abandonment work in apps: A product needs providerProductId (your product ID); title, imageUrl, url, price or priceCents and currency make abandonment emails richer. These events wait in the same queue as track and are sent once the user is signed in.

Profile

setProfile sets the signed-in contact’s first name, last name and custom attributes. Attributes merge into the ones the contact already has; pass null for a name or an attribute to clear it. Like events, changes wait on the device until the user is identified and are retried when the device is offline; later calls merge into the pending change.
Platform-owned values are rejected: email, firstName and lastName as attribute names, Stripe billing attributes such as mrr and stripeCustomerId, and internal. A user can only change their own contact, but they can change it, so set anything that grants access or money (plan, credits) from your backend instead.

Signups

For people who are not signed in, such as a newsletter or waitlist screen, subscribe adds an email through a published Sequenzy signup form: the form’s lists, tags, duplicate handling and double opt-in apply, as they do on a website. It does not identify the device.
Forms with bot protection send app signups a confirmation email, because an app cannot run the browser check. Signups are rate limited per IP address and per email address.

Push notifications

Upload your APNs key and Firebase service account first, as described in Push notifications. Registering a device before then works, and it starts receiving push once the credentials are in place. The SDK registers the token when it changes, after identify (which links the device to the contact) and at least once a day. On iOS the Notification Service Extension reports deliveries for pushes with an image; pushes without one are counted when they are opened. reset() unregisters it, so a shared device stops receiving the previous user’s notifications. When the user taps a notification, the SDK reports the open and opens its link or deep link.

Asking for push permission

Each registration carries the device’s notification permission (granted, provisional, ephemeral, denied or not_determined), and the SDK registers again when it changes, for example after the user turns notifications on in Settings. Sequenzy uses it for the app opt-in rate in Settings > Push and for the contact’s pushPermission attribute, which holds the most permissive status across their devices. Push primers ask for permission from an in-app message. The iOS and Android SDKs handle them on their own: iOS uses UNUserNotificationCenter, and Android 13+ shows the system prompt through an invisible activity the SDK adds. You can also ask from your own UI:
React Native and Flutter have no built-in permission API, so pass your notifications library’s calls. Without pushPermission the SDK reports no permission and your app receives no push primers.
Sequenzy.requestPushPermission() is available on every platform. After the contact allows notifications, hand the new token to the SDK as usual.

Live Activities

iOS apps can show Live Activities that your backend starts, updates and ends through Sequenzy. You build the Live Activity UI in a Widget Extension as usual, and the SDK reports the ActivityKit push tokens. The Live Activities guide covers the Xcode setup step by step, with a test you can run on your iPhone. iOS (Swift). Link SequenzyLiveActivities to the app and the widget extension, adopt SequenzyLiveActivityAttributes in your attributes, and call observeLiveActivities once per type right after configure:
DeliveryAttributes.swift (app and widget extension)
AppDelegate.swift
React Native and Flutter. The widget and ActivityKit are Swift, so:
  1. In the ios/ project, add the Swift package https://github.com/Sequenzy/sequenzy-swift and link only SequenzyLiveActivities to the app and the widget extension. Your JavaScript or Dart SDK stays the Sequenzy client.
  2. Add the widget extension, the attributes type, the widget and Supports Live Activities, as in steps 1 to 4 of the guide.
  3. Write a small native module that observes ActivityKit and sends each token to JavaScript or Dart as lowercase hex (data.map { String(format: "%02x", $0) }.joined()), together with the activity’s attributes.sequenzy.activityId for update tokens. Off-the-shelf Live Activity libraries use their own attributes type, so they cannot adopt SequenzyLiveActivityAttributes.
  4. Pass each token to the SDK, and report when an activity ends:
  1. On sign-out, end the running activities, then call Sequenzy.reset().
In Flutter use LiveActivityToken.pushToStart(...) and LiveActivityToken.update(...) with the same fields. Every SDK stores the tokens, sends them again on identify so they link to the contact, and on reset() unlinks them and keeps only the push-to-start tokens for the next user. If a different user signs in without reset(), only the push-to-start tokens move to them. A newer token for the same activity type or activity replaces the stored one. The iOS SDK also ends the running activities on reset() and reports activities that ended while the app was closed; in React Native and Flutter, end your activities on sign-out yourself. Android has no Live Activities.

In-app messages and cards

Every SDK draws messages to the same design as the preview in the step composer:
  • Modal: a sheet that rises from the bottom (swipe down or tap outside to close), or a centered dialog. On tablets a sheet is drawn as a dialog.
  • Banner: a floating card under the status bar or above the home indicator that does not block the app; swipe it toward its edge to close it.
  • Full screen: the whole screen, with buttons at the bottom.
  • An image sits above the text, or behind it with the text on a dark gradient.
  • The first link button is filled with your button color; a second button is plain text.
  • Animations follow the system’s Reduce Motion setting, and text follows the system text size up to 1.4×.
After identify, and whenever the app comes to the foreground, the SDK fetches open messages and shows them one at a time, styled with the colors, corners and font from the step’s Design tab. While the app stays open it checks again every minute, so a message started by something the user just did shows up without leaving the app. Shown, clicked and dismissed messages are reported for the step’s stats. To decide yourself when a message may appear, return false from the SDK’s shouldShow callback; the message waits for the next check. To show messages with your own UI, turn off automatic display and use fetchMessages() with report(). Content cards are for an inbox or feed screen. Each SDK returns them with fetchCards() (pinned first). React Native (useInAppCards and InAppCard) and Flutter (InAppCardsController and InAppCardView) include a ready-made card view that reports clicks and dismissals; call markRead when a card scrolls into view. On iOS and Android, draw cards in your own list and report read, clicked and dismissed with report().

Custom HTML messages

Custom HTML messages (surveys, Braze-style custom HTML) show full screen in a sandboxed web view, after the document has loaded. Their JavaScript bridge closes the message, opens links through your URL handler, and logs events and attributes for the signed-in contact. If your app switches over the message format (Swift InAppMessage.Format, Kotlin InAppMessage.Format, the React Native format type), add a case for html when you upgrade. Apps that show messages themselves get HTML messages only when they ask: fetchMessages(includeHtml: true) in Swift and Flutter, fetchMessages(includeHtml = true) in Kotlin, and fetchMessages({ includeHtml: true }) in React Native. On iOS and Android the SDK uses the system font unless the step’s font is installed in your app. In React Native, pass fonts to SequenzyInAppHost and InAppCard to map brand font names to fonts your app bundles.

Geofences

Report when the signed-in contact enters or leaves your geofences with the geofencing add-on of each SDK: SequenzyGeofences (iOS), com.sequenzy:sequenzy-android-geofences (Android), @sequenzy/react-native-geofences and sequenzy_flutter_geofences. They watch the nearest geofences natively and report visits also while the app is not running. Setup is in Geofences.

Client endpoints

The SDKs call these endpoints. You only need them to build your own client. Every call sends the publishable key as x-sequenzy-key (or publicKey in the body) and the app ID as x-sequenzy-app-id, and identified calls add email and identityToken to the body. Registering with an email links the device to that contact, creating it if needed; without one the device stays anonymous and keeps any link it already had. Possessing the push token is what authorizes removing it. An event’s type is custom (the default), screen (recorded as app.screen_viewed; properties.screen is required) or commerce (name is product_viewed, product_added_to_cart, product_removed_from_cart, cart_viewed, collection_viewed or search_submitted, and properties carries product, cartLine, cart, collection or searchQuery as the web SDK sends them) or geofence (transition is enter or exit and geofenceId names one of your active geofences; recorded as app.geofence_entered or app.geofence_exited, see Geofences). A geofence event for a paused or deleted geofence is rejected; a repeat inside the geofence’s cooldown, or past 100 transitions per contact per day, is accepted and ignored. /api/v1/geofences/nearby rounds the position to two decimals (about 1 km) before using it and neither stores nor logs it. It answers 503 when geofences cannot be loaded; retry later. /api/v1/app-events judges events one by one: a 202 lists the events it rejected (a built-in name, an occurredAt more than 24 hours old or in the future, invalid properties) and records the rest. A client should drop the whole batch after a 202 and retry it, with the same event IDs, after a network error or a 408, 425, 429 or 5xx.

Troubleshooting

  • 403 “App is not allowed for this web tracking key”: add the app’s bundle ID or package name under Allowed app IDs. Changes apply within about a minute.
  • Events or the feed do nothing after sign-in: the SDK has no identity token. Pass one to identify or set an identity token provider; with debug logging on, the SDK says which is missing.
  • Device registered but no push arrives: the registration response has pushConfigured: false until the platform’s credentials are uploaded. On iOS, development builds need the Sandbox APNs environment.