tencent cloud

移动推送

产品动态
公告
产品功能动态
Android SDK 发布动态
iOS SDK 发布动态
macOS SDK 发布动态
产品简介
产品概述
产品优势
应用场景
全球化部署
购买指南
价格总览
购买指引
计费模式
免费试用
欠费说明
快速入门
创建产品和应用
Android 快速接入
iOS 快速接入
创建推送任务
查询推送记录
推送测试方法指引
产品限制说明
操作指南
推送管理
推送高级功能
实践教程
iOS 平台角标功能实践
API 文档
简介
API 概览
调用方式
推送相关接口
标签相关接口
账号相关接口
统计相关接口
用户属性相关接口
服务端错误码
服务端 SDK
API(Java)
SDK 文档
Android 接入指南
iOS 接入指南
客户端集成插件
macOS接入指南
用户及权限
快速入门配置
进阶自定义配置
资源标签
服务协议
服务等级协议
开发者协议
常见问题
iOS 常见问题
Android 常见问题
Flutter 常见问题
其他问题
移动推送政策
移动推送隐私协议
TPNS 数据处理和安全协议
Developer Agreement
联系我们
词汇表

接口文档

PDF
聚焦模式
字号
最后更新时间: 2024-01-16 17:42:20

启动腾讯移动推送服务

以下为设备注册相关接口方法,若需了解调用时机及调用原理,可查看 设备注册流程

接口说明

通过使用在腾讯移动推送官网注册的应用信息,启动腾讯移动推送服务。
- (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];

移动推送 Token 及注册结果

查询移动推送 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:移动推送生成的 Token,推送消息时需要使用此值。移动推送维护此值与 APNs 的 Device Token 的映射关系。
error:错误信息,若 error 为 nil,则注册推送服务成功。

注册失败回调

接口说明

当注册推送服务失败会走此回调。
- (void)xgPushDidFailToRegisterDeviceTokenWithError:(nullable NSError *)error

通知授权弹窗的回调

接口说明

通知弹窗授权的结果会走此回调。
- (void)xgPushDidRequestNotificationPermission:(bool)isEnable error:(nullable NSError *)error;

返回参数说明

isEnable:是否同意授权。
error:错误信息,若 error 为 nil,则获取弹窗结果成功。

账号功能

以下为账号相关接口方法,若需了解调用时机及调用原理,可查看 账号相关流程

添加账号

接口说明

若原来没有该类型账号,则添加;若原来有,则覆盖。
- (void)upsertAccountsByDict:(nonnull NSDictionary<NSNumber *, NSString *> *)accountsDict;
说明:
此接口应该在 xgPushDidRegisteredDeviceToken:error: 返回正确之后被调用。

参数说明

accountsDict:账号字典。
说明:
账号类型和账号名称一起作为联合主键。
需要使用字典类型,key 为账号类型,value 为账号,示例:@{@(accountType):@"account"}。
Objective-C的写法 : @{@(0):@"account0",@(1):@"account1"};Swift的写法:[NSNumber(0):@"account0",NSNumber(1):@"account1"]。
更多 accountType 请参照 SDK Demo 包内的 XGPushTokenAccountType 枚举或 账号类型取值表

示例代码

XGPushTokenAccountType accountType = XGPushTokenAccountTypeUNKNOWN;
NSString *account = @"account";
[[XGPushTokenManager defaultTokenManager] upsertAccountsByDict:@{ @(accountType):account }];

添加手机号

接口说明

添加或更新用户手机号,等于调用upsertAccountsByDict:@{@(1002):@"具体手机号"}
- (void)upsertPhoneNumber:(nonnull NSString *)phoneNumber;

参数说明

phoneNumber:E.164标准,格式为+[国家或地区码][手机号],例如+8613711112222。SDK内部加密传输。

示例代码

[[XGPushTokenManager defaultTokenManager] upsertPhoneNumber:@"13712345678"];;

注意:
1. 此接口应该在xgPushDidRegisteredDeviceToken:error:返回正确之后被调用
2. 如需要删除手机号,调用delAccountsByKeys:[[NSSet alloc] initWithObjects:@(1002), nil]

删除账号

接口说明

接口说明:删除指定账号类型下的所有账号。
- (void)delAccountsByKeys:(nonnull NSSet<NSNumber *> *)accountsKeys;

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

参数说明

accountsKeys:账号类型组成的集合。
说明:
使用集合且 key 是固定要求。
更多 accountType 请参照 SDK 包内 XGPush.h 文件中的 XGPushTokenAccountType 枚举。

示例代码

XGPushTokenAccountType accountType = XGPushTokenAccountTypeUNKNOWN;

NSSet *accountsKeys = [[NSSet alloc] initWithObjects:@(accountType), nil];

[[XGPushTokenManager defaultTokenManager] delAccountsByKeys:accountsKeys];


清除账号

接口说明

清除所有设置的账号。
- (void)clearAccounts;
说明:
此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。

示例代码

[[XGPushTokenManager defaultTokenManager] clearAccounts];


标签功能

以下为标签相关接口方法,若需了解调用时机及调用原理,可查看 标签相关流程

绑定/解绑标签

接口说明

开发者可以针对不同的用户绑定标签,然后对该标签进行推送。
- (void)appendTags:(nonnull NSArray<NSString *> *)tags
- (void)delTags:(nonnull NSArray<NSString *> *)tags
说明:
此接口为追加方式。
此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用
单个应用最多可以有10000个自定义 tag, 每个设备 Token 最多可绑定100个自定义 tag,如需提高该限制,请 提交工单 联系我们,每个自定义 tag 可绑定的设备 Token 数量无限制。

参数说明

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

示例代码

//绑定标签:
[[XGPushTokenManager defaultTokenManager] appendTags:@[ tagStr ]];

//解绑标签
[[XGPushTokenManager defaultTokenManager] delTags:@[ tagStr ]];


更新标签

接口说明

清空已有标签,然后批量添加标签。
- (void)clearAndAppendTags:(nonnull NSArray<NSString *> *)tags
说明:
此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。
此接口会将当前 Token 对应的旧有的标签全部替换为当前的标签。

参数说明

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

示例代码

[[XGPushTokenManager defaultTokenManager] clearAndAppendTags:@[ tagStr ]];

清除全部标签

接口说明

清除所有设置的标签。
- (void)clearTags
说明:
此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。

示例代码

[[XGPushTokenManager defaultTokenManager] clearTags];


查询标签

接口说明

查询设备绑定的标签。
- (void)queryTags:(NSUInteger)offset limit:(NSUInteger)limit;
说明:
此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。

参数说明

offset:此次查询的偏移大小。
offset:limit 此次查询的分页大小, 最大200。

示例代码

[[XGPushTokenManager defaultTokenManager] queryTags:0 limit:100];

查询标签的回调

接口说明

查询标签的结果会走此回调。
- (void)xgPushDidQueryTags:(nullable NSArray<NSString *> *)tags totalCount:(NSUInteger)totalCount error:(nullable NSError *)error;

返回参数说明

tags:查询条件返回的标签。
totalCount:设备绑定的总标签数量。
error:错误信息,若 error 为 nil,则查询成功。

用户属性功能

以下为用户属性相关接口方法,若需了解调用时机及调用原理,可查看 用户属性相关流程

新增用户属性

接口说明

添加或更新用户属性(key-value 结构,若原来没有该 key 的用户属性 value,则新增;若原来有该 key 的用户属性 value,则更新该 value)。
- (void)upsertAttributes:(nonnull NSDictionary<NSString *,NSString *> *)attributes
说明:
此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。

参数说明

attributes:用户属性字符串字典,字符串不允许有空格或者是 tab 字符。
说明:
需要先在管理台配置用户属性的键,才能操作成功。
key,value 长度都限制50个字符以内。
需要使用字典且 key 是固定要求。
Objective-C 的写法 : @{@"gender": @"Female", @"age": @"29"}
Swift 的写法:["gender":"Female", "age": "29"]

示例代码

[[XGPushTokenManager defaultTokenManager] upsertAttributes:attributes];


删除用户属性

接口说明

删除用户已有的属性。
- (void)delAttributes:(nonnull NSSet<NSString *> *)attributeKeys
说明:
此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。

参数说明

attributeKeys:用户属性 key 组成的集合,字符串不允许有空格或者是 tab 字符。
说明:
使用集合且 key 是固定要求。

示例代码

[[XGPushTokenManager defaultTokenManager] delAttributes:attributeKeys];

清空已有用户属性

接口说明

清空已有用户属性。
- (void)clearAttributes;
说明:
此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。

示例代码

[[XGPushTokenManager defaultTokenManager] clearAttributes];

更新用户属性

接口说明

清空已有用户属性,然后批量添加用户属性。
- (void)clearAndAppendAttributes:(nonnull NSDictionary<NSString *,NSString *> *)attributes
说明:
此接口应在 xgPushDidRegisteredDeviceToken:error: 返回正确后被调用。

示例代码

[[XGPushTokenManager defaultTokenManager] clearAndAppendAttributes:attributes];

角标功能

同步角标

接口说明

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

参数说明

badgeNumber:应用的角标数。
注意:
当本地应用角标设置后需调用此接口同步角标值到移动推送服务器,并在下次推送时生效,此接口必须在移动推送注册成功后调用(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 日志的上报,反馈问题 提交工单 时,请将文件地址提供给我们,便于排查问题。
- (void)uploadLogCompletionHandler:(nullable void(^)(BOOL result, NSString * _Nullable errorMessage))handler;

参数说明

@brief:上报日志信息 。
@param handler:上报回调。

示例代码

[[XGPush defaultManager] uploadLogCompletionHandler:nil];

移动推送日志托管

接口说明

可以在此方法获取移动推送的 log 日志。此方法和 XGPush > enableDebug 无关。

参数说明

logInfo:日志信息。

示例代码

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

本地推送

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

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈