====== APNs 离线推送 ======

----

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

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

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

<code objc>
EMOptions *options = [EMOptions optionsWithAppkey:@"appkey"];
options.apnsCertName = @"apnsCertName";
[[EMClient sharedClient] initializeSDKWithOptions:options];
</code>

3. 代码注册离线推送。

<code objc>
UIApplication *application = [UIApplication sharedApplication];

//iOS10 注册APNs
if (NSClassFromString(@"UNUserNotificationCenter")) {
    [[UNUserNotificationCenter currentNotificationCenter] requestAuthorizationWithOptions:UNAuthorizationOptionBadge | UNAuthorizationOptionSound | UNAuthorizationOptionAlert completionHandler:^(BOOL granted, NSError *error) {
        if (granted) {
#if !TARGET_IPHONE_SIMULATOR
            [application registerForRemoteNotifications];
#endif
        }
    }];
    return;
}

if([application respondsToSelector:@selector(registerUserNotificationSettings:)])
{
    UIUserNotificationType notificationTypes = UIUserNotificationTypeBadge | UIUserNotificationTypeSound | UIUserNotificationTypeAlert;
    UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:notificationTypes categories:nil];
    [application registerUserNotificationSettings:settings];
}

#if !TARGET_IPHONE_SIMULATOR
if ([application respondsToSelector:@selector(registerForRemoteNotifications)]) {
    [application registerForRemoteNotifications];
}else{
    UIRemoteNotificationType notificationTypes = UIRemoteNotificationTypeBadge |
    UIRemoteNotificationTypeSound |
    UIRemoteNotificationTypeAlert;
    [[UIApplication sharedApplication] registerForRemoteNotificationTypes:notificationTypes];
}
#endif
</code>

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

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

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

** APNs 注册失败，一般是由于使用了通用证书或者是模拟器调试导致，请检查证书并用真机调试。此处是 iOS 系统报的错，如仍不能确定，请从网上查找相关资料。**

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

APNs 属性需要从服务器获取端获取。

<code objc>
EMError *error = nil;
EMPushOptions *options = [[EMClient sharedClient] getPushOptionsFromServerWithError:&error];
</code>

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

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

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

<code objc>
/*!
 @property
 @brief 更新服务器推送属性配置
 @discussion
    同步方法，会阻塞当前线程
 */
- (EMError *)updatePushOptionsToServer;

//调用：[[EMClient sharedClient] updatePushOptionsToServer];  
</code>

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

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

<code objc>
[[EMClient sharedClient] setApnsNickname:@"推送昵称"];
</code>

===== 设置推送显示详情 =====
<code objc>
EMPushOptions *options = [[EMClient sharedClient] pushOptions];
options.displayStyle = EMPushDisplayStyleMessageSummary // 显示消息内容
// options.displayStyle = EMPushDisplayStyleSimpleBanner // 显示“您有一条新消息”
EMError *error = [[EMClient sharedClient] updatePushOptionsToServer]; // 更新配置到服务器，该方法为同步方法，如果需要，请放到单独线程
if(!error) {
   // 成功
}else {
   // 失败
}

</code>


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

<code objc>
/*!
 @method
 @brief 屏蔽/取消屏蔽群组推送
 @param aGroupId    群组ID
 @param aIgnore     是否屏蔽
 @result 错误信息
 @discussion
    同步方法，会阻塞当前线程
 */
- (EMError *)ignoreGroupPush:(NSString *)aGroupId
                      ignore:(BOOL)aIgnore; 

//调用:
//[[EMClient sharedClient].groupManager ignoreGroupPush:@"groupId" ignore:YES];
</code>

批量指定群组是否接收 APNs

<code objc>
/*!
 *  屏蔽/取消屏蔽群组消息的推送
 *
 *  同步方法，会阻塞当前线程
 *
 *  @param aGroupIDs   群组ID列表
 *  @param aIgnore     是否屏蔽
 *
 *  @result 错误信息
 */
- (EMError *)ignoreGroupsPush:(NSArray *)aGroupIDs
                       ignore:(BOOL)aIsIgnore;
                       
//调用:
//[[EMClient sharedClient].groupManager ignoreGroupsPush:@[@"group1",@"group2"] ignore:YES];
</code>

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

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

<code objc>
NSArray *ignoredGroupIds = [[EMClient sharedClient].groupManager getAllIgnoredGroupIds];
</code>

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

登录成功后设置。

<code objc>
/*!
 @enum
 @brief 推送免打扰设置的状态
 @constant EMPushNoDisturbStatusDay     全天免打扰
 @constant EMPushNoDisturbStatusCustom  自定义时间段免打扰
 @constant EMPushNoDisturbStatusClose   关闭免打扰模式
 */
typedef NS_ENUM(NSInteger, EMPushNoDisturbStatus) {
    EMPushNoDisturbStatusDay = 0,
    EMPushNoDisturbStatusCustom,
    EMPushNoDisturbStatusClose,
};

// 设置全天免打扰，设置后，您将收不到任何推送
EMPushOptions *options = [[EMClient sharedClient] pushOptions];
options.noDisturbStatus = EMPushNoDisturbStatusDay;
options.noDisturbingStartH = 0;
options.noDisturbingEndH = 24;
EMError *error = [[EMClient sharedClient] updatePushOptionsToServer];


// 设置免打扰时段，设置后，在改时间内不收推送
EMPushOptions *options = [[EMClient sharedClient] pushOptions];
options.noDisturbStatus = EMPushNoDisturbStatusCustom;
options.noDisturbingStartH = 9;
options.noDisturbingEndH = 22;
EMError *error = [[EMClient sharedClient] updatePushOptionsToServer];
</code>


----
<WRAP group>
<WRAP half column>
上一页：[[im:300iosclientintegration:apns|APNs推送]]
</WRAP>

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

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