- 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
- 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.
- 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.
- The SDK sends events, registers the push token and fetches in-app items with the publishable key and the identity token.
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 examplecom.example.app. A key with app IDs and no origins works only
from your apps, never from a website.
With the CLI:
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 (scopescommerce:write, automations:trigger and
subscribers:write) and returns identityToken to the app:
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
- iOS
- Android
- React Native
- Flutter
Add the package The app ID defaults to the bundle ID. For push images and delivery reports,
add a Notification Service Extension target that links
https://github.com/Sequenzy/sequenzy-swift in Xcode
(File → Add Package Dependencies) and link the Sequenzy product to
your app.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 thesequence_*events) are rejected, so a device cannot fake a purchase. Send those from your backend with Track Event.
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.
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.
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, afteridentify (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:
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). LinkSequenzyLiveActivities 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
- In the
ios/project, add the Swift packagehttps://github.com/Sequenzy/sequenzy-swiftand link onlySequenzyLiveActivitiesto the app and the widget extension. Your JavaScript or Dart SDK stays the Sequenzy client. - Add the widget extension, the attributes type, the widget and Supports Live Activities, as in steps 1 to 4 of the guide.
- 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’sattributes.sequenzy.activityIdfor update tokens. Off-the-shelf Live Activity libraries use their own attributes type, so they cannot adoptSequenzyLiveActivityAttributes. - Pass each token to the SDK, and report when an activity ends:
- On sign-out, end the running activities, then call
Sequenzy.reset().
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×.
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 asx-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
identifyor 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: falseuntil the platform’s credentials are uploaded. On iOS, development builds need the Sandbox APNs environment.