Client SDKs
The Arsel client SDKs run inside your own app — a website, an Android app, or an iOS app — and do two things:
- Events and identity. Record what a person does (
product.viewed,added_to_cart) and who they are, without you writing queueing, retry, or session logic. - Push notifications. Register the device so Arsel can deliver notifications to it, and report back what happened to each one.
These are two independent subsystems. Events and identity work on a device that has never granted notification permission and has no push token at all — a visitor who declines notifications still has a contact and a behavioural history. Only delivery needs push.
Available SDKs
| Platform | Package | Requirements |
|---|---|---|
| Web | @arsel.sa/web-sdk — ESM + UMD, no dependencies | Chrome/Edge 79+, Firefox 72+, Safari 16.4+ |
| Android | sa.arsel:core + sa.arsel:push-fcm | minSdk 23, Firebase Messaging (push only) |
| iOS | Swift Package, zero dependencies | iOS 15+, Swift 5.10 |
All three SDKs follow Semantic Versioning. The public API and the wire contract are frozen within a major version — additive changes ship as minor releases, and anything breaking waits for the next major. A breaking change costs every integrator an app-store release, so they are rare by design.
Source code
Every SDK is open source under the MIT licence, and each repository is the reference for its own platform — versioned with the code you install, so it never describes a release you are not on. The platform pages above link straight into it.
| Platform | Repository |
|---|---|
| Web | BasicsEngage/arsel-web-sdk |
| Android | BasicsEngage/arsel-android-sdk |
| iOS | BasicsEngage/arsel-ios-sdk |
Issues and questions about an SDK are best raised on its own repository, where they sit next to the code.
Authenticating an SDK
Client SDKs authenticate with a client key, not an API key:
pub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
A client key is publishable — it is designed to be compiled into your app bundle or served in your page's JavaScript, exactly like a Google Maps or Stripe publishable key. It is not a secret, and it grants far less than a be_ API key: it can record events and register devices for your organization, and nothing else. It cannot read contacts, send campaigns, or manage your account.
Your be_ API key must never ship in client code. See Authentication for the full comparison.
For web, a client key is additionally constrained by an origin allowlist — you register the domains allowed to use it, and requests from anywhere else are rejected. Native apps send no Origin header and are not subject to it.
Find your client key in the Arsel Dashboard under Integration > Push, and see Setting Up Push for the rest of the configuration.
Binding a device to a known contact
Registering a device tells Arsel the device exists. Binding it to a contact tells Arsel whose device it is — which is what makes targeted campaigns possible.
The SDKs handle this themselves. Every registration carries the SDK's anonymous ID, so a device that registers before anyone signs in still resolves to the same contact its events are building — and when your app calls identify(), that contact merges forward.
If your backend already knows who is signed in and you would rather assert the binding from your server, read the installation ID from the SDK and call Register Device with your be_ API key. A server-asserted binding overrides the anonymous one.
Server-side alternatives
Everything the SDKs do has a server-side equivalent, which is the right choice when you are migrating existing device tokens or your app cannot embed an SDK:
| Task | Server endpoint |
|---|---|
| Record an event | Send Event |
| Register a device | Register Device |
| Revoke a device | Unregister Device |
| Inspect a contact's devices | List Contact Devices |
| Send to one contact | Send Push |
Delivered, opened, and clicked counts are reported by the SDK on the device. A device registered server-side without an embedded SDK still receives notifications, but contributes no delivery or engagement data — those metrics read zero for it. Register devices server-side for migration; embed the SDK for measurement.