导航|地址|刷新
iOS SDK API接口-个推文档中心






文档中心开发者中心

，欢迎您！

您的优惠服务将于到期。





基本资料



安全设置



应用管理




退出登录
登录/注册SDK下载个推学堂请选择产品
消息推送

用户运营

OneID服务

AI应用工坊

统计分析

用户分析

标签管理

模型管理

短信服务

数字人外呼

一键认证

合规检测

点击提升







体验更多产品服务


欢迎登录开发者中心

立即登录

本月不再提醒





快速入门
快速接入指南

产品简介

开发者中心使用说明

进阶功能

名词解释

多厂商推送接入说明


客户端
Android
概述

3分钟演示

集成指南

API接口

进阶功能

AppLink集成

Maven集成视频


Android多厂商
厂商应用开通指南

厂商SDK集成指南

厂商消息报表补全

厂商SDK更新日志

厂商通道限额&QPS说明


iOS
概述

3分钟演示

集成指南

API接口

AppLink集成

iOS 证书配置指南

iOS集成视频

隐私清单说明


HarmonyOS
概述

集成指南

厂商应用开通指南

API接口


小程序

客户端插件

卓信ID
概述

使用指南

Android接口

iOS接口

服务端接口


Open Harmony
简介

使用入门

通知类型介绍

获取Push Token

推送场景化消息
发送通知消息

发送语音播报消息

推送后台消息


Push Kit常见问题



服务端
RestAPI V2 (推荐使用)
开发前必读

接口调用规范

进阶功能说明

公共参数

多厂商参数

鉴权API

推送API

统计API

用户API

返回码说明

服务端 SDK


老版文档
导航


个推回执文档

Open Harmony API
场景化消息
功能介绍

请求体结构说明

请求体参数说明

响应参数

请求示例


基于应用信息生成鉴权令牌



推送应用场景
三方账号打通

自定义通知铃声

消息分类

自定义通知图标

角标设置

通知大图、大文本

标签推送

emoji 表情推送

消息终止、覆盖和撤回

微信小程序推送

iOS 时效性通知（即时通知）

LiveActivity(灵动岛）文档说明


点击提升方案
文案圈人操作手册

流程画布操作手册

应用内弹窗操作手册

点击提升方案集成指南

到达率提升方案

点击率提升方案


常见问题
客户端推送常见问题

Android常见问题

iOS常见问题

服务端常见问题


SDK更新日志

购买指南
消息推送计费说明

消息推送购买指引


推送服务使用协议




当前位置：个推文档 > 客户端 > iOS > API接口



iOS SDK API接口


iOS SDK API接口

1. 初始化服务
+ (void)startSdkWithAppId:(NSString *)appid appKey:(NSString *)appKey appSecret:(NSString *)appSecret delegate:(id<GeTuiSdkDelegate>)delegate launchingOptions:(NSDictionary * __nullable)launchOptions;
参数:

appid： 个推登记应用的appid

appKey：个推登记应用的appKey

appSecret：个推登记应用的appSecret

delegate：个推SDK回调代理

launchOptions：传入didFinishLaunchingWithOptions中的launchOptions参数

说明:

初始化个推服务，接口调用后个推服务后台运行，联网成功后，通过GeTuiSdkDelegate回调接口返回 cid 信息。

appid、appKey 和 appSecret 必须正确，否则会导致推送消息无法接收。

该方法需要在主线程中调用。

launchOptions用于回执报表统计。

头文件:

GeTuiSdk.h

接口调用示例：
[GeTuiSdk startSdkWithAppId:kGtAppId appKey:kGtAppKey appSecret:kGtAppSecret delegate:self launchingOptions:launchingOptions]; // 通过 appId、 appKey 、appSecret 启动SDK，注：该方法需要在主线程中调用
请求结果处理示例：
/// [ GTSDK回调 ] SDK启动成功返回cid- (void)GeTuiSdkDidRegisterClient:(NSString *)clientId { NSLog(@"[ TestDemo ] [GTSdk RegisterClient]:%@", clientId); }
2. 注册远程通知
+ (void)registerRemoteNotification:(UNAuthorizationOptions)types;
参数:

types： UNAuthorizationOptions类型的通知选项

说明:

必须使用个推注册远程通知，否则通过个推代理无法获取部分APNs回调！！

注意，个推内部自动关联DeviceToken和cid，无需开发者手动调用[GeTuiSdk registerDeviceTokenData:deviceToken]关联。

该方法需要在主线程中调用。个推内部兼容iOS10以下注册远程通知逻辑，开发者无需特殊处理。

头文件:

GeTuiSdk.h

接口调用示例：
UNAuthorizationOptions types = (UNAuthorizationOptionBadge | UNAuthorizationOptionAlert | UNAuthorizationOptionSound); [GeTuiSdk registerRemoteNotification:types];
3. 监听在线状态
- (void)GeTuiSDkDidNotifySdkState:(SdkStatus)status;
参数：

status：SDK运行的状态

SdkStatusStarting 正在启动

SdkStatusStarted 启动

SdkStatusStoped 停止

SdkStatusOffline 离线

说明：

监控SDK运行状态, SDK初始化到cid登入成功为正在启动状态, cid登入成功后为启动状态。

示例：
- (void)GeTuiSDkDidNotifySdkState:(SdkStatus)status { NSLog(@"[GetuiSdk Status]:%u", status); }
4. 展示APNs通知
- (void)GeTuiSdkNotificationCenter:(UNUserNotificationCenter *)centerwillPresentNotification:(UNNotification * )notificationcompletionHandler:(void (^) (UNNotificationPresentationOptions))completionHandler;
参数：

center： 通知中心实例

notification： 接收到的APNs通知内容

completionHandler： 是否展示通知回调详情block

说明：

支持iOS10及以上，App在前台时收到APNs通知后的展示回调。用户可以设定当前通知的展示权限。

本方法接管了系统的userNotificationCenter: willPresentNotification: withCompletionHandler:展示回调。开发者需要调用个推注册远程通知[GeTuiSdk registerRemoteNotification]。

头文件：

GeTuiSdk.h

接口调用示例：
- (void)GeTuiSdkNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification completionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler { NSString *msg = [NSString stringWithFormat:@"[ TestDemo ] [APNs] %@ \n%@", NSStringFromSelector(_cmd), notification.request.content.userInfo]; [self.homePage logMsg:msg]; // [ 参考代码，开发者注意根据实际需求自行修改 ] 根据APP需要，判断是否要提示用户Badge、Sound、Alert等//completionHandler(UNNotificationPresentationOptionNone); 若不显示通知，则无法点击通知 completionHandler(UNNotificationPresentationOptionBadge | UNNotificationPresentationOptionSound | UNNotificationPresentationOptionAlert); }
5. 接收APNs通知
- (void)GeTuiSdkDidReceiveNotification:(NSDictionary *)userInfonotificationCenter:(nullableUNUserNotificationCenter *)centerresponse:(nullableUNNotificationResponse *)responsefetchCompletionHandler:(nullablevoid (^)(UIBackgroundFetchResult))completionHandler;
参数：

userInfo：通知内容

center：UNUserNotificationCenter（iOS10及以上版本）

response：UNNotificationResponse（iOS10及以上版本）

fetchCompletionHandler：用来在后台状态下进行操作（iOS10以下版本）

说明：

APNs接收通知回调。

本方法接管了系统的application: didReceiveRemoteNotification: fetchCompletionHandler: 和
userNotificationCenter: didReceiveNotificationResponse: withCompletionHandler: 通知回调。开发者需要调用个推注册远程通知[GeTuiSdk registerRemoteNotification]。

注意：如果你重写了application: didReceiveRemoteNotification: fetchCompletionHandler: 和 当前方法，要注意只保留一个completionHandler调用，调用多次可能多导致偶现crash。

头文件：

GeTuiSdk.h

示例：
- (void)GeTuiSdkDidReceiveNotification:(NSDictionary *)userInfo notificationCenter:(UNUserNotificationCenter *)center response:(UNNotificationResponse *)response fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler { NSString *msg = [NSString stringWithFormat:@"[ TestDemo ] [APNs] %@ \n%@", NSStringFromSelector(_cmd), userInfo]; [self.homePage logMsg:msg]; if(completionHandler) { // [ 参考代码，开发者注意根据实际需求自行修改 ] 根据APP需要自行修改参数值 completionHandler(UIBackgroundFetchResultNoData); } - (void)application:(UIApplication*)application didReceiveRemoteNotification:(NSDictionary*)userInfo fetchCompletionHandler:(void(^)(UIBackgroundFetchResult))completionHandler { //注意，如果执行了上述代理方法中的completionHandler，就不要执行当前回调中的completionHandler。//防止两次调用completionHandler引起崩溃//completionHandler(UIBackgroundFetchResultNewData); }
6. 接收透传消息
- (void)GeTuiSdkDidReceiveSlience:(NSDictionary *)userInfo fromGetui:(BOOL)fromGetui offLine:(BOOL)offLine appId:(nullableNSString *)appId taskId:(nullableNSString *)taskId msgId:(nullableNSString *)msgId fetchCompletionHandler:(nullablevoid (^)(UIBackgroundFetchResult))completionHandler;
参数:

userInfo： 推送消息内容

fromGetui： YES: 个推通道，NO：苹果APNs通道

offLine： YES: 个推离线消息，NO: 个推在线消息

appId： 应用的appId

taskId： 推送消息的任务id

msgId： 推送消息的messageid

completionHandler： 用来在后台状态下进行操作（通过苹果APNs通道的消息 才有此参数值）

说明：

通过个推发送透传消息时，如果下发时cid在线，GeTuiSdkDelegate将收到回调且offLine=NO。如果下发时cid离线，消息将存入个推离线服务器，通过苹果APNS发送静默消息通知。 cid在线后将收到本条消息且offLine=YES。

本方法接管了系统的application: didReceiveRemoteNotification: fetchCompletionHandler:通知回调，处理来自苹果APNs的静默消息通知回调。开发者需要调用个推注册远程通知[GeTuiSdk registerRemoteNotification]。

个推在线渠道的点击数，需要您在客户端在线透传消息自处理展示后，自己监听点击动作，当客户端出现点击动作时，调用sendFeedbackMessage方法，上报actionid为60002的点击回执，以此来补全统计苹果在线个推渠道透传消息的点击数。

静默通知相关说明

头文件:

GeTuiSdk.h

示例:
- (void)GeTuiSdkDidReceiveSlience:(NSDictionary *)userInfo fromGetui:(BOOL)fromGetui offLine:(BOOL)offLine appId:(NSString *)appId taskId:(NSString *)taskId msgId:(NSString *)msgId fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler { NSString *msg = [NSString stringWithFormat:@"[ TestDemo ] [APN] %@ \nReceive Slience: fromGetui:%@ appId:%@ offLine:%@ taskId:%@ msgId:%@ userInfo:%@ ", NSStringFromSelector(_cmd), fromGetui ? @"个推消息" : @"APNs消息", appId, offLine ? @"离线" : @"在线", taskId, msgId, userInfo]; [self.homePage logMsg:msg]; if(completionHandler) { // [ 参考代码，开发者注意根据实际需求自行修改 ] 根据APP需要自行修改参数值 completionHandler(UIBackgroundFetchResultNoData); } } //以下处理用于推送苹果在线透传消息时，补全上报个推渠道消息点击数；需通过上述userInfo的_gmid_中获取到taskId 和msgId，_gmid_组成格式是taskId:msgId:clientid，以冒号区分；在您自身点击事件逻辑触发时，执行上报埋点，点击id固定为60002。// [GeTuiSdk sendFeedbackMessage:60002 andTaskId:taskId andMsgId:msgId];
7. 授权回调
- (void)GetuiSdkGrantAuthorization:(BOOL)granted error:(NSError *)error;
参数:

granted： 是否授权

error： 错误信息

说明：

开发者需要调用个推注册远程通知[GeTuiSdk registerRemoteNotification]。

用户的授权状态会通过回调GetuiSdkGrantAuthorization告知开发者。

头文件:

GeTuiSdk.h

示例:
- (void)GetuiSdkGrantAuthorization:(BOOL)granted error:(NSError *)error { NSString *msg = [NSString stringWithFormat:@"[ TestDemo ] [APNs] %@ \n%@ %@", NSStringFromSelector(_cmd), @(granted), error]; NSLog(@"%@", msg); }
8. 通知设置回调
- (void)GeTuiSdkNotificationCenter:(UNUserNotificationCenter *)center openSettingsForNotification:(nullable UNNotification *)notification
参数:

center：UNUserNotificationCenter（iOS10及以上版本）

notification： 接收到的APNs通知内容

说明：

支持iOS10及以上，注册远程通知时，若设置UNAuthorizationOptionProvidesAppNotificationSettings（此配置支持iOS12+），开发者可以申请自定义通知设置。在”设置“对应的通知设置中跳转到当前App的回调。

本方法接管了系统的userNotificationCenter: openSettingsForNotification:通知设置回调。开发者需要调用个推注册远程通知[GeTuiSdk registerRemoteNotification]。

头文件:

GeTuiSdk.h

9. 发送自定义回执
+ (BOOL)sendFeedbackMessage:(NSInteger)actionId andTaskId:(NSString *)taskId andMsgId:(NSString *)msgId;
参数:

actionId：用户自定义的actionid，int类型，取值90001-90999

taskId：下发任务的任务ID

msgId：下发任务的消息ID

返回:

BOOL: 发送成功 YES, 发送失败 NO，taskid 为空或者 messageid 为空 或者 actionid 不在取值范围以内。

说明：

第三方自定义回执，可用于数据统计。

头文件:

GeTuiSdk.h

示例:
/// [ GTSDK回调 ] SDK收到透传消息回调 - (void)GeTuiSdkDidReceivePayloadData:(NSData *)payloadData andTaskId:(NSString *)taskId andMsgId:(NSString *)msgId andOffLine:(BOOL)offLine fromGtAppId:(NSString *)appId { // [ GTSDK ]：汇报个推自定义事件(反馈透传消息) [GeTuiSdk sendFeedbackMessage:90001andTaskId:taskId andMsgId:msgId]; }
10. APPLink 点击回执
+ (NSString*) handleApplinkFeedback:(NSURL* )webUrl;
参数：

webUrl: applink的 url 对象

返回：

返回 weburl 中的 payload 信息

说明：

APPLink 用户点击回执。

返回下发中的透传信息，开发者可在获取到payload内容后处理具体业务逻辑。

该接口可统计APPLink用户点击次数。

头文件：

GeTuiSdk.h

示例：
/// [ 系统回调 ] APPLink回调 - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void(^)(NSArray<id<UIUserActivityRestoring>> * __nullable restorableObjects))restorationHandler { if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) { NSURL *webUrl = userActivity.webpageURL; // [ GTSDK ]：处理个推APPLink回执统计// APPLink url 示例：https://link.gl.ink/getui?n=payload&p=mid， 其中 n=payload 字段存储用户透传信息，可以根据透传内容进行业务操作。NSString *payload = [GeTuiSdk handleApplinkFeedback:webUrl]; if (payload) { NSLog(@"[ TestDemo ] 个推APPLink中携带的用户payload信息: %@,URL : %@", payload, webUrl); // TODO: 用户可根据具体 payload 进行业务处理 } } returnYES; }
11. 关闭推送
+ (void)setPushModeForOff:(BOOL)isValue;
参数:

isValue：关闭推送模式功能，关闭推送 YES， 开启推送 NO，默认推送开启。

说明:

客户端可以关闭服务器的推送功能，关闭后，服务器将不给该客户端发推送消息，默认推送开启。

请求回调见 GeTuiSdkDelegate 中的- (void)GeTuiSdkDidSetPushMode:(BOOL)isModeOff error:(NSError *)error;具体可参考GeTuiSdkDelegate 回调中的说明。

头文件：

GeTuiSdk.h

接口调用示例：
[GeTuiSdk setPushModeForOff:NO];
请求结果处理示例：
- (void)GeTuiSdkDidSetPushMode:(BOOL)isModeOff error:(NSError *)error { if (error) { NSString* errorInfo = [NSString stringWithFormat:@">>>[SetModeOff error]: %@", [error localizedDescription]]; NSLog(@"GeTuiSdkDidSetPushMode with error : %@", errorInfo); return; } NSString *msg = [NSString stringWithFormat:@">>>[GeTuiSdkDidSetPushMode]: %@ %@", isModeOff ? @"关闭推送" : @"开启推送", [error localizedDescription]]; NSLog(@"%@", msg); }
12. 设置标签
+ (BOOL)setTags:(NSArray *)tags; + (BOOL)setTags:(NSArray *)tags andSequenceNum:(NSString *)aSn;
参数：

tags：NSString 的对象数组，不能为 nil。只能包含中文字符、英文字母、0-9、+-*.的组合（不支持空格）

aSn：用户自定义的请求序列号，用来唯一标识该动作。若不指定sn，会根据tags自动生成sn。建议每个设置标签操作设置不同的sn标识。

说明：

设置一组标签（覆盖操作，cid只会绑定当前传入的标签），后续可使用该标签定向推送。

需要在获取到 cid 之后调用。默认一天只能成功设置一次（可联系技术支持进行修改）。

请求回调见 GeTuiSdkDelegate 中的- (void)GeTuiSdkDidSetTagsAction:(NSString *)sequenceNum result:(BOOL)isSuccess error:(NSError *)aError;。

头文件：

GeTuiSdk.h

接口调用示例：
[GeTuiSdk setTags:@[@"标签1",@"标签2",@"标签3"]]; [GeTuiSdk setTags:@[@"标签1",@"标签2",@"标签3" andSequenceNum:@"seqtag-1"];
请求结果处理示例：
-(void)GeTuiSdkDidSetTagsAction:(NSString*)sequenceNumresult:(BOOL)isSuccesserror:(NSError*)aError{/*参数说明sequenceNum:请求的序列码isSuccess:操作成功YES,操作失败NOaError.code:20001：tag数量过大（单次设置的tag数量不超过100)20002：调用次数超限（默认一天只能成功设置一次）20003：标签重复20004：服务初始化失败20005：setTag异常20006：tag为空20007：sn为空20008：离线，还未登陆成功20009：该appid已经在黑名单列表（请联系技术支持处理）20010：已存tag数目超限20011：tag内容格式不正确*/NSLog(@"GeTuiSdkDidSetTagActionsequenceNum:%@isSuccess:%@error:%@",sequenceNum,@(isSuccess),aError);}
13. 绑定别名
+ (void)bindAlias:(NSString *)aliasandSequenceNum:(NSString *)aSn;
参数：

alias：别名名称，长度40字节，支持中、英文（区分大小写）、数字以及下划线

aSn： 绑定序列码,不为nil

说明：

绑定别名，后续可以使用该别名进行定向推送，重复绑定以最后一次为准，两次调用的间隔需大于 5s，单个 cid 在 24 小时内限制调用50次。

可用于与客户账号系统关联，建议将邮箱、昵称、手机号等用户标识设为别名

使用场景：同一个账号（比如手机号）分别登陆在 A、B、C 三台设备上的同一个 APP， 产生了 3 个不同的 cid, 想让这三台设备同时接收到推送，就可以考虑使用该接口，让三台设备的三个 cid 都绑定同一个别名也就是你的账号（比如手机号），最多支持 10 台设备，也就是最多绑定 10 个 cid

请求回调见 GeTuiSdkDelegate 中的
GeTuiSdkDidAliasAction:(NSString *)action result:(BOOL)isSuccess sequenceNum:(NSString *)aSn error:(NSError *)aError;具体可参考GeTuiSdkDelegate 回调中的说明。

头文件：

GeTuiSdk.h

接口调用示例：
[GeTuiSdk bindAlias:@"个推"andSequenceNum:@"seq-1"];
请求结果处理示例：
- (void)GeTuiSdkDidAliasAction:(NSString *)actionresult:(BOOL)isSuccesssequenceNum:(NSString *)aSnerror:(NSError *)aError { /* 参数说明 isSuccess: 操作成功 YES, 操作失败 NO aError.code: 30001：操作别名失败，频率过快，两次调用的间隔需大于 5s 30002：操作别名失败，参数错误 30003：当前 cid 绑定别名次数超限 30004：操作别名失败，未知异常 30005：操作别名时，cid 未获取到 30006：操作别名时，发生网络错误 30007：别名无效 30008：sn 无效 */if([action isEqual:kGtResponseBindType]) { NSLog(@"[ TestDemo ] bind alias result sn = %@, code = %@", aSn, @(aError.code)); } if([action isEqual:kGtResponseUnBindType]) { NSLog(@"[ TestDemo ] unbind alias result sn = %@, code = %@", aSn, @(aError.code)); } }
14. 解绑别名
+ (void)unbindAlias:(NSString *)alias andSequenceNum:(NSString *)aSn andIsSelf:(BOOL) isSelf;
参数:

alias: 别名名称：长度40字节，支持中、英文（区分大小写）、数字以及下划线

aSn： 绑定序列码,不为nil

isSelf ：是否只对当前cid有效，如果是YES，只对当前cid做解绑；如果是NO，对所有绑定该别名的cid列表做解绑

说明:

解绑别名，两次调用的间隔需大于 5s。只能解绑与当前应用 cid 关联的别名，单个 cid 在 24 小时内限制调用50次。


请求回调同绑定别名



GeTuiSdk.h


示例：
[GeTuiSdk unbindAlias:@"个推"andSequenceNum:@"seq-1"andIsSelf:YES];
15. 设置角标
+ (void)setBadge:(NSUInteger)value;
参数：

value：设置的角标值, 取值范围:[0, 99999]

说明：

同步服务器角标计数。

APP角标显示需额外调用 [[UIApplication sharedApplication] setApplicationIconBadgeNumber:badge] 进行设置。

头文件：

GeTuiSdk.h

示例：
[GeTuiSdk setBadge:5]; //如果需要角标显示需要调用系统方法设置[[UIApplication sharedApplication]setApplicationIconBadgeNumber:5];
16. 复位角标
+ (void)resetBadge;
说明：

设置服务器角标计数为0。

APP角标复位需额外调用 [[UIApplication sharedApplication] setApplicationIconBadgeNumber:0] 进行设置。

头文件：

GeTuiSdk.h

示例：
//重置角标[GeTuiSdk resetBadge]; //如果需要角标清空需要调用系统方法设置[[UIApplication sharedApplication]setApplicationIconBadgeNumber:0];
17. 清空通知
+ (void)clearAllNotificationForNotificationBar;
说明：

清空下拉通知栏全部通知，并将角标置 0，即不显示角标。

头文件：

GeTuiSdk.h

示例：
//清空通知和角标 [GeTuiSdk clearAllNotificationForNotificationBar];
18. 获取缓存CID
+ (NSString *)clientId;
返回：

clientId： NSString* 个推唯一 ID，用于标识当前应用

说明：

获取当前用户缓存的 cid（长时间未登录或 AppId 发生变化造成的 cid 变化以17. 获取回调CID接口中的 cid 为准）

头文件：

GeTuiSdk.h

示例：
[GeTuiSdk clientId];
19. 获取个推CID
- (void)GeTuiSdkDidRegisterClient:(NSString *)clientId;
参数：

clientId：个推唯一 ID，用于标识当前应用

说明：

启动GeTuiSdk后，SDK会自动向个推服务器注册SDK，当成功注册时，SDK通知应用注册成功获取到cid。

注册成功仅表示推送通道建立，如果appid/appkey/appSecret等验证不通过，依然无法接收到推送消息，请确保验证信息正确。

请求回调见 GeTuiSdkDelegate 中的- (void)GeTuiSdkDidRegisterClient:(NSString *)clientId;具体可参考GeTuiSdkDelegate 回调中的说明。

头文件：

GeTuiSdk.h

示例：
- (void)GeTuiSdkDidRegisterClient:(NSString *)clientId { NSLog(@"[GetuiSDK ClientId]:%@", clientId); }
20. 获取 SDK 服务状态
+ (SdkStatus)status;
返回：

SdkStatus：sdk状态

SdkStatusStarting 正在启动

SdkStatusStarted 启动

SdkStatusStoped 停止

SdkStatusOffline 离线
说明：


获取当前 SDK 的服务状态。

头文件：

GeTuiSdk.h
…(内容过长已截断)

------
导航页 打开网址