- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// 注册推送。
[application registerForRemoteNotifications];
// 初始化 `Options`，设置 App Key。
EMOptions *options = [EMOptions optionsWithAppkey:@"easemob-demo#easeim"];
// 填写上传证书时设置的名称。
options.apnsCertName = @"PushCertName";
[EMClient.sharedClient initializeSDKWithOptions:options];
return YES;
}
==== 3. 获取并将 device token 传递给 SDK ====
DeviceToken 注册后，iOS 系统会通过以下方式将 DeviceToken 回调给你，你需要把 DeviceToken 传给 SDK。
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
[EMClient.sharedClient registerForRemoteNotificationsWithDeviceToken:deviceToken completion:^(EMError *aError) {
if (aError) {
NSLog(@"bind deviceToken error: %@", aError.errorDescription);
}
}];
}
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
NSLog(@"Register Remote Notifications Failed");
}
==== 4. 设置离线推送 ====
环信 IM 3.9.2 及以上版本对离线消息推送进行了优化。你可以对 app 以及各类型的会话开启和关闭离线推送功能，关闭时可设置关闭时长。
环信 IM 支持你对离线推送功能进行如下配置：
* 设置推送通知，包含设置推送通知方式和免打扰模式。
* 配置推送翻译和推送模板。
=== 4.1 设置推送通知 ===
为优化用户在处理大量推送通知时的体验，环信 IM 在 app 和会话层面提供了推送通知和免打扰（DND）模式的细粒度选项，如下表所示：
| 模式 | 选项 | App | 会话 |
|---|---|---|---|
| 推送通知方式 | All：接收所有离线消息的推送通知。 | ✓ | ✓ |
| MentionOnly：仅接收提及消息的推送通知。 | ✓ | ✓ | |
| NONE：不接收离线消息的推送通知。 | ✓ | ✓ | |
| 免打扰模式 | silentModeDuration：在指定时长内不接收推送通知。 | ✓ | ✓ |
| silentModeStartTime & silentModeEndTime：在指定的时间范围内不接收推送通知。 | ✓ | ✗ |
//设置推送通知方式为 `MentionOnly`。
EMSilentModeParam *param = [[EMSilentModeParam alloc]initWithParamType:EMSilentModeParamTypeRemindType];
param.remindType = EMPushRemindTypeMentionOnly;
//设置 app 的离线推送免打扰模式。
[[EMClient sharedClient].pushManager setSilentModeForAll:param completion:^(EMSilentModeResult *aResult, EMError *aError) {
if (aError) {
NSLog(@"setSilentModeForAll error---%@",aError.errorDescription);
}
}];
//设置离线推送免打扰时长为 15 分钟。
EMSilentModeParam *param = [[EMSilentModeParam alloc]initWithParamType:EMSilentModeParamTypeDuartion];
param.silentModeDuration = 15;
//设置离线推送的免打扰时间段为 8:30 到 15:00。
EMSilentModeParam *param = [[EMSilentModeParam alloc]initWithParamType:EMSilentModeParamTypeInterval];
param.silentModeStartTime = [[EMSilentModeTime alloc]initWithHours:8 minutes:30];
param.silentModeEndTime = [[EMSilentModeTime alloc]initWithHours:15 minutes:0];
== 4.1.2 获取 app 的推送通知设置 ==
你可以调用 ''%%getSilentModeForAll%%'' 获取 app 级别的推送通知设置，如以下代码示例所示：
[[EMClient sharedClient].pushManager getSilentModeForAllWithCompletion:^(EMSilentModeResult *aResult, EMError *aError) {
if (!aError) {
//获取 app 的推送通知方式。
EMPushRemindType remindType = aResult.remindType;
//获取 app 的离线推送免打扰过期 Unix 时间戳。
NSTimeInterval ex = aResult.expireTimestamp;
//获取 app 的离线推送免打扰时段的开始时间。
EMSilentModeTime *startTime = aResult.silentModeStartTime;
EMSilentModeTime *endTime = aResult.silentModeEndTime;
}else{
NSLog(@"getSilentModeForAll error---%@",aError.errorDescription);
}
}];
== 4.1.3 设置单个会话的推送通知 ==
你可以调用 ''%%setSilentModeForConversation%%'' 设置指定会话的推送通知，并通过指定 ''%%EMSilentModeParam%%'' 字段设置推送通知方式和免打扰模式，如以下代码示例所示：
//设置推送通知方式为 `MentionOnly`。
EMSilentModeParam *param = [[EMSilentModeParam alloc]initWithParamType:EMSilentModeParamTypeRemindType];
param.remindType = EMPushRemindTypeMentionOnly;
//设置离线推送免打扰时长为 15 分钟。
EMSilentModeParam *param = [[EMSilentModeParam alloc]initWithParamType:EMSilentModeParamTypeDuartion];
param.silentModeDuration = 15;
EMConversationType conversationType = EMConversationTypeGroupChat;
[[EMClient sharedClient].pushManager setSilentModeForConversation:@"conversationId" conversationType:conversationType params:param completion:^(EMSilentModeResult *aResult, EMError *aError) {
if (aError) {
NSLog(@"setSilentModeForConversation error---%@",aError.errorDescription);
}
}];
== 4.1.4 获取单个会话的推送通知设置 ==
你可以调用 ''%%getSilentModeForAllWithCompletion%%'' 获取指定会话的推送通知设置，如以下代码示例所示：
[[EMClient sharedClient].pushManager getSilentModeForAllWithCompletion:^(EMSilentModeResult *aResult, EMError *aError) {
if (!aError) {
//获取会话的推送通知方式。
if(aResult.isSetConversationRemindType){
EMPushRemindType remindType = aResult.remindType;
}
//获取会话的离线推送免打扰过期 Unix 时间戳。
NSTimeInterval ex = aResult.expireTimestamp;
//获取会话的离线推送免打扰时段的开始时间。
EMSilentModeTime *startTime = aResult.silentModeStartTime;
EMSilentModeTime *endTime = aResult.silentModeEndTime;
}else{
NSLog(@"getSilentModeForAll error---%@",aError.errorDescription);
}s
}];
== 4.1.5 获取多个会话的推送通知设置 ==
- 你可以在每次调用中最多获取 20 个会话的设置。
- 如果会话继承了 app 设置或其推送通知设置已过期，则返回的字典不包含此会话。
你可以调用 ''%%getSilentModeForConversations%%'' 获取多个会话的推送通知设置，如以下代码示例所示：
NSArray *conversations = @[conversation1,conversation2];
[[EMClient sharedClient].pushManager getSilentModeForConversations:conversationArray completion:^(NSDictionary*aResult, EMError *aError) {
if (aError) {
NSLog(@"getSilentModeForConversations error---%@",aError.errorDescription);
}
}];
== 4.1.6 清除单个会话的推送通知方式的设置 ==
你可以调用 ''%%clearRemindTypeForConversation:%%'' 清除指定会话的推送通知方式的设置。清除后，默认情况下，此会话会继承 app 的设置。
以下代码示例显示了如何清除会话的推送通知方式的设置：
//清除指定会话的推送通知方式的设置。清除后，该会话会采取 app 的设置。
[[EMClient sharedClient].pushManager clearRemindTypeForConversation:@"" conversationType:conversationType completion:^(EMSilentModeResult *aResult, EMError *aError) {
if (aError) {
NSLog(@"clearRemindTypeForConversation error---%@",aError.errorDescription);
}
}];
=== 4.2 设置显示属性 ===
== 4.2.1 设置推送通知的显示属性 ==
你可以调用 ''%%updatePushDisplayName%%'' 设置推送通知中显示的昵称，如以下代码示例所示：
[EMClient.sharedClient.pushManager updatePushDisplayName:@"displayName" completion:^(NSString * aDisplayName, EMError * aError) {
if (aError)
{
NSLog(@"update push display name error: %@", aError.errorDescription);
}
}];
你也可以调用 ''%%updatePushDisplayStyle%%'' 设置推送通知的显示样式，如下代码示例所示：
[EMClient.sharedClient.pushManager updatePushDisplayStyle:EMPushDisplayStyleSimpleBanner completion:^(EMError * aError)
{
if(aError)
{
NSLog(@"update display style error --- %@", aError.errorDescription);
}
}];
''%%DisplayStyle%%'' 是枚举类型。
^参数 ^描述 ^
|''%%EMPushDisplayStyleSimpleBanner%%'' |显示“你有一条新消息”。 |
|''%%EMPushDisplayStyleMessageSummary%%'' |显示消息内容。 |
== 4.2.2 获取推送通知的显示属性 ==
你可以调用 ''%%getPushNotificationOptionsFromServerWithCompletion%%'' 获取推送通知中的显示属性，如以下代码示例所示：
[EMClient.sharedClient.pushManager getPushNotificationOptionsFromServerWithCompletion:^(EMPushOptions * aOptions, EMError * aError)
{
if (aError)
{
NSLog(@"get push options error --- %@", aError.errorDescription);
}
}];
''%%EMPushOptions%%'' 推送配置对象。
^属性名 ^描述 ^
|''%%displayName%%'' |对方收到推送时发送方展示的名称。 |
|''%%displayStyle%%'' |推送显示类型。 |
==== 4.3 设置推送翻译 ====
如果用户启用 [[https://docs-im.easemob.com/ccim/ios/translation#%E8%AE%BE%E7%BD%AE%E8%87%AA%E5%8A%A8%E7%BF%BB%E8%AF%91|自动翻译]]功能并发送消息，SDK 会同时发送原始消息和翻译后的消息。
推送通知与翻译功能协同工作。作为接收方，你可以设置你在离线时希望接收的推送通知的首选语言。如果翻译消息的语言符合你的设置，则翻译消息显示在推送通知中；否则，将显示原始消息。
以下代码示例显示了如何设置和获取推送通知的首选语言：
//设置离线推送的首选语言。
[[EMClient sharedClient].pushManager setPreferredNotificationLanguage:@"EU" completion:^(EMError *aError) {
if (aError) {
NSLog(@"setPushPerformLanguageCompletion error---%@",aError.errorDescription);
}
}];
//获取离线推送的首选语言。
[[EMClient sharedClient].pushManager getPreferredNotificationLanguageCompletion:^(NSString *aLaguangeCode, EMError *aError) {
if (!aError) {
NSLog(@"getPushPerformLanguage---%@",aLaguangeCode);
}
}];
=== 4.4 设置推送模板 ===
环信 IM 支持自定义推送通知模板。使用前，你可参考以下步骤在环信即时通讯云管理后台上创建推送模板：
- 登录环信 IM Console，进入首页。
- 在 **应用列表** 区域中，点击对应 app 的 **操作** 一栏中的 **查看** 按钮。
- 在环信 IM 配置页面的左侧导航栏，选择 **即时通讯 > 功能配置 > 消息推送 > 模板管理**，进入推送模板管理页面。
{{:ccim:android:push_console_template_mgmt.png|}}
- 点击 **添加推送模板**。弹出以下页面，进行参数配置。
{{:ccim:android:push_android_ios_template_add.png|}}
在环信即时通讯云管理后台中完成模板创建后，用户可以在发送消息时选择此推送模板作为默认布局，如下代码示例所示：
//下面以文本消息为例，其他类型的消息设置方法相同。
EMTextMessageBody *body = [[EMTextMessageBody alloc]initWithText:@"test"];
EMChatMessage *message = [[EMChatMessage alloc]initWithConversationID:@"conversationId" from:@"currentUsername" to:@"conversationId" body:body ext:nil];
//设置推送模板。设置前需在环信即时通讯云管理后台上创建推送模板。
NSDictionary *pushObject = @{
@"name":@"templateName",//设置推送模板名称。
@"title_args":@[@"titleValue1"],//设置填写模板标题的 value 数组。
@"content_args":@[@"contentValue1"]//设置填写模板内容的 value 数组。
};
message.ext = @{
@"em_push_template":pushObject,
};
message.chatType = EMChatTypeChat;
[[EMClient sharedClient].chatManager sendMessage:message progress:nil completion:nil];
==== 5. 解析收到的推送字段 ====
当设备收到推送并点击时，iOS 会通过 ''%%launchOptions%%'' 将推送中的 JSON 传递给 app，这样就可以根据推送的内容定制 app 的一些行为，比如页面跳转等。 当收到推送通知并点击推送时，app 获取推送内容的方法：
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
NSDictionary *userInfo = launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey];
}
userInfo:
{
"aps":{
"alert":{
"body":"你有一条新消息"
},
"badge":1,
"sound":"default"
},
"f":"6001",
"t":"6006",
"g":"1421300621769",
"m":"373360335316321408"
}
^参数 ^描述 ^
|''%%body%%'' |显示内容。 |
|''%%badge%%'' |角标数。 |
|''%%sound%%'' |提示铃声。 |
|''%%f%%'' |消息发送方 ID。 |
|''%%t%%'' |消息接收方 ID。 |
|''%%g%%'' |群组 ID，单聊无该字段。 |
|''%%m%%'' |消息 ID。 |
===== 更多功能 =====
==== 自定义字段 ====
向推送中添加自定义业务字段满足业务需求，例如，通过这条推送跳转到某个活动页面。
EMTextMessageBody *body = [[EMTextMessageBody alloc] initWithText:@"test"];
EMChatMessage *message = [[EMChatMessage alloc] initWithConversationID:conversationId from:currentUsername to:conversationId body:body ext:nil];
message.ext = @{@"em_apns_ext":@{@"extern":@"custom string"}};
message.chatType = EMChatTypeChat;
[EMClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];
^参数 ^描述 ^
|''%%body%%'' |消息体。 |
|''%%ConversationID%%'' |消息属于的会话 ID。 |
|''%%from%%'' |消息发送方，一般为当前登录 ID。 |
|''%%to%%'' |消息接收方 ID，一般与 ''%%ConversationID%%'' 一致。 |
|''%%em_apns_ext%%'' |消息扩展，使用扩展的方式向推送中添加自定义字段，该值为固定值，不可修改。 |
|''%%extern%%'' |自定义字段 key，用于设置自定义的内容，该值为固定值，不可修改。 |
|''%%custom string%%'' |自定义字段内容。 |
**解析的内容**
{
"apns": {
"alert": {
"body": "test"
},
"badge": 1,
"sound": "default"
},
"e": "custom string",
"f": "6001",
"t": "6006",
"m": "373360335316321408"
}
^参数 ^描述 ^
|''%%body%%'' |显示内容。 |
|''%%badge%%'' |角标数。 |
|''%%sound%%'' |提示铃声。 |
|''%%f%%'' |消息发送方 ID。 |
|''%%t%%'' |消息接收方 ID。 |
|''%%e%%'' |自定义信息。 |
|''%%m%%'' |消息 ID。 |
==== 自定义显示 ====
自定义显示内容时，你可以随意设置 APNs 通知时显示的内容。
EMTextMessageBody *body = [[EMTextMessageBody alloc] initWithText:@"test"];
EMChatMessage *message = [[EMChatMessage 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 = EMChatTypeChat;
[EMClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];
^参数 ^描述 ^
|''%%body%%'' |消息体。 |
|''%%ConversationID%%'' |消息属于的会话 ID。 |
|''%%from%%'' |消息发送方，一般为当前登录 ID。 |
|''%%to%%'' |消息接收方 ID，一般与 ''%%ConversationID%%'' 一致。 |
|''%%em_apns_ext%%'' |消息扩展，使用扩展的方式向推送中添加自定义字段，该值为固定值，不可修改。 |
| ''%%em_alert_title%%'' | 推送通知的自定义标题。 |
| ''%%em_alert_subTitle%%'' | 推送通知的自定义副标题。 |
| ''%%em_alert_body%%'' |推送通知展示的自定义内容。 |
**解析的内容**
{
"aps":{
"alert":{
"body":"custom push content"
},
"badge":1,
"sound":"default"
},
"f":"6001",
"t":"6006",
"m":"373360335316321408",
}
^参数 ^描述 ^
|''%%body%%'' |显示内容。 |
|''%%badge%%'' |角标数。 |
|''%%sound%%'' |提示铃声。 |
|''%%f%%'' |消息发送方 ID。 |
|''%%t%%'' |消息接收方 ID。 |
|''%%m%%'' |消息 ID。 |
==== 自定义铃声 ====
推送铃声是指用户收到推送时的提示音，你需要将音频文件加入到 app 中，并在推送中配置使用的音频文件名称。
EMTextMessageBody *body = [[EMTextMessageBody alloc] initWithText:@"test"];
EMChatMessage *message = [[EMChatMessage alloc] initWithConversationID:conversationId from:currentUsername to:conversationId body:body ext:nil];
message.ext = @{@"em_apns_ext":@{@"em_push_sound":@"custom.caf"}};
message.chatType = EMChatTypeChat;
[EMClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];
^参数 ^描述 ^
|''%%body%%'' |消息体。 |
|''%%ConversationID%%'' |消息属于的会话 ID。 |
|''%%from%%'' |消息发送方，一般为当前登录 ID。 |
|''%%to%%'' |消息接收方 ID，一般与 ''%%ConversationID%%'' 一致。 |
|''%%em_apns_ext%%'' |消息扩展，使用扩展的方式向推送中添加自定义字段，该值为固定值，不可修改。 |
|''%%em_push_sound%%'' |自定义字段，用于设置自定义要显示的内容，该值为固定值，不可修改。 |
|''%%custom.caf%%'' |音频文件名称。 |
**解析的内容**
{
"aps":{
"alert":{
"body":"你有一条新消息"
},
"badge":1,
"sound":"custom.caf"
},
"f":"6001",
"t":"6006",
"m":"373360335316321408"
}
^参数 ^描述 ^
|''%%body%%'' |显示内容。 |
|''%%badge%%'' |角标数。 |
|''%%sound%%'' |提示铃声。 |
|''%%f%%'' |消息发送方 ID。 |
|''%%t%%'' |消息接收方 ID。 |
|''%%m%%'' |消息 ID。 |
==== 强制推送 ====
使用该方式设置后，本条消息会忽略接收方的免打扰设置，不论是否处于免打扰时间段都会正常向对方推送通知；
EMTextMessageBody *body = [[EMTextMessageBody alloc] initWithText:@"test"];
EMChatMessage *message = [[EMChatMessage alloc] initWithConversationID:conversationId from:currentUsername to:conversationId body:body ext:nil];
message.ext = @{@"em_force_notification":@YES};
message.chatType = EMChatTypeChat;
[EMClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];
^参数 ^描述 ^
|''%%body%%'' |消息体。 |
|''%%ConversationID%%'' |消息属于的会话 ID。 |
|''%%from%%'' |消息发送方，一般为当前登录 ID。 |
|''%%to%%'' |消息接收方 ID，一般与 ''%%ConversationID%%'' 一致。 |
|''%%em_force_notification%%'' |标志是否为强制推送的关键字，不可修改。 |
==== 基于 UNNotificationServiceExtension 的扩展功能 ====
在 iOS10 之后生效，目的是为了唤醒 [[https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension?language=objc|UNNotificationServiceExtension]]，让你可以做更多的扩展。
EMTextMessageBody *body = [[EMTextMessageBody alloc] initWithText:@"test"];
EMChatMessage *message = [[EMChatMessage alloc] initWithConversationID:conversationId from:currentUsername to:conversationId body:body ext:nil];
message.ext = @{@"em_apns_ext":@{@"em_push_mutable_content":@YES}};
message.chatType = EMChatTypeChat;
[EMClient.sharedClient.chatManager sendMessage:message progress:nil completion:nil];
^参数 ^描述 ^
|''%%body%%'' |消息体。 |
|''%%ConversationID%%'' |消息属于的会话 ID。 |
|''%%from%%'' |消息发送方，一般为当前登录 ID。 |
|''%%to%%'' |消息接收方 ID，一般与 ''%%ConversationID%%'' 一致。 |
|''%%em_apns_ext%%'' |消息扩展，使用扩展的方式向推送中添加自定义字段，该值为固定值，不可修改。 |
|''%%em_push_mutable_content%%'' |是否使用推送扩展的关键字，不可修改。 |
**解析的内容**
{
"aps":{
"alert":{
"body":"test"
},
"badge":1,
"sound":"default",
"mutable-content":1
},
"f":"6001",
"t":"6006",
"m":"373360335316321408"
}
^参数 ^描述 ^
|''%%body%%'' |显示内容。 |
|''%%badge%%'' |角标数。 |
|''%%sound%%'' |提示铃声。 |
|''%%mutable-content%%'' |苹果要求的关键字，存在之后才可唤醒 UNNotificationServiceExtension。 |
|''%%f%%'' |消息发送方 ID。 |
|''%%t%%'' |消息接收方 ID。 |
|''%%m%%'' |消息 ID。 |