Android push notifications with FCM

How it works

With the Firebase Messaging SDK, the app gets a registration token: the address of that app on that device. The sender posts the notification to FCM through the HTTP v1 API, authenticated with a service account from the Firebase project. Google delivers it to the device.

What you need

• A Firebase project with your Android app added.
• The Firebase Messaging SDK in the app, to get the registration token.
• The JSON file of a service account for the project.
• On Android 13 or later, ask the user for the POST_NOTIFICATIONS permission. Without it, the device does not show notifications.

Connecting FCM to vivapush

1. In the Firebase Console, open Project settings → Service accounts and generate a new private key. Firebase downloads a JSON file.
2. In the vivapush dashboard, open the app's credentials and upload that JSON for the Android channel.
3. vivapush checks the account with a validation send (no real notification) accepted by FCM and shows the result.

The key is encrypted and never shown in full. If Google later rejects the service account, the credential is marked invalid and the warning shows in the sending monitor, instead of piling up retries.

If you don't have that file, invite whoever builds the app from the dashboard. They get access to connecting channels only.

Registering the device

vivapush has no native Android SDK. The app talks to the public API in a few calls, using the app's public key (it starts with vp_pub_), which can only register devices and never send.

POST /api/v1/devices
X-VivaPush-App-Key: vp_pub_...

{
  "installation_id": "inst-123456",
  "platform": "android",
  "token": "FCM registration token",
  "external_user_id": "customer-42",
  "language": "en", "country": "US", "timezone": "America/New_York",
  "push_opt_in": true
}

Registration is idempotent per installation_id: when FCM rotates the token (the SDK calls onNewToken), register again and the new token replaces the old one for that installation. When the app opens, call POST /api/v1/devices/activity so the user counts as active for the month.

What the app receives

Each notification carries a title, a message and, when set, a large image. The data fields include vp_nid (the notification ID), vp_url (what to open on tap) and any fields you define.

With the app in the background, Android shows the notification on its own. With the app open, the Firebase SDK hands the message to your code, which decides what to show.

High priority is for urgent alerts; normal lets the system save battery. The time to live (TTL) sets how long FCM keeps trying a device that is offline.

Confirming delivery and opens

When the app receives or opens a notification, call POST /api/v1/events with the vp_nid and the type ("delivered", "opened" or "clicked"). This is the only source of “reached the device” in vivapush: “accepted for delivery” only means FCM took the message.

When FCM reports that a token no longer exists (for example, the app was uninstalled), the device is marked as no longer receiving and the subscriptions.invalidated webhook tells your system.

Frequently asked questions