Setup Push Notifications (Native Apps)
Push notifications are triggered on various transactional events (such as a order confirmation) or by backend marketing or informational processes.
The system sends push via Firebase Cloud Messaging (FCM) This doc is the client-side integration checklist in case you want to implement that push messaging yourself: one required baseline, plus optional add-ons you only build if you want that feature. The optional pieces are independent of each other — none require another to already be in place.
If the shop wants to send push through its own provider instead, see external push provider — this document is about receiving the platform's own push in a native app.
Overview (see Details below)
- provide oekobox-online with your iOS App bundle ID, Team ID and APNs Authentication Key
.p8file (Apple developer platform → Certificates, Identifiers & Profiles → Keys → create one with the "Apple Push Notifications service (APNs) for Sandbox & Production" capability enabled) along with the Keys ID - provide oekobox-online with your Android package name
- oekobox-online will issue you a
google-services.jsonandGoogleService-Info.plitfor Android and iOS respectively - oekobox-online will issue you a API key for iOS and Android seperately, only used for identification (not authentication) of the apps used by the device registration endpoint
Provided by obox
- A Firebase App registered under the shared project for your package name (Android) /
bundle ID (iOS), and the resulting
google-services.jsonorGoogleService-Info.plist. - An API key (
x-oo-apikey) identifying your specific app build — required onregisterpushtokencalls (see step 4 below); a missing or unrecognized one is rejected withinvalid_apikey, nothing gets registered. This is a per-app-build identifier, not a login credential — bake it into your build config, don't ask a user for it. Ifwhitelabel-ios,whitelabel-android,esst.bio-ios,esst.bio-android(or any future app) are separate builds, request a separate key for each — it's what lets obox tell which app product a device belongs to.
You don't add your own Firebase project — everything is scoped by the config file you're given.
Required from you, for iOS only — APNs Authentication Key
Push to iOS goes through Firebase → APNs, and Firebase can't reach APNs without an Authentication Key that only you can generate: it comes from your Apple Developer account (Certificates, Identifiers & Profiles → Keys → create one with the "Apple Push Notifications service (APNs)" capability enabled). It's tied to your Apple Developer Team ID, not to obox's Firebase project, so obox can't create it on your behalf.
Generate it and send us the .p8 file plus its Key ID and your Team ID — we'll upload it
to the shared Firebase project's Cloud Messaging settings. This has to happen before push will
actually deliver to iOS devices; it doesn't block starting the SDK integration work below, but
don't leave it until the end.
Required — Bare push
Title + body notification, tap opens the app.
- Add the Firebase Cloud Messaging SDK to your build (Gradle for Android, CocoaPods/SPM for iOS) and drop in the config file you were given.
- Initialize Firebase at app startup.
- Request notification permission from the OS — Android 13+ needs the runtime
POST_NOTIFICATIONSpermission, iOS needs theUNUserNotificationCenterprompt. Skip this and a successfully delivered push just never shows. - Implement the token listener (
onNewTokenon Android,messaging(_:didReceiveRegistrationToken:)on iOS) and callPOST api/client/registerpushtoken. Every call must include your app'sx-oo-apikey(see "Provided by obox" above) — without it, or with an unrecognized one, the call fails withinvalid_apikeyand nothing gets registered, regardless of session state.- On every app start, regardless of login state. No session is required — an
unauthenticated call registers the device as a guest (
cid=0), which is what makes it reachable for tenant-wide broadcasts even before anyone logs in. - Again on login, with the same token — this reassigns/claims the device to the now-known
customer (needed for customer-targeted push and for OTP-based login push). This call must
carry the authenticated obox session (the same cookie/session your other logged-in API
calls use) —
cidis taken exclusively from that session server-side, never from a request parameter, so if this call fires without it (wrong HTTP client instance, missing cookie jar, etc.) it re-registers as guest instead of claiming the device, and the customer-targeted/OTP push case below won't work. The response's result value tells you which happened:registeredmeans it was actually claimed by the customer,registered_guestmeans it was stored as a guest device — check forregisteredright after your login-time call to confirm the claim went through instead of assuming it silently worked. - Again whenever Firebase hands you a refreshed token — this is not a one-time call, FCM
tokens rotate over the device's lifetime. This is the call most likely to have no valid
session (token refresh can happen at any point in the app's lifecycle, not just right after
a login flow) — see the
claimTokenparameter below for how to make sure it still gets attributed to the right customer instead of silently falling back to guest. - Parameters:
token(required),platform(androidorios),reportsAnalytics(boolean, defaultfalse— leave it off unless you've built the analytics section below; see there for what it's for),claimToken(see below).
- On every app start, regardless of login state. No session is required — an
unauthenticated call registers the device as a guest (
- Store and resend the
claimTokenfrom the response. Anyregistered/registered_via_claimresponse includes aclaimTokenfield — a random credential you should persist alongside the FCM token itself (Keychain on iOS,EncryptedSharedPreferenceson Android; not plainUserDefaults/SharedPreferences, it's a real credential) and send back as theclaimTokenparameter on every subsequentregisterpushtokencall, including ones that also carry a session. This exists because native registration code can't reliably depend on the session cookie at all:WKWebView(iOS) and AndroidWebVieweach maintain their own cookie store, entirely separate from whatever HTTP client your native code uses to fire this call — documented platform behavior, not something fixable by bridging cookies around. PresentingclaimTokenlets the backend re-associate the device with its customer without needing a session at all, which is exactly the case that matters most: a token-refresh call firing while the app has no live session. A session, when present, always takes priority server-side, so sendingclaimTokenalongside one is harmless — send it whenever you have one, unconditionally. Every claim (session- orclaimToken-based) returns a newclaimToken— always overwrite your stored value with the latest one, never reuse an old one after a newer one has been issued. - Do not call
droppushtokenon ordinary logout — a logged-out device should stay registered (seePOST api/client/droppushtoken). Only call it for deliberate removal: an explicit "forget this device" / disable-notifications action, if your app has one. Same no-session rule applies — a guest can drop their own guest-registered token.
That's the whole baseline — with just this, your app receives and displays title/body pushes.
Android shows them from the OS notification tray automatically with no further code; iOS needs a
UNUserNotificationCenterDelegate implementation to present notifications while the app is in
the foreground (background/killed-state delivery is handled by the OS).
Optional — Deep-linking on tap
Extra cost: your own routing logic. Nothing extra needed on the registration side.
obox sends the target URL as a custom data field, link — not part of the visible
notification payload, so there's nothing to display automatically. On notification tap, read
data["link"] (Android: RemoteMessage.getData().get("link"); iOS: the userInfo["link"] key
in your notification response handler) and route to that destination yourself. This is entirely
your app's own navigation/routing code — obox only ever hands you the raw URL string.
Optional — Rich image display
Extra cost: an iOS Notification Service Extension. Android is close to free.
obox sets notification.image on messages that include one.
- Android: the default FCM notification builder displays the image without extra work in most cases.
- iOS: plain APNs delivery does not fetch/display the image on its own — you need to add a Notification Service Extension target to your Xcode project that downloads the image URL and attaches it to the notification content before it's presented. This is a real, separate piece of iOS-specific setup (new extension target, entitlements, download/attach code) — budget for it as its own task if you want image support on iOS, not just a config flag.
Optional — Delivery & open analytics
Plain FCM delivery only ever tells obox "accepted for delivery," never whether a device actually received or opened the notification. This is FCM-only — OneSignal already reports its own delivered/opened stats through its own dashboard.
-
Implement the two report-back calls:
POST <cb>api/client/pushdelivered— parampushId(required). Call as soon as your message handler receives the push (onMessageReceivedon Android; on iOS, your Notification Service Extension if you've built rich image display above, otherwise wherever you first see the message).POST <cb>api/client/pushopened— parampushId(required). Call when the user taps the notification.
Read
pushIdthe same way you'd readlink(Android:RemoteMessage.getData().get("pushId"); iOS:userInfo["pushId"]) — it's always present on every message, regardless of whether the push has a link or image. Treat it as an opaque string: it's a random per-message token, not a sequential/incrementing id, so don't try to parse it, sort by it, or infer anything from its value — just echo it back unchanged. Both calls are fire-and-forget and need no session (a guest-owned device reports the same as a logged-in one) — obox does the counting, and an unrecognizedpushId(e.g. a stale/duplicate report) is silently ignored rather than erroring.<cb>is the base URL to call, read fromdata["cb"]on the same message (Android:RemoteMessage.getData().get("cb"); iOS:userInfo["cb"]) — always present alongsidepushId, already ending in a trailing slash (e.g.https://oekobox-online.de/v3/shop/mysysname/), so just concatenate it withapi/client/pushdelivered/pushopeneddirectly. Don't hardcode or configure a fixed API base URL for these two calls: the same app binary can serve multiple tenants (whitelabel/esst.bio installs aren't one-tenant-per-build) against the one shared Firebase project, so only the individual push message itself knows which tenant sent it. Using the wrong base would report the delivery/open to the wrong tenant'spush_history, not just fail outright — so don't reuse acbvalue across messages or cache it beyond the message it came with. -
Once, and only once, your app build actually makes those two calls, start passing
reportsAnalytics=trueon everyregisterpushtokencall (see## Required — Bare pushabove — same endpoint, this is just an additional parameter on it). This is what tells obox "this specific device is capable of reporting back," which is the only way it can distinguish "nobody received this push" from "none of the targeted devices were ever going to report back in the first place" — without it, both look identical as0 delivered. It's per-device, not global: set it on every registration call from a build that has the callbacks, including the very first one at app start (not just the one on login). Leaving itfalse/omitted is always safe and is the default — it doesn't disable or break anything, it just correctly excludes that device from the "how many could report" count instead of making its silence look like a failed delivery.
Testing
Once a token is registered, send yourself a test push directly from the admin "APP Push
Messages" panel (page=dev&group=app in the tenant admin area) — enter your own customer id as
the addressee and submit. No obox-side involvement needed, and no code required on your end to
trigger it.