Set up Push notifications
PublicPush notifications reach users on their browser, Android device, or iPhone. Active Reach supports four configurations depending on your platform coverage.
Push is a property-scoped channel, not workspace-scoped. Each property = one SDK install (web app / Android app / iOS app / kiosk), and each property has its own VAPID, FCM, or APNs keys. A multi-app brand will have one push configuration per property, all rolling up under the same workspace.
Before you start
You’ll need:
- Admin access to your Active Reach workspace
- For FCM (Android/Web): a Firebase project with a service account JSON key
- For APNs (iOS): an Apple Developer account ($99/year) with a .p8 key
Choose your path
| Path | Platforms covered | Requires | Setup time |
|---|---|---|---|
| Managed (Web VAPID) | Chrome, Firefox, Safari (web only) | Nothing — Active Reach hosts VAPID keys | 1 business day |
| BYOM FCM | Android + Web | Firebase service-account.json | 10 minutes |
| BYOM APNs | iOS only | Apple .p8 key | 10 minutes |
| BYOM FCM + APNs | Android + iOS + Web | Both Firebase and Apple credentials | 15 minutes |
Managed setup (Web Push)
Choose “Active Reach-Managed (Web Push)”
Go to Settings → Channels → Push → Setup under the property you want to enable push for. Select the managed option. Active Reach manages VAPID key rotation and delivery infrastructure for that property — no Firebase or Apple accounts needed. Repeat per property if you have multiple SDK installs (web + mobile app + kiosk).
Provide business details
Fill in company name, contact email, website, use case, and expected monthly volume.
Install the SDK
The wizard shows platform-specific code snippets with your write key and workspace ID pre-filled. For web push:
<script src="https://cdn.activereach.ai/sdk/aegis.min.js"></script>
<script>
Aegis.init('YOUR_WRITE_KEY', {
workspace_id: 'YOUR_WORKSPACE_ID',
push: { enabled: true }
});
</script>Send a test push
Enter a device token (from your browser’s push subscription) and send a test notification. Verify it arrives.
Wait for activation
Managed web push requests are reviewed within 1 business day. You’ll be notified when the channel is live.
BYOM FCM setup (Android + Web)
Choose “BYOM FCM (Firebase)” and select your platforms
Select FCM on the mode page. On the platform page, confirm you want Android, Web, or both.
Upload your Firebase service account JSON
Download the key from Firebase Console → Project Settings → Service accounts → Generate new private key.
Drag-and-drop the JSON file into the uploader. The wizard extracts:
- Project ID
- Client email (service account)
- Private key
Credentials are validated live against Firebase before you can proceed. Stored AES-256-GCM encrypted.
Install the SDK
The wizard shows code snippets for each selected platform:
- Web — HTML script tag with
push: { enabled: true } - Android (Kotlin) — Gradle dependency +
Aegis.initialize()in your Application class - React Native — npm install + initialization
- Flutter — pubspec.yaml dependency + initialization
All snippets are pre-filled with your write key and workspace ID. Copy and paste.
Send a test push
Select the platform (Web or Android), enter a device token, optionally customize the title and body, and hit Send test.
You’re done
Summary shows your Firebase Project ID, platforms configured, and test result.
BYOM APNs setup (iOS)
Choose “BYOM APNs (Apple)”
Select APNs on the mode page.
Enter your Apple credentials
You’ll need these from developer.apple.com → Certificates, IDs & Profiles → Keys:
| Field | Where to find it | Format |
|---|---|---|
| Team ID | Apple Developer membership page | 10 characters |
| Key ID | Keys page in Developer portal | 10 characters |
| Bundle ID | Your app’s bundle identifier | e.g., com.yourbrand.app |
| Private key | Download the .p8 file and paste its full contents | Starts with -----BEGIN PRIVATE KEY----- |
| Environment | Production or Sandbox | Select based on your build type |
Credentials are validated live — the wizard fires a JWT test against APNs.
Apple enforces a 2-key-per-account hard limit. If you’re sharing a .p8 key across multiple push providers (CleverTap, Braze, etc.), check “Skip validation” to bypass the live JWT test.
Send a test push
Enter an iOS device token and send a test. Verify the notification appears on the device.
You’re done
Summary shows your APNs Bundle ID, environment, and test result.
Full cross-platform (FCM + APNs)
Follow both the FCM and APNs steps above. The wizard walks you through Firebase first, then Apple, then the SDK install, then a combined test step where you can test each platform individually.
Final coverage: Android + iOS + Web — every platform push can reach.
Push engagement signals
Once an SDK install is active, Active Reach receives push lifecycle signals from the user’s device automatically — there is nothing extra to wire on your side beyond installing the SDK.
| Signal | Fires when | Source |
|---|---|---|
push.delivered | The OS confirmed the notification reached the device | FCM service / iOS NSE / web Service Worker |
push.shown | Banner was rendered (web push only) | Service Worker |
push.clicked | User tapped the notification | Host app’s notification delegate |
push.dismissed | User swiped the notification away | Android DeleteIntent receiver shipped with the SDK / iOS UN delegate |
push.permission_denied | User declined the OS prompt | Host app on permission flow |
push.subscribed / push.resubscribed | New or refreshed push token | SDK push manager |
The SDK posts each signal to POST /v1/push/engagement at the
ingestion gateway. See Event ingestion
for the full wire shape. The signals flow through to:
delivery_events(ClickHouse) —channel='push', status one ofshown/clicked/dismissed. Powers the campaign analytics reports (delivery rate, click rate, dismiss rate per platform).timeline_cards— surfaces in the contact activity feed.- Outbound webhooks — fan out as
delivery.delivered/delivery.opened/delivery.clickedevents (see Webhook event types).
Engagement reporting is best-effort — push notifications still display even if the engagement POST is dropped (network failure, OS killing the NSE before it finishes, etc.). Treat the analytics as a representative sample, not a perfect count.
iOS Notification Service Extensions only have ~30 seconds before the
OS kills the process, so push.delivered is reliable but
push.clicked / push.dismissed must originate from the host app’s
UNUserNotificationCenterDelegate (in the main app process, not the
NSE).
What’s next
- Create your first push campaign
- View push analytics — delivery rates, failure analysis, platform breakdown
- Troubleshoot delivery issues