====== APNs 推送 ======

----

===== 必备条件 =====

1. 后台上传了推送证书，具体步骤见 [[start:300iosclientintegration:10prepareforsdkimport#制作并上传推送证书|集成 iOS SDK 前的准备工作-制作并上传推送证书]]。

2. 代码配置 APNs 使用的推送证书。

<code objc>
[[EaseMob sharedInstance] registerSDKWithAppKey:@"appkey" apnsCertName:apnsCertName];
</code>

3. 代码注册离线推送。

<code objc>
//iOS8以上 注册APNs
if ([application respondsToSelector:@selector(registerForRemoteNotifications)]) {
    [application registerForRemoteNotifications];
    UIUserNotificationType notificationTypes = UIUserNotificationTypeBadge |
    UIUserNotificationTypeSound |
    UIUserNotificationTypeAlert;
    UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:notificationTypes categories:nil];
    [application registerUserNotificationSettings:settings];
    }
else{
    UIRemoteNotificationType notificationTypes = UIRemoteNotificationTypeBadge |
    UIRemoteNotificationTypeSound |
    UIRemoteNotificationTypeAlert;
    [[UIApplication sharedApplication] registerForRemoteNotificationTypes:notificationTypes];
}
</code>

您注册了推送功能，iOS 会自动回调以下方法，得到 deviceToken，您需要将 deviceToken 传给 SDK。

<code objc>
// 将得到的deviceToken传给SDK
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{
    [[EaseMob sharedInstance] application:application didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

// 注册deviceToken失败
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error{
    [[EaseMob sharedInstance] application:application didFailToRegisterForRemoteNotificationsWithError:error];
    NSLog(@"error -- %@",error);
}
</code>

**注意：**

  * APNs 注册失败，一般是由于使用了通用证书或者是模拟器调试导致，请检查证书并用真机调试。此处是 iOS 系统报的错，如仍不能确定，请从网上查找相关资料；
  * 当 APP 后台，但是长连接存在的情况下，环信不会给您发送 APNs，需要您自己监听 didReceiveMessage: 方法回调来实现本地通知。

===== 获取全局 APNs 配置 =====

登录成功之后，SDK 会自返回 APNs 属性，获取代码如下：

<code objc>
EMPushNotificationOptions *options = [[EaseMob sharedInstance].chatManager pushNotificationOptions];
</code>

===== 设置 APNs 全局属性 =====

提供三种方法。可以配置 APNs 免打扰时间，APNs 昵称，推送样式，EMPushNotificationOptions 中的属性传入你想设置的值，调用以下方法即可。

以下方法会将 options 参数中的所有属性都更新到服务器上，请确保传入的 options 参数中的配置符合你的要求。

1. 同步方法

<code objc>
/*!
@method
@brief 更新消息推送相关属性配置（同步方法）
@param options    属性
@param pError     更新错误信息
@result    最新的属性配置
*/
- (EMPushNotificationOptions *)updatePushOptions:(EMPushNotificationOptions *)options
error:(EMError **)pError;
</code>

2. block 异步方法

<code objc>
/*!
@method
@brief 更新消息推送相关属性配置（异步方法）
@param options    属性
@param completion 回调
@param aQueue     回调时的线程
@result
*/
- (void)asyncUpdatePushOptions:(EMPushNotificationOptions *)options
completion:(void (^)(EMPushNotificationOptions *options, EMError *error))completion
onQueue:(dispatch_queue_t)aQueue;
</code>

3. EMChatManagerPushNotificationDelegate 回调方法

<code objc>
/*!
@method
@brief 更新消息推送相关属性配置（异步方法）
@param options    属性
@discussion
方法执行完之后，调用[didUpdatePushOptions:error:];
*/
- (void)asyncUpdatePushOptions:(EMPushNotificationOptions *)options;
-
</code>

===== APNs 显示消息详情 =====

EMPushNotificationOptions 中的 displayStyle 属性可以设置推送显示内容。

<code objc>
/*!
 @enum
 @brief 推送消息的定制信息
 @constant ePushNotificationDisplayStyle_simpleBanner   简单显示一条“您有一条新消息”的文本
 @constant ePushNotificationDisplayStyle_messageSummary 会显示一条具有消息内容的推送消息
 */
typedef NS_ENUM(NSInteger, EMPushNotificationDisplayStyle) {
    ePushNotificationDisplayStyle_simpleBanner = 0,
    ePushNotificationDisplayStyle_messageSummary = 1,
};

</code>

===== 单独设置 APNs 昵称 =====

登录成功之后，按照以下代码设置当前登录用户的 APNs 昵称。

<code objc>
[[EaseMob sharedInstance].chatManager asyncLoginWithUsername:username
password:password completion:^(NSDictionary *loginInfo, EMError *error) {
    [self hideHud];
    if (loginInfo && !error) 
    {
        //设置推送设置
        [[EaseMob sharedInstance].chatManager setApnsNickname:@"推送昵称"];
    }
} onQueue:nil];
</code>

===== 设置指定群组是否接收 APNs =====

1. 同步方法

<code objc>
/*!
@method
@brief 屏蔽接收群的推送消息
@param groupId    需要屏蔽/取消屏蔽 推送消息的群ID
@param ignore     屏蔽/取消屏蔽
@param pError     错误信息
@result           返回已屏蔽接收推送消息的群列表
@discussion
全局的屏蔽推送消息属性优先于此设置
*/
- (NSArray *)ignoreGroupPushNotification:(NSString *)groupId ignore:(BOOL)ignore error:(EMError **)pError;
-
</code>

2. block 异步方法

<code objc>
/*!
@method
@brief 屏蔽接收群的推送消息，异步方法
@param groupId    需要屏蔽/取消屏蔽 推送消息的群ID
@param isIgnore   屏蔽/取消屏蔽
@param completion 回调
@param aQueue     回调时的线程
@discussion
全局的屏蔽推送消息属性优先于此设置;
*/
- (void)asyncIgnoreGroupPushNotification:(NSString *)groupId isIgnore:(BOOL)isIgnore completion:(void (^)(NSArray *ignoreGroupsList, EMError *error))completion onQueue:(dispatch_queue_t)aQueue;
-
</code>

3. EMChatManagerPushNotificationDelegate 回调方法

<code objc>
/*!
@method
@brief 屏蔽接收群的推送消息，异步方法
@param groupId    需要屏蔽/取消屏蔽 推送消息的群ID
@param isIgnore   屏蔽/取消屏蔽
@discussion
全局的屏蔽推送消息属性优先于此设置；
方法执行完之后，调用[didIgnoreGroupPushNotification:error:].
*/
- (void)asyncIgnoreGroupPushNotification:(NSString *)groupId isIgnore:(BOOL)isIgnore;
-
</code>

===== 获取不接收 APNs 的群组 ID =====

登录成功之后，SDK 会自动返回不接收 APNs 的群组 ID，获取代码如下：

<code objc>
NSArray *ignoredGroupIds = [[EaseMob sharedInstance].chatManager ignoredGroupIds];
</code>

===== 全局免打扰设置 =====

登录成功后设置。

<code objc>
/*!
 @enum
 @brief 推送消息免打扰设置的状态
 @constant ePushNotificationNoDisturbStatusDay     全天免打扰
 @constant ePushNotificationNoDisturbStatusCustom  自定义时间段免打扰
 @constant ePushNotificationNoDisturbStatusClose   关闭免打扰模式
 */
typedef NS_ENUM(NSInteger, EMPushNotificationNoDisturbStatus) {
    ePushNotificationNoDisturbStatusDay = 0,
    ePushNotificationNoDisturbStatusCustom = 1,
    ePushNotificationNoDisturbStatusClose = 2,
};

// 设置全天免打扰，设置后，您将收不到任何推送
EMPushNotificationOptions *options = [[EaseMob sharedInstance].chatManager pushNotificationOptions];
options.noDisturbStatus = ePushNotificationNoDisturbStatusDay;
[[EaseMob sharedInstance].chatManager asyncUpdatePushOptions:options];


// 设置免打扰时段，设置后，在改时间内不收推送
EMPushNotificationOptions *options = [[EaseMob sharedInstance].chatManager pushNotificationOptions];
options.noDisturbStatus = ePushNotificationNoDisturbStatusCustom;
options.noDisturbingStartH = 9;
options.noDisturbingEndH = 22;
[[EaseMob sharedInstance].chatManager asyncUpdatePushOptions:options];
</code>

----
<WRAP group>
<WRAP half column>
上一页：[[start:300iosclientintegration:300iosredpacket|红包集成]]
</WRAP>

<WRAP half column>
下一页：[[start:300iosclientintegration:85apnscontent|APNs 内容解析]]
</WRAP>
</WRAP>
===== 收不到离线推送？ =====

您可以登录[[https://console.easemob.com|环信管理后台]]，在应用列表中选中相应的APP，再点击"IM用户"，在用户列表中搜索收不到推送的用户，找到相应的用户后，点击右侧的"操作"下拉菜单，再点击"测试离线推送"，系统会推送一条测试消息给这个用户，如果出现了问题会做出对应的错误原因提示来协助您排查问题，可能的错误提示有：
  * 用户不存在
  * 用户没有绑定Device Token
  * 用户没有绑定证书
  * 证书不存在或被禁