移动推送
视频服务与安全产品捉虫活动邀您参加！> HOT
文档中心>移动推送>SDK 文档>iOS 接入指南>接口文档

接口文档

最近更新时间：2023-08-30 15:50:32

我的收藏

本页目录：

说明

本文档中账号功能、标签功能及用户属性功能适用于 SDK 1.2.9.0或更高版本，1.2.7.2及之前版本请参见 接口文档。

启动腾讯移动推送服务

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

接口说明

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

移动推送 Token 及注册结果

查询移动推送 Token

接口说明

查询当前应用从腾讯移动推送服务器生成的 Token 字符串。
@property (copy, nonatomic, nullable, readonly) NSString *xgTokenString;

示例代码

NSString *token = [[XGPushTokenManager defaultTokenManager] xgTokenString];
注意
token 的获取应该在 xgPushDidRegisteredDeviceToken:error: 返回正确之后被调用。

注册结果回调

接口说明

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，则注册推送服务成功。

注册失败回调

接口说明

SDK 1.2.7.2 新增，当注册推送服务失败会走此回调。
/// @note TPNS SDK1.2.7.2+
- (void)xgPushDidFailToRegisterDeviceTokenWithError:(nullable NSError *)error

通知授权弹窗的回调

接口说明

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


返回参数说明

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

账号功能

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

添加账号

接口说明

若原来没有该类型账号，则添加；若原来有，则覆盖。（移动推送 SDK1.2.9.0+ 新增）
- (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):@"具体手机号"}。
/// @note TPNS SDK1.3.2.0+
- (void)upsertPhoneNumber:(nonnull NSString *)phoneNumber;

参数说明

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

示例代码

[[XGPushTokenManager defaultTokenManager] upsertPhoneNumber:@"+8613712345678"];;

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

删除账号

接口说明

接口说明：删除指定账号类型下的所有账号。（移动推送 SDK1.2.9.0+ 新增）
- (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];

查询标签

接口说明

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

参数说明

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

示例代码

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

查询标签的回调

接口说明

SDK 1.3.1.0 新增，查询标签的结果会走此回调。
- (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：应用的角标数。
注意
当本地应用角标设置后需调用此接口同步角标值到移动推送服务器，并在下次推送时生效，此接口必须在移动推送长链接建立后调用（xgPushNetworkConnected）。

示例代码

/// 冷启动调用时机
- (void)xgPushDidRegisteredDeviceToken:(nullable NSString *)deviceToken xgToken:(nullable NSString *)xgToken error:(nullable NSError *)error {
    /// 在注册完成后上报角标数目
    if (!error) {
     /// 重置应用角标，-1不清空通知栏，0清空通知栏
     [XGPush defaultManager].xgApplicationBadgeNumber = -1;
        /// 重置服务端自动+1基数
        [[XGPush defaultManager] setBadge:0];
    }
}

/// 热启动调用时机
/// _launchTag热启动标识，业务自行管理
- (void)xgPushNetworkConnected {
    if (_launchTag) {
        /// 重置应用角标，-1不清空通知栏，0清空通知栏
        [XGPush defaultManager].xgApplicationBadgeNumber = -1;
        /// 重置服务端自动+1基数
        [[XGPush defaultManager] setBadge:0];
        _launchTag = NO;
    }
}

实时活动 LiveActivity

接口说明

iOS 应用端 ActivityKit 初始化实时活动成功后上报 activityId 及 pushToken 给 TPNS Server 或者用来结束实时活动。
/**
 @brief 实时活动回调结果
 @param result 返回请求的liveActivity的id和token @{@"activityId":@"idValue", @"token":@"tokenValue"}
 */
typedef void(^XGPushLiveActivityCompletion)(NSDictionary * _Nonnull result, NSError *_Nullable error);

/**
 @brief 开始实时活动，pushToken有变化时需重新调用

 @param activityId liveActivity的名字
 @param token liveActivity对应的pushToken，该token有变化时需要及时调用此方法更新
 @param completionHandler 请求回执，error为nil代表请求成功
 @note 实时活动结束时需要及时调用该方法且pushToken传nil
 */
- (void)startLiveActivityWithId:(nonnull NSString *)activityId pushToken:(nullable NSString *)token withCompletionHandler:(nullable XGPushLiveActivityCompletion)completionHandler __API_AVAILABLE(ios(16.1));

参数说明

activityId：liveActivity 的名字，例如某场活动或比赛。
token：liveActivity 对应的 pushToken，该 token 有变化时需要及时调用此方法更新。
completionHandler：请求回执，error 为 nil 代表请求成功，参考 XGPushLiveActivityCompletion 类型。
说明：
实时活动仅支持 P8 证书鉴权方式，推送实时活动前，您需要在 Apple 开发者中心申请 P8 证书，并上传到 TPNS 管理台，请参见 API 协议文档 进行推送。
示例代码：
XGPush.defaultManager().startLiveActivity(withId: orderActivity.id, pushToken: DeviceToken(data: data).hexString, withCompletionHandler: {(p1, p2) in})

查询设备通知权限

接口说明

查询设备通知权限是否被用户允许。 
- (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];

移动推送日志托管

接口说明

可以在此方法获取移动推送的 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];

本地推送

本地推送相关功能请参见 苹果开发者文档。
中国站
文档反馈
文档活动
message-icon联系我们
目录