@djangocfg/layouts 2.1.36 → 2.1.38

package/src/snippets/PushNotifications/@docs/guides/django-integration.md

@@ -0,0 +1,648 @@
+# Django Integration Guide
+
+Complete guide to integrating PushNotifications snippet with Django-CFG backend.
+
+## Overview
+
+This guide shows how to:
+1. Set up Django backend for push notifications
+2. Create subscription endpoints
+3. Send push notifications from Django
+4. Connect with DjangoPushProvider
+
+## Prerequisites
+
+- ✅ Django project setup
+- ✅ VAPID keys generated ([VAPID Setup Guide](./vapid-setup.md))
+- ✅ Service worker configured ([Service Worker Guide](./service-worker.md))
+- ✅ Python 3.8+
+
+## Step 1: Install Dependencies
+
+```bash
+pip install pywebpush
+```
+
+Update requirements:
+```bash
+pip freeze > requirements.txt
+```
+
+## Step 2: Configure Django Settings
+
+### settings.py
+
+```python
+# settings.py
+import os
+from pathlib import Path
+
+# VAPID Configuration
+VAPID_PUBLIC_KEY = os.getenv('VAPID_PUBLIC_KEY')
+VAPID_PRIVATE_KEY = os.getenv('VAPID_PRIVATE_KEY')
+VAPID_MAILTO = os.getenv('VAPID_MAILTO', 'mailto:admin@example.com')
+
+# Validate VAPID keys (development)
+if DEBUG and not all([VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY]):
+    import warnings
+    warnings.warn(
+        "VAPID keys not configured. "
+        "Run: npx web-push generate-vapid-keys"
+    )
+
+# CORS (if frontend on different domain)
+CORS_ALLOWED_ORIGINS = [
+    'http://localhost:3000',  # Next.js dev
+    'https://your-domain.com',
+]
+
+CORS_ALLOW_CREDENTIALS = True
+```
+
+### Environment Variables
+
+```bash
+# .env
+VAPID_PUBLIC_KEY=BM8xT...
+VAPID_PRIVATE_KEY=abc123...
+VAPID_MAILTO=mailto:your-email@example.com
+```
+
+## Step 3: Create Push Models
+
+### models.py
+
+```python
+# apps/notifications/models.py
+from django.db import models
+from django.contrib.auth.models import User
+from django.utils import timezone
+
+class PushSubscription(models.Model):
+    """Store user push subscriptions"""
+
+    user = models.ForeignKey(
+        User,
+        on_delete=models.CASCADE,
+        related_name='push_subscriptions'
+    )
+
+    endpoint = models.URLField(max_length=500, unique=True)
+    p256dh = models.CharField(max_length=255)  # Public key
+    auth = models.CharField(max_length=255)    # Auth secret
+
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    is_active = models.BooleanField(default=True)
+
+    # Browser info (optional)
+    user_agent = models.TextField(blank=True)
+    ip_address = models.GenericIPAddressField(null=True, blank=True)
+
+    class Meta:
+        db_table = 'push_subscriptions'
+        ordering = ['-created_at']
+        indexes = [
+            models.Index(fields=['user', 'is_active']),
+            models.Index(fields=['endpoint']),
+        ]
+
+    def __str__(self):
+        return f"{self.user.username} - {self.endpoint[:50]}..."
+
+    @property
+    def subscription_info(self):
+        """Format for pywebpush"""
+        return {
+            "endpoint": self.endpoint,
+            "keys": {
+                "p256dh": self.p256dh,
+                "auth": self.auth
+            }
+        }
+
+
+class PushNotification(models.Model):
+    """Log sent notifications"""
+
+    subscription = models.ForeignKey(
+        PushSubscription,
+        on_delete=models.CASCADE,
+        related_name='notifications'
+    )
+
+    title = models.CharField(max_length=255)
+    body = models.TextField()
+    icon = models.URLField(blank=True)
+    url = models.URLField(blank=True)
+
+    sent_at = models.DateTimeField(auto_now_add=True)
+    success = models.BooleanField(default=True)
+    error_message = models.TextField(blank=True)
+
+    class Meta:
+        db_table = 'push_notifications'
+        ordering = ['-sent_at']
+
+    def __str__(self):
+        return f"{self.title} - {self.sent_at}"
+```
+
+### Migrate
+
+```bash
+python manage.py makemigrations
+python manage.py migrate
+```
+
+## Step 4: Create Views
+
+### views.py
+
+```python
+# apps/notifications/views.py
+from django.http import JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_http_methods
+from django.contrib.auth.decorators import login_required
+from django.conf import settings
+import json
+
+from .models import PushSubscription
+from .utils import send_push_notification
+
+
+@csrf_exempt  # Remove in production, use CSRF token
+@require_http_methods(["POST"])
+@login_required
+def subscribe(request):
+    """
+    Subscribe user to push notifications
+
+    Expects JSON body:
+    {
+        "endpoint": "https://...",
+        "keys": {
+            "p256dh": "...",
+            "auth": "..."
+        }
+    }
+    """
+    try:
+        data = json.loads(request.body)
+
+        # Validate data
+        if not all([
+            data.get('endpoint'),
+            data.get('keys', {}).get('p256dh'),
+            data.get('keys', {}).get('auth')
+        ]):
+            return JsonResponse({
+                'success': False,
+                'error': 'Invalid subscription data'
+            }, status=400)
+
+        # Create or update subscription
+        subscription, created = PushSubscription.objects.update_or_create(
+            endpoint=data['endpoint'],
+            defaults={
+                'user': request.user,
+                'p256dh': data['keys']['p256dh'],
+                'auth': data['keys']['auth'],
+                'is_active': True,
+                'user_agent': request.META.get('HTTP_USER_AGENT', ''),
+                'ip_address': request.META.get('REMOTE_ADDR'),
+            }
+        )
+
+        return JsonResponse({
+            'success': True,
+            'created': created,
+            'subscriptionId': subscription.id
+        })
+
+    except json.JSONDecodeError:
+        return JsonResponse({
+            'success': False,
+            'error': 'Invalid JSON'
+        }, status=400)
+    except Exception as e:
+        return JsonResponse({
+            'success': False,
+            'error': str(e)
+        }, status=500)
+
+
+@csrf_exempt
+@require_http_methods(["POST"])
+@login_required
+def unsubscribe(request):
+    """Unsubscribe from push notifications"""
+    try:
+        data = json.loads(request.body)
+        endpoint = data.get('endpoint')
+
+        if not endpoint:
+            return JsonResponse({
+                'success': False,
+                'error': 'Endpoint required'
+            }, status=400)
+
+        # Deactivate subscription
+        updated = PushSubscription.objects.filter(
+            endpoint=endpoint,
+            user=request.user
+        ).update(is_active=False)
+
+        return JsonResponse({
+            'success': True,
+            'unsubscribed': updated > 0
+        })
+
+    except Exception as e:
+        return JsonResponse({
+            'success': False,
+            'error': str(e)
+        }, status=500)
+
+
+@require_http_methods(["POST"])
+@login_required
+def send_test_push(request):
+    """Send test notification to user"""
+    try:
+        data = json.loads(request.body)
+
+        # Get user's active subscriptions
+        subscriptions = PushSubscription.objects.filter(
+            user=request.user,
+            is_active=True
+        )
+
+        if not subscriptions.exists():
+            return JsonResponse({
+                'success': False,
+                'error': 'No active subscriptions'
+            }, status=400)
+
+        # Notification data
+        notification = {
+            'title': data.get('title', 'Test Notification'),
+            'body': data.get('body', 'This is a test from Django'),
+            'icon': data.get('icon', '/icon-192.png'),
+            'url': data.get('url', '/'),
+        }
+
+        # Send to all subscriptions
+        results = []
+        for subscription in subscriptions:
+            success = send_push_notification(
+                subscription.subscription_info,
+                notification
+            )
+            results.append({
+                'subscriptionId': subscription.id,
+                'success': success
+            })
+
+        return JsonResponse({
+            'success': True,
+            'results': results
+        })
+
+    except Exception as e:
+        return JsonResponse({
+            'success': False,
+            'error': str(e)
+        }, status=500)
+```
+
+### utils.py
+
+```python
+# apps/notifications/utils.py
+from pywebpush import webpush, WebPushException
+from django.conf import settings
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def send_push_notification(subscription_info, notification_data):
+    """
+    Send push notification using pywebpush
+
+    Args:
+        subscription_info: dict with 'endpoint' and 'keys'
+        notification_data: dict with 'title', 'body', 'icon', etc.
+
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    try:
+        # Send push
+        response = webpush(
+            subscription_info=subscription_info,
+            data=json.dumps(notification_data),
+            vapid_private_key=settings.VAPID_PRIVATE_KEY,
+            vapid_claims={
+                "sub": settings.VAPID_MAILTO
+            }
+        )
+
+        logger.info(f"Push sent successfully: {notification_data.get('title')}")
+        return True
+
+    except WebPushException as e:
+        logger.error(f"Push failed: {e}")
+
+        # Handle specific errors
+        if e.response and e.response.status_code == 410:
+            # Subscription expired - deactivate it
+            logger.warning(f"Subscription expired: {subscription_info['endpoint']}")
+
+        return False
+
+    except Exception as e:
+        logger.error(f"Unexpected error sending push: {e}")
+        return False
+```
+
+## Step 5: Configure URLs
+
+### urls.py
+
+```python
+# apps/notifications/urls.py
+from django.urls import path
+from . import views
+
+app_name = 'notifications'
+
+urlpatterns = [
+    path('push/subscribe/', views.subscribe, name='push_subscribe'),
+    path('push/unsubscribe/', views.unsubscribe, name='push_unsubscribe'),
+    path('push/test/', views.send_test_push, name='push_test'),
+]
+```
+
+### Main urls.py
+
+```python
+# project/urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    # ... other patterns
+    path('api/', include('apps.notifications.urls')),
+]
+```
+
+## Step 6: Configure Frontend
+
+### Using DjangoPushProvider
+
+```tsx
+// app/layout.tsx
+import { DjangoPushProvider, PushPrompt } from '@/snippets/PushNotifications';
+
+const VAPID_KEY = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!;
+
+export default function Layout({ children }) {
+  return (
+    <DjangoPushProvider
+      vapidPublicKey={VAPID_KEY}
+      autoSubscribe={false}
+      onSubscribed={(sub) => console.log('Subscribed:', sub)}
+      onSubscribeError={(err) => console.error('Error:', err)}
+    >
+      {children}
+      <PushPrompt requirePWA={true} />
+    </DjangoPushProvider>
+  );
+}
+```
+
+### Send Test Notification
+
+```tsx
+// components/TestPushButton.tsx
+'use client';
+
+import { useDjangoPushContext } from '@/snippets/PushNotifications';
+
+export function TestPushButton() {
+  const { sendTestPush, isSubscribed } = useDjangoPushContext();
+
+  if (!isSubscribed) {
+    return null;
+  }
+
+  const handleTest = async () => {
+    const success = await sendTestPush({
+      title: 'Test from Frontend',
+      body: 'This is a test notification',
+      url: '/dashboard',
+    });
+
+    if (success) {
+      alert('Test notification sent!');
+    } else {
+      alert('Failed to send notification');
+    }
+  };
+
+  return (
+    <button onClick={handleTest}>
+      Send Test Notification
+    </button>
+  );
+}
+```
+
+## Step 7: Admin Integration (Optional)
+
+### admin.py
+
+```python
+# apps/notifications/admin.py
+from django.contrib import admin
+from .models import PushSubscription, PushNotification
+
+
+@admin.register(PushSubscription)
+class PushSubscriptionAdmin(admin.ModelAdmin):
+    list_display = ['user', 'endpoint_short', 'is_active', 'created_at']
+    list_filter = ['is_active', 'created_at']
+    search_fields = ['user__username', 'endpoint']
+    readonly_fields = ['created_at', 'updated_at']
+
+    def endpoint_short(self, obj):
+        return obj.endpoint[:50] + '...'
+    endpoint_short.short_description = 'Endpoint'
+
+
+@admin.register(PushNotification)
+class PushNotificationAdmin(admin.ModelAdmin):
+    list_display = ['title', 'subscription', 'success', 'sent_at']
+    list_filter = ['success', 'sent_at']
+    search_fields = ['title', 'body']
+    readonly_fields = ['sent_at']
+```
+
+## Step 8: Testing
+
+### Test Flow
+
+```bash
+# 1. Start Django
+python manage.py runserver
+
+# 2. Start Next.js
+npm run dev
+
+# 3. Open browser
+# Navigate to http://localhost:3000
+
+# 4. Subscribe to push
+# Click "Enable Notifications" button
+
+# 5. Send test notification
+# Click "Test" button or use Django admin
+```
+
+### Django Shell Testing
+
+```python
+python manage.py shell
+
+>>> from apps.notifications.models import PushSubscription
+>>> from apps.notifications.utils import send_push_notification
+
+>>> # Get user subscription
+>>> sub = PushSubscription.objects.filter(is_active=True).first()
+
+>>> # Send test
+>>> send_push_notification(
+...     sub.subscription_info,
+...     {
+...         'title': 'Test from Shell',
+...         'body': 'Testing push',
+...         'url': '/dashboard'
+...     }
+... )
+```
+
+## Production Considerations
+
+### Security
+
+```python
+# Remove @csrf_exempt in production
+# Use Django's CSRF protection
+
+from django.views.decorators.csrf import ensure_csrf_cookie
+
+@ensure_csrf_cookie
+@require_http_methods(["POST"])
+@login_required
+def subscribe(request):
+    # ... implementation
+```
+
+### Rate Limiting
+
+```python
+from django.core.cache import cache
+from django.http import JsonResponse
+
+def rate_limit(request, key, max_requests=10, window=60):
+    """Simple rate limiting"""
+    cache_key = f'rate_limit:{key}:{request.user.id}'
+    current = cache.get(cache_key, 0)
+
+    if current >= max_requests:
+        return JsonResponse({
+            'error': 'Rate limit exceeded'
+        }, status=429)
+
+    cache.set(cache_key, current + 1, window)
+    return None
+
+@login_required
+def send_test_push(request):
+    # Check rate limit
+    rate_limit_response = rate_limit(request, 'push_test', max_requests=5, window=60)
+    if rate_limit_response:
+        return rate_limit_response
+
+    # ... rest of implementation
+```
+
+### Logging
+
+```python
+# settings.py
+LOGGING = {
+    'version': 1,
+    'disable_existing_loggers': False,
+    'handlers': {
+        'file': {
+            'level': 'INFO',
+            'class': 'logging.FileHandler',
+            'filename': 'push_notifications.log',
+        },
+    },
+    'loggers': {
+        'apps.notifications': {
+            'handlers': ['file'],
+            'level': 'INFO',
+            'propagate': True,
+        },
+    },
+}
+```
+
+## Troubleshooting
+
+### Issue: Subscription fails
+
+**Check**:
+1. CSRF token (if not using `@csrf_exempt`)
+2. User authentication
+3. CORS settings
+4. VAPID keys match
+
+### Issue: Push not received
+
+**Check**:
+1. Subscription is active in database
+2. Service worker registered
+3. Notification permission granted
+4. VAPID keys correct on backend
+
+### Issue: 410 Gone error
+
+**Solution**: Subscription expired, remove from database
+
+```python
+# Handle in utils.py
+if e.response and e.response.status_code == 410:
+    from .models import PushSubscription
+    PushSubscription.objects.filter(
+        endpoint=subscription_info['endpoint']
+    ).update(is_active=False)
+```
+
+## Next Steps
+
+- [VAPID Setup](./vapid-setup.md) - Configure VAPID keys
+- [Service Worker](./service-worker.md) - Configure SW
+- [Main README](../../README.md) - API reference
+
+## References
+
+- [pywebpush Documentation](https://github.com/web-push-libs/pywebpush)
+- [Django REST Framework](https://www.django-rest-framework.org/)
+- [Web Push Protocol](https://datatracker.ietf.org/doc/html/rfc8030)