Merge pull request #1679 from appwrite/blog-push-notification-announcement

Blog: Add push notification announcement

Author: ebenezerdon

src/routes/blog/post/announcing-new-push-notifications-features/+page.markdoc

@@ -0,0 +1,219 @@
+---
+layout: post
+title: Announcing new features for Push Notifications
+description: 'Appwrite Messaging now supports background updates, critical alerts, and priority controls for push notifications.'
+date: 2025-01-22
+cover: /images/blog/announcing-new-push-notifications-features/cover.png
+timeToRead: 5
+author: jake-barnby
+category: product
+callToAction: true
+---
+
+We're excited to introduce new additions to Appwrite Messaging that give you greater control over how you send and handle push notifications in your app.
+The push notification API now affords you finer control over both how and when your notifications are delivered.
+You can run background updates silently, send critical alerts that bypass Do Not Disturb, and manage delivery priorities.
+These changes enable you to handle common scenarios - such as data syncs, urgent alerts, and battery-conscious updates more effectively.
+
+Here's a quick overview of the new features:
+
+# Background updates (iOS)
+
+We're now supporting Apple's background notifications through the `contentAvailable` parameter. This lets your iOS app process updates in the background without displaying notifications to users. Background notifications are useful for data syncs, content updates, and state changes that don't require user interaction.
+
+When you set `contentAvailable`, your app wakes up in the background to handle the notification payload. This works well for messaging apps that need to fetch new messages, news apps refreshing content, or any app that needs to update data periodically. Since no UI is shown to users during background updates, you can omit both the title and body.
+
+A few things to keep in mind when using background notifications:
+
+-   You'll need to configure your app to handle background processing using [Background Modes](https://developer.apple.com/documentation/xcode/configuring-background-execution-modes) in Xcode.
+-   Set the notification priority to normal to ensure proper background delivery.
+-   Apple limits background notifications to about 2-3 per hour to preserve battery life.
+-   For Android users, you can achieve similar functionality by sending a data-only notification (just omit the title and body).
+
+To implement background notifications, set `contentAvailable` to true and handle the [application:didReceiveRemoteNotification:fetchCompletionHandler:](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application) method in your app.
+
+# Critical alerts (iOS)
+
+Sometimes, users need to see a notification even when their phone is on **Do Not Disturb**. The new `critical` parameter attempts to mark the notification as critical, which can bypass silent and do not disturb settings when approved. To use critical alerts, you'll need to request the critical alert entitlement from Apple through your developer account - just visit [Apple's developer portal](https://developer.apple.com/contact/request/notifications-critical-alerts-entitlement/) and fill out a brief form explaining your use case.
+
+Critical alerts are essential for apps that handle time-sensitive or safety-related notifications, such as:
+
+-   Healthcare apps sending urgent medical alerts
+-   Home security apps warning about break-ins
+-   Connected device apps alerting about smoke or carbon monoxide detection
+-   Emergency response apps sending evacuation notices
+-   Financial apps warning about suspicious transactions
+
+# Priority controls
+
+You can now set notifications as either normal or high priority:
+
+-   **Normal priority:** The system delivers these at convenient times based on battery life and may group notifications together.
+-   **High priority:** These go out right away - useful for time-sensitive updates.
+
+# Other updates
+
+-   **Badge numbers (iOS):** Set a number to display on your app icon to show pending notifications. Set it to 0 to clear existing badges. Must be an integer.
+-   **Data payload:** Both title and body are now optional fields. This gives you more flexibility, especially for background updates.
+
+# Technical details
+
+These new parameters work with our existing `createPush` and `updatePush` endpoints. We pass these parameters directly to the underlying push notification services (APNs for Apple and FCM for Android) - you just need to set the parameters you want.
+
+Here are some examples to get you started:
+
+## Example 1: Background update for fetching new messages
+
+{% multicode %}
+
+```dart
+Future result = await messaging.createPush(
+  messageId: 'background-sync-1',
+  title: null,                    // Optional for background updates
+  body: null,                     // Optional for background updates
+  topics: [],                     // Optional: Send to specific topics
+  users: [],                      // Optional: Send to specific users
+  targets: [],                    // Optional: Send to specific devices
+  data: {                         // Optional: Custom data payload
+    'type': 'message_sync',
+    'lastSyncId': '123'
+  },
+  contentAvailable: true,         // iOS background updates
+  priority: 'normal',             // Required for background updates
+);
+```
+
+```js
+const result = await messaging.createPush(
+    'background-sync-1', // messageId
+    null, // title (optional for background updates)
+    null, // body (optional for background updates)
+    [], // topics (optional)
+    [], // users (optional)
+    [], // targets (optional)
+    {
+        // data (optional)
+        type: 'message_sync',
+        lastSyncId: '123'
+    },
+    null, // action (optional)
+    null, // icon (optional)
+    null, // sound (optional)
+    null, // color (optional)
+    null, // tag (optional)
+    0, // badge (optional)
+    true, // contentAvailable
+    false, // critical (optional)
+    'normal' // priority
+);
+```
+
+{% /multicode %}
+
+## Example 2: Critical alert for security breach
+
+{% multicode %}
+
+```dart
+Future result = await messaging.createPush(
+  messageId: 'security-alert-1',
+  title: 'Security Alert',
+  body: 'Unusual activity detected at front door',
+  topics: [],                     // Optional: Send to specific topics
+  users: [],                      // Optional: Send to specific users
+  targets: [],                    // Optional: Send to specific devices
+  data: {                         // Optional: Custom data payload
+    'type': 'security_alert',
+    'deviceId': 'front_door_cam'
+  },
+  badge: 1,                       // Must be an integer
+  critical: true,                 // iOS-only parameter
+  priority: 'high',              // High priority for critical alerts
+);
+```
+
+```js
+const result = await messaging.createPush(
+    'security-alert-1', // messageId
+    'Security Alert', // title
+    'Unusual activity detected at front door', // body
+    [], // topics (optional)
+    [], // users (optional)
+    [], // targets (optional)
+    {
+        // data (optional)
+        type: 'security_alert',
+        deviceId: 'front_door_cam'
+    },
+    null, // action (optional)
+    null, // icon (optional)
+    null, // sound (optional)
+    null, // color (optional)
+    null, // tag (optional)
+    1, // badge (must be an integer)
+    false, // contentAvailable (optional)
+    true, // critical (iOS-only)
+    'high' // priority
+);
+```
+
+{% /multicode %}
+
+## Example 3: Normal notification for all platforms
+
+{% multicode %}
+
+```dart
+Future result = await messaging.createPush(
+  messageId: 'chat-message-1',
+  title: 'New Message',
+  body: 'Sarah sent you a photo',
+  topics: [],                     // Optional: Send to specific topics
+  users: [],                      // Optional: Send to specific users
+  targets: [],                    // Optional: Send to specific devices
+  data: {                         // Optional: Custom data payload
+    'chatId': '456',
+    'messageType': 'photo'
+  },
+  badge: 3,                       // Integer for iOS, ignored on Android
+  priority: 'normal',            // Normal priority delivery
+);
+```
+
+```js
+const result = await messaging.createPush(
+    'chat-message-1', // messageId
+    'New Message', // title
+    'Sarah sent you a photo', // body
+    [], // topics (optional)
+    [], // users (optional)
+    [], // targets (optional)
+    {
+        // data (optional)
+        chatId: '456',
+        messageType: 'photo'
+    },
+    null, // action (optional)
+    null, // icon (optional)
+    null, // sound (optional)
+    null, // color (optional)
+    null, // tag (optional)
+    3, // badge (integer for iOS)
+    false, // contentAvailable (optional)
+    false, // critical (optional)
+    'normal' // priority
+);
+```
+
+{% /multicode %}
+
+Each example shows different combinations of the new parameters based on common use cases. Note that some parameters like `critical` and `badge` are iOS-specific, while others work across platforms. You can mix and match these parameters based on your needs.
+
+# Documentation and resources
+
+-   See the full implementation details in our [docs](https://appwrite.io/docs/products/messaging/messages)
+-   Check out our best practices for sending [push notifications](https://appwrite.io/blog/post/push-notifications-best-practices)
+-   Watch the [feature walkthrough](https://www.youtube.com/watch?v=QdDgPeuBZ1I)
+-   Learn more about [Messaging](https://appwrite.io/products/messaging)
+
+If you run into any issues or have questions about implementing these features, check the documentation or reach out to us through our support channels.

src/routes/changelog/(entries)/2025-01-22.markdoc

@@ -0,0 +1,22 @@
+---
+layout: changelog
+title: "Push notifications: new delivery options and controls"
+date: 2025-01-22
+cover: /images/changelog/2025-01-22.png
+---
+
+We've introduced new additions to Appwrite Messaging that give you greater control over how you send and handle push notifications in your apps.
+
+## What's new
+
+- **Background updates for iOS**: We've added support for silent background updates on iOS, with equivalent data-only notifications available for Android.
+- **Critical alerts for iOS**: You can now send notifications that bypass Do Not Disturb and notification settings.
+- **Priority controls for all platforms**: We've added options to manage delivery speed and battery usage across platforms.
+- **Badge numbers for iOS**: The badge parameter now accepts integers instead of strings for better type safety.
+- **Optional title and body for all platforms**: You can now send notifications without title and body for background and data-only updates.
+
+These updates will help you build better notification experiences for your users. Try them out and share your feedback with us.
+
+{% arrow_link href="/blog/post/announcing-new-push-notifications-features" %}
+Read the announcement to learn more
+{% /arrow_link %}