npm - @djangocfg/layouts - Versions diffs - 2.1.37 → 2.1.38 - Mend

@djangocfg/layouts 2.1.37 → 2.1.38

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/src/snippets/PushNotifications/@docs/guides/service-worker.md ADDED Viewed

@@ -0,0 +1,467 @@
+# Service Worker Setup for Push Notifications
+Complete guide to configuring Service Worker for receiving and displaying push notifications.
+## Overview
+Service Workers handle push notifications **even when your app is closed**. They:
+1. Listen for push events from the browser
+2. Display notifications to the user
+3. Handle notification clicks
+## Prerequisites
+- ✅ VAPID keys configured ([VAPID Setup Guide](./vapid-setup.md))
+- ✅ Service worker registered in your app
+- ✅ HTTPS (required for service workers)
+## Step 1: Create Service Worker File
+### Location
+```
+public/
+└── sw.js          # Service worker file
+```
+### Basic Service Worker
+```javascript
+// public/sw.js
+// Service Worker version (increment to force update)
+const SW_VERSION = 'v1.0.0';
+console.log(`[SW] ${SW_VERSION} loaded`);
+// Install event
+self.addEventListener('install', (event) => {
+  console.log('[SW] Installing...');
+  self.skipWaiting(); // Activate immediately
+});
+// Activate event
+self.addEventListener('activate', (event) => {
+  console.log('[SW] Activating...');
+  event.waitUntil(clients.claim()); // Take control immediately
+});
+// Push event - receive notification
+self.addEventListener('push', (event) => {
+  console.log('[SW] Push received');
+  // Parse notification data
+  let data = {
+    title: 'Notification',
+    body: 'You have a new notification',
+    icon: '/icon-192.png',
+    badge: '/badge-72.png',
+  };
+  if (event.data) {
+    try {
+      data = event.data.json();
+    } catch (e) {
+      console.error('[SW] Failed to parse push data:', e);
+    }
+  }
+  // Show notification
+  event.waitUntil(
+    self.registration.showNotification(data.title, {
+      body: data.body,
+      icon: data.icon || '/icon-192.png',
+      badge: data.badge || '/badge-72.png',
+      data: data.data || {}, // Custom data for click handler
+      tag: data.tag || 'default', // Notification grouping
+      requireInteraction: data.requireInteraction || false,
+    })
+  );
+});
+// Notification click event
+self.addEventListener('notificationclick', (event) => {
+  console.log('[SW] Notification clicked');
+  event.notification.close();
+  // Handle click action
+  const urlToOpen = event.notification.data?.url || '/';
+  event.waitUntil(
+    clients.matchAll({ type: 'window', includeUncontrolled: true })
+      .then((clientList) => {
+        // Check if app is already open
+        for (const client of clientList) {
+          if (client.url === urlToOpen && 'focus' in client) {
+            return client.focus();
+          }
+        }
+        // Open new window
+        if (clients.openWindow) {
+          return clients.openWindow(urlToOpen);
+        }
+      })
+  );
+});
+```
+## Step 2: Register Service Worker
+### Next.js App
+```tsx
+// app/layout.tsx or components/ServiceWorkerRegistration.tsx
+'use client';
+import { useEffect } from 'react';
+export function ServiceWorkerRegistration() {
+  useEffect(() => {
+    if ('serviceWorker' in navigator) {
+      navigator.serviceWorker
+        .register('/sw.js')
+        .then((registration) => {
+          console.log('[App] SW registered:', registration);
+        })
+        .catch((error) => {
+          console.error('[App] SW registration failed:', error);
+        });
+    }
+  }, []);
+  return null;
+}
+```
+```tsx
+// app/layout.tsx
+import { ServiceWorkerRegistration } from '@/components/ServiceWorkerRegistration';
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <ServiceWorkerRegistration />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+## Step 3: Advanced Features
+### Custom Notification Options
+```javascript
+// public/sw.js - Enhanced notification options
+self.addEventListener('push', (event) => {
+  const data = event.data ? event.data.json() : {};
+  const options = {
+    // Basic
+    body: data.body || 'New notification',
+    icon: data.icon || '/icon-192.png',
+    badge: data.badge || '/badge-72.png',
+    // Visual
+    image: data.image, // Large image
+    vibrate: [200, 100, 200], // Vibration pattern
+    silent: data.silent || false,
+    // Interaction
+    requireInteraction: data.important || false,
+    tag: data.tag || 'default', // Group notifications
+    // Actions (buttons)
+    actions: data.actions || [
+      { action: 'view', title: 'View' },
+      { action: 'dismiss', title: 'Dismiss' },
+    ],
+    // Custom data
+    data: {
+      url: data.url || '/',
+      timestamp: Date.now(),
+      ...data.data,
+    },
+  };
+  event.waitUntil(
+    self.registration.showNotification(data.title || 'Notification', options)
+  );
+});
+```
+### Handle Notification Actions
+```javascript
+// public/sw.js - Handle action buttons
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close();
+  if (event.action === 'view') {
+    // User clicked "View" button
+    const url = event.notification.data.url || '/';
+    event.waitUntil(clients.openWindow(url));
+  } else if (event.action === 'dismiss') {
+    // User clicked "Dismiss" button
+    // Notification already closed
+  } else {
+    // User clicked notification body
+    const url = event.notification.data.url || '/';
+    event.waitUntil(clients.openWindow(url));
+  }
+});
+```
+### Background Sync
+```javascript
+// public/sw.js - Sync notifications with server
+self.addEventListener('sync', (event) => {
+  if (event.tag === 'sync-notifications') {
+    event.waitUntil(
+      fetch('/api/notifications/sync')
+        .then(response => response.json())
+        .then(data => {
+          // Handle synced notifications
+          console.log('[SW] Synced notifications:', data);
+        })
+    );
+  }
+});
+```
+## Step 4: Testing
+### Local Testing
+```javascript
+// Browser console - Send test notification
+// 1. Get service worker registration
+navigator.serviceWorker.ready.then((registration) => {
+  // 2. Show test notification
+  registration.showNotification('Test', {
+    body: 'This is a test notification',
+    icon: '/icon-192.png',
+    data: { url: '/dashboard' },
+  });
+});
+```
+### Backend Testing
+```python
+# Django - Send test push
+from utils.push import send_push_notification
+subscription = {
+    "endpoint": "https://fcm.googleapis.com/fcm/send/...",
+    "keys": {
+        "auth": "...",
+        "p256dh": "..."
+    }
+}
+notification = {
+    "title": "Test Notification",
+    "body": "Testing push from backend",
+    "icon": "/icon-192.png",
+    "data": {"url": "/dashboard"}
+}
+send_push_notification(subscription, notification)
+```
+## Step 5: Production Optimization
+### Service Worker Caching
+```javascript
+// public/sw.js - Add caching for offline support
+const CACHE_NAME = 'pwa-cache-v1';
+const urlsToCache = [
+  '/',
+  '/icon-192.png',
+  '/badge-72.png',
+];
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME)
+      .then((cache) => cache.addAll(urlsToCache))
+  );
+});
+self.addEventListener('fetch', (event) => {
+  event.respondWith(
+    caches.match(event.request)
+      .then((response) => response || fetch(event.request))
+  );
+});
+```
+### Update Strategy
+```javascript
+// public/sw.js - Smart update strategy
+const SW_VERSION = 'v1.0.1'; // Increment on changes
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    // Delete old caches
+    caches.keys().then((cacheNames) => {
+      return Promise.all(
+        cacheNames.map((cacheName) => {
+          if (cacheName !== CACHE_NAME) {
+            console.log('[SW] Deleting old cache:', cacheName);
+            return caches.delete(cacheName);
+          }
+        })
+      );
+    })
+  );
+});
+```
+## Notification Permissions
+### Check Permission State
+```tsx
+// Check if user granted permission
+const permission = Notification.permission;
+// 'default' | 'granted' | 'denied'
+```
+### Request Permission
+```tsx
+import { useDjangoPushContext } from '@/snippets/PushNotifications';
+function NotifyButton() {
+  const { subscribe, permission } = useDjangoPushContext();
+  if (permission === 'denied') {
+    return <p>Notifications blocked</p>;
+  }
+  return (
+    <button onClick={subscribe}>
+      {permission === 'granted' ? 'Subscribed' : 'Enable Notifications'}
+    </button>
+  );
+}
+```
+## Browser Compatibility
+| Feature | Chrome | Firefox | Safari | Edge |
+|---------|--------|---------|--------|------|
+| Service Workers | ✅ 40+ | ✅ 44+ | ✅ 11.1+ | ✅ 17+ |
+| Push API | ✅ 42+ | ✅ 44+ | ✅ 16.4+ | ✅ 17+ |
+| Notification Actions | ✅ 48+ | ✅ 56+ | ❌ | ✅ 18+ |
+| Badge | ✅ 53+ | ✅ 60+ | ⚠️ Limited | ✅ 18+ |
+**iOS Note**: Push requires Safari 16.4+ and PWA must be installed.
+## Troubleshooting
+### Issue: Service Worker Not Registering
+**Solution**:
+```javascript
+// Check if HTTPS
+if (location.protocol !== 'https:' && location.hostname !== 'localhost') {
+  console.error('Service workers require HTTPS');
+}
+// Check browser support
+if (!('serviceWorker' in navigator)) {
+  console.error('Service workers not supported');
+}
+```
+### Issue: Push Not Received
+**Check**:
+1. Service worker registered: `navigator.serviceWorker.ready`
+2. Push subscription active: `registration.pushManager.getSubscription()`
+3. Notification permission: `Notification.permission === 'granted'`
+4. VAPID keys match between frontend and backend
+### Issue: Notification Not Showing
+**Solution**:
+```javascript
+// Ensure notification is shown in push event
+self.addEventListener('push', (event) => {
+  // ❌ Wrong - async not awaited
+  self.registration.showNotification('Test');
+  // ✅ Correct - use event.waitUntil
+  event.waitUntil(
+    self.registration.showNotification('Test')
+  );
+});
+```
+## Security
+### Content Security Policy
+```html
+<!-- Add to HTML head -->
+<meta http-equiv="Content-Security-Policy"
+      content="default-src 'self';
+               connect-src 'self' https://*.googleapis.com;
+               img-src 'self' data: https:;">
+```
+### Validate Push Data
+```javascript
+// public/sw.js - Validate notification data
+function isValidNotification(data) {
+  return (
+    data &&
+    typeof data.title === 'string' &&
+    typeof data.body === 'string'
+  );
+}
+self.addEventListener('push', (event) => {
+  const data = event.data ? event.data.json() : null;
+  if (!isValidNotification(data)) {
+    console.error('[SW] Invalid notification data');
+    return;
+  }
+  // Process valid notification...
+});
+```
+## Next Steps
+- [VAPID Setup](./vapid-setup.md) - Configure VAPID keys
+- [Django Integration](./django-integration.md) - Backend setup
+- [Main README](../../README.md) - API reference
+## References
+- [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
+- [Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API)
+- [Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)