Carillon docsSDK overview
Shared SDK methods, registration behavior, retries, and diagnostics.
Choose the SDK for your app:
| SDK | Requirements | Setup |
|---|---|---|
| Swift | iOS 15 or later | iOS integration |
| Kotlin | Android 7.0 or later | Android integration |
| React Native | React Native New Architecture; Expo plugin available | React Native integration |
Methods
| Call | What it does |
|---|---|
configure | Acquires the push token and registers the device, silently |
requestPermission | Shows the system dialogue and answers with the resulting state |
identify / clearIdentity | Sets or erases your own identifier for the person |
setTags | Replaces the device's tag map whole |
optIn / optOut | Your app's own switch, separate from the OS permission |
onOpened | A notification was tapped, with its payload |
onReceived | A notification arrived while the app was in the foreground; answer show or suppress within three seconds, or it is shown |
clearNotifications | Removes the app's delivered notifications from the notification centre or tray |
deviceId (getDeviceId in React Native) | The Carillon device ID from the last successful registration, or null before one |
onDeviceIdChanged | The device ID was assigned or changed; silent when a registration keeps the same ID |
debugInfo | Returns registration state and diagnostics |
Registration and permission
configure() starts registration without displaying a permission prompt.
Call requestPermission() separately when your app should ask to display notifications.
The SDK sends the resulting permission state on the next registration.
The Kotlin permission method takes an Activity. Swift and React Native require no argument.
Registration and retries
The SDK computes a fingerprint of the device state and calls POST /v1/devices only when it has
changed. So a cold start that changed nothing costs no request, while turning notifications off in
Settings, updating the OS or installing a new build all re-register by themselves.
Repeated registration updates the same device. One registration is in flight at a time; the latest device state is used for the next attempt.
Retries are on network failures, 429 and 5xx, with backoff from one second up to five minutes.
Never on another 4xx, which would fail the same way on every attempt.
What is collected
Everything on the devices page, and nothing else.
Not collected: advertising identifiers, the carrier, IP geolocation, screen metrics, battery state and the device model.
Debug logging
configure(key:debug:) turns on verbose logging: every registration attempt and its result, event
queue flushes, HTTP status and the error detail, token changes, and the environment as detected.
It cannot be enabled in a production build. On iOS the logging paths are compiled out under a
release build. On Android the flag is refused at runtime when the application is not debuggable. A
debug: true forgotten in shipped code therefore logs nothing.
debugInfo() returns diagnostics in all builds. Inspect it when registration or open tracking fails.
Versions and compatibility
The SDKs follow semver. Their public surface is under the same rule as the public API: additive only. An SDK ships inside your binary and cannot be updated from our side.
The version in each installation snippet is the one the SDK repository targets. Check the repository's tags or the package registry for the versions actually available before pinning one; a version that is not tagged there is not installable yet.