iOS API 指南

最新更新:2024-09-18

适用版本

本文匹配的 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 用来操作别名(alias)与标签(tags)。

这几个 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;

        
此代码块在浮窗中显示

参数说明

  • tags

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

    • 用于回调返回对应的参数 tags。并返回对应的状态码:0 为成功,其他返回码请参考错误码定义。seq 为调用时传入的会话序列号
  • 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;

        
此代码块在浮窗中显示

参数说明

  • tags

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

    • 用于回调返回对应的参数 tags。并返回对应的状态码:0 为成功,其他返回码请参考错误码定义。seq 为调用时传入的会话序列号
  • 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;

        
此代码块在浮窗中显示

参数说明

  • tags

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

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

    • 请求时传入的序列号,会在回调时原样返回

清空标签

调用此 API 来清除所有标签,在 block 中返回结果

支持的版本

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

接口定义

+ (void)cleanTags:(MTPushTagsOperationCompletion)completion seq:(NSInteger)seq;
          + (void)cleanTags:(MTPushTagsOperationCompletion)completion
        seq:(NSInteger)seq;

        
此代码块在浮窗中显示

参数说明

  • completion

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

    • 请求时传入的序列号,会在回调时原样返回

查询标签

调用此 API 来获取所有标签,在 block 中返回结果

支持的版本

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

接口定义

+ (void)getAllTags:(MTPushTagsOperationCompletion)completion seq:(NSInteger)seq;
          + (void)getAllTags:(MTPushTagsOperationCompletion)completion
        seq:(NSInteger)seq;

        
此代码块在浮窗中显示

参数说明

  • completion

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

    • 请求时传入的序列号,会在回调时原样返回

验证标签

调用此 API 来验证目标 tag 是否已经设置

支持的版本

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

接口定义

+ (void)validTag:(NSString *)tag completion:(MTPushTagValidOperationCompletion)completion seq:(NSInteger)seq;
          + (void)validTag:(NSString *)tag
 completion:(MTPushTagValidOperationCompletion)completion
        seq:(NSInteger)seq;

        
此代码块在浮窗中显示

参数说明

  • tag

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

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

    • 请求时传入的序列号,会在回调时原样返回

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 编码)
  • completion

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

    • 请求时传入的序列号,会在回调时原样返回

删除别名

调用此 API 来删除别名,在 block 中返回结果

支持的版本

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

接口定义

+ (void)deleteAlias:(MTPushAliasOperationCompletion)completion seq:(NSInteger)seq;
          + (void)deleteAlias:(MTPushAliasOperationCompletion)completion
            seq:(NSInteger)seq;

        
此代码块在浮窗中显示

参数说明

  • completion

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

    • 请求时传入的序列号,会在回调时原样返回

查询别名

调用此 API 来查询当前别名,在 block 中返回结果

支持的版本

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

接口定义

+ (void)getAlias:(MTPushAliasOperationCompletion)completion seq:(NSInteger)seq;
          + (void)getAlias:(MTPushAliasOperationCompletion)completion
         seq:(NSInteger)seq;

        
此代码块在浮窗中显示

参数说明

  • completion

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

    • 请求时传入的序列号,会在回调时原样返回

Alias Block

typedef void (^MTPushAliasOperationCompletion)(NSInteger iResCode, NSString *iAlias, NSInteger seq);
          typedef void (^MTPushAliasOperationCompletion)(NSInteger iResCode, NSString *iAlias, NSInteger seq);

        
此代码块在浮窗中显示

应用内消息

支持的版本

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

功能说明

使用应用内消息功能,需要配置该接口。 应用内消息在页面切换的时候会触发展示逻辑,且应用内消息可以指定页面进行展示。 该接口将页面的进入和离开动作同步给 SDK,SDK 会根据该逻辑进行应用内消息的展示逻辑处理。

接口定义

+ (void)pageEnterTo:(NSString *)pageName + (void)pageLeave:(NSString *)pageName;
          + (void)pageEnterTo:(NSString *)pageName
+ (void)pageLeave:(NSString *)pageName;

        
此代码块在浮窗中显示

调用示例

调用说明

请配套使用 pageEnterTo: 和 pageLeave: 接口,在进入页面的时候调用 pageEnterTo: ,在离开页面的时候调用 pageLeave: 。

调用示例

// 例如可以在 ViewController 的 viewDidAppear: 和 viewDidDisappear: 方法中配套调用 - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; [MTPushService pageEnterTo:@"AViewController"]; } - (void)viewDidDisappear:(BOOL)animated { [super viewDidDisappear:animated]; [MTPushService pageLeave:@"AViewController"]; }
          // 例如可以在 ViewController 的 viewDidAppear: 和  viewDidDisappear: 方法中配套调用
- (void)viewDidAppear:(BOOL)animated {
  [super viewDidAppear:animated];
  [MTPushService pageEnterTo:@"AViewController"];
}

- (void)viewDidDisappear:(BOOL)animated {
  [super viewDidDisappear:animated];
  [MTPushService pageLeave:@"AViewController"];
}

        
此代码块在浮窗中显示

获取 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。

获取应用内消息推送内容

支持的版本

v4.5.0 及后续版本

功能说明

应用内消息:APP 在前台运行的时候才能收到应用内消息。应用内消息现分三种类型,横幅、插屏和全屏。

通过设置应用内消息功能的代理和实现相应的代理方法,可以获取应用内消息的内容。

实现方法

添加 Delegate

@interface AppDelegate ()<MTPushInAppMessageDelegate> @end
          @interface AppDelegate ()<MTPushInAppMessageDelegate>

@end

        
此代码块在浮窗中显示

设置代理

请将以下代码添加到 -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

[MTPushService setInAppMessageDelegate:self];
           [MTPushService setInAppMessageDelegate:self];

        
此代码块在浮窗中显示

添加应用内消息回调的代理方法

#pragma mark - MTPushInAppMessageDelegate - (void)mtPushInAppMessageDidShow:(MTPushInAppMessage *)inAppMessage { NSString *mesageId = inAppMessage.mesageId; // 消息id NSString *title = inAppMessage.title; // 标题 NSString *content = inAppMessage.content; // 内容 NSArray *target = inAppMessage.target; // 目标页面 NSString *clickAction = inAppMessage.clickAction; // 跳转地址 NSDictionary *extras = inAppMessage.extras; // 附加字段 NSLog(@"InAppMessageDidShow:\n mesageId: %@ \n title:%@ \n content:%@ \n target:%@ \n clickAction:%@ \n extras:%@", mesageId,title,content,target,clickAction,extras); } - (void)mtPushInAppMessageDidClick:(MTPushInAppMessage *)inAppMessage { NSString *mesageId = inAppMessage.mesageId; // 消息id NSString *title = inAppMessage.title; // 标题 NSString *content = inAppMessage.content; // 内容 NSArray *target = inAppMessage.target; // 目标页面 NSString *clickAction = inAppMessage.clickAction; // 跳转地址 NSDictionary *extras = inAppMessage.extras; // 附加字段 NSLog(@"mtPushInAppMessageDidClick:\n mesageId: %@ \n title:%@ \n content:%@ \n target:%@ \n clickAction:%@ \n extras:%@", mesageId,title,content,target,clickAction,extras); }
          #pragma mark - MTPushInAppMessageDelegate
- (void)mtPushInAppMessageDidShow:(MTPushInAppMessage *)inAppMessage {
  NSString *mesageId = inAppMessage.mesageId;    // 消息id
  NSString *title = inAppMessage.title;       // 标题
  NSString *content = inAppMessage.content;     // 内容
  NSArray  *target = inAppMessage.target;      // 目标页面
  NSString *clickAction = inAppMessage.clickAction; // 跳转地址
  NSDictionary *extras = inAppMessage.extras;  // 附加字段
  NSLog(@"InAppMessageDidShow:\n mesageId: %@ \n title:%@ \n content:%@ \n target:%@ \n clickAction:%@ \n extras:%@", mesageId,title,content,target,clickAction,extras);
}

- (void)mtPushInAppMessageDidClick:(MTPushInAppMessage *)inAppMessage {
  NSString *mesageId = inAppMessage.mesageId;    // 消息id
  NSString *title = inAppMessage.title;       // 标题
  NSString *content = inAppMessage.content;     // 内容
  NSArray  *target = inAppMessage.target;      // 目标页面
  NSString *clickAction = inAppMessage.clickAction; // 跳转地址
  NSDictionary *extras = inAppMessage.extras;  // 附加字段
  NSLog(@"mtPushInAppMessageDidClick:\n mesageId: %@ \n title:%@ \n content:%@ \n target:%@ \n clickAction:%@ \n extras:%@", mesageId,title,content,target,clickAction,extras);
}

        
此代码块在浮窗中显示

获取 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 的服务器时才返回对应的值,否则返回空字符串。

接口定义

+(NSString *)registrationID
          +(NSString *)registrationID

        
此代码块在浮窗中显示

温馨提示:
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 值

接口定义

+ (BOOL)setBadge:(int)value
          + (BOOL)setBadge:(int)value

        
此代码块在浮窗中显示

参数说明

  • value 取值范围:[0,99999]

本地仍须调用 UIApplication:setApplicationIconBadgeNumber 函数设置图标上显示的 badge 值

  • 返回值
    • 在 value 的取值区间内返回 TRUE,否则返回 FALSE

清空角标

清空 MTPush 服务器中存储的 badge 值,即 [setBadge:0]

接口定义

+ (void)resetBadge
          + (void)resetBadge

        
此代码块在浮窗中显示

本地通知

支持的版本

开始支持的版本: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)addNotification:(MTPushNotificationRequest *)request;
          + (void)addNotification:(MTPushNotificationRequest *)request;

        
此代码块在浮窗中显示

参数说明

  • request [MTPushNotificationRequest] 实体类型,可传入推送的属性。

调用说明

request 中传入已有推送的 request.requestIdentifier 即更新已有的推送,否则为注册新推送。

代码示例

- (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 以下版本)。

接口定义

+ (void)removeNotification:(MTPushNotificationIdentifier *)identifier;
          + (void)removeNotification:(MTPushNotificationIdentifier *)identifier;

        
此代码块在浮窗中显示

参数说明

  • identifier [MTPushNotificationIdentifier]实体类型。

调用说明

  • 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 以下版本)。

接口定义

+ (void)findNotification:(MTPushNotificationIdentifier *)identifier;
          + (void)findNotification:(MTPushNotificationIdentifier *)identifier;

        
此代码块在浮窗中显示

参数说明

  • identifier [MTPushNotificationIdentifier]实体类型

调用说明

  • 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)setDebugMode;
          + (void)setDebugMode;

        
此代码块在浮窗中显示

调用说明

当需要了解更多的调试信息时候,调用 API 开启 Debug 模式。

代码示例

[MTPushService setDebugMode];
          [MTPushService setDebugMode];

        
此代码块在浮窗中显示

关闭日志信息

支持的版本

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

功能说明

API 用来关闭日志信息(除了必要的错误信息)。

接口定义

+ (void)setLogOFF;
          + (void)setLogOFF;

        
此代码块在浮窗中显示

调用说明

不需要任何调试信息的时候,调用此 API (发布时建议调用此 API,用来屏蔽日志信息,节省性能消耗)。

代码示例

[MTPushService setLogOFF];
          [MTPushService setLogOFF];

        
此代码块在浮窗中显示

设置手机号码

支持的版本

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

功能说明

用于短信补充功能。设置手机号码后,可实现“推送不到短信到”的通知方式,提高推送达到率。

接口定义

+ (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加密连接

接口定义

+ (void)setTcpSSL:(BOOL)isSSL;
          + (void)setTcpSSL:(BOOL)isSSL;

        
此代码块在浮窗中显示

参数说明

  • isSSL:YES 加密, NO 不加密

调用说明

请在初始化接口前调用。

代码示例

[MTPushService setTcpSSL:YES];
            [MTPushService setTcpSSL:YES];

        
此代码块在浮窗中显示

语音播报功能

功能介绍

使用该功能需要为您的bundleid开启appGroups功能。开启appGroups功能的步骤请参考 iOS 证书设置指南

该功能支持iOS14及以上的系统。

受系统限制,语音播报的时长和手机通知弹出展示的时间大致保持一致(大概10秒左右,不同系统可能会有稍许差异),通知弹出消失时语音播报也会停止,请注意控制播报的语音时长。

设置appGroupId

支持的版本

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

调用说明

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

接口定义

+ (void)setAppGroupId:(NSString *)appGroupId;
          + (void)setAppGroupId:(NSString *)appGroupId;

        
此代码块在浮窗中显示

参数说明

  • appGroupId:您为bundleid开通appGroupId能力时填写的appGroupId

调用说明

请在初始化接口前调用。

代码示例

[MTPushService setAppGroupId:@"您的appGroupId"];
            [MTPushService setAppGroupId:@"您的appGroupId"];

        
此代码块在浮窗中显示

设置是否开启语音播报功能

支持的版本

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

功能说明

开启或者关闭语音播报功能

接口定义

+ (void)enablePushTextToSpeech:(BOOL)enable;
          + (void)enablePushTextToSpeech:(BOOL)enable;

        
此代码块在浮窗中显示

参数说明

  • enable:YES:打开,NO:关闭,默认为NO

调用说明

请在初始化接口前调用。默认为关闭。

代码示例

[MTPushService enablePushTextToSpeech:YES];
            [MTPushService enablePushTextToSpeech:YES];

        
此代码块在浮窗中显示

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 为调用时传入的会话序列号

  • seq

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

typedef void (^MTPLiveActivityTokenCompletion)(NSInteger iResCode, NSString *iLiveActivityId, NSData *token, NSInteger seq);
          
typedef void (^MTPLiveActivityTokenCompletion)(NSInteger iResCode, NSString *iLiveActivityId, NSData *token, NSInteger seq);

        
此代码块在浮窗中显示

上报 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 为调用时传入的会话序列号

  • seq

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

typedef void (^MTPLiveActivityTokenCompletion)(NSInteger iResCode, NSString *iLiveActivityId, NSData *token, NSInteger seq);
          
typedef void (^MTPLiveActivityTokenCompletion)(NSInteger iResCode, NSString *iLiveActivityId, NSData *token, NSInteger seq);

        
此代码块在浮窗中显示

Voip 推送

功能说明

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

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

支持版本

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

提交 Token

registerVoipToken:

向EngageLab服务器提交 Voip Token

接口定义

+ (void)registerVoipToken:(NSData *)voipToken;
          + (void)registerVoipToken:(NSData *)voipToken;

        
此代码块在浮窗中显示

参数说明

  • voipToken 系统返回的 VoipToken

处理 Voip 消息

handleVoipNotification:

处理收到的 Voip 的消息,用于统计 Voip 下发情况

接口定义

+ (void)handleVoipNotification:(NSDictionary *)remoteInfo;
          + (void)handleVoipNotification:(NSDictionary *)remoteInfo;

        
此代码块在浮窗中显示

参数说明

  • remoteInfo 消息内容

Notification Service Extension 相关接口

支持的版本

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

功能说明

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

设置 appkey 接口

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

接口定义

+ (void)mtpushSetAppkey:(NSString *)appkey
          + (void)mtpushSetAppkey:(NSString *)appkey

        
此代码块在浮窗中显示

参数说明

  • appkey  需要和 main app 中的 MTPush SDK 的 appkey 保持一致

消息展示统计

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

接口定义

+ (void)mtpushReceiveNotificationRequest:(UNNotificationRequest *)request with:(void (^)(void))completion
          + (void)mtpushReceiveNotificationRequest:(UNNotificationRequest *)request with:(void (^)(void))completion

        
此代码块在浮窗中显示

参数说明

  • request  UNNotificationRequest
  • completion 消息送达上报回调,请在该回调中执行显示 APNs 等操作。

关闭日志

默认为开启,建议发布时关闭以减少不必要的 IO

接口定义

+ (void)setLogOff
          + (void)setLogOff

        
此代码块在浮窗中显示

语音播报功能

该功能支持iOS14及以上的系统。

支持的版本

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

设置appGroupId

+ (void)mtpushSetAppGroupId:(NSString *)appGroupId;
          + (void)mtpushSetAppGroupId:(NSString *)appGroupId;

        
此代码块在浮窗中显示

参数说明

  • 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);
    }];
    
  }];

}


        
此代码块在浮窗中显示
在文档中心打开
icon
Contact Sales