Offline Push

Agora Chat supports the integration of Apple Push Notification service (APNs). This enables iOS developers to use an offline push notification service. The service features low latency, high delivery, high concurrency, and no violation of the users' personal data.

Understand the tech

The following figure shows the basic workflow of Agora Chat:

Assume that User A sends a message to User B, but User B goes offline before receiving it. The Agora Chat server pushes a notification to the device of User B via APN and temporarily stores this message. Once User B comes back online, the Agora Chat SDK pulls the message from the server and pushes the message to User B using persistent connections.

Prerequisites

Before proceeding, ensure that you meet the following requirements:

• You have initialized the Agora Chat SDK. For details, see Get Started with iOS.
• You understand the call frequency limit of the Agora Chat APIs supported by different pricing plans as described in Limitations.
• You have activated the advanced features for push in Agora Console. Advanced features allow you to set the push notification mode, do-not-disturb mode, and custom push template.

Integrate APN with Agora Chat

1. Create push certificates

Follow these steps to enable the APNs service:

1. Request a Certificate Signing Request (CSR) file.

   1. Open the Keychain Access app on your device, and select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority.
   2. In the Certificate Assistant dialog box, fill in User Email Address and Common Name, select Saved to disk, and click Continue to specify a path to save the file.
      
   3. You can get a CSR file named CertificateSigningRequest.certSigningRequest in the specified path.

2. Create an App ID.

   1. Log in to the iOS Developer Center, and select Account > Certificates, Identifiers & Profiles > Identifiers.
   2. In the Identifiers tab, click the + icon to the right of Identifiers.
   3. In the Register a new identifier page, select App for the type, and click Continue.
   4. In the Register an App ID page, configure the following fields:
      • Description: Fill in the description of the App ID.
      • Bundle ID: Specify a value in com.YourCompany.YourProjectName format.
      • Capabilities: Select Push Notifications.
   5. Confirm the information, and click Register to generate the App ID.

3. Create a push certificate for both the development environment and the production environment in turn.

   1. Go back to the Identifiers tab, and select the App ID created in step 2.
   2. In the Edit your App ID Configuration page, locate Push Notifications, and click Configure.
   3. In the Apple Push Notification service SSL Certificates dialog box, click Create Certificate to create the push certificate for the development environment or the production environment, as applicable.
   4. In the Create a New Certificate page, select iOS for Platform, upload the CSR file created in step 1, and click Continue.
   5. In the Download Your Certificate page, click Download to generate the Apple Push Services certificate.

4. Generate the push certificate.

   1. Double-click to import the push certificate created in step 3 to the Keychain.
   2. Open Keychain Access, select login > Certificates, right-click the push certificate to export as a .p12 file, and set the certificate key.

5. Generate a Provisioning Profile file.

   1. Log in to iOS Developer Center, and select Account > Certificates, Identifiers & Profiles > Profiles.
   2. In the Profiles tab, click the + icon to the right of Profiles.
   3. In the Register a New Provisioning Profile page, select iOS App Development for Development, select Ad Hoc for Distribution, and click Continue.
      For an official release on the App Store, select App Store instead for Distribution.
   4. In the Generate a Provisioning Profile page, configure the following fields:
      • App ID: Fill in the App ID created in step 2.
      • Select Certificates: Select the .p12 file generated in step 4.
      • Select Devices: Select the device used to develop.
      • Provisioning Profile Name: Fill in the name used to identify the profile.
   5. Confirm the information, and click Download to generate the Provisioning Profile file.

2. Upload push certificates

Follow the steps to upload the certificates to Agora Console:

1. Log in to Agora Console, and click Project Management in the left navigation bar.

2. On the Project Management page, locate the project that has Chat enable and click Config.

3. On the project edit page, click Config next to Chat.

4. On the project config page, select Features > Push Certificate and click Add Push Certificate.

5. In the pop-up window, select the APPLE tab, and configure the following fields:

   • Certificate Type: Select the file type specified when the certificate was exported. In this case, select p12.

   • Certificate Name: Fill in the name specified when the certificate was exported.

   • Push Key: Fill in the secret specified when the certificate was exported.

   • Upload Certificate: Upload the certificate exported.

   • Integration Environment: Select Development or Production Environment. Upload the p12 file for the development and production environments in turn.

   • Bind ID: Fill in the bundle ID specified when the App ID was created.

     Click Save to add the push certificate.

3. Enable APN in Agora Chat SDK

1. Open Xcode, and select TARGETS > Capability > Push Notifications to enable push notifications.

2. Pass the certificate name to the SDK.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Register for notifications
    [application registerForRemoteNotifications];

    // Initialize Options and set AppKey
    AgoraChatOptions *options = [AgoraChatOptions optionsWithAppkey:@"XXXX#XXXX"];

    // Fill in the name specified when uploading the certificate
    options.apnsCertName = @"PushCertName";

    [AgoraChatClient.sharedClient initializeSDKWithOptions:options];

    return YES;
}

3. Get a Device Token, and pass it to the SDK.

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [AgoraChatClient.sharedClient registerForRemoteNotificationsWithDeviceToken:deviceToken completion:^(AgoraChatError *aError) {
        if (aError) {
            NSLog(@"bind deviceToken error: %@", aError.errorDescription);
        }
    }];
}
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
    NSLog(@"Register Remote Notifications Failed");
}

Set up push notifications

To optimize user experience when dealing with an influx of push notifications, Agora Chat provides fine-grained options for the push notification and do-not-disturb (DND) modes at both the app and conversation levels, as shown in the following table:

Push notification mode

The setting of the push notification mode at the conversation level takes precedence over that at the app level, and those conversations that do not have specific settings for the push notification mode inherit the app setting by default.

For example, assume that the push notification mode of the app is set to MentionOnly, while that of the specified conversation is set to All. You receive all the push notifications from this conversation, while you only receive the push notifications for mentioned messages from all the other conversations.

Do-not-disturb mode

For both the app and all the conversations in the app, the setting of the DND mode takes precedence over the setting of the push notification mode.

For example, assume that a DND time period is specified at the app level and the push notification mode of the specified conversation is set to All. The DND mode takes effect regardless of the setting of the push notification mode, that is, you do not receive any push notifications during the specified DND time period.

Alternatively, assume that a DND time period is specified for a conversation, while the app does not have any DND settings and its push notification mode is set to All. You do not receive any push notifications from this conversation during the specified DND time period, while the push of all the other conversations remains the same.

Set the push notifications of an app

You can call setSilentModeForAll to set the push notifications at the app level and set the push notification mode and DND mode by specifying the AgoraChatSilentModeParam field, as shown in the following code sample:

// Sets the push notification mode to `MentionOnly` for an app.
AgoraChatSilentModeParam *param = [[AgoraChatSilentModeParam alloc]initWithParamType:AgoraChatSilentModeParamTypeRemindType];
    param.remindType = AgoraChatPushRemindTypeMentionOnly;
// Sets the push notifications at the app level.
[[AgoraChatClient sharedClient].pushManager setSilentModeForAll:param completion:^(AgoraChatSilentModeResult *aResult, AgoraChatError *aError) {
            if (aError) {
                NSLog(@"setSilentModeForAll error---%@",aError.errorDescription);
            }
        }];
// Sets the DND duration to 15 minutes.
AgoraChatSilentModeParam *param = [[AgoraChatSilentModeParam alloc]initWithParamType:AgoraChatSilentModeParamTypeDuration];
    param.silentModeDuration = 15;
// Sets the DND time frame from 8:30 to 15:00.
AgoraChatSilentModeParam *param = [[AgoraChatSilentModeParam alloc]initWithParamType:AgoraChatSilentModeParamTypeDuration];
    param.silentModeStartTime = [[AgoraChatSilentModeTime alloc]initWithHours:8 minutes:30];
    param.silentModeEndTime = [[AgoraChatSilentModeTime alloc]initWithHours:15 minutes:0];

Retrieve the push notification setting of an app

You can call getSilentModeForAllWithCompletion to retrieve the push notification settings at the app level, as shown in the following code sample:

[[AgoraChatClient sharedClient].pushManager getSilentModeForAllWithCompletion:^(AgoraChatSilentModeResult *aResult, AgoraChatError *aError) {
            if (!aError) {
                // Retrieves the setting of the push notification mode at the app level.
                AgoraChatPushRemindType remindType = aResult.remindType;
                // Retrieves the Unix timestamp when the DND duration of an app expires.
                NSTimeInterval ex = aResult.expireTimestamp;
                // Retrieves the start time specified in the DND time frame at the app level.
                AgoraChatSilentModeTime *startTime = aResult.silentModeStartTime;
                // Retrieves the end time specified in the DND time frame at the app level.
                AgoraChatSilentModeTime *endTime = aResult.silentModeEndTime;
            }else{
                NSLog(@"getSilentModeForAll error---%@",aError.errorDescription);
            }
        }];

Set the push notifications of a conversation

You can call setSilentModeForConversation to set the push notifications for the conversation specified by the conversationId and AgoraChatConversationType fields, as shown in the following code sample:

// Sets the push notification mode to `MentionOnly` for a conversation.
AgoraChatSilentModeParam *param = [[AgoraChatSilentModeParam alloc]initWithParamType:AgoraChatSilentModeParamTypeRemindType];
    param.remindType = AgoraChatPushRemindTypeMentionOnly;
// Sets the DND duration to 15 minutes.
AgoraChatSilentModeParam *param = [[AgoraChatSilentModeParam alloc]initWithParamType:AgoraChatSilentModeParamTypeDuration];
    param.silentModeDuration = 15;
// Sets the push notifications at the conversation level.                                    
AgoraChatConversationType conversationType = AgoraChatConversationTypeGroupChat;
[[AgoraChatClient sharedClient].pushManager setSilentModeForConversation:@"conversationId" conversationType:conversationType params:param completion:^(AgoraChatSilentModeResult *aResult, AgoraChatError *aError) {
        if (aError) {
                NSLog(@"setSilentModeForConversation error---%@",aError.errorDescription);
         }
     }];

Retrieve the push notification setting of a conversation

You can call getSilentModeForConversation to retrieve the push notification settings of the conversation specified by the conversationId and AgoraChatConversationType fields, as shown in the following code sample:

[[AgoraChatClient sharedClient].pushManager getSilentModeForConversation:@"conversationId" conversationType:AgoraChatConversationTypeChat completion:^(AgoraChatSilentModeResult * _Nullable aResult, AgoraChatError * _Nullable aError) {
    }];

Retrieve the push notification settings of multiple conversations

You can call getSilentModeForConversations to retrieve the push notification settings of multiple conversations, as shown in the following code sample:

NSArray *conversations = @[conversation1,conversation2];
[[AgoraChatClient sharedClient].pushManager getSilentModeForConversations:conversationArray completion:^(NSDictionary<NSString*,AgoraChatSilentModeResult*>*aResult, AgoraChatError *aError) {
        if (aError) {
            NSLog(@"getSilentModeForConversations error---%@",aError.errorDescription);
        }
    }];

Clear the push notification mode of a conversation

You can call clearRemindTypeForConversation to clear the push notification mode of the specified conversation. Once the specific setting of a conversation is cleared, this conversation inherits the app setting by default.

The following code sample shows how to clear the push notification mode of a conversation:

    [[AgoraChatClient sharedClient].pushManager clearRemindTypeForConversation:@"" conversationType:conversationType completion:^(AgoraChatSilentModeResult *aResult, AgoraChatError *aError) {
            if (aError) {
                NSLog(@"clearRemindTypeForConversation error---%@",aError.errorDescription);
            }
    }];

Set up display attributes

Set the display attributes of push notifications

You can call updatePushDisplayName to set the nickname displayed in your push notifications, as shown in the following code sample:

[AgoraChatClient.sharedClient.pushManager updatePushDisplayName:@"displayName" completion:^(NSString * aDisplayName, AgoraChatError * aError) {
    if (aError) 
    {
        NSLog(@"update push display name error: %@", aError.errorDescription);
    }
}];

You can also call updatePushDisplayStyle to set the display style of push notifications, as shown in the following code sample:

// `AgoraPushDisplayStyleSimpleBanner` indicates that only "You have a new message" displays.
// To display the message content, set `DisplayStyle` to `AgoraPushDisplayStyleMessageSummary`.
[AgoraChatClient.sharedClient.pushManager updatePushDisplayStyle:AgoraPushDisplayStyleSimpleBanner completion:^(AgoraChatError * aError)
{
    if(aError)
    {
        NSLog(@"update display style error --- %@", aError.errorDescription);
    }
}];

Retrieve the display attributes of push notifications

You can call getPushNotificationOptionsFromServerWithCompletion to retrieve the display attributes in push notifications, as shown in the following code sample:

[[AgoraChatClient sharedClient] getPushNotificationOptionsFromServerWithCompletion:^(AgoraChatPushOptions *aOptions, AgoraChatError *aError) {
            if (!aError) {
                // Retrieves the nickname displayed in push notifications.
                NSString *displayName = aOptions.displayName;
                // Retrieves the display style of push notifications.
                AgoraChatPushDisplayStyle dispalyStyle = aOptions.displayStyle;
            }
        }];

Set up push translations

If a user enables the automatic translation feature and sends a message, the SDK sends both the original message and the translated message.

Push notifications work in tandem with the translation feature. As a receiver, you can set the preferred language of push notifications that you are willing to receive when you are offline. If the language of the translated message meets your setting, the translated message displays in push notifications; otherwise, the original message displays instead.

The following code sample shows how to set and retrieve the preferred language of push notifications

// Sets the preferred language of push notifications.
[[AgoraChatClient sharedClient].pushManager setPreferredNotificationLanguage:@"EU" completion:^(AgoraChatError *aError) {
    if (aError) {
        NSLog(@"setPushPerformLanguageCompletion error---%@",aError.errorDescription);
    }
}];
// Retrieves the preferred language of push notifications.
[[AgoraChatClient sharedClient].pushManager getPreferredNotificationLanguageCompletion:^(NSString *aLaguangeCode, AgoraChatError *aError) {
    if (!aError) {
        NSLog(@"getPushPerformLanguage---%@",aLaguangeCode);
    }
}];

Set up push templates

Agora Chat allows users to use ready-made templates for push notifications.

You can create and provide push templates for users by referring to the following steps:

1. Log in to Agora Console, and click Project Management in the left navigation bar.

2. On the Project Management page, locate the project that has Chat enable and click Config.

3. On the project edit page, click Config next to Chat.

4. On the project config page, select Features > Push Template and click Add Push Template, and configure the fields in the pop-up window, as shown in the following figure:

Once the template creation is complete in Agora Console, users can choose this push template as their default layout when sending a message, as shown in the following code sample:

// This code sample takes a TXT message as an example. You can use the same approach to set IMAGE messages and FILE messages.
AgoraChatTextMessageBody *body = [[AgoraChatTextMessageBody alloc]initWithText:@"test"];
AgoraChatMessage *message = [[AgoraChatMessage alloc]initWithConversationID:@"conversationId" from:@"currentUsername" to:@"conversationId" body:body ext:nil];
       // Sets the push template created in Agora Console as their default layout.
       NSDictionary *pushObject = @{
           @"name":@"templateName",// Sets the template name.
           @"title_args":@[@"titleValue1"],// Sets the template title by specifying the variable.
           @"content_args":@[@"contentValue1"]// Sets the template content by specifying the variable.
       };
       message.ext = @{
           @"em_push_template":pushObject,
       };
       message.chatType = AgoraChatTypeChat;
[[AgoraChatClient sharedClient].chatManager sendMessage:message progress:nil completion:nil];

What's next

This section includes more versatile push notification features that you can use to implement additional functions if needed.

If the ready-made templates do not meet your requirements, Agora Chat also enables you to customize your push notifications.

Custom fields

The following code sample shows how to add an extension field in push notifications:

AgoraChatTextMessageBody *body = [[AgoraChatTextMessageBody alloc] initWithText:@"test"];
AgoraChatMessage *message = [[AgoraChatMessage alloc] initWithConversationID:conversationId from:currentUsername to:conversationId body:body ext:nil];
message.ext = @{@"em_apns_ext":@{@"extern":@"custom string"}}; 
message.chatType = AgoraChatTypeChat; 
[AgoraChatClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];

An example is as follows:

{
    "apns": {
        "alert": {
            "body": "test"
        }, 
        "badge": 1, 
        "sound": "default"
    }, 
    "e": "custom string", 
    "f": "6001", 
    "t": "6006", 
    "m": "373360335316321408"
}

Custom displays

The following code sample shows how to customize the display style in push notifications:

AgoraChatTextMessageBody *body = [[AgoraChatTextMessageBody alloc] initWithText:@"test"];
AgoraChatMessage *message = [[AgoraChatMessage alloc] initWithConversationID:conversationId from:currentUsername to:conversationId body:body ext:nil];
message.ext = @{@"em_apns_ext":@{
    @"em_alert_title": @"customTitle",
    @"em_alert_subTitle": @"customSubTitle",
    @"em_alert_body": @"customBody"
}};
message.chatType = AgoraChatTypeChat; 
[AgoraChatClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];

An example is as follows:

{
    "aps":{
        "alert":{
            "body":"custom push content"
        },     
        "badge":1,                 
        "sound":"default"         
    },
    "f":"6001",                     
    "t":"6006",                     
    "m":"373360335316321408",
}

Custom sounds

To use a custom sound for push notifications, you need to add the audio file to the app and configure the filename for the push. For details, see Apple Official Documentation.
The following sample code customizes the sound of the push notification:

AgoraChatTextMessageBody *body = [[AgoraChatTextMessageBody alloc] initWithText:@"test"];
AgoraChatMessage *message = [[AgoraChatMessage alloc] initWithConversationID:conversationId from:currentUsername to:conversationId body:body ext:nil];
message.ext = @{@"em_apns_ext":@{@"em_push_sound":@"custom.caf"}};
message.chatType = AgoraChatTypeChat; 
[AgoraChatClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];

An example is as follows:

{
    "aps":{
        "alert":{
            "body":"You have a new message"
        },  
        "badge":1,  
        "sound":"custom.caf"  
    },
    "f":"6001",  
    "t":"6006",  
    "m":"373360335316321408"  
}

Force push notifications

Once you force a push notification to a user, the user receives the message regardless of the do-not-disturb settings.
The following sample code forces a push notification:

AgoraChatTextMessageBody *body = [[AgoraChatTextMessageBody alloc] initWithText:@"test"];
AgoraChatMessage *message = [[AgoraChatMessage alloc] initWithConversationID:conversationId from:currentUsername to:conversationId body:body ext:nil];
message.ext = @{@"em_force_notification":@YES};
message.chatType = AgoraChatTypeChat; 
[AgoraChatClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];

Extensions

If the receiver uses a device running iOS 10.0 or later, you can refer to the following sample code to enable the
UNNotificationServiceExtension extension.

AgoraChatTextMessageBody *body = [[AgoraChatTextMessageBody alloc] initWithText:@"test"];
AgoraChatMessage *message = [[AgoraChatMessage alloc] initWithConversationID:conversationId from:currentUsername to:conversationId body:body ext:nil];
message.ext = @{@"em_apns_ext":@{@"em_push_mutable_content":@YES}}; 
message.chatType = AgoraChatTypeChat; 
[AgoraChatClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];

An example is as follows:

{
    "aps":{
        "alert":{
            "body":"test"
        },  
        "badge":1,  
        "sound":"default",
        "mutable-content":1  
    },
    "f":"6001",  
    "t":"6006",  
    "m":"373360335316321408"  
}