In-app Chat
  • iOS
  • Android
  • Web
  • Flutter : Dart
  • React Native
  • Unity3D
  • Windows
  • macOS
  • Introduction
    • Overview
    • Basic concepts
  • Sample app
  • Getting started
  • Client SDKs
    • SDK downloads
    • Release notes
    • Upgrade guide
  • Guides
    • Authentication
    • Manage users
    • Room
    • Group
    • Messaging
    • Call invitation (signaling)
    • Manage sessions
  • Offline push notifications
  • Error codes
  • Client APIs
  • Server APIs
  • Documentation
  • In-app Chat
  • Offline push notifications
  • Implement offline push notification

Implement offline push notification

Last updated:2024-03-07 16:21

ZEGOCLOUD's In-app Chat (the ZIM SDK) provides the capability of sending offline push notifications. That is, in one-on-one chat or group chat, if your app is frozen, killed by the system or a user in the backend, and get disconnected with the ZEGOCLOUD service backend due to timeout, with the offline push notification feature, the ZEGOCLOUD backend will send offline push notifications to the target users.

You can integrate the ZPNs SDK and use it together with the ZIM SDK to implement the offline push notification feature.

Solution

The solution we provide is as follows:

  1. The receiver (the client user that receives the offline push notifications) enables the push channel of the corresponding vendors, and sends a request to get the Token from the vendor's Server.

  2. Vendor's Server returns the Token.

  3. The receiver generates a PushID, and sends it to the ZIM Server for binding the client user and PushID.

    If you use the ZPNs SDK together with the ZIM SDK, the SDK will automatically bind the client user to PushID, you don't need to do other operations; If you use the ZPNs SDK alone, you will need to connect to the ZPNs server and implement the binding logic. Note: Before switching the userID on the same device, remember to call the logout method to remove the PushID that userID is binding.

  1. The sender starts sending messages, and the messages are stored in the ZIM Server.
  2. The ZIM Server checks whether the receiver is online.
  3. If the receiver is offline, then the messages will be transferred to the ZPNs Server.
  4. The ZPNs Server sends offline push notifications to the vendor's Server.
  5. Vendor's Server pushes the offline push notifications to the receiver. The receiver receives the offline messages when gets back online.

Prerequisites

Before you implement this, make sure you complete the following:

  • Platform-specific requirements:

    iOS:

    • Xcode 7.0 or later.
    • An iOS device that is running on iOS 9.0 or later and supports audio and video.
    • iOS device is connected to the internet.

    Android:

    • Android Studio 2.1 or later
    • Android SDK Packages: Android SDK 25, Android SDK Build-Tools 25.0.2, Android SDK Platform-Tools 25.x.x or later.
    • An Android device or Simulator that is running on Android 9.0 or later and supports audio and video. We recommend you use a real device.
  • A project is created in the ZEGOCLOUD console, and the application ID and the application signature for connecting to ZIM SDK are obtained. The ZIM service is activated in the ZEGOCLOUD console. For more information, see Authentication. If the ZIM service cannot be activated, contact ZEGOCLOUD technical support for help.
  • Your project is integrated with ZIM SDK. For more information, see the "Integrate the SDK" section of the Send and receive messages topic.

Implementation steps

Integrate push notification channel

First, you will need to integrate the third-party vendor's offline push notification channel.

Now we support integrating the following third-party vendor's offline push notification: Huawei, Xiaomi, OPPO, Vivo, Apple, and Google.

Integrate the ZPNs SDK

Import the ZPNs SDK

Open the pubspec.yaml file, and add the zego_zim dependencies as follows:

dependencies:
flutter:
sdk: flutter
zego_zpns: ^2.2.0

Set permissions

Permissions can be set as needed.

  • iOS:

Call the applyNotificationPermission method to apply for the push notification permission. (This interface takes effect only when called for the first time.)

ZPNs.getInstance().applyNotificationPermission();
  • Android:

Open the AndroidManifest.xml file under the app/src/main directory to set permissions.

<!-- The following permissions are required for the ZPNs SDK -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.GET_TASKS" />

Set up the offline push notification feature using the ZPNs SDK

  1. Set up the ZPNsEventHandler method to receive the related event callbacks.

The ZPNsEventHandler class contains all event callbacks' static functions, you can pass the following callback to Function to receive ZPNs related event callbacks, and use it to handle SDK exceptions or receive message event notifications.

  • onNotificationClicked: Callback for clicking on the pushed notification. This will be triggered when the user clicks on the pushed notification.

  • onNotificationArrived: Callback for displaying the pushed notifications, and this will be triggered when receiving the pushed notification (when the App is running in the foreground).

  • onRegistered: Callback for the result on setting up the Push Notification callback. The result of setting up the push notification will be returned in this callback, and you can get the pushID through this callback.

    Regarding the callback support from major manufacturers:

    Callback name Description Manufacturer support
    onRegistered Callback for the result of registering "offline push" with the manufacturer. The result of registering "offline push" with the manufacturer will be thrown in this interface. You can obtain the PushID through this callback. -
    onNotificationClicked Callback for notification clicks from the manufacturer. Notification clicks from various manufacturers will be thrown in this interface. Xiaomi: Can receive this callback when the app is killed.
    Vivo: Does not support this callback.
    Huawei: Does not support this callback.
    Google Push: Does not support this callback.
    Oppo: Does not support this callback
    Apple: Supports this callback.
    onNotificationArrived Callback for notification display from the manufacturer. Notification display from various manufacturers will be thrown in this interface. Xiaomi: Can receive this callback when the app is in foreground or background.
    Vivo: Does not support this callback
    Huawei: Does not support this callback.
    Google Push: Does not support this callback.
    Oppo: Does not support this callback
    Apple: Supports this callback.
    onThroughMessageReceived Callback for a transparent message from the manufacturer. The transparent message returned by various manufacturers will trigger this interface and throw notifications in this interface. Xiaomi: Can receive this callback when the app is in foreground or background.
    Vivo: Does not support this callback.
    Huawei: Can receive this callback when the app is in foreground or background.
    Google Push: Can receive this callback when the app is in foreground or background.
    Oppo: Does not support this callback
    Apple: Does not support this callback yet.
Sample code for listening up event callbacks using the ZPNsEventHandler
  1. You can define a ZPNsEventHandlerManager class, and create a new static method loadingEventHandler in the class. And implement the callback onRegistered in the created new method, and log the pushID when the callback is triggered.
class ZPNsEventHandlerManager {
    static loadingEventHandler() {
        ZPNsEventHandler.onRegistered = (ZPNsRegisterMessage registerMessage) {
            log(registerMessage.errorCode.toString());
            log(registerMessage.errorMessage);
            log(registerMessage.pushID);
        };
    }
}
  1. When running the program, call the loadingEventHandler method and implement the callback ZPNsEventHandler.
void main() {
    ZPNsEventHandlerManager.loadingEventHandler();

    runApp(const MyApp());
}

And the pushID will be logged when the onRegistered is triggered by events.

  1. Configure a push notification channel.

To configure a push notification channel: First, integrate the third-party vendor's push notification SDK according to the Prerequisites steps, and modify the Boolean value. Then, call the setPushConfig method to enable the Push Notification service provided by the third-party vendors to configure a push notification channel.

ZPNsConfig zpnsConfig = ZPNsConfig();
zpnsConfig.fcmPush = true;
ZPNs.getInstance().setPushConfig(zpnsConfig);
  1. Set up the offline push notification feature.
ZPNs.getInstance().registerPush(iOSEnvironment: ZPNsIOSEnvironment.Automatic)
.catchError((onError) {
  if (onError is PlatformException) {
  // Notice exception here
  log(onError.message ?? "");
  }
});

After setting up the offline push notification feature, listen for the callback onRegistered of the class ZPNsEventHandler, and get the pushID to push offline push notifications to specified devices.

4 Implement the offline push notification using the ZIM SDK

ZEGOCLOUD's In-app Chat (the ZIM SDK) provides the capability of sending offline push notifications for one-on-one or group chats.

4.1 Send one-on-one messages with offline push notification

  1. Set the offline push notification title, content, and other properties in the ZIMPushConfig object.

    ZIMPushConfig pushConfig = ZIMPushConfig();
    pushConfig.title = "offline push notification title";
    pushConfig.content = "offline push notification content";
    pushConfig.extendedData = "Customizable field, optional.";
  2. Set up the configurations for offline push notification by modifying the pushConfig parameter of the ZIMMessageSendConfig object.

     ZIMMessageSendConfig sendConfig = ZIMMessageSendConfig();
     sendConfig.pushConfig = pushConfig;
  1. The message sender calls the sendPeerMessage method with the sendConfig to send one-to-one messages.

    ZIM.getInstance().sendPeerMessage(
        ZIMTextMessage(message: 'message'), 'toUserID', sendConfig).then((value) {}).catchError((error) {});
  2. The receiver will receive the offline messages when gets back online.

4.2 Send group messages with offline push notification

  1. Set the offline push notification title, content, and other properties in the ZIMPushConfig object.

    ZIMPushConfig pushConfig = ZIMPushConfig();
    pushConfig.title = "offline push notification title";
    pushConfig.content = "offline push notification content";
    pushConfig.extendedData = "Customizable field, optional.";
  2. Set up the configurations for offline push notification by modifying the pushConfig parameter of the ZIMMessageSendConfig object.

    ZIMMessageSendConfig sendConfig = ZIMMessageSendConfig();
    sendConfig.pushConfig = pushConfig;
  1. The message sender calls the sendGroupMessage method with the sendConfig to send the group messages.

    ZIM.getInstance().sendGroupMessage(
        ZIMTextMessage(message: 'message'), 'toGroupID', sendConfig).then((value) {}).catchError((error) {});
  2. The group members who are offline can receive offline messages when getting back online in the group.

Page Directory