Setup Push Notifications (Native Apps)

← API Index

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)

  1. provide oekobox-online with your iOS App bundle ID, Team ID and APNs Authentication Key .p8 file (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
  2. provide oekobox-online with your Android package name
  3. oekobox-online will issue you a google-services.json and GoogleService-Info.plit for Android and iOS respectively
  4. 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

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.

  1. 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.
  2. Initialize Firebase at app startup.
  3. Request notification permission from the OS — Android 13+ needs the runtime POST_NOTIFICATIONS permission, iOS needs the UNUserNotificationCenter prompt. Skip this and a successfully delivered push just never shows.
  4. Implement the token listener (onNewToken on Android, messaging(_:didReceiveRegistrationToken:) on iOS) and call POST api/client/registerpushtoken. Every call must include your app's x-oo-apikey (see "Provided by obox" above) — without it, or with an unrecognized one, the call fails with invalid_apikey and 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) — cid is 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: registered means it was actually claimed by the customer, registered_guest means it was stored as a guest device — check for registered right 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 claimToken parameter 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 (android or ios), reportsAnalytics (boolean, default false — leave it off unless you've built the analytics section below; see there for what it's for), claimToken (see below).
  5. Store and resend the claimToken from the response. Any registered/registered_via_claim response includes a claimToken field — a random credential you should persist alongside the FCM token itself (Keychain on iOS, EncryptedSharedPreferences on Android; not plain UserDefaults/SharedPreferences, it's a real credential) and send back as the claimToken parameter on every subsequent registerpushtoken call, 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 Android WebView each 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. Presenting claimToken lets 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 sending claimToken alongside one is harmless — send it whenever you have one, unconditionally. Every claim (session- or claimToken-based) returns a new claimToken — always overwrite your stored value with the latest one, never reuse an old one after a newer one has been issued.
  6. Do not call droppushtoken on ordinary logout — a logged-out device should stay registered (see POST 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.

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.

  1. Implement the two report-back calls:

    • POST <cb>api/client/pushdelivered — param pushId (required). Call as soon as your message handler receives the push (onMessageReceived on 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 — param pushId (required). Call when the user taps the notification.

    Read pushId the same way you'd read link (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 unrecognized pushId (e.g. a stale/duplicate report) is silently ignored rather than erroring.

    <cb> is the base URL to call, read from data["cb"] on the same message (Android: RemoteMessage.getData().get("cb"); iOS: userInfo["cb"]) — always present alongside pushId, already ending in a trailing slash (e.g. https://oekobox-online.de/v3/shop/mysysname/), so just concatenate it with api/client/pushdelivered/pushopened directly. 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's push_history, not just fail outright — so don't reuse a cb value across messages or cache it beyond the message it came with.

  2. Once, and only once, your app build actually makes those two calls, start passing reportsAnalytics=true on every registerpushtoken call (see ## Required — Bare push above — 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 as 0 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 it false/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.