Skip to main content
The Push Notifications channel lets you send browser and mobile notifications through Web Push, Firebase Cloud Messaging (FCM), and Apple Push Notification service (APNs). This guide explains what you configure in the Sagepilot UI and which parts your app developer must implement.
For mobile integration, follow the React Native installation and integration guide using matching 0.4.2 base SDK and push add-on packages. Existing chat-only apps do not need the add-on.

Before you start

  • Decide which platforms you need: Web Push, Android, iOS, or a combination.
  • For Web Push, prepare VAPID public key, VAPID private key, and contact email.
  • For Android, prepare a Firebase service account JSON file.
  • For iOS, prepare APNs team ID, key ID, bundle ID, private key, and sandbox setting.
  • Ask your app developer to register the intended customer’s device on this push channel and implement the Firebase callbacks and native forwarding for analytics.
  • For SDK customers, prepare a backend that can issue a signed identity proof. Keep its signing secret on the backend.

Create the push channel

1

Open Channels

In Sagepilot, open Channels and click Create Channel.
2

Select Push Notifications

Choose Push Notifications from the Voice & Mobile category.
3

Set general details

Add the channel name and enable the provider types you plan to use.
4

Configure Web Push

Add VAPID public key, VAPID private key, and contact email.
5

Configure Android

Upload or paste the Firebase service account JSON. Sagepilot reads the Firebase project details from the JSON.
6

Configure iOS

Add APNs team ID, key ID, bundle ID, private key, and choose production or sandbox mode.
7

Save and test

Click Save Changes. For SDK integration, complete SDK & delivery, save again, then follow the Android Test Send procedure below.
To change an existing channel, open its Push Channel Settings. Changes take effect after Save Changes. Cancel closes the editor without saving.

General and platform settings

In General, configure: A channel needs a name, at least one enabled delivery mode and a complete enabled provider configuration before you can save. SDK push always requires a backend-signed identity proof. Generate a signing secret before connecting the SDK. Existing webhook-only channels can save without configuring an SDK secret.

Android credentials

Open Android after enabling Android Push: When a service account is already stored, leave the JSON input blank to retain it. Upload or paste a replacement to update it.
The channel needs a service-account JSON. The app’s google-services.json is a different file and does not belong in this field. Your developer adds the app configuration to the Android project separately.

iOS credentials

Open iOS after enabling iOS Push. Supply APNs Team ID, APNs Key ID, APNs Bundle ID and APNs Private Key (.p8). The bundle ID must match your app. Leave the private-key field blank to retain a stored key. Enable Use APNs Sandbox for the matching development environment. Use the production environment for production builds. The app still needs its native push entitlements and, for images, an embedded and signed image extension. If your iOS app obtains an FCM token through Firebase, also configure that Firebase project’s Apple app and APNs credentials with your developer. A Firebase token uses the channel’s FCM credentials. The iOS tab configures direct APNs delivery.

Web Push credentials

Open Web Push after enabling that mode. Supply VAPID Public Key, VAPID Contact Email and VAPID Private Key. Leave the private-key field blank to retain a stored key. Follow the Web Push integration guide to install the browser add-on, deploy its service worker, identify customers and request permission safely.

SDK and delivery controls

Open SDK & delivery to configure the following channel policies. These settings do not install the SDK, request OS permission or grant marketing consent on a customer’s behalf. Existing channels retain their saved choices when reopened.

SDK identity verification

The Identity signing secret generated here is the same secret your backend uses to create customer-specific push proofs. No second secret is required. The app receives a short-lived proof, while the signing secret stays on your backend. You can return the proof with your existing login response. See how the dashboard secret, proof and FCM token work together.
  1. Open SDK & delivery. Identity verification is always required for SDK push.
  2. Click Generate secret.
  3. Click Copy new secret and store it in your backend’s secret configuration.
  4. Click Save Changes and have your backend issue the short-lived identity proof.
After saving, the field stays filled with a masked value showing only the last five characters. The full saved secret cannot be retrieved. Rotate secret prepares a replacement after confirmation. Copy the new secret to your backend, then click Save Changes to apply it. Discard new secret keeps the current key. Rotation affects new proofs, while existing grants can remain valid for up to 24 hours. Keep this secret separate from the Firebase service account and out of the mobile app.

Anonymous customers

Anonymous means the customer has no stored email or phone. They still need a stable external customer ID and a verified SDK identity proof. After an explicit allow/block policy has been saved, the compatibility choice is disabled. You can still switch between allow and block. Reuse the same client_customer_id in webhook mapping and SDK identity proof. A matching existing device registration can be reused; an FCM token alone does not prove customer identity. Channel policy and customer consent are separate: allowing anonymous customers does not opt them into marketing. Blocking future sends cannot recall notifications already handed to the provider.

Notification display

For a standard first rollout, use Firebase / operating system. Select SDK display when you specifically need the supported Android rendering path and have tested it in your app. Both modes support static images. Firebase remains the delivery transport for FCM devices in either mode. The channel’s explicit display choice overrides the installation preference, but cannot give an older app capabilities it does not have. Changing this setting does not require a new build when the required integration is already installed; adding the native add-on or image extension does require a rebuild. Firebase/OS display supports Sagepilot analytics. Configure createFirebasePushAdapter with the native push add-on and forward Firebase/native callbacks as shown in the integration guide. The display dropdown is not an analytics switch. Token registration or a display setting alone does not report app engagement.

Notification images

Keep Notification images on and add an Image URL in Test Send, a template or a journey action. This is a channel-wide permission to include media; it does not provide a default image. Turning it off omits images from sends without deleting the URL from your saved content. Use publicly accessible HTTPS JPEG/PNG images without login requirements or redirects. Prefer files under 1 MB for provider compatibility. On Android SDK display, text appears first and the same notification updates when the image downloads. A failed image download retains text. iOS needs the app’s image extension and matching signing. Video and carousels are outside v1.

Create an image template

  1. Open Content → Push, select your push channel and click Create template.
  2. Enter the required name, Title and Body, then add the optional Image URL and Deep link.
  3. Use Add variable for customer-specific content, including the image URL. Complete each variable’s mapping.
  4. Check the notification preview and click Save template. Reopen the template to edit it; clear Image URL to make it text-only.
The same image preview appears when selecting a template for a campaign and on the campaign detail page. If an image cannot load, the preview retains the notification text. The preview does not prove device delivery. The selected channel’s image policy and the app’s capabilities still apply when the notification is sent.

Configure a journey or campaign

For a journey, add the existing Send Push Notification action. Select Push Channel, enter Title and Body, and optionally supply Deep Link and Image URL. Use the available customer/event variables for personalized content and check the preview. The channel controls display mode and whether images are included; these are not separate per-node switches. For a push campaign, select the intended audience, push channel and saved push template, then check the content and image preview before scheduling. A customer needs an active device registration on that channel and the required notification consent to receive the send. Being in a segment alone does not establish reachability. Start with a segment or list containing only your actual test customer and their registered device. Use an existing journey trigger supported by your workspace. After the customer enters, inspect that customer’s progress and the push node’s analytics before widening the audience.

Send an Android test

The Test Send tab currently sends to Android via FCM. It does not provide a web/iOS test selector. Save the channel first, and save any setting changes before testing. Click Send Test Notification, check the phone, then tap the notification and confirm the intended screen opens. The success banner reflects that the test was queued; it is not proof of handset receipt. A Test Send is not a journey entry or campaign run. Send through a test journey/campaign to verify its corresponding reports. To compare rendering, send once with Firebase / operating system and once with SDK on supported Android installations, saving between tests. Use an Android app with the add-on installed and registered for SDK display capability. Test an image that loads and an unavailable image to confirm text fallback. Check foreground and background behavior separately.

View push analytics

Open a journey and click View Analytics on a Send Push Notification node for that step’s push metrics. For the whole journey, open its analytics from the journey list. Campaign-triggered journeys are listed under Broadcast Journeys. The Push Notification Performance cards and Push Performance Funnel distinguish the following: The funnel is Targeted → Accepted → Opened → Destination opened. Receipts are shown separately because the OS may not supply a receipt callback. Card percentages use targeted notification deliveries as their denominator. Unique customer/device counts are separate counts, not alternative denominators. Expand Device activity and delivery details for targeted customers/devices/deliveries, customers/devices that opened, foreground presentation requests, presentation failures, destination failures, observed dismissals, accepted sends with unknown receipt, pending deliveries and mean time to open. Time to open runs from the first dispatch attempt to the recorded tap; invalid timestamps are excluded. Failures and exclusions explains unsuccessful or excluded deliveries when present. Most counts are per device delivery; missing endpoints count customer messages. A retry that succeeds is no longer counted as a failure. These reports work with both Firebase/provider and SDK display when the app implements the callbacks. Your developer must explicitly report destination success/failure and any action/conversion outcomes. There is no channel toggle that automatically measures reads or conversions. See callback wiring and metric availability. Mixed push/WhatsApp journeys keep push opens separate from WhatsApp delivery/read metrics. Journey entries count the whole journey. Reports may update after events are uploaded and processed; an offline or closed app can upload retained observations later. Firebase console analytics are not imported into these reports.

What your developer configures

SDK buffering, retry intervals and image-download limits are not editable channel fields. Deep links do not create application screens. For websites, use the Web Push integration guide and Web SDK API reference. For mobile apps, use the React Native Push guide and React Native method reference.

Platform checklist

Verify the setup

  1. Save the channel with the platform provider enabled.
  2. Register the intended customer’s push token on that channel and confirm permission and consent.
  3. Send a test notification from Sagepilot.
  4. Confirm text/image display, then tap and confirm the destination opens.
  5. Run a journey or campaign for that same test customer and check acceptance, available receipt, open and destination metrics.
  6. Test an unavailable image, then confirm that text and navigation remain usable.

Operational notes

  • Do not mix sandbox and production APNs credentials.
  • Complete SDK customer identification, device registration and consent before relying on journeys. The SDK obtains FCM tokens through Firebase; your brand does not need a separate token database for this integration.
  • Rotate provider credentials according to your mobile security policy.