接口文档

最近更新时间:2020-09-18 10:15:10

启动腾讯移动推送服务

接口说明

通过使用在腾讯移动推送官网注册的应用信息,启动腾讯移动推送服务。
(此接口为 SDK 1.2.7.2版本新增,1.2.7.1及之前版本请参考 SDK 包内 XGPush.h 文件startXGWithAppID 接口)。

/// @note TPNS SDK1.2.7.2+
- (void)startXGWithAccessID:(uint32_t)accessID accessKey:(nonnull NSString *)accessKey delegate:(nullable id<XGPushDelegate>)delegate;

参数说明

  • accessID:通过前台申请的 AccessID。
  • accessKey:通过前台申请的 AccessKey。
  • Delegate:回调对象。
注意:

接口所需参数必须要正确填写,反之腾讯移动推送服务将不能正确为应用推送消息。

示例代码

 [[XGPush defaultManager] startXGWithAccessID:<your AccessID> accessKey:<your AccessKey> delegate:self];

终止腾讯移动推送服务

接口说明

终止腾讯移动推送服务后,将无法通过腾讯移动推送服务向设备推送消息,如再次需要接收腾讯移动推送服务的消息推送,则必须需要再次调用 startXGWithAccessID:accessKey:delegate: 方法重启腾讯移动推送服务。

- (void)stopXGNotification;

示例代码

[[XGPush defaultManager] stopXGNotification];

TPNS Token 及注册结果

查询 TPNS Token

接口说明

查询当前应用从腾讯移动推送服务器生成的 Token 字符串。

@property (copy, nonatomic, nullable, readonly) NSString *xgTokenString;

示例代码

NSString *token = [[XGPushTokenManager defaultTokenManager] xgTokenString];

注册结果回调

接口说明

SDK 启动之后,通过此方法回调来返回注册结果及 Token。

- (void)xgPushDidRegisteredDeviceToken:(nullable NSString *)deviceToken xgToken:(nullable NSString *)xgToken error:(nullable NSError *)error

返回参数说明

  • deviceToken:APNs 生成的 Device Token。
  • xgToken:TPNS 生成的 Token,推送消息时需要使用此值。TPNS 维护此值与 APNs 的 Device Token 的映射关系。
  • error:错误信息,若 error 为 nil,则注册推送服务成功。

注册失败回调

接口说明

SDK 1.2.7.2 新增,当注册推送服务失败会走此回调。

/// @note TPNS SDK1.2.7.2+
- (void)xgPushDidFailToRegisterDeviceTokenWithError:(nullable NSError *)error

账号功能

设置账号

接口说明

设置账号,若之前已绑定账号则会覆盖原有账号,若未绑定过账号,则新增当前账号。

说明:

  1. 此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。
  2. 如果您是多账号体系,请参考 SDK 包内 XGPush.h 文件中的 bindWithIdentifiers 接口。
- (void)updateBindedIdentifiers:(nonnull NSArray *)identifiers bindType:(XGPushTokenBindType)type;

参数说明

  • identifiers:账号标识。
  • type:操作类型,账号操作为:XGPushTokenBindTypeAccount。
说明:

  • 账号操作需要使用字典数组且 key 是固定要求。
  • Objective-C 的写法 : @[@{@"account":identifier, @"accountType":@(0)}]。
  • Swift 的写法:[["account":identifier, "accountType":NSNumber(0)]]。
  • 更多 accountType 请参照 XGPushTokenAccountType 枚举。

示例代码

//设置账号:
[[XGPushTokenManager defaultTokenManager] updateBindedIdentifiers:@[@{@"account" : identifier, @"accountType" : @(0)}]
bindType:XGPushTokenBindTypeAccount];

清除账号

接口说明

清除所有设置的账号。

说明:

此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。

- (void)clearAllIdentifiers:(XGPushTokenBindType)type;

参数说明
type:操作类型,账号操作为:XGPushTokenBindTypeAccount。

示例代码

[[XGPushTokenManager defaultTokenManager] clearAllIdentifiers:XGPushTokenBindTypeAccount];

标签功能

绑定/解绑标签

接口说明

开发者可以针对不同的用户绑定标签,然后对该标签进行推送。

说明:

  • 此接口为追加方式。
  • 此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用
  • 单个应用最多可以有10000个自定义tag, 每个设备 token 最多可绑定100个自定义 tag,如需提高该限制,请 提交工单 联系我们,每个自定义 tag 可绑定的设备 token 数量无限制。

操作接口

- (void)bindWithIdentifiers:(nonnull NSArray *)identifiers type:(XGPushTokenBindType)type;
- (void)unbindWithIdentifers:(nonnull NSArray *)identifiers type:(XGPushTokenBindType)type;

参数说明

  • identifiers:指定绑定标识,标签字符串不允许有空格或者是 tab 字符。
  • type:操作类型,标签操作为:XGPushTokenBindTypeTag。
说明:

标签操作 identifiers 为标签字符串数组(标签字符串不允许有空格或者是 tab 字符)。

示例代码

//绑定标签:
[[XGPushTokenManager defaultTokenManager] bindWithIdentifiers:@[identifier] type:XGPushTokenBindTypeTag];

//解绑标签
[[XGPushTokenManager defaultTokenManager] unbindWithIdentifers:@[identifier] type:XGPushTokenBindTypeTag];

更新标签

接口说明

覆盖原有的标签,若之前没有绑定标签,则会执行新增标签。

说明:

此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。

- (void)updateBindedIdentifiers:(nonnull NSArray *)identifiers bindType:(XGPushTokenBindType)type;

参数说明

  • identifiers:标签标识字符串数组,标签字符串不允许有空格或者是 tab 字符。
  • type:操作类型,标签操作为:XGPushTokenBindTypeTag。
说明:

identifiers 为标签字符串数组(标签字符串不允许有空格或者是 tab 字符)。

  • 此接口会将当前 Token 对应的旧有的标签全部替换为当前的标签。

清除全部标签

接口说明

清除所有设置的标签。

说明:

此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。

- (void)clearAllIdentifiers:(XGPushTokenBindType)type;

参数说明

  • type:操作类型,标签操作为:XGPushTokenBindTypeTag。

示例代码

[[XGPushTokenManager defaultTokenManager] clearAllIdentifiers:XGPushTokenBindTypeTag];

角标功能

同步角标

接口说明

当应用本地角标值更改后,需调用此接口将角标值同步到TPNS服务器,下次推送时以此值为基准,此功能在管理台位置(新建推送->高级设置->角标数字)。

- (void)setBadge:(NSInteger)badgeNumber;

参数说明

badgeNumber: 应用的角标数。

注意:

注意: 当本地应用角标设置后需调用此接口同步角标值到TPNS服务器,并在下次推送时生效,此接口必须在TPNS注册成功后调用(xgPushDidRegisteredDeviceToken),

示例代码

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    /// 每次启动 App 应用角标清零(本地应用角标设置需要在主线程执行)
    if ([XGPush defaultManager].xgApplicationBadgeNumber > 0) {
        [XGPush defaultManager].xgApplicationBadgeNumber = 0;
    }
    return YES;
}

- (void)xgPushDidRegisteredDeviceToken:(nullable NSString *)deviceToken xgToken:(nullable NSString *)xgToken error:(nullable NSError *)error {
    /// 在注册完成后同步角标数到TPNS
    if (!error) {
        [[XGPush defaultManager] setBadge:0];
    }
}

查询设备通知权限

接口说明

查询设备通知权限是否被用户允许。

- (void)deviceNotificationIsAllowed:(nonnull void (^)(BOOL isAllowed))handler;

参数说明

handler:查询结果的返回方法。

示例代码

[[XGPush defaultManager] deviceNotificationIsAllowed:^(BOOL isAllowed) {
        <#code#>
    }];

查询 SDK 版本

接口说明

查询当前 SDK 的版本。

- (nonnull NSString *)sdkVersion;

示例代码

[[XGPush defaultManager] sdkVersion];

日志上报接口

接口说明

开发者如果发现推送相关功能异常,可以调用该接口,触发本地 push 日志的上报,反馈问题时,请将文件地址提供给我们,便于排查问题。

/// @note TPNS SDK1.2.4.1+
- (void)uploadLogCompletionHandler:(nullable void(^)(BOOL result,  NSString * _Nullable errorMessage))handler;

参数说明

  • @brief:上报日志信息 (SDK1.2.4.1+)。
  • @param handler:上报回调。

示例代码

[[XGPush defaultManager] uploadLogCompletionHandler:nil];

注销信鸽平台推送服务

接口说明

背景:如果 App 的推送服务是从信鸽平台(https://xg.qq.com)迁移到腾讯移动推送平台,在两个平台同时推送时,可能会出现重复消息。因此需要调用 TPNS SDK(1.2.5.3+) 的接口将设备信息在信鸽平台中进行反注册。
引入头文件:XGForFreeVersion.h,在 startXGWithAccessID 之前调用:

@property uint32_t freeAccessId;

参数说明

  • @freeAccessId 信鸽平台的 accessId(SDK1.2.5.3+)。

示例代码

[XGForFreeVersion defaultForFreeVersion].freeAccessId = 2200262432;

TPNS 日志托管

接口说明

可以在此方法获取TPNS的log日志。此方法和 XGPush > enableDebug 无关。

参数说明

  • logInfo 日志信息

示例代码

- (void)xgPushLog:(nullable NSString *)logInfo;

自定义通知栏消息行为

创建消息支持的行为

接口说明

在通知消息中创建一个可以点击的事件行为。

+ (nullable id)actionWithIdentifier:(nonnull NSString *)identifier title:(nonnull NSString *)title options:(XGNotificationActionOptions)options;

参数说明

  • identifier:行为唯一标识。
  • title:行为名称。
  • options:行为支持的选项。

示例代码

XGNotificationAction *action1 = [XGNotificationAction actionWithIdentifier:@"xgaction001" title:@"xgAction1" options:XGNotificationActionOptionNone];
注意:

通知栏带有点击事件的特性,只有在 iOS8.0+ 以上支持,iOS 7.x or earlier 的版本,此方法返回空。

创建分类对象

接口说明

创建分类对象,用以管理通知栏的 Action 对象。

+ (nullable id)categoryWithIdentifier:(nonnull NSString *)identifier actions:(nullable NSArray<id> *)actions intentIdentifiers:(nullable NSArray<NSString *> *)intentIdentifiers options:(XGNotificationCategoryOptions)options

参数说明

  • identifier:分类对象的标识。
  • actions:当前分类拥有的行为对象组。
  • intentIdentifiers:用以表明可以通过 Siri 识别的标识。
  • options:分类的特性。
注意:

通知栏带有点击事件的特性,只有在 iOS8+ 以上支持,iOS 8 or earlier的版本,此方法返回空。

示例代码

XGNotificationCategory *category = [XGNotificationCategory categoryWithIdentifier:@"xgCategory" actions:@[action1, action2] intentIdentifiers:@[] options:XGNotificationCategoryOptionNone];

创建配置类

接口说明

管理推送消息通知栏的样式和特性。

+ (nullable instancetype)configureNotificationWithCategories:(nullable NSSet<id> *)categories types:(XGUserNotificationTypes)types;

参数说明

  • categories:通知栏中支持的分类集合。
  • types:注册通知的样式。

示例代码

XGNotificationConfigure *configure = [XGNotificationConfigure configureNotificationWithCategories:[NSSet setWithObject:category] types:XGUserNotificationTypeAlert|XGUserNotificationTypeBadge|XGUserNotificationTypeSound];

本地推送

本地推送相关功能请参考 苹果开发者文档

目录