Push Notifications

This document provides a comprehensive guide to implementing and managing push notifications within your applications using App Services. Push notifications are a crucial tool for engaging users, delivering timely updates, and driving application usage.

Introduction to Push Notifications

App Services offers a robust, cross-platform solution for sending targeted push notifications to your users via various mobile operating systems (iOS, Android) and web browsers. Our system simplifies the complex task of device registration, token management, and message delivery.

Key Concepts

• Device Token: A unique identifier registered by the operating system for each app installation on a device. This token is essential for sending notifications to a specific device.
• Platform: Refers to the target operating system (e.g., ios, android, web).
• Topic/Channel: A mechanism to group devices or users, allowing you to send notifications to multiple recipients simultaneously based on their interests or subscriptions.
• Payload: The data sent within a push notification. This typically includes alert messages, sounds, badges, and custom data.

Getting Started with Notifications

1. Platform Setup

Before you can send notifications, you need to configure your App Services project with the necessary credentials for each platform:

• iOS: Provide your APNs (Apple Push Notification service) certificate or key.
• Android: Provide your Firebase Cloud Messaging (FCM) Server Key.
• Web: Ensure your web application is configured to handle push notifications using the Web Push protocol.

You can manage these settings in the App Services console under the "Notifications" section.

2. Device Registration

Your client applications must register with the App Services notification backend to receive notifications. This typically involves:

1. Obtaining the device token from the respective platform's SDK.
2. Sending this token, along with the platform type and any relevant user or topic information, to your App Services backend.

The following JavaScript snippet illustrates a simplified device registration process:

async function registerDevice(userId, deviceToken, platform) {
    const response = await fetch('/api/v1/notifications/register', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer ' + getAuthToken() // Assuming you have an auth token
        },
        body: JSON.stringify({
            userId,
            deviceToken,
            platform
        })
    });
    if (!response.ok) {
        throw new Error('Failed to register device');
    }
    return response.json();
}
            

Sending Notifications

Sending to a Specific Device

You can send a notification directly to a device using its registered token.

async function sendNotificationToDevice(deviceToken, title, body) {
    const response = await fetch('/api/v1/notifications/send', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer ' + getAdminAuthToken() // Requires admin privileges
        },
        body: JSON.stringify({
            tokens: [deviceToken],
            notification: {
                title: title,
                body: body,
                // Additional options like 'sound', 'badge'
            }
        })
    });
    if (!response.ok) {
        throw new Error('Failed to send notification');
    }
    return response.json();
}
            

Sending to a Topic

Subscribe devices to topics and send messages to all subscribers of a topic.

async function subscribeToTopic(userId, topic) {
    // ... API call to subscribe user to topic
}

async function sendNotificationToTopic(topic, title, body) {
    const response = await fetch('/api/v1/notifications/topic/send', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer ' + getAdminAuthToken()
        },
        body: JSON.stringify({
            topic: topic,
            notification: {
                title: title,
                body: body
            }
        })
    });
    if (!response.ok) {
        throw new Error('Failed to send notification to topic');
    }
    return response.json();
}
            

Notification Payload Structure

The structure of the notification payload can vary slightly depending on the platform, but a common structure is supported:

{
    "title": "New Message!",
    "body": "You have received a new message from John Doe.",
    "data": {
        "messageId": "12345",
        "screen": "chat",
        "userId": "john-doe-id"
    },
    "sound": "default", // or a custom sound file
    "badge": 1 // for iOS
}
            

The data object allows you to send custom key-value pairs that your client application can use to perform specific actions when the notification is received.

Managing Notifications

The App Services console provides tools to monitor notification delivery, view statistics, and manage device registrations. You can also leverage our APIs to programmatically manage subscriptions and send notifications.

API Endpoints

• POST /api/v1/notifications/register: Register a new device.
• POST /api/v1/notifications/unregister: Unregister a device.
• POST /api/v1/notifications/send: Send notifications to specific tokens.
• POST /api/v1/notifications/topic/subscribe: Subscribe a device/user to a topic.
• POST /api/v1/notifications/topic/unsubscribe: Unsubscribe a device/user from a topic.
• POST /api/v1/notifications/topic/send: Send notifications to a topic.