Firebase Cloud Messaging

Step 1: Register apps in Firebase

1. Open Firebase Console and create or select a project.
2. Add an Android app with package name com.yourcompany.yourapp. Download google-services.json.
3. Add an iOS app with bundle ID <your-bundle-id>. Download GoogleService-Info.plist.
4. iOS: enable the Push Notifications capability on your App ID in the Apple Developer Portal.

Step 1b: Upload an APNs key to Firebase (iOS)

iOS devices receive pushes through Apple. Firebase needs an APNs Authentication Keyto deliver those messages. Upload it in Firebase Console — not in WebToApp. The .p8 on the iOS tab is an App Store Connect API key for uploading builds; it is a different file.

1. Open Apple Developer → Keys, click +, enable Apple Push Notifications service (APNs), register, and download the .p8 (once only). Copy the Key ID and your Team ID. One APNs key per Apple team is enough.
2. In Firebase Console → your project → the gear → Project settings → Cloud Messaging, under Apple app configuration, upload that APNs key and paste the Key ID and Team ID.

Your Firebase project ID (after you upload a config file): <your-firebase-project-id>

Step 2: Configure in WebToApp

1. Open Integrations and unlock Firebase Cloud Messaging (9 credits, once per app).
2. Turn FCM on. If OneSignal is on, you will be asked to confirm turning it off.
3. Upload google-services.json and GoogleService-Info.plist.
4. Pick an Android status-bar notification icon: a preset silhouette, or upload a custom PNG (transparent background). A full-color square shows as a white square.
5. Request a new Android build and a new iOS build.

In-App Messaging (while the app is open)

FCM builds also include Firebase In-App Messaging. Create campaigns in Firebase Console → Engage → In-App Messaging (not Cloud Messaging). They appear as a card, modal, banner, or image while the app is in the foreground. No extra WebToApp unlock. Rebuild after enabling FCM.

• Triggers: app_launch, on_foreground, or a custom event from your site.
• JS userId / userTags also set Analytics user id and user properties so you can target logged-in users or a plan tag.
• Custom trigger:{ type: 'analyticsEvent', name: 'checkout_start', params: {} }
• Action URL on your website’s domain loads in the WebView. A different domain opens in an in-app browser tab (same rule as in-app links and push openUrl).
• Campaigns wait until splash and the first page load finish. If an opening interstitial is enabled, they also wait until that ad has shown or failed. They stay hidden while interstitial or rewarded ads are on screen.

Step 3: Identify users from your website

The same userId message used for OneSignal subscribes the device to an FCM topic so your backend can target that user (including multiple devices). WebToApp does not store tokens or user mappings — the native app tells your webapp who is subscribed so you can save that on your side.

window.FlutterWebView.postMessage(JSON.stringify({
  type: 'userId',
  userId: 'user_12345'
}));

window.FlutterWebView.postMessage(JSON.stringify({
  type: 'userId',
  userId: null
}));

window.FlutterWebView.postMessage(JSON.stringify({
  type: 'userTags',
  tags: { plan: 'premium' }
}));

Topic name: wta_user_ plus a sanitized id (characters outside [a-zA-Z0-9-_.~%] become _). Prefer opaque IDs, not email addresses.

Read the subscription in your webapp

After FCM is ready, and again after every page load, the app sets window.FlutterFcm and dispatches a FlutterFcmToken event. Use either.

function savePushMapping(detail) {
  if (!detail.token || detail.permission === 'denied') {
    const stale = detail.previousToken || detail.token;
    if (stale) {
      fetch('/api/push/fcm', {
        method: 'DELETE',
        headers: { 'Content-Type': 'application/json' },
        credentials: 'include',
        body: JSON.stringify({ token: stale, remove: true })
      });
    }
    return;
  }
  fetch('/api/push/fcm', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    credentials: 'include',
    body: JSON.stringify({
      token: detail.token,
      previousToken: detail.previousToken,
      userId: detail.userId,
      topic: detail.topic,
      broadcastTopic: detail.broadcastTopic,
      tags: detail.tags,
      platform: detail.platform
    })
  });
}

window.addEventListener('FlutterFcmToken', (event) => {
  savePushMapping(event.detail);
  // After switching from OneSignal, re-send userId if the user is already logged in
  if (!event.detail.userId && window.currentUserId) {
    window.FlutterWebView.postMessage(JSON.stringify({
      type: 'userId',
      userId: window.currentUserId
    }));
  }
});

if (window.FlutterFcm) {
  savePushMapping(window.FlutterFcm);
}

window.FlutterWebView.postMessage(JSON.stringify({ type: 'getFcmToken' }));

Listen first, then read window.FlutterFcm, then call getFcmToken so you do not miss a payload that arrived before your script ran. To target a user, send to detail.topic (all of that user’s devices). To target one device, send to detail.token. On token refresh, send previousToken so your backend can delete the old row. If token is null or permission is denied, delete the stored mapping. Uninstall does not notify the WebView — when you send to a stored token and FCM returns unregistered / not-registered, delete that row.

Switching from OneSignal

Notification permission belongs to the app (bundle ID / package name), not to OneSignal or FCM. After you disable OneSignal, enable FCM, and users install the new build:

• Users who already allowed notifications are not asked again. The app registers with FCM and subscribes the device to wta_all on first launch.
• Users who never decided are prompted once (same as a new install). Users who denied are not prompted again; the app does not join wta_all and emits a null token so your backend can delete the mapping.
• OneSignal player IDs and tags do not transfer. The FCM token is new. Per-user topics require your site to post userId again (on login, or when you receive FlutterFcmToken with a null userId while the user is already logged in).

Step 4: Send from your backend

Use FCM HTTP v1 against project <your-firebase-project-id>. Include a notification block so a system banner is shown, plus data.openUrl to open a page in the app.

POST https://fcm.googleapis.com/v1/projects/<project-id>/messages:send

{
  "message": {
    "topic": "wta_user_user_12345",
    "notification": {
      "title": "New order",
      "body": "Tap to view"
    },
    "data": {
      "openUrl": "https://yoursite.com/orders/42"
    },
    "fcm_options": {
      "analytics_label": "targeted"
    },
    "android": {
      "priority": "high",
      "notification": { "channel_id": "webtoapp_push" },
      "fcm_options": { "analytics_label": "targeted" }
    },
    "apns": {
      "payload": { "aps": { "sound": "default" } },
      "fcm_options": { "analytics_label": "targeted" }
    }
  }
}

Data-only messages (no notification title/body) do not show a banner. In Firebase Console, add Custom data key openUrl (value: the https URL). Tapping the notification opens that page even if the app was killed. Set HTTP v1 fcm_options.analytics_label (and the Android/APNs equivalents) so Messaging Reports can filter by campaign. Labels must match ^[a-zA-Z0-9-_.~%]{1,50}$.

Every installed app also subscribes to topic wta_all. Use that from Firebase Console or HTTP v1 to reach all devices. Do not target “All users” / user segments in Console — that still needs Analytics audiences. Native Analytics is included for delivery reports, not for replacing topic broadcasts.

Messaging Reports

Firebase Console → Messaging → Reports needs Google Analytics enabled for the Firebase project (Project settings → Integrations → Google Analytics) and a native app rebuild after this FCM Analytics SDK. Envios (sends) count HTTP v1 accepts. Recebidas, Impressões, and opens are Android-only and only for background system notification messages. iOS and web still show sends without those columns. Reports can lag up to 24 hours. Filter by the Android app.

• The Integrations “Google Analytics” G- ID is WebView GA4. It does not fill FCM Reports.
• Foreground Android banners shown via local notifications are not FCM impressions. Foreground iOS uses the system banner only.
• FCM Analytics does not show an App Tracking Transparency prompt. Advertising ID / ad personalization collection is off.