添加链接
link管理
链接快照平台
  • 输入网页链接,自动生成快照
  • 标签化管理网页链接
icon AppPush WebPush WhatsApp Email EngageLab 文档 AppPush 客户端 SDK iOS SDK iOS API 指南 控制台指南 控制台管理 客户端 SDK Android SDK 海外厂商通道推送说明 厂商通道回执配置指南 Engagelab 通道集成指南 厂商通道参数申请指南 厂商通道集成指南 通道所需权限说明 SDK API 本地通知消息
  • 快速测试推送
    • 快速测试自定义消息 快速测试通知消息 SDK FAQ iOS SDK iOS SDK 集成指南 iOS API 指南 iOS 证书设置指南 iOS 版本特性指南 客户端错误码 SDK FAQ 客户端集成插件 REST API REST API 概述 创建推送 API 标签别名 API 分组推送API 统计 API 定时任务 API 推送语音播报API HTTP 状态码 最佳实践指南 iOS LiveActivity
    • 服务端SDK
      • 常见问题
        • Android SDK iOS SDK EngageLab 文档 AppPush 客户端 SDK iOS SDK iOS API 指南

          iOS API 指南

          最新更新:2024-05-08

          适用版本

          本文匹配的 MTPush iOS SDK 版本为:v3.0.0 及以后版本。

          设置数据中心

          此功能用于匹配你在EngageLab门户(Portal)所选定的数据中心。请确保你所设置的数据中心和在门户端选定的一致。 不设置的话,SDK会使用默认的新加坡数据中心节点。

          v4.3.5及之后版本,该接口失效,开发者无需手动调用该接口设置数据中心,SDK会根据appkey自动匹配对应数据中心。

          支持的版本

          开始支持的版本:v4.3.0

          开始失效的版本:v4.3.5

        • (void)setSiteName:(NSString *)siteName;
        • siteName

        • 数据中心的名称
        • 请在调用初始化接口(setupWithOption:channel:apsForProduction:advertisingIdentifier)之前调用此接口。

          标签与别名 API(iOS)

          温馨提示,设置标签别名请注意处理 call back 结果。

          只有 call back 返回值为 0 才设置成功,才可以向目标推送。否则服务器 API 会返回 1011 错误。所有回调函数都在主线程运行。

          这几个 API 可以在 App 里任何地方调用。

          别名 alias

          为安装了应用程序的用户,取个别名来标识。以后给该用户 Push 消息时,就可以用此别名来指定。
          每个用户只能指定一个别名。

          同一个应用程序内,对不同的用户,建议取不同的别名。这样,尽可能根据别名来唯一确定用户。

          系统限定一个别名只能指定一个用户。

          举例:在一个用户要登录的游戏中,可能设置别名为 userid。游戏运营时,发现该用户 3 天没有玩游戏了,则根据 userid 调用服务器端 API 发通知到客户端提醒用户。

          标签 tag

          为安装了应用程序的用户,打上标签。其目的主要是方便开发者根据标签,来批量下发 Push 消息。

          可为每个用户打多个标签。

          举例: game, old_page, women

          调用此 API 来增加标签,在 block 中返回结果

          Note:这个接口是增加逻辑,而不是覆盖逻辑

          支持的版本

          开始支持的版本:v3.5.0。

          + (void)addTags:(NSSet<NSString *> *)tags completion:(MTPushTagsOperationCompletion)completion seq:(NSInteger)seq;
          + ( void )addTags:( NSSet < NSString *> *)tags completion:(MTPushTagsOperationCompletion)completion seq:( NSInteger )seq;
          此代码块在浮窗中显示
        • 不能设置 nil 或者空集合([NSSet set])
        • 集合成员类型要求为 NSString 类型
        • 每次调用至少设置一个 tag
        • 有效的标签组成:字母(区分大小写)、数字、下划线、汉字、特殊字符@!#$&*+=.|
        • 限制:每个 tag 命名长度限制为 40 字节,最多支持设置 1000 个 tag,但总长度不得超过 5 K 字节。(判断长度需采用 UTF-8 编码)
        • 单个设备最多支持设置 1000 个 tag。App 全局 tag 数量无限制
        • completion

        • 用于回调返回对应的参数 tags。并返回对应的状态码:0 为成功,其他返回码请参考错误码定义。seq 为调用时传入的会话序列号
        • 请求时传入的序列号,会在回调时原样返回
        • 调用此 API 来设置标签,在 block 中返回结果

          Note:这个接口是覆盖逻辑,而不是增加逻辑,调用此接口会覆盖之前设置的全部标签

          支持的版本

          开始支持的版本:v3.5.0。

          + (void)setTags:(NSSet<NSString *> *)tags completion:(MTPushTagsOperationCompletion)completion seq:(NSInteger)seq;
          + ( void )setTags:( NSSet < NSString *> *)tags completion:(MTPushTagsOperationCompletion)completion seq:( NSInteger )seq;
          此代码块在浮窗中显示
        • 不能设置 nil 或者空集合([NSSet set])
        • 集合成员类型要求为 NSString 类型
        • 每次调用至少设置一个 tag
        • 有效的标签组成:字母(区分大小写)、数字、下划线、汉字、特殊字符@!#$&*+=.|
        • 限制:每个 tag 命名长度限制为 40 字节,最多支持设置 1000 个 tag,但总长度不得超过 5 K 字节。(判断长度需采用 UTF-8 编码)
        • 单个设备最多支持设置 1000 个 tag。App 全局 tag 数量无限制
        • completion

        • 用于回调返回对应的参数 tags。并返回对应的状态码:0 为成功,其他返回码请参考错误码定义。seq 为调用时传入的会话序列号
        • 请求时传入的序列号,会在回调时原样返回
        • 调用此 API 来删除标签,在 block 中返回结果

          支持的版本

          开始支持的版本:v3.5.0。

          + (void)deleteTags:(NSSet<NSString *> *)tags completion:(MTPushTagsOperationCompletion)completion seq:(NSInteger)seq;
          + ( void )deleteTags:( NSSet < NSString *> *)tags completion:(MTPushTagsOperationCompletion)completion seq:( NSInteger )seq;
          此代码块在浮窗中显示
        • 不能设置 nil 或者空集合([NSSet set])
        • 集合成员类型要求为 NSString 类型
        • 每次调用至少删除一个 tag
        • 有效的标签组成:字母(区分大小写)、数字、下划线、汉字、特殊字符@!#$&*+=.|
        • 限制:每个 tag 命名长度限制为 40 字节,最多支持删除 1000 个 tag,但总长度不得超过 5 K 字节。(判断长度需采用 UTF-8 编码)
        • completion

        • 回调返回对应的参数 tags。并返回对应的状态码:0 为成功,其他返回码请参考错误码定义。seq 为调用时传入的会话序列号
        • 请求时传入的序列号,会在回调时原样返回
        • 调用此 API 来清除所有标签,在 block 中返回结果

          支持的版本

          开始支持的版本:v3.5.0。

          + (void)validTag:(NSString *)tag completion:(MTPushTagValidOperationCompletion)completion seq:(NSInteger)seq;
          + ( void )validTag:( NSString *)tag completion:(MTPushTagValidOperationCompletion)completion seq:( NSInteger )seq;
          此代码块在浮窗中显示
        • 不能设置 nil 或者空字符串
        • 有效的标签组成:字母(区分大小写)、数字、下划线、汉字、特殊字符@!#$&*+=.|
        • 限制:每个 tag 命名长度限制为 40 字节(判断长度需采用 UTF-8 编码)
        • completion

        • 回调返回对应的参数 tag。并返回对应的状态码:0 为成功,其他返回码请参考错误码定义。seq 为调用时传入的会话序列号
        • 在回调中查看 isBind 属性查看是否已经设置,YES 为已经设置
        • 请求时传入的序列号,会在回调时原样返回
        • Tags Block

          typedef void (^MTPushTagsOperationCompletion)(NSInteger iResCode, NSSet *iTags, NSInteger seq); typedef void (^MTPushTagValidOperationCompletion)(NSInteger iResCode, NSSet *iTags, NSInteger seq, BOOL isBind);
          typedef void (^ MTPushTagsOperationCompletion )( NSInteger iResCode, NSSet *iTags, NSInteger seq); typedef void (^ MTPushTagValidOperationCompletion )( NSInteger iResCode, NSSet *iTags, NSInteger seq, BOOL isBind);
          此代码块在浮窗中显示

          调用此 API 来设置别名

          支持的版本

          开始支持的版本:v3.5.0。

          + (void)setAlias:(NSString *)alias completion:(MTPushAliasOperationCompletion)completion seq:(NSInteger)seq;
          + (void)setAlias:(NSString *) alias completion:(MTPushAliasOperationCompletion)completion seq :(NSInteger) seq ;
          此代码块在浮窗中显示
        • alias
          • 不能设置 nil 或者空字符串 @""
          • 每次调用设置有效的别名,覆盖之前的设置
          • 有效的别名组成:字母(区分大小写)、数字、下划线、汉字、特殊字符@!#$&*+=.|
          • 限制:alias 命名长度限制为 40 字节。(判断长度需采用 UTF-8 编码)
          • typedef void (^MTPushAliasOperationCompletion)(NSInteger iResCode, NSString *iAlias, NSInteger seq);
            typedef void (^ MTPushAliasOperationCompletion )( NSInteger iResCode, NSString *iAlias, NSInteger seq);
            此代码块在浮窗中显示

获取 APNs(通知) 推送内容

支持的版本

开始支持的版本:v3.0.0。

iOS 设备收到一条推送(APNs),用户点击推送通知打开应用时,应用程序根据状态不同进行处理需在 AppDelegate 中的以下两个方法中添加代码以获取 apn 内容。

  • 如果 App 状态为未运行,此函数将被调用,如果 launchOptions 包含 UIApplicationLaunchOptionsRemoteNotificationKey 表示用户点击 apn 通知导致 app 被启动运行;如果不含有对应键值则表示 App 不是因点击 apn 而被启动,可能为直接点击 icon 被启动或其他。
  • - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions; // apn 内容获取: NSDictionary *remoteNotification = [launchOptions objectForKey: UIApplicationLaunchOptionsRemoteNotificationKey]
    - ( BOOL )application:( UIApplication *)application didFinishLaunchingWithOptions:( NSDictionary *)launchOptions; // apn 内容获取: NSDictionary *remoteNotification = [launchOptions objectForKey: UIApplicationLaunchOptionsRemoteNotificationKey ]
    此代码块在浮窗中显示
  • 基于 iOS 6 及以下的系统版本,如果 App 状态为正在前台或者点击通知栏的通知消息,那么此函数将被调用,并且可通过 AppDelegate 的 applicationState 是否为 UIApplicationStateActive 判断程序是否在前台运行。此种情况在此函数中处理:
  • - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo;
    - ( void )application:( UIApplication *)application didReceiveRemoteNotification:( NSDictionary *)userInfo;
    此代码块在浮窗中显示
  • 基于 iOS 7 及以上的系统版本,如果是使用 iOS 7 的 Remote Notification 特性那么处理函数需要使用:
  • - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler;
    - ( void )application:( UIApplication *)application didReceiveRemoteNotification:( NSDictionary *)userInfo fetchCompletionHandler:( void (^)( UIBackgroundFetchResult ))completionHandler;
    此代码块在浮窗中显示
  • 基于 iOS 10 及以上的系统版本,原 [application: didReceiveRemoteNotification:] 将会被系统废弃, 由新增 UserNotifications Framework中的[UNUserNotificationCenterDelegate willPresentNotification:withCompletionHandler:] 或者 [UNUserNotificationCenterDelegate didReceiveNotificationResponse:withCompletionHandler:] 方法替代。 在当前版本及以上可实现 SDK 封装的 MTPushRegisterDelegate 协议方法,适配 iOS10 新增的 delegate 协议方法。 即以下两个方法:
  • - (void)mtpushNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(NSInteger))completionHandler; // NSDictionary * userInfo = notification.request.content.userInfo; // APNs 内容为 userInfo - (void)mtpNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)())completionHandler; // NSDictionary * userInfo = response.notification.request.content.userInfo; // APNs 内容为 userInfo
    - (void) mtpushNotificationCenter: (UNUserNotificationCenter *) center willPresentNotification: (UNNotification *) notification withCompletionHandler: (void (^) (NSInteger) )completionHandler; // NSDictionary * userInfo = notification.request.content.userInfo; // APNs 内容为 userInfo - (void) mtpNotificationCenter: (UNUserNotificationCenter *) center didReceiveNotificationResponse: (UNNotificationResponse *) response withCompletionHandler: (void (^) () )completionHandler; // NSDictionary * userInfo = response.notification.request.content.userInfo; // APNs 内容为 userInfo
    此代码块在浮窗中显示
    - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { // 取得 APNs 标准信息内容 NSDictionary *aps = [userInfo valueForKey:@"aps"]; NSString *content = [aps valueForKey:@"alert"]; //推送显示的内容 NSInteger badge = [[aps valueForKey:@"badge"] integerValue]; //badge 数量 NSString *sound = [aps valueForKey:@"sound"]; //播放的声音 // 取得 Extras 字段内容 NSString *customizeField1 = [userInfo valueForKey:@"customizeExtras"]; //服务端中 Extras 字段,key 是自己定义的 NSLog(@"content =[%@], badge=[%d], sound=[%@], customize field =[%@]",content,badge,sound,customizeField1); // iOS 10 以下 Required [MTPushService handleRemoteNotification:userInfo]; //iOS 7 Remote Notification - (void)application:(UIApplication *)application didReceiveRemoteNotification: (NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler { NSLog(@"this is iOS7 Remote Notification"); // iOS 10 以下 Required [MTPushService handleRemoteNotification:userInfo]; completionHandler(UIBackgroundFetchResultNewData); #pragma mark- MTPushRegisterDelegate // 2.1.9 版新增MTPushRegisterDelegate,需实现以下两个方法 // iOS 10 Support - (void)mtpNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(NSInteger))completionHandler { // Required NSDictionary * userInfo = notification.request.content.userInfo; if([notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) { [MTPushService handleRemoteNotification:userInfo]; else { // 本地通知 completionHandler(UNNotificationPresentationOptionAlert); // 需要执行这个方法,选择是否提醒用户,有 Badge、Sound、Alert 三种类型可以选择设置 // iOS 10 Support - (void)mtpNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler: (void (^)())completionHandler { // Required NSDictionary * userInfo = response.notification.request.content.userInfo; if([response.notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) { [MTPushService handleRemoteNotification:userInfo]; else { // 本地通知 completionHandler(); // 系统要求执行这个方法 - ( void )application:( UIApplication *)application didReceiveRemoteNotification:( NSDictionary *)userInfo { // 取得 APNs 标准信息内容 NSDictionary *aps = [userInfo valueForKey: @"aps" ]; NSString *content = [aps valueForKey: @"alert" ]; //推送显示的内容 NSInteger badge = [[aps valueForKey: @"badge" ] integerValue]; //badge 数量 NSString *sound = [aps valueForKey: @"sound" ]; //播放的声音 // 取得 Extras 字段内容 NSString *customizeField1 = [userInfo valueForKey: @"customizeExtras" ]; //服务端中 Extras 字段,key 是自己定义的 NSLog ( @"content =[%@], badge=[%d], sound=[%@], customize field =[%@]" ,content,badge,sound,customizeField1); // iOS 10 以下 Required [MTPushService handleRemoteNotification:userInfo]; //iOS 7 Remote Notification - ( void )application:( UIApplication *)application didReceiveRemoteNotification: ( NSDictionary *)userInfo fetchCompletionHandler:( void (^)( UIBackgroundFetchResult ))completionHandler { NSLog ( @"this is iOS7 Remote Notification" ); // iOS 10 以下 Required [MTPushService handleRemoteNotification:userInfo]; completionHandler( UIBackgroundFetchResultNewData ); # pragma mark- MTPushRegisterDelegate // 2.1.9 版新增MTPushRegisterDelegate,需实现以下两个方法 // iOS 10 Support - ( void )mtpNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:( void (^)( NSInteger ))completionHandler { // Required NSDictionary * userInfo = notification.request.content.userInfo; if ([notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class ]]) { [MTPushService handleRemoteNotification:userInfo]; else { // 本地通知 completionHandler(UNNotificationPresentationOptionAlert); // 需要执行这个方法,选择是否提醒用户,有 Badge、Sound、Alert 三种类型可以选择设置 // iOS 10 Support - ( void )mtpNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler: ( void (^)())completionHandler { // Required NSDictionary * userInfo = response.notification.request.content.userInfo; if ([response.notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class ]]) { [MTPushService handleRemoteNotification:userInfo]; else { // 本地通知 completionHandler(); // 系统要求执行这个方法
    此代码块在浮窗中显示
  • 基于iOS 12以上的版本,UserNotifications Framework新增回调方法[userNotificationCenter:openSettingsForNotification:],在3.1.1及以上版本MTPushRegisterDelegate同样新增了对应的回调方法。当从应用外部通知界面或通知设置界面进入应用时,该方法将回调。
  • // iOS 12 Support - (void)mtpNotificationCenter:(UNUserNotificationCenter *)center openSettingsForNotification:(UNNotification *)notification{ if (notification) { //从通知界面直接进入应用 }else{ //从通知设置界面进入应用 // iOS 12 Support - ( void )mtpNotificationCenter:(UNUserNotificationCenter *)center openSettingsForNotification:(UNNotification *)notification{ if (notification) { //从通知界面直接进入应用 } else { //从通知设置界面进入应用
    此代码块在浮窗中显示

    参考文档: Handling Local and Remote Notifications

    获取自定义消息推送内容

    支持的版本

    开始支持的版本:v3.0.0。

  • 只有在前端运行的时候才能收到自定义消息的推送。
  • 从 MTPush 服务器获取用户推送的自定义消息内容和标题以及附加字段等。
  • 获取 iOS 的推送内容需要在 delegate 类中注册通知并实现回调方法。

    在方法- (BOOL)application:(UIApplication _)application didFinishLaunchingWithOptions:(NSDictionary _) launchOptions 加入下面的代码:

    NSNotificationCenter *defaultCenter = [NSNotificationCenter defaultCenter]; [defaultCenter addObserver:self selector:@selector(networkDidReceiveMessage:) name:kMTCNetworkDidReceiveMessageNotification object:nil];
    NSNotificationCenter *defaultCenter = [ NSNotificationCenter defaultCenter]; [defaultCenter addObserver: self selector: @selector (networkDidReceiveMessage:) name:kMTCNetworkDidReceiveMessageNotification object: nil ];
    此代码块在浮窗中显示

    实现回调方法 networkDidReceiveMessage

    - (void)networkDidReceiveMessage:(NSNotification *)notification {     NSDictionary * userInfo = [notification userInfo];     NSString *content = [userInfo valueForKey:@"content"];     NSString *messageID = [userInfo valueForKey:@"_j_msgid"]; NSDictionary *extras = [userInfo valueForKey:@"extras"];     NSString *customizeField1 = [extras valueForKey:@"customizeField1"]; //服务端传递的 Extras 附加字段,key 是自己定义的 - ( void )networkDidReceiveMessage:( NSNotification *)notification { NSDictionary * userInfo = [notification userInfo]; NSString *content = [userInfo valueForKey: @"content" ]; NSString *messageID = [userInfo valueForKey: @"_j_msgid" ]; NSDictionary *extras = [userInfo valueForKey: @"extras" ]; NSString *customizeField1 = [extras valueForKey: @"customizeField1" ]; //服务端传递的 Extras 附加字段,key 是自己定义的
    此代码块在浮窗中显示
  • content:获取推送的内容
  • messageID:获取推送的 messageID(key 为 @"_j_msgid")
  • extras:获取用户自定义参数
  • customizeField1:根据自定义 key 获取自定义的 value
  • 更多实现参考 SDK 下载压缩包中的 demo。

    获取 RegistrationID

    支持的版本

    开始支持的版本:v3.0.0。

    RegistrationID 定义

    集成了 MTPush SDK 的应用程序在第一次成功注册到 MTPush 服务器时,MTPush 服务器会给客户端返回一个唯一的该设备的标识 - RegistrationID。MTPush SDK 会以广播的形式发送 RegistrationID 到应用程序。

    应用程序可以把此 RegistrationID 保存以自己的应用服务器上,然后就可以根据 RegistrationID 来向设备推送消息或者通知。

    获取 registrationID(with block)

    + (void)registrationIDCompletionHandler:(void(^)(int resCode,NSString *registrationID))completionHandler;
    + ( void )registrationIDCompletionHandler:( void (^)( int resCode, NSString *registrationID))completionHandler;
    此代码块在浮窗中显示
  • (void(^)(int resCode,NSString *registrationID))completionHandler
    • completionHandler 用于处理设置返回结果
    • resCode 返回的结果状态码
    • registrationID 返回 registrationID
    • [MTPushService registrationIDCompletionHandler:^(int resCode, NSString *registrationID) { NSLog(@"resCode : %d,registrationID: %@",resCode,registrationID); [MTPushService registrationIDCompletionHandler:^( int resCode, NSString *registrationID) { NSLog ( @"resCode : %d,registrationID: %@" ,resCode,registrationID);
      此代码块在浮窗中显示

      温馨提示:
      建议使用此接口获取 registrationID,模拟器中调用此接口 resCode 返回 1011,registrationID 返回 nil。

      获取 registrationID

      调用此 API 来取得应用程序对应的 RegistrationID。 只有当应用程序成功注册到 MTPush 的服务器时才返回对应的值,否则返回空字符串。

      此代码块在浮窗中显示
  • 温馨提示:
    iOS 9 系统,应用卸载重装,APNs 返回的 devicetoken 会发生变化,开发者需要获取设备最新的 Registration id。请在 kMTCNetworkDidLoginNotification 的实现方法里面调用 "RegistrationID" 这个接口来获取 RegistrationID。

    通过 RegistrationID 推送消息和通知

    可以通过 RegistrationID 来推送消息和通知,当 audience 参数为 RegistrationID 时候即可根据  RegistrationID 推送。

    设置 Badge

    支持的版本

    开始支持的版本:v3.0.0。

    badge 是 iOS 用来标记应用程序状态的一个数字,出现在程序图标右上角。 MTPush 封装 badge 功能,允许应用上传 badge 值至 MTPush 服务器,由 MTPush 后台帮助管理每个用户所对应的推送 badge 值,简化了设置推送 badge 的操作。

    实际应用中,开发者可以直接对 badge 值做增减操作,无需自己维护用户与 badge 值之间的对应关系。 推送消息时,只需在控制台 设置角标 +1,EngageLab 会在服务器中存储的每个用户的 badge 值上自动 +1 后下发给用户。

    API setBadge 设置 MTPush 服务器中存储的 badge 值

  • value 取值范围:[0,99999]
  • 本地仍须调用 UIApplication:setApplicationIconBadgeNumber 函数设置图标上显示的 badge 值

  • 在 value 的取值区间内返回 TRUE,否则返回 FALSE
  • 清空 MTPush 服务器中存储的 badge 值,即 [setBadge:0]

    开始支持的版本:v3.0.0。

    iOS 设备收到一条本地通知,用户点击通知打开应用时,应用程序根据状态不同进行处理需在 AppDelegate 中的以下两个方法中添加代码以获取本地通知内容:

  • 如果 App 状态为未运行,此函数将被调用,如果 launchOptions 包含 UIApplicationLaunchOptionsLocalNotificationKey 表示用户点击本地通知导致 app 被启动运行;如果不含有对应键值则表示 App 不是因点击本地通知而被启动,可能为直接点击 icon 被启动或其他。
  • - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions; // 本地通知内容获取:NSDictionary *localNotification = [launchOptions objectForKey: UIApplicationLaunchOptionsLocalNotificationKey]
    - ( BOOL )application:( UIApplication *)application didFinishLaunchingWithOptions:( NSDictionary *)launchOptions; // 本地通知内容获取:NSDictionary *localNotification = [launchOptions objectForKey: UIApplicationLaunchOptionsLocalNotificationKey]
    此代码块在浮窗中显示
  • 如果 App 状态为正在前台或者后台运行,那么此函数将被调用,并且可通过 AppDelegate的applicationState 是否为 UIApplicationStateActive 判断程序是否在前台运行。此种情况在此函数中处理:
  • // NS_DEPRECATED_IOS(4_0, 10_0, "Use UserNotifications Framework's -[UNUserNotificationCenterDelegate willPresentNotification:withCompletionHandler:] or -[UNUserNotificationCenterDelegate didReceiveNotificationResponse:withCompletionHandler:]") - (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification; // 本地通知为 notification
    // NS_DEPRECATED_IOS(4_0, 10_0, "Use UserNotifications Framework's -[UNUserNotificationCenterDelegate willPresentNotification:withCompletionHandler:] or -[UNUserNotificationCenterDelegate didReceiveNotificationResponse:withCompletionHandler:]") - ( void )application:( UIApplication *)application didReceiveLocalNotification:( UILocalNotification *)notification; // 本地通知为 notification
    此代码块在浮窗中显示
  • 在 iOS 10 以上上述方法将被系统废弃,由新增 UserNotifications Framework 中的 -[UNUserNotificationCenterDelegate willPresentNotification:withCompletionHandler:] 或者 -[UNUserNotificationCenterDelegate didReceiveNotificationResponse:withCompletionHandler:] 方法替代。为此,SDK 封装了 MTPushRegisterDelegate 协议,只需实现相应的协议方法即可适配 iOS 10 新增的delegate方法,与上述远程推送新回调方法一致,也即是如下方法:
  • - (void)mtpNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^) (NSInteger))completionHandler; // if (![notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) { // 本地通知为 notification - (void)mtpNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler: (void (^)())completionHandler; // if (![response.notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) { // 本地通知为 response.notification - (void) mtpNotificationCenter: (UNUserNotificationCenter *) center willPresentNotification: (UNNotification *) notification withCompletionHandler: (void (^) (NSInteger) )completionHandler; // if (![notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) { // 本地通知为 notification - (void) mtpNotificationCenter: (UNUserNotificationCenter *) center didReceiveNotificationResponse: (UNNotificationResponse *) response withCompletionHandler: (void (^) () )completionHandler; // if (![response.notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) { // 本地通知为 response.notification
    此代码块在浮窗中显示

    注册/更新本地通知

    支持的版本

    开始支持的版本:v3.0.0。

    API 用于注册或更新推送(支持 iOS 10,并兼容 iOS 10 以下版本)。

    - (void)testAddNotification { MTPushNotificationContent *content = [[MTPushNotificationContent alloc] init]; content.title = @"Test Notifications"; content.subtitle = @"2016"; content.body = @"This is a test code"; content.badge = @1; content.categoryIdentifier = @"Custom Category Name"; // 5s 后提醒 iOS 10 以上支持 MTPushNotificationTrigger *trigger1 = [[MTPushNotificationTrigger alloc] init]; trigger1.timeInterval = 5; //每小时重复 1 次 iOS 10 以上支持 MTPushNotificationTrigger *trigger2 = [[MTPushNotificationTrigger alloc] init]; trigger2.timeInterval = 3600; trigger2.repeat = YES; //每周一早上 8:00 提醒,iOS 10 以上支持 NSDateComponents *components = [[NSDateComponents alloc] init]; components.weekday = 2; components.hour = 8; MTPushNotificationTrigger *trigger3 = [[MTPushNotificationTrigger alloc] init]; trigger3.dateComponents = components; trigger3.repeat = YES; //#import <CoreLocation/CoreLocation.h> //一到某地点提醒,iOS 8 以上支持 CLLocationCoordinate2D cen = CLLocationCoordinate2DMake(37.335400, -122.009201); CLCircularRegion *region = [[CLCircularRegion alloc] initWithCenter:cen radius:2000.0 identifier:@"engagelab"]; MTPushNotificationTrigger *trigger4 = [[MTPushNotificationTrigger alloc] init]; trigger4.region = region; //5s 后提醒,iOS 10 以下支持 MTPushNotificationTrigger *trigger5 = [[MTPushNotificationTrigger alloc] init]; trigger5.fireDate = [NSDate dateWithTimeIntervalSinceNow:5]; MTPushNotificationRequest *request = [[MTPushNotificationRequest alloc] init]; request.requestIdentifier = @"sampleRequest"; request.content = content; request.trigger = trigger1;//trigger2;//trigger3;//trigger4;//trigger5; request.completionHandler = ^(id result) { NSLog(@"结果返回:%@", result); [MTPushService addNotification:request]; - (void)testAddNotification { MTPushNotificationContent * content = [[ MTPushNotificationContent alloc] init ]; content.title = @ "Test Notifications" ; content.subtitle = @ "2016" ; content.body = @ "This is a test code" ; content.badge = @ 1 ; content.categoryIdentifier = @ "Custom Category Name" ; // 5s 后提醒 iOS 10 以上支持 MTPushNotificationTrigger * trigger1 = [[ MTPushNotificationTrigger alloc] init ]; trigger1.timeInterval = 5 ; //每小时重复 1 次 iOS 10 以上支持 MTPushNotificationTrigger * trigger2 = [[ MTPushNotificationTrigger alloc] init ]; trigger2.timeInterval = 3600 ; trigger2.repeat = YES ; //每周一早上 8:00 提醒,iOS 10 以上支持 NSDateComponents * components = [[ NSDateComponents alloc] init ]; components.weekday = 2 ; components.hour = 8 ; MTPushNotificationTrigger * trigger3 = [[ MTPushNotificationTrigger alloc] init ]; trigger3.dateComponents = components; trigger3.repeat = YES ; //#import <CoreLocation/CoreLocation.h> //一到某地点提醒,iOS 8 以上支持 CLLocationCoordinate2D cen = CLLocationCoordinate2DMake ( 37.335400 , - 122.009201 ); CLCircularRegion * region = [[ CLCircularRegion alloc] initWithCenter:cen radius: 2000.0 identifier:@ "engagelab" ]; MTPushNotificationTrigger * trigger4 = [[ MTPushNotificationTrigger alloc] init ]; trigger4.region = region; //5s 后提醒,iOS 10 以下支持 MTPushNotificationTrigger * trigger5 = [[ MTPushNotificationTrigger alloc] init ]; trigger5.fireDate = [ NSDate dateWithTimeIntervalSinceNow: 5 ]; MTPushNotificationRequest * request = [[ MTPushNotificationRequest alloc] init ]; request.requestIdentifier = @ "sampleRequest" ; request.content = content; request.trigger = trigger1; //trigger2;//trigger3;//trigger4;//trigger5; request.completionHandler = ^ (id result) { NSLog (@ "结果返回:%@" , result); [ MTPushService addNotification:request];
    此代码块在浮窗中显示

    移除本地通知

    支持的版本

    开始支持的版本:v3.0.0。

    API 用于移除待推送或已在通知中心显示的推送(支持 iOS 10,并兼容 iOS 10 以下版本)。

  • iOS 10 以上 identifier 设置为 nil,则移除所有在通知中心显示推送和待推送请求,也可以通过设置 identifier.delivered 和 identifier.identifiers 来移除相应在通知中心显示推送或待推送请求,identifier.identifiers 如果设置为 nil 或空数组则移除相应标志下所有在通知中心显示推送或待推送请求。
  • iOS 10 以下 identifier 设置为 nil,则移除所有推送,identifier.delivered 属性无效,另外可以通过 identifier.notificationObj 传入特定推送对象来移除此推送。
  • - (void)testRemoveNotification { MTPushNotificationIdentifier *identifier = [[MTPushNotificationIdentifier alloc] init]; identifier.identifiers = @[@"sampleRequest"]; identifier.delivered = YES; //iOS 10 以上有效,等于 YES 则在通知中心显示的里面移除,等于 NO 则为在待推送的里面移除;iOS 10 以下无效 [MTPushService removeNotification:identifier]; - (void)testRemoveAllNotification { [MTPushService removeNotification:nil]; // iOS 10 以下移除所有推送;iOS 10 以上移除所有在通知中心显示推送和待推送请求 // //iOS 10 以上支持 // MTPushNotificationIdentifier *identifier = [[MTPushNotificationIdentifier alloc] init]; // identifier.identifiers = nil; // identifier.delivered = YES; //等于 YES 则移除所有在通知中心显示的,等于 NO 则为移除所有待推送的 // [MTPushService removeNotification:identifier]; - ( void )testRemoveNotification { MTPushNotificationIdentifier *identifier = [[MTPushNotificationIdentifier alloc] init ]; identifier.identifiers = @[ @"sampleRequest" ]; identifier.delivered = YES; //iOS 10 以上有效,等于 YES 则在通知中心显示的里面移除,等于 NO 则为在待推送的里面移除;iOS 10 以下无效 [ MTPushService removeNotification:identifier ]; - ( void )testRemoveAllNotification { [ MTPushService removeNotification:nil ]; // iOS 10 以下移除所有推送;iOS 10 以上移除所有在通知中心显示推送和待推送请求 // //iOS 10 以上支持 // MTPushNotificationIdentifier *identifier = [[MTPushNotificationIdentifier alloc] init]; // identifier.identifiers = nil; // identifier.delivered = YES; //等于 YES 则移除所有在通知中心显示的,等于 NO 则为移除所有待推送的 // [MTPushService removeNotification:identifier];
    此代码块在浮窗中显示

    查找本地通知

    支持的版本

    开始支持的版本:v3.0.0。

    API 用于查找推送(支持 iOS 10,并兼容 iOS 10 以下版本)。

  • iOS 10 以上可以通过设置 identifier.delivered和identifier.identifiers 来查找相应在通知中心显示推送或待推送请求,identifier.identifiers 如果设置为 nil 或空数组则返回相应标志下所有在通知中心显示推送或待推送请求;iOS 10 以下 identifier.delivered 属性无效,identifier.identifiers 如果设置 nil 或空数组则返回所有未触发的推送。
  • 须要设置 identifier.findCompletionHandler 回调才能得到查找结果,通过 (NSArray *results) 返回相应对象数组。
  • - (void)testFindNotification { MTPushNotificationIdentifier *identifier = [[MTPushNotificationIdentifier alloc] init]; identifier.identifiers = @[@"sampleRequest"]; identifier.delivered = YES; //iOS 10 以上有效,等于 YES 则在通知中心显示的里面查找,等于 NO 则在待推送的里面查找;iOS10 以下无效 identifier.findCompletionHandler = ^(NSArray *results) { NSLog(@"返回结果为:%@", results); // iOS 10 以下返回 UILocalNotification 对象数组,iOS10 以上根据 delivered 传入值返回 UNNotification 或 UNNotificationRequest 对象数组 [MTPushService findNotification:identifier]; - (void)testFindAllNotification { MTPushNotificationIdentifier *identifier = [[MTPushNotificationIdentifier alloc] init]; identifier.identifiers = nil; identifier.delivered = YES; //iOS 10 以上有效,等于 YES 则查找所有在通知中心显示的,等于 NO 则为查找所有待推送的;iOS 10 以下无效 identifier.findCompletionHandler = ^(NSArray *results) { NSLog(@"返回结果为:%@", results); // iOS 10 以下返回 UILocalNotification 对象数组,iOS 10 以上根据 delivered 传入值返回 UNNotification 或 UNNotificationRequest 对象数组 [MTPushService findNotification:identifier]; - ( void )testFindNotification { MTPushNotificationIdentifier *identifier = [[MTPushNotificationIdentifier alloc] init]; identifier.identifiers = @[ @"sampleRequest" ]; identifier.delivered = YES ; //iOS 10 以上有效,等于 YES 则在通知中心显示的里面查找,等于 NO 则在待推送的里面查找;iOS10 以下无效 identifier.findCompletionHandler = ^( NSArray *results) { NSLog ( @"返回结果为:%@" , results); // iOS 10 以下返回 UILocalNotification 对象数组,iOS10 以上根据 delivered 传入值返回 UNNotification 或 UNNotificationRequest 对象数组 [MTPushService findNotification:identifier]; - ( void )testFindAllNotification { MTPushNotificationIdentifier *identifier = [[MTPushNotificationIdentifier alloc] init]; identifier.identifiers = nil ; identifier.delivered = YES ; //iOS 10 以上有效,等于 YES 则查找所有在通知中心显示的,等于 NO 则为查找所有待推送的;iOS 10 以下无效 identifier.findCompletionHandler = ^( NSArray *results) { NSLog ( @"返回结果为:%@" , results); // iOS 10 以下返回 UILocalNotification 对象数组,iOS 10 以上根据 delivered 传入值返回 UNNotification 或 UNNotificationRequest 对象数组 [MTPushService findNotification:identifier];
    此代码块在浮窗中显示

    日志等级设置

    支持的版本

    开始支持的版本:v3.0.0。

    开启 Debug 模式

    API 用于开启 Debug 模式,显示更多的日志信息。

    + (void)setMobileNumber:(NSString *)mobileNumber completion:(void (^)(NSError *error))completion
    + ( void )setMobileNumber:( NSString *)mobileNumber completion:( void (^)( NSError *error))completion
    此代码块在浮窗中显示
  • mobileNumber  手机号码。只能以 “+” 或者数字开头,后面的内容只能包含 “-” 和数字,并且长度不能超过 20。如果传 nil 或空串则为解除号码绑定操作。
  • completion 响应回调。成功则 error 为空,失败则 error 带有错误码及错误信息,具体错误码详见错误码定义。
  • 此接口调用频率有限制,10s 之内最多 3 次。建议在登录成功以后,再调用此接口。结果信息通过 completion 异步返回,也可将completion 设置为 nil 不处理结果信息。

    [MTPushService setMobileNumber:@"xxx" completion:^(NSError *error) { if (error) { NSLog(@"error:%@", error); else { // success [MTPushService setMobileNumber:@ "xxx" completion:^(NSError * error ) { if ( error ) { NSLog(@ "error:%@" , error ); else { // success
    此代码块在浮窗中显示

    上报语言信息

    支持的版本

    开始支持的版本:v3.0.0。

    API 用于上报用户语言信息

    + (void)setUserLanguage:(NSString *)language completionHandler:(void(^)(int resCode, NSError *error))handler;
    + ( void )setUserLanguage:( NSString *)language completionHandler:( void (^)( int resCode, NSError *error))handler;
    此代码块在浮窗中显示
  • language:语言信息
  • handler:上报回调
  • 建议在登录成功之后调用此接口。

    [MTPushService setUserLanguage:@"zh_Hans" completionHandler:^(int resCode, NSError *error) { NSLog(@"language report: %d, %@", resCode, error); [MTPushService setUserLanguage:@ "zh_Hans" completionHandler:^( int resCode, NSError * error ) { NSLog(@ "language report: %d, %@" , resCode, error );
    此代码块在浮窗中显示

    设置TCP加密模式

    支持的版本

    开始支持的版本:v3.3.0。

    API 用于设置是否TCP加密连接

    开始支持的版本:v4.3.4。

    用来设置appGroupId,需要与notification service extension 中通过 mtpushSetAppGroupId: 方法设置的appGroupId 一致,用以定义主工程和notification service extension 共享存储空间,该空间用来存储语音播报相关资源。

    LiveActivity

    上报 liveActivity 的 PushToStartToken (启动token)

    Method - registerLiveActivity:pushToStartToken:completion:seq:

    调用此 API 来上报 liveActivity 的 pushToStartToken,在 block 中返回结果。

    支持的版本

    开始支持的版本:4.4.0

    + (void)registerLiveActivity:(NSString *)activityAttributes pushToStartToken:(NSData *)pushToStartToken completion:(MTPLiveActivityTokenCompletion)completion seq:(NSInteger)seq; + ( void )registerLiveActivity:( NSString *)activityAttributes pushToStartToken:( NSData *)pushToStartToken completion:(MTPLiveActivityTokenCompletion)completion seq:( NSInteger )seq;
    此代码块在浮窗中显示
  • activityAttributes

  • 某liveActivity定义的属性类型
  • pushToStartToken

  • 对应该 liveactivity 的 pushToStartToken, pushToStartToken
  • completion

    *用于回调返回对应的状态码:0 为成功,其他返回码请参考错误码定义。seq 为调用时传入的会话序列号

  • 请求时传入的序列号,会在回调时原样返回
  • LiveActivity pushToStartToken 上报回调(Block)

    此代码块在浮窗中显示
  • 上报 liveActivity 的 PushToken (更新token)

    Method - registerLiveActivity:pushToken:completion:seq:

    调用此 API 来上报某一个 liveActivity 的 PushToken,在 block 中返回结果。

    支持的版本

    开始支持的版本:4.4.0

    + (void)registerLiveActivity:(NSString *)liveActivityId pushToken:(NSData *)pushToken completion:(MTPLiveActivityTokenCompletion)completion seq:(NSInteger)seq; + ( void )registerLiveActivity:( NSString *)liveActivityId pushToken:( NSData *)pushToken completion:(MTPLiveActivityTokenCompletion)completion seq:( NSInteger )seq;
    此代码块在浮窗中显示
  • liveActivityId

  • 不能设置 liveActivityId 24 个字节。
  • 标识某一个 liveActivity,开发者自定义,建议唯一。 EngageLab通过该 liveActivityId 确定目标人群。 该类型必须是 NSString 类型。
  • liveActivity 的 pushToken 有变化时,请及时调用该接口上报。

  • pushToken

  • 对应该 liveactivity 的 pushToken。
  • completion

    *用于回调返回对应的状态码:0 为成功,其他返回码请参考错误码定义。seq 为调用时传入的会话序列号

  • 请求时传入的序列号,会在回调时原样返回
  • LiveActivity PushToken 上报回调(Block)

    在 iOS 8 之后引入了一个基于 PushKit 框架的 Voip 推送,可以使得用户的 APP 在杀死的情况下唤醒 APP, 并执行代码。

    警告:在 iOS 13 之后 Apple 不再允许 PushKit 应用在非 Voip 电话的场景下,如果需要使用 Pushkit 则需要接入 Callkit 的接口

    开始支持的版本:v4.4.0。

    提交 Token

    registerVoipToken:

    向EngageLab服务器提交 Voip Token

    Notification Service Extension 相关接口

    支持的版本

    Notification Service Extension SDK v3.0.0 及以后的版本。

    使用 Notification Service Extension SDK 上报推送送达情况。

    设置 appkey 接口

    设置 appkey 接口,必须提前调用

    + (void)mtpushReceiveNotificationRequest:(UNNotificationRequest *)request with:(void (^)(void))completion
    + ( void )mtpushReceiveNotificationRequest:(UNNotificationRequest *)request with :( void (^)( void ))completion
    此代码块在浮窗中显示
  • request  UNNotificationRequest
  • completion 消息送达上报回调,请在该回调中执行显示 APNs 等操作。
  • 默认为开启,建议发布时关闭以减少不必要的 IO

  • appGroupId:  需要和 main app 中的 通过 + (void)setAppGroupId:(NSString *)appGroupId; 方法设置的appGroupId值相同。
  • 处理语音通知

    消息送达统计接口,调用该接口上报 APNs 消息体中的 MTPush 相关数据。

    + (void)handleVoice:(UNNotificationRequest *)request with:(void (^)(NSString *soundName))completion;
    + ( void )handleVoice:(UNNotificationRequest *)request with :( void (^)(NSString *soundName))completion;
    此代码块在浮窗中显示
  • request  UNNotificationRequest
  • completion 语音通知处理完成后的回调,处理成功后会返回处理后的语音名称 soundName, 将该语音名称替换  UNNotificationRequest.content.sound 的值
  • - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler { UNMutableNotificationContent *bestAttemptContent = [request.content mutableCopy]; [MTNotificationExtensionService mtpushSetAppGroupId:@"xxx"]; [MTNotificationExtensionService setSiteName:@"您的siteName"]; // 4.3.5版本及以后不需要主动设置数据中心 [MTNotificationExtensionService mtpushSetAppkey:@"您的appkey"]; // 处理语音文件 [MTNotificationExtensionService handleVoice:request with:^(NSString *soundName) { if (soundName && soundName.length >= 0 ) { // 语音文件处理成功后将通知的sound设置为处理好的语音文件名 bestAttemptContent.sound = [UNNotificationSound soundNamed:soundName]; // 继续调用推送统计上报功能api [MTNotificationExtensionService mtpushReceiveNotificationRequest:request with:^ { NSLog(@"apns upload success"); self.contentHandler(bestAttemptContent); - ( void )didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:( void (^)(UNNotificationContent * _Nonnull))contentHandler { UNMutableNotificationContent *bestAttemptContent = [request.content mutableCopy]; [ MTNotificationExtensionService mtpushSetAppGroupId:@ "xxx" ]; [ MTNotificationExtensionService setSiteName:@ "您的siteName" ]; // 4.3.5版本及以后不需要主动设置数据中心 [ MTNotificationExtensionService mtpushSetAppkey:@ "您的appkey" ]; // 处理语音文件 [ MTNotificationExtensionService handleVoice:request with:^(NSString *soundName) { if (soundName && soundName.length >= 0 ) { // 语音文件处理成功后将通知的sound设置为处理好的语音文件名 bestAttemptContent.sound = [UNNotificationSound soundNamed:soundName ]; // 继续调用推送统计上报功能api [ MTNotificationExtensionService mtpushReceiveNotificationRequest:request with:^ { NSLog(@ "apns upload success" ); self.contentHandler(bestAttemptContent);