---
name: cometchat-angular-push
description: Push notifications for CometChat Angular UI Kit v5 (@cometchat/chat-uikit-angular@5) — web push via Firebase Cloud Messaging (FCM) + the CometChat Notifications API. Covers dashboard FCM provider setup, the firebase-messaging-sw.js service worker, Notification permission, getting the FCM token, registering it with CometChatNotifications.registerPushToken + PushPlatforms.FCM_WEB AFTER login, an Angular PushService, environment config, foreground vs background handling, click-through routing, and logout cleanup.
license: "MIT"
compatibility: "Angular >=17 <22; @cometchat/chat-uikit-angular ^5.0; @cometchat/chat-sdk-javascript ^4.1"
metadata:
  author: "CometChat"
  version: "4.0.0"
  tags: "cometchat angular web push notifications fcm firebase service-worker registerPushToken PushPlatforms notifications-api standalone v5"
---

## Purpose

Web push for CometChat **Angular UI Kit v5** (`@cometchat/chat-uikit-angular@5`). On the web, CometChat push runs through **Firebase Cloud Messaging (FCM)** plus the **CometChat Notifications API** — CometChat hosts the send path. You do NOT build your own push server or webhook for the basic flow: configure an FCM provider in the CometChat dashboard, register the browser's FCM token with `CometChatNotifications.registerPushToken(...)`, and CometChat delivers a push whenever a message arrives for that user.

This is the v5 (standalone, Angular 17–21) rewrite. The previous v4 skill used `@angular/service-worker` + `SwPush` + a self-hosted VAPID web-push server + a CometChat webhook. **That hand-rolled path is replaced** — v5 uses FCM end-to-end through the CometChat Notifications API, which is the documented, supported web-push path.

**Read these skills first:**
- `cometchat-angular-core` — `UIKitSettingsBuilder` init, Promise-based `login(uid)` (bare string), `loggedInUser$`, environment config. Push registration hangs off the same login lifecycle.
- `cometchat-react-push` is the React sibling for the *self-hosted* Web Push model; the FCM + `CometChatNotifications` plumbing in THIS skill is the shared web SDK API and is the recommended path for both. Where they differ, this skill wins for Angular.
- `cometchat-angular-production` — server-minted auth tokens (push registration is tied to the logged-in auth token).

**Ground truth (verify before relying on any symbol):** **Official docs:** https://www.cometchat.com/docs/notifications/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP).
- Chat SDK types: `node_modules/@cometchat/chat-sdk-javascript/CometChat.d.ts` — `CometChatNotifications`, `PushPlatforms`.
- FCM (web): https://firebase.google.com/docs/cloud-messaging/js/client
- CometChat dashboard → **Notifications** → **Push Notifications** (FCM provider config).

> The Chat SDK is `@cometchat/chat-sdk-javascript@^4.1`. The web push API documented below is its **real** notification API — `CometChatNotifications.registerPushToken`, `PushPlatforms.FCM_WEB`, `CometChatNotifications.unregisterPushToken`. Do not substitute mobile-only symbols (APNs, FCM_ANDROID, etc.) — the only web platform enum value is `FCM_WEB`.

---

## 1. Architecture

```
Browser (your Angular app)
  ├── Firebase JS SDK (firebase/messaging)  — gets the FCM registration token
  ├── firebase-messaging-sw.js              — service worker; receives background push
  └── Notification permission               — granted by the user

CometChat backend
  ├── FCM provider config (server key / service account)  ← set in dashboard
  └── Notifications service — sends an FCM push to the user's registered token(s)
                              whenever a message arrives for them

Your Angular code
  └── After login → get FCM token → CometChatNotifications.registerPushToken(token, FCM_WEB)
```

You own: the Firebase project, the service worker file, the permission prompt, token registration after login, and token cleanup on logout. CometChat owns the actual send. No self-hosted push server, no VAPID web-push library, no CometChat webhook for the basic flow.

---

## 2. Dashboard — enable the FCM push provider (one-time)

In the CometChat dashboard:

1. **Notifications** → **Push Notifications** → enable.
2. Add a **provider** of type **FCM**.
3. Supply your Firebase credentials. Modern FCM (HTTP v1) wants the **service-account JSON** (from Firebase Console → Project settings → Service accounts → Generate new private key). Older configs accept the legacy **Server Key** + **Sender ID** (Cloud Messaging tab). Match whatever the dashboard's FCM form currently asks for.
4. Note the **Provider ID** you assign (default is `default`). You pass this same string as the third arg to `registerPushToken` if you used a non-default provider.

The Firebase **web app config** (`apiKey`, `authDomain`, `projectId`, `messagingSenderId`, `appId`) and the **VAPID key pair** (Firebase Console → Cloud Messaging → Web configuration → "Web Push certificates") are client-side — they go in `environment.ts` (§4). The service-account JSON / Server Key is **server-side only** — it lives in the CometChat dashboard, never in your Angular bundle.

---

## 3. Install Firebase + add the service worker

```bash
npm install firebase
```

> Do **not** use `@angular/service-worker` / `SwPush` for CometChat web push — FCM ships its own service worker contract (`firebase-messaging-sw.js`) and the Firebase JS SDK manages the token. The v4 `ngsw` path is gone.

### `src/firebase-messaging-sw.js`

This file MUST be served from the origin root (`/firebase-messaging-sw.js`) — `firebase.messaging()` registers it by that exact path. Add it as an Angular asset so the build copies it to the output root.

```js
// src/firebase-messaging-sw.js
// Loaded by the browser as a service worker — runs OUTSIDE Angular.
// Use the compat builds; ES module imports are not available in classic SWs.
importScripts("https://www.gstatic.com/firebasejs/10.12.0/firebase-app-compat.js");
importScripts("https://www.gstatic.com/firebasejs/10.12.0/firebase-messaging-compat.js");

firebase.initializeApp({
  apiKey: "YOUR_FIREBASE_API_KEY",
  authDomain: "YOUR_PROJECT.firebaseapp.com",
  projectId: "YOUR_PROJECT_ID",
  messagingSenderId: "YOUR_SENDER_ID",
  appId: "YOUR_APP_ID",
});

const messaging = firebase.messaging();

// Background handler — fires when the tab is closed/backgrounded.
messaging.onBackgroundMessage((payload) => {
  const title = payload.notification?.title ?? payload.data?.senderName ?? "New message";
  self.registration.showNotification(title, {
    body: payload.notification?.body ?? payload.data?.text ?? "",
    icon: payload.notification?.icon ?? "/assets/chat-icon.png",
    tag: payload.data?.conversationId,          // dedupe per conversation
    data: payload.data ?? {},                   // carried into notificationclick
  });
});

// Click-through — focus an open tab or open a new one, deep-linking to the thread.
self.addEventListener("notificationclick", (event) => {
  event.notification.close();
  const data = event.notification.data || {};
  const url = data.receiverType === "group"
    ? `/messages/group/${data.conversationId}`
    : `/messages/user/${data.sender}`;
  event.waitUntil(
    clients.matchAll({ type: "window", includeUncontrolled: true }).then((wins) => {
      for (const w of wins) {
        if ("focus" in w) { w.focus(); w.postMessage({ type: "open_conversation", ...data }); return; }
      }
      return clients.openWindow(url);
    })
  );
});
```

> The `payload.data` keys (`conversationId`, `sender`, `receiverType`, `text`, `senderName`) are whatever CometChat's FCM payload carries — confirm the exact field names against a real push in DevTools → Application → Service Workers, and adjust. Do not assume; CometChat's data-payload shape is the source of truth.

### Register the SW file as an Angular asset

`angular.json` → `projects.<app>.architect.build.options.assets` (alongside the mandatory CometChat assets glob from `cometchat-angular-core` §2):

```json
{ "glob": "firebase-messaging-sw.js", "input": "src", "output": "/" }
```

Build output then serves it at `/firebase-messaging-sw.js`. Verify after `ng build` that the file is at the dist root, not under `assets/`.

---

## 4. Environment config

Angular has no `process.env`. The Firebase web config + VAPID key live in `src/environments/environment.ts` (these are publishable client values — `apiKey` here is a Firebase identifier, not a secret):

```typescript
// src/environments/environment.ts
export const environment = {
  production: false,
  cometchat: {
    appId: "YOUR_APP_ID",
    region: "us",                 // "us" | "eu" | "in"
    authKey: "YOUR_AUTH_KEY",     // dev only
  },
  firebase: {
    apiKey: "YOUR_FIREBASE_API_KEY",
    authDomain: "YOUR_PROJECT.firebaseapp.com",
    projectId: "YOUR_PROJECT_ID",
    messagingSenderId: "YOUR_SENDER_ID",
    appId: "YOUR_FIREBASE_APP_ID",
    vapidKey: "YOUR_WEB_PUSH_CERTIFICATE_KEY_PAIR",   // FCM → Web configuration
  },
  // Provider ID set in the dashboard (§2). Omit / "default" if you didn't change it.
  cometchatPushProviderId: "default",
};
```

Keep the same shape in `environment.prod.ts`. The CometChat **REST API Key** and the Firebase **service-account JSON** never appear in any `src/` file — Angular ships `src/` to the client.

---

## 5. PushService — get the FCM token and register it

```typescript
// src/app/services/push.service.ts
import { Injectable, Inject, PLATFORM_ID } from "@angular/core";
import { isPlatformBrowser } from "@angular/common";
import { Router } from "@angular/router";
import { initializeApp } from "firebase/app";
import { getMessaging, getToken, onMessage, deleteToken, Messaging } from "firebase/messaging";
import { CometChatNotifications } from "@cometchat/chat-sdk-javascript";
import { environment } from "../../environments/environment";

@Injectable({ providedIn: "root" })
export class PushService {
  private messaging: Messaging | null = null;

  constructor(
    private router: Router,
    @Inject(PLATFORM_ID) private platformId: object,
  ) {
    if (!isPlatformBrowser(this.platformId)) return;       // SSR / prerender guard
    if (!("serviceWorker" in navigator) || !("Notification" in window)) return;

    const app = initializeApp(environment.firebase);
    this.messaging = getMessaging(app);

    // Foreground messages: the SW background handler does NOT fire while the tab
    // is focused. Decide your own UX here (toast, in-app banner, or a manual
    // Notification). Don't double-notify.
    onMessage(this.messaging, (payload) => {
      // e.g. show an in-app toast; skip an OS notification if the chat is focused.
      console.debug("Foreground push:", payload);
    });

    // SW → app messages from notificationclick (deep-link into the thread).
    navigator.serviceWorker?.addEventListener("message", (event: MessageEvent) => {
      const d = event.data;
      if (d?.type === "open_conversation") {
        const url = d.receiverType === "group"
          ? `/messages/group/${d.conversationId}`
          : `/messages/user/${d.sender}`;
        this.router.navigateByUrl(url);
      }
    });
  }

  /** Call AFTER CometChatUIKit.login(uid) resolves. Must be user-gesture-initiated
   *  (Notification.requestPermission requires it on most browsers). */
  async register(): Promise<void> {
    if (!this.messaging) return;

    const permission = await Notification.requestPermission();
    if (permission !== "granted") return;                  // user declined — bail quietly

    // The Firebase SDK registers /firebase-messaging-sw.js itself; pass the
    // VAPID key from the FCM Web configuration.
    const fcmToken = await getToken(this.messaging, { vapidKey: environment.firebase.vapidKey });
    if (!fcmToken) return;

    // The ONE call that wires the browser into CometChat's push pipeline.
    await CometChatNotifications.registerPushToken(
      fcmToken,
      CometChatNotifications.PushPlatforms.FCM_WEB,   // = "fcm_web" — the only web value
      environment.cometchatPushProviderId,                     // optional; defaults to "default"
    );
  }

  /** Call BEFORE CometChatUIKit.logout(). Order matters — registration is tied
   *  to the current auth token, which logout invalidates. */
  async unregister(): Promise<void> {
    if (!this.messaging) return;
    try {
      await CometChatNotifications.unregisterPushToken();   // clears CometChat-side
    } finally {
      await deleteToken(this.messaging).catch(() => {});              // clears the FCM token too
    }
  }
}
```

**API notes (verified against the v5 Chat SDK `.d.ts`):**
- `CometChatNotifications.registerPushToken(pushToken: string, platform: PushPlatforms, providerId?: string): Promise<string>` — registers the FCM token against the **current logged-in auth token**. Third arg is optional and defaults to `"default"`.
- `PushPlatforms.FCM_WEB = "fcm_web"` — the **only** web platform value in the enum. There is no web APNs/Android variant.
- `CometChatNotifications.unregisterPushToken(): Promise<string>` — unregisters the token for the current auth token. Takes **no arguments**.
- Both are static members of the **top-level** `CometChatNotifications` class — import it directly: `import { CometChatNotifications } from "@cometchat/chat-sdk-javascript"`. It is NOT nested under the `CometChat` namespace (there is no `CometChat.CometChatNotifications`).
- `PushPlatforms` is itself a top-level export of the SDK; the enum is also re-exposed as a static on the class (`CometChatNotifications.PushPlatforms`). Either `PushPlatforms.FCM_WEB` (with a top-level import) or `CometChatNotifications.PushPlatforms.FCM_WEB` is valid — both resolve to `"fcm_web"`.

> Legacy note: the SDK also exposes the deprecated `CometChat.registerTokenForPushNotification(token, settings?)`. It predates the Notifications service. Do **not** use it for new v5 integrations — `CometChatNotifications.registerPushToken` is the current API.

---

## 6. Wire into the login lifecycle

Registration MUST happen **after** `login(uid)` resolves — `registerPushToken` binds the token to the live auth token. (See `cometchat-angular-core` §3–§4 for the init → login order; init resolves in `main.ts` before `bootstrapApplication` — the v5 canonical path; `APP_INITIALIZER` is an alternative — and login happens in your auth service / route guard.)

```typescript
// src/app/services/auth.service.ts
import { Injectable } from "@angular/core";
import { CometChatUIKit } from "@cometchat/chat-uikit-angular";
import { PushService } from "./push.service";

@Injectable({ providedIn: "root" })
export class AuthService {
  constructor(private push: PushService) {}

  async login(uid: string): Promise<void> {
    const existing = CometChatUIKit.getLoggedInUser();      // sync getter, capital "In"
    if (!existing) {
      await CometChatUIKit.login(uid);                      // bare string in v5
    }
    // Push is opt-in + gesture-gated — do NOT auto-register here.
    // Call this.push.register() from a button click (see §7).
  }

  async logout(): Promise<void> {
    await this.push.unregister();                           // CRITICAL: before logout
    await CometChatUIKit.logout();
  }
}
```

---

## 7. "Enable notifications" button (gesture requirement)

`Notification.requestPermission()` must be called from a user gesture on most browsers — calling it from `ngOnInit` is silently rejected. Wire `register()` to a click:

```typescript
// src/app/components/enable-push.component.ts
import { Component } from "@angular/core";
import { CommonModule } from "@angular/common";
import { PushService } from "../services/push.service";
import { CometChatUIKit } from "@cometchat/chat-uikit-angular";

@Component({
  selector: "app-enable-push",
  standalone: true,
  imports: [CommonModule],
  template: `
    <button *ngIf="!enabled" (click)="enable()">Enable notifications</button>
  `,
})
export class EnablePushComponent {
  enabled = Notification.permission === "granted";

  constructor(private push: PushService) {}

  async enable(): Promise<void> {
    if (!CometChatUIKit.getLoggedInUser()) return;          // must be logged in first
    await this.push.register();
    this.enabled = Notification.permission === "granted";
  }
}
```

Mount it in the chat header, a settings page, or a one-time onboarding card.

---

## 8. Foreground vs background

- **Background / tab closed:** `onBackgroundMessage` in `firebase-messaging-sw.js` fires; you call `showNotification` (§3).
- **Foreground / tab focused:** the SW handler does **not** fire. `onMessage` in `PushService` fires instead (§5). Show an in-app toast/banner, or skip entirely if the relevant conversation is already on screen — never both, or the user sees a duplicate. CometChat's UI Kit already updates the message list live when the tab is focused, so a silent foreground handler is often the right call.

---

## 9. Notification permission states

`Notification.permission` is `"default"` (not yet asked), `"granted"`, or `"denied"`. Once `"denied"`, you cannot re-prompt programmatically — the user must change it in browser site settings. Reflect this in the UI: show the enable button only when `permission === "default"`, and a "notifications blocked — enable in browser settings" hint when `"denied"`.

---

## 10. HTTPS requirement

Service Workers, the Push API, and FCM all require **HTTPS** (or `http://localhost` for dev). On a LAN IP or plain `http://`, `getToken` and SW registration fail. Use `ng serve` (localhost is allowed) or `ng serve --ssl` for HTTPS-in-dev. Production hosts (Vercel / Netlify / Cloudflare Pages / Firebase Hosting) are HTTPS by default.

---

## 11. SSR / prerender (Angular Universal)

If the app uses SSR or prerendering, every Firebase/Notification touch must be browser-guarded — the `PushService` constructor already short-circuits with `isPlatformBrowser` (§5). Without it, `initializeApp` / `navigator.serviceWorker` throw `ReferenceError` at server boot. Keep all `firebase/messaging` access behind that guard; never call `register()` from server-rendered code paths.

---

## 12. Anti-patterns

1. **Registering the token before login resolves.** `registerPushToken` ties the token to the current auth token — call it only after `CometChatUIKit.login(uid)` succeeds.
2. **Calling `Notification.requestPermission()` from `ngOnInit`.** Browsers reject permission requests not tied to a user gesture. Use a clicked button (§7).
3. **Using `@angular/service-worker` / `SwPush`.** That was the v4 path. v5 web push uses Firebase's own `firebase-messaging-sw.js` + the FCM token — the two SW systems conflict if both register.
4. **Inventing platform enum values.** The only web value is `PushPlatforms.FCM_WEB` (`"fcm_web"`). There is no `FCM_ANDROID`/`APNS` for web.
5. **Using the deprecated `registerTokenForPushNotification`.** It predates the Notifications service; use `CometChatNotifications.registerPushToken`.
6. **Putting the Firebase service-account JSON / CometChat REST API Key in `environment.ts`.** Those are server-only (dashboard). The Firebase web config + VAPID key are the only push values that belong client-side.
7. **Serving `firebase-messaging-sw.js` from `/assets/`.** It must be at the origin root (`/firebase-messaging-sw.js`) or Firebase can't register it.
8. **Not unregistering on logout.** The previous user keeps receiving pushes. Call `unregisterPushToken()` (+ `deleteToken`) before `CometChatUIKit.logout()`.
9. **Double-notifying in the foreground.** `onMessage` and the SW `onBackgroundMessage` are mutually exclusive by tab focus — don't manually `showNotification` from foreground on top of the SW.
10. **No SSR guard in a Universal app.** `initializeApp` at server boot throws. Guard with `isPlatformBrowser`.

---

## 13. Verification checklist

- [ ] Dashboard: **Notifications → Push Notifications** enabled with an **FCM** provider; service-account JSON (or Server Key) supplied server-side
- [ ] `firebase` installed; `firebase-messaging-sw.js` in `src/`, registered as an Angular asset, served at `/firebase-messaging-sw.js` after build
- [ ] Firebase web config + VAPID key in `environment.ts`; service-account JSON / REST API Key NOT in any `src/` file
- [ ] `PushService` guards on `isPlatformBrowser` + `"serviceWorker" in navigator`
- [ ] `Notification.requestPermission()` fired from a user gesture (button), not `ngOnInit`
- [ ] FCM token fetched via `getToken(messaging, { vapidKey })`
- [ ] Token registered with `CometChatNotifications.registerPushToken(token, PushPlatforms.FCM_WEB, providerId)` **after** `login(uid)` resolves
- [ ] `onMessage` foreground handler defined; does not double-notify with the SW
- [ ] `onBackgroundMessage` + `notificationclick` in the SW deep-link to the conversation
- [ ] Logout calls `unregisterPushToken()` (+ `deleteToken`) BEFORE `CometChatUIKit.logout()`
- [ ] HTTPS or localhost only
- [ ] SSR projects keep all `firebase/messaging` access behind the browser guard

---

## 14. Pointers

- `cometchat-angular-core` — init → login order, `loggedInUser$`, environment config
- `cometchat-angular-production` — server-minted auth tokens (registration binds to the auth token)
- `cometchat-react-push` — sibling web-push concepts (self-hosted Web Push model; FCM + Notifications API here is the shared, recommended SDK path)
- `cometchat-angular-troubleshooting` — SW registration / FCM token debugging