Setting Up Push Notifications

Each platform you send to is set up on its own, in the Arsel Dashboard under Integration > Push. Set up only the ones you ship on.

Platform	What you supply	Where it comes from
Android	A Firebase service-account JSON	Your own Firebase project
iOS	An APNs auth key (.p8) plus its Key ID, your Team ID and your bundle ID	Apple Developer
Web	The origins allowed to register devices	Nothing external — Arsel generates the keys

Quick Start

1. Set up the platforms you ship on, using the sections below.
2. Copy your client key (pub_…) and give it to whoever integrates the SDK.

You keep your own credentials

Arsel sends under your own sender identity, using credentials you upload. It does not proxy through an Arsel-owned sender.

This matters more than it sounds:

• Device tokens are scoped to a sender. Because the sender stays yours, tokens you already hold keep working when you move to Arsel — no re-registration, no forced app release, no audience loss.
• You keep control. Revoking the service account key or the APNs key immediately stops Arsel from sending, without involving support.

It also means the FCM quota consumed is your project's, not a shared pool.

iOS does not use Firebase

Apple is the only party that can deliver to an iPhone, and Arsel talks to Apple directly. There is no Firebase project in the iOS path — you upload one .p8 key and that is the whole setup. If your app happens to run Firebase Messaging for other reasons, it does not conflict; Arsel simply does not use its token.

Before You Start

You need, for each platform you send to:

• Android — a Firebase project with your app registered, and Owner or Editor access to the underlying Google Cloud project, enough to create a service account.
• iOS — an Apple Developer account, and the ability to create a key under Certificates, Identifiers & Profiles.
• Web — nothing external at all; see Web Push below.

---

Android

Step 1 — Enable the Firebase Cloud Messaging API

A new Firebase project does not always have the v1 messaging API switched on.

1. Open the Google Cloud console and select your Firebase project from the project dropdown.
2. Go to APIs & Services > Library.
3. Search for Firebase Cloud Messaging API and click Enable.

If it already reads "Manage" rather than "Enable", it is on.

Step 2 — Create a service account key

1. In the Google Cloud console, go to IAM & Admin > Service Accounts.
2. Either use the existing firebase-adminsdk-… account Firebase created, or click Create Service Account and give it a descriptive name such as arsel-push-sender.
3. Grant it a role that includes the cloudmessaging.messages.create permission. The predefined Firebase Cloud Messaging API Admin role covers it; a custom role with just that one permission is tighter and works equally well.
4. Open the account, go to Keys > Add Key > Create new key, choose JSON, and download the file.

The JSON file is a credential

Anyone holding it can send push notifications through your Firebase project. Do not commit it to source control or email it around. Upload it to Arsel and then delete your local copy.

The file must contain project_id, client_email, and private_key. Arsel rejects the upload if any are missing.

Step 3 — Upload it to Arsel

1. In the Arsel Dashboard, go to Integration > Push.
2. Under Android, upload the JSON file. The first validated credential switches Android on for you.

Arsel validates the credential immediately by making an authenticated call to FCM with a deliberately invalid device token. Authentication happens before token validation, so a response rejecting the token proves the credential works. Once validated, the configuration goes active.

If validation fails, the usual causes are:

Symptom	Cause
Authentication rejected	The Firebase Cloud Messaging API is not enabled (Step 1)
Permission denied	The service account lacks cloudmessaging.messages.create
File rejected on upload	The JSON is missing project_id, client_email, or private_key

Rotating the key

Upload a replacement from the same screen. Rotation is zero-downtime — the previous credential keeps serving in-flight sends until the new one is validated, so there is no window where sending fails. Revoke the old key in Google Cloud once the new one is active.

---

iOS

Apple's APNs auth key is a single .p8 file. Unlike a certificate it does not expire, and one key serves every one of your apps in the same developer team.

Step 1 — Create the key

1. In the Apple Developer portal, go to Certificates, Identifiers & Profiles > Keys.
2. Click +, name the key (e.g. Arsel Push), and tick Apple Push Notifications service (APNs).
3. Register it and download the .p8.

Apple lets you download a .p8 exactly once

There is no second chance and no way to re-download it. Save it somewhere durable before you leave the page. If you lose it, revoke the key and create a new one.

The key is also team-wide — it can send to every app in your developer account. Treat it like a production credential: do not commit it to source control or email it around.

Step 2 — Collect the three identifiers

The .p8 alone is not enough; Apple needs to know how to interpret it.

Value	Where to find it
Key ID	Shown next to the key in the Keys list — 10 characters
Team ID	Top-right of the Apple Developer portal, or your membership page — 10 characters
Bundle ID	Your app's bundle identifier, e.g. com.example.app

Step 3 — Upload it to Arsel

In Integration > Push, under iOS, upload the .p8 and fill in the three identifiers.

Arsel validates the key immediately by sending to a deliberately meaningless device token. Apple authenticates before it looks at the token, so a response rejecting the token proves the key, the team and the bundle ID are all correct.

Symptom	Cause
Bundle ID rejected (TopicDisallowed)	The bundle ID does not match an app in this team, or the key belongs to a different team
Key rejected (InvalidProviderToken)	The Key ID or Team ID does not match the uploaded .p8, or the key lacks the APNs capability

Debug builds vs the App Store

Apple runs two independent hosts — sandbox for development builds, production for TestFlight and the App Store — and a token minted for one is rejected by the other. You do not have to configure this: the same .p8 authenticates against both, and the Arsel SDK reports which host its build was signed for at registration.

Rotating the key

Upload a replacement from the same screen. The outgoing key keeps serving in-flight sends until the new one validates, so rotation has no downtime. Revoke the old key in the Apple Developer portal once the new one is active.

---

Web Push

Web Push does not use Firebase. It uses the browser's own Web Push standard with VAPID keys, which Arsel generates for you — there is nothing to obtain from Google, and the private key never leaves the server.

1. In Integration > Push, enable Web Push.
2. Add your allowed origins — every domain that may register devices, e.g. https://shop.example.com.
3. Choose your signing keys: let Arsel generate a keypair (the default), or import an existing one if you are migrating — see below.

That is the whole setup. Arsel signs each push with its own VAPID sub contact, so there is no address for you to supply — push services escalate to whoever operates the sending infrastructure, and that is us.

Origins are an allowlist, and it fails closed

A client key from an origin that is not on the list is rejected. An empty allowlist denies everything.

Include every origin you actually serve from — apex and www are different origins, as are staging domains and http://localhost:4200 during development.

Your page must be served over HTTPS. http://localhost is the browser's one exemption, for local development.

Migrating an existing web audience

If you already send web push through another provider, import your existing VAPID keypair instead of letting Arsel generate one. Choose Import my existing keypair when you provision Web Push, and paste both halves.

This is not a preference — it decides whether your current subscribers survive the move:

• A browser welds each subscription to the applicationServerKey it was created with. Every send afterwards is signed with the matching private key, and the push service checks it against the key that subscription was born with.
• Provision a different key and every existing subscription becomes permanently unsignable. Nothing errors on your side at setup time; campaigns simply reach nobody.
• You cannot recover by asking them again. Browser permission is one-shot and sticky: a user who already granted it never sees another prompt, so those subscribers stay silently unreachable until they happen to return to your site and re-subscribe.

Arsel verifies the two halves are genuinely a pair before storing them — a mismatched pair authenticates nothing and would fail at send time against every push service at once.

Once provisioned, the keypair is fixed

Importing is only available the first time you provision Web Push, because overwriting a live key would strand the subscriptions bound to it. If a key genuinely has to change later, use Rotate VAPID keypair, which keeps the outgoing key serving existing subscribers during a grace period.

Starting fresh on web? Let Arsel generate the keypair. There is nothing to keep track of, and the private key never transits a browser or a form.

---

Handing off to your developers

Once push is configured, your integration team needs:

What	Where to find it
Client key (pub_…)	Integration > Push. Publishable — safe to ship in app code.
API key (be_…)	Settings > API Keys. Secret — server-side only.
SDK installation guides	The Client SDKs overview
Server-side endpoints	The Push API reference

---

Migrating from another push provider

Mobile

Because the Firebase sender and the Apple key stay yours, your existing device tokens remain valid:

1. Export your current tokens, each with the contact identifier it belongs to.
2. Import them 1,000 at a time with Bulk Register Devices, omitting sdk_version. The import runs in the background; poll each job for its status and per-row errors to reconcile against your export.
3. Those devices are immediately sendable and render notifications natively.
4. When you later ship a build embedding the Arsel SDK, it adopts the imported device rather than creating a duplicate.

Imported devices receive notifications but report no delivery or engagement data until the SDK is embedded — see the warning in Client SDKs.

Check what kind of token your iOS export actually contains

Arsel sends to iOS through Apple directly, so an imported ios device must carry an APNs device token. If your previous provider relayed iOS through Firebase, your export holds FCM registration tokens instead — those are meaningless to Apple and cannot be imported as iOS devices. Those users have to re-register, which happens on their own once they open a build carrying the Arsel SDK.

Providers that take your APNs key or certificate directly (CleverTap among them) hold real APNs tokens, so their exports import cleanly.

Also send apns_environment if any exported tokens came from development builds — a sandbox token is rejected by Apple's production host, and the default is production.

Web

Web subscriptions are not portable as tokens — they are bound to a signing key, so what you carry over is the key itself. Import your existing VAPID keypair when you provision Web Push; see Migrating an existing web audience.