Implement offline push notification

---

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 APNs channel, and sends a request to get the DeviceToken from the APNs Server.

2. The APNs Server returns the DeviceToken.

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.

4. The sender starts sending messages, and the messages are stored in the ZIM Server.

5. The ZIM Server checks whether the receiver is online.

6. If the receiver is offline, then the messages will be transferred to the ZPNs Server.

7. The ZPNs Server sends offline push notifications to the APNs Server.

8. The APNs Server pushes the offline push notifications to the receiver. The receiver receives the offline messages when gets back online.

Prerequisites

• Create a project in ZEGOCLOUD Console. Then, contact Technical Support to activate the In-app Chat service, and get the AppID and ServerSecret for SDK integration. The ZIM service permission is not enabled by default. Before using it, please activate the ZIM service by yourself in ZEGOCLOUD Console (for details, please refer to Project Management - In-app Chat), if you cannot activate the ZIM service, please contact ZEGOCLOUD technical support to activate it.
• Get the Token that SDK required for login authentication. For details, see Authentication.
• Integrate the ZIM SDK. For details, see the Integrate the SDK chapter of Send and receive messages.

• 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.

Get the APNs certificate

1. Go to the Apple Developer Account to get the APNs push notification service certificate.
2. Double-click the .cer file you get, and export it to .p12 file in Keychain Access.
3. Contact ZEGOCLOUD Technical Support for further configuration.

Integrate the ZPNs SDK

1. Download the latest version of the SDK (the ZPNs SDK included).

2. Extract the downloaded SDK package to the libs folder.

3. Select the target project, click General > Frameworks, Libraries, and Embedded Content tab, add the ZIM.xcframework, and then set the Embed to Embed & Sign.

Enable the push notifications

Enable the Push Notifications for the iOS device (which can only be running on a real device):

In Xcode, select the target object, click the Signing & Capabilities > Capabilities > Push Notification, select the Capability, and then enable the Push Notifications.

Get the DeviceToken

The DeviceToken is required for the ZIM SDK to configure and implement the offline push notification feature.

Import the header file

Import the header file AppDelegate.m.

import <ZPNs/ZPNs.h>

Apply for the push permission of the App

You need to call the requestAuthorizationWithOptions official method to apply for the push permission of the App; That is, when sending offline messages, a pop-up window on the mobile device prompts the user whether to agree to push.

UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
    //Request push notification permission (mark, sound, popbox).
    [center requestAuthorizationWithOptions:(UNAuthorizationOptionBadge|UNAuthorizationOptionSound|UNAuthorizationOptionAlert) completionHandler:^(BOOL granted, NSError * _Nullable error) {
        if(granted){
            NSLog(@"Notifications are allowed to be pushed.");
        }
    }];
    center.delegate = [ZPNs shared];

Get APNs's DeviceToken

1. In the AppDelegate.m file, you will need to implement the following callback for receiving the deviceToken.

- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {

}

2. Call the registerAPNs method to set up the APNs. You will receive the DeviceToken through the callback didRegisterForRemoteNotificationsWithDeviceToken when APNs is set successfully.

   [[ZPNs shared] registerAPNs];

Get the DeviceToken using the ZPNs SDK

In the callback didRegisterForRemoteNotificationsWithDeviceToken, you will need to call the setDeviceToken method to get the DeviceToken.

// Get the DeviceToken using the ZPNs SDK
- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
/// Required - Used to get DeviceToken.
//isProduct indicates whether the environment is a production environment.
  [[ZPNs shared] setDeviceToken:devicetoken isProduct:false];
}

After the ZPNs SDK obtains the DeviceToken, it will transfer the DeviceToken to the ZIM SDK, and the ZIM SDK will perform corresponding offline push processing logic based on the DeviceToken.

Implement the offline push notification feature with 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.

Get the pushID through onRegistered

- (void)onRegistered:(NSString *)Pushid{

}

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 alloc] init];
   pushConfig.title = @"offline push notification title";
   pushConfig.content = @"offline push notification content";
   pushConfig.payload = @"Customizable field, optional.";
   pushConfig.resourcesID = @"resourcesID";

2. Set up the configurations for offline push notification by modifying the pushConfig parameter of the ZIMMessageSendConfig object.

   ZIMMessageSendConfig *sendConfig = [ZIMMessageSendConfig alloc] init];
   sendConfig.pushConfig = pushConfig;

3. The message sender calls the sendPeerMessage method with the sendConfig to send one-to-one messages.

   [zim sendPeerMessage:textMessage toUserID:@"toUserID" config:sendConfig callback:^(ZIMMessage * _Nonnull message, ZIMError * _Nonnull errorInfo) {
   
   }];

4. The receiver will receive the offline messages when gets back online.

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 alloc] init];
   pushConfig.title = @"offline push notification title;
   pushConfig.content = @"offline push notification content";
   pushConfig.payload = @"Customizable field, optional.";
   pushConfig.resourcesID = @"resourcesID";

2. Set up the configurations for offline push notification by modifying the pushConfig parameter of the ZIMMessageSendConfig object.

   ZIMMessageSendConfig *sendConfig = [ZIMMessageSendConfig alloc] init];
   sendConfig.pushConfig = pushConfig;

3. The message sender calls the sendGroupMessage method with the sendConfig to send group messages.

   [zim sendGroupMessage:textMessage toUserID:@"myGroupID" config:sendConfig callback:^(ZIMMessage * _Nonnull message, ZIMError * _Nonnull errorInfo) {
   
   }];

4. The group members who are offline can receive offline messages when getting back online in the group.

Unregister Offline Push

If developers no longer want a certain device to receive offline push notifications, they can unregister it by calling the unregisterAPNs interface. After unregistering, both alert push and silent push will no longer take effect.

[[ZPNs shared] unregisterAPNs];