最近更新时间:2024.03.25 14:16:58
首次发布时间:2022.10.31 09:54:30
App 弹窗是 GMP ReachSDK 提供的弹窗触达功能。
需提供 iOS 应用包名和开发者 team id,然后在 GMP 后台配置(管理中心-消息管理-客户端SDK-鉴权配置),需保证与 app 的实际信息一致,可联系您的客户端开发人员获取。该项配置用于接口的安全鉴权校验,不会用于其他用途。
示例如下:
team id:55XXXX22XX bundle id:com.example.gmp
在 GMP 控制台中配置 APP 的鉴权信息
iOS 鉴权所需的配置信息以及获取方式如下
team id 需要在苹果开发者后台上获取,在账号页面下滑,找到会员资格详细信息,其中的团队 ID 就是 team id
iOS 工程上的 bundl identifier
注意
弹窗 SDK 集成 Demo,可参考 https://www.volcengine.com/docs/6315/1130446
Demo 需要在初始化时配置对应的参数才能获取到对应的数据
弹窗 SDK 依赖 Finder SDK 进行数据回流,在使用弹窗 SDK 前,请确保已经集成了 Finder SDK,并且 Finder SDK 版本在 6.15.2 以上。
Finder iOS SDK接入指南地址:Finder接入
推荐使用 cocoapods 集成弹窗 SDK,在 Podfile 中,引入 SDK,并执行pod install --repo-update
更新Pods
iOS 弹窗、资源位 SDK 版本记录
//需要额外添加一个这两个source source 'https://github.com/CocoaPods/Specs.git' source 'https://github.com/volcengine/volcengine-specs.git' pod 'GMPReachSDK', '请到版本记录获取最新版本', :subspecs => [ 'Popup', 'Resource', 'Core', 'Finder' #数据上报功能子库,当引入此子库时,SDK 会默认使用 Finder SDK 来进行数据上报和获取 id,若不使用 Finder SDK 上报数据,可不引入此库,但需要自己实现数据上报功能,详见 4.2其他平台uba配置部分 ]
推荐您远程引入SDK。如特殊情况需要手动引入,请补充阅读本小节。
请在 iOS 弹窗、资源位 SDK 版本记录 下载对应版本文件,然后将下载好的文件解压后拉入项目工程中即可
说明
如果您的工程中未引入 SDWebImage 库,还需下载以下文件,并且解压后拖入到项目工程中
在gmp首页,点击右上角头像-项目管理,即可进入项目后台页查看对应项目的项目id和应用id(项目id是初始化弹窗sdk的appid,应用id是用于初始化Finder SDK的appid)
进入火山引擎控制台,点击右上角头像 icon,红框中的账号 ID 即是主帐号 id
在GMP首页,选择管理中心-通道管理-App弹窗-应用管理即可打开弹窗应用列表,最左侧一栏为弹窗应用id,将所选应用的弹窗应用id传入sdk初始化即可
首先您需要初始化 Finder SDK,具体可参考:初始化 Finder SDK - 火山引擎
在初始化的地方导入 GMPReachSDK.h
,建议在 appdelegate.m
的 didFinishLaunchingWithOptions
方法中进行弹窗 SDK 的初始化。
#import <GMPReachSDK/GMPReachSDK.h>
#import <GMPReachSDK/GMPReachSDK.h> - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { GMPReachConfig *reachConfig = [[GMPReachConfig alloc] init]; reachConfig.appId = @"{{APPID}}"; // GMP 项目ID reachConfig.host = @"{{host}}"; // 私有化部署域名 reachConfig.enableLog = YES; // 是否打开日志 reachConfig.teamId = @"XXXXXXXX"; // 开发者账号 teamid,从苹果开发者后台获取,请确保与 GMP 平台上配置的一致 // 如果项目支持自动登陆,用户画像已经存在,需要提前设置上 reachConfig.uuid = @"uuid"; reachConfig.uuidType = @"uuid_type"; [GMPPopupManager startWithAppId:@"your popup appid" config:reachConfig]; [GMPPopupManager sharedManager].delegate = self; }
#import <GMPReachSDK/GMPReachSDK.h> - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { GMPReachConfig *reachConfig = [[GMPReachConfig alloc] init]; reachConfig.appId = @"{{APPID}}"; // GMP 项目ID reachConfig.enableLog = YES; // 是否打开日志 reachConfig.teamId = @"XXXXXXXX"; // 开发者账号 teamid,从苹果开发者后台获取,请确保与 GMP 平台上配置的一致 reachConfig.mainAccountId = @"{{MainAccountId}}" // SaaS 火山引擎账号 id // 如果项目支持自动登陆,用户画像已经存在,需要提前设置上 reachConfig.uuid = @"uuid"; reachConfig.uuidType = @"uuid_type"; [GMPPopupManager startWithAppId:@"your popup appid" config:reachConfig]; [GMPPopupManager sharedManager].delegate = self; }
ReachConfig 详细配置如下
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
appId | NSString | 是 | gmp 项目 id,在 gmp 后台注册,详见 3.1.1 |
host | NSString | 是 | 私有化部署的域名,saas 环境下无须传入 |
uuid | NSString | 否 | 用户id,若初始化 SDK 时已存在自有帐号体系的用户 id,则需传入自有帐号体系用户 id,否则传空 |
uuidType | NSString | 否 | 自有帐号体系的用户 id 在 cdp 上对应的 id code |
mainAccountId | BOOL | 是 | saas 环境下必须传入,获取方法详见 3.1.2 |
enableLog | BOOL | 否 | 是否打开日志 |
teamId | NSString | 是 | 开发者账号 teamid,从苹果开发者后台获取,请确保与 GMP 平台上配置的一致| |
ubaInstance | id | 否 | 设置finder配置,如无特殊需求可不传入 |
GMPPopupManager 初始化参数
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
popupAppId | NSString | 是 | 弹窗项目 appId,在 GMP 后台注册,详见 3.1.3 |
config | ReachConfig | 是 | 触达配置 |
pollingInterva | NSInteger | 否 | 弹窗规则轮询间隔,默认为 300 秒,设置为 0 则不进行轮询 |
如您的产品中有账户体系,请在用户登录后立即设置 uuid,以保证用户登录前后口径一致性。Finder SDK 登陆态变化可参考:Finder SDK 登陆态变化
除此之外,您还需要及时通知弹窗SDK用户画像的变化
警告
在SDK版本 >= 2.1.0 之后,更新用户画像只能通过手动更新,旧版升级上来的请改成手动更新模式
注意 : 务必在 BDAutoTrack.setCurrentUserUniqueID 设置前调用手动更新
2.1.0 以下版本需要为 ReachConfig 增加以下配置:
GMPReachConfig *reachConfig = [[GMPReachConfig alloc] init]; // 设置自动更新 uuid 为关闭 reachConfig.isAutoUpdateUserId = NO; ...省略其他配置... [GMPPopupManager startWithAppId:@"your popup appid" config:config];
以下配置在各个SDK版本均要配置
登录用户
// uuid: 自有账号体系 id // uuidType: 自有账号体系 id 类型,需要在 CDP 平台上查看对应的 id code [GMPPopupManager updateUUID:@"uuid" uuidType:@"uuidType"];
退出登录
// uuid , uuid type 填空字符串 [GMPPopupManager updateUUID:@"" uuidType:@""]; [BDAutoTrack clearUserUniqueID];
接入方可以通过实现 GMPPopupViewDelegate
中的如下方法来实现弹窗行为回调的处理。具体的处理相关逻辑交由接入方自己实现。
建议接入方在 appdelegate
中初始化时设置 appdelegate
对象为 GMPPopupManager
的代理对象,并实现 GMPPopupViewDelegate
代理方法。
/** * 准备触达弹窗 * * @return true 表示准备好了,触达即将开始;false 表示不进行触达 */ - (BOOL)popupViewShouldShow; /** * 弹窗展示 * * @param windowControl 弹窗控制器,可用于关闭弹窗 */ - (void)popupViewDidShow:(GMPPopupWindowControl *)windowControl; /** * 弹窗点击 * * @param urlString 跳转链接 */ - (void)popupViewClick:(NSString *)urlString; /** * 是否拦截 SDK 跳转行为 * * @param urlString 跳转链接 * @return 是否自行处理跳转链接 YES:自行处理 NO:SDK 默认处理 */ - (BOOL)interceptPopupViewClick:(NSString *)urlString; /** * 弹窗关闭 */ - (void)popupViewDidClose; /** * 校验是否通过 * * @param json 透传数据 * @param callback 校验通过callback(YES) 校验不通过callback(NO) */ - (void)popupViewShowJudgeFromClient:(NSDictionary *)json callback:(void (^)(BOOL show))callback;
点击预览弹窗后,接入方可以通过扫一扫获取到弹窗的id,将其传入SDK的预览接口可以在当前页面立刻弹出对应弹窗,调用SDK预览接口示例如下
[GMPPopupManager testPopupWithTestId:@"test id"];
在gmp平台管理中心-通道管理-app弹窗,找到需要预览的弹窗扫码即可获取到对应弹窗的 testId
在某些沉浸式场景(如视频播放)或已弹窗场景可以禁止弹窗SDK的弹窗以避免对用户的体验带来干扰(关闭后需要在允许弹窗的场景再次调用来重新启用弹窗功能)
// 设置为不允许弹窗 [GMPPopupManager setPopupEnable:NO]; // 设置为不允许弹窗,同时关闭正在弹出的弹窗 [GMPPopupManager setPopupEnable:NO closeShowingPopupView:YES];
为了降低弹窗弹出的时延,弹窗SDK支持对即将弹出的弹窗中的图片进行预加载,接入方可以根据自身需求设置不同等级的图片预加载
通过设置 [GMPPopupManager sharedManager].imagePrefetchType
控制图片预加载策略,默认是只预加载背景图片。
字段 | 说明 | 类型 |
---|---|---|
ImagePreLoadLevel | 弹窗SDK图片预加载等级,默认值 ONLY_BACKGROUND
| enum |
GMPPopupManager.sharedManager.imagePrefetchType = GMPPopupImagePrefetchAll;
APP弹窗是事件触发型的通道,在客户端本地完成弹窗的触发,「app弹窗」的触发可能在以下场景下触发失败;
当前触发失败后本次触达任务就结束了,因此在触发弹窗时允许设置补偿机制使本次触发失败的弹窗任务在下一次事件触发时尝试进行弹窗。
设置弹窗补偿的示例代码如下
GMPPopupManager.sharedManager.enableCompensate = YES;
最新版本的弹窗 SDK 是通过轮询的方式来更新弹窗规则的,默认的轮询间隔是 300 秒。如果您对弹窗任务实时性有着更高事实性的要求,可以在初始化弹窗 SDK 时传入 pollingInterval 自定义轮询的时间间隔。
// pollingInterval 默认为 300 秒,若设置为 0,则 SDK 不会轮询请求规则,仅在初始化时以及应用前后台切换、uuid 变更时重新请求 [GMPPopupManager startWithAppId:@"your popup appid" config:reachConfig pollingInterval:300];
若使用 Finder SDK 进行数据上报,则无需关注此部分。若确认不使用 Finder SDK 上报数据,而是使用自己的 UBA 库进行数据上报,则需自行实现 UBA 上报能力,并注入到 SDK 中
// 首先需要实现 GMPUBAInterface 接口 @interface UBAImplement : NSObject <GMPUBAInterface> @end @implementation UBAImplement - (instancetype)init { if (self = [super init]) { // 在 UBA 事件发生时应调用 GMPPopupManager consumeEvent 方法通知事件发生 [[BDAutoTrack sharedTrack] setEventHandler:^BDAutoTrackEventPolicy(BDAutoTrackDataType type, NSString * _Nonnull event, NSMutableDictionary<NSString *, id> * _Nonnull properties) { [GMPPopupManager consumeEvent:event params:properties]; return BDAutoTrackEventPolicyAccept; } forTypes:BDAutoTrackDataTypeAll]; } return self; } - (NSDictionary *)getCommonParams { // 返回 UBA 额外参数,会附加于 SDK 请求中,需传入 appid 即可 return @{ @"finder_app_id": @([[BDAutoTrack appID] integerValue]) }; } - (NSString *)getDid { // 返回 UBA 的唯一设备标识,若无返回 nil 即可 return [BDAutoTrack rangersDeviceID];; } - (NSString *)getBaseId { // 返回 UBA 的唯一用户标识,若无返回 nil 即可 return [BDAutoTrack ssID]; } - (BOOL)eventV3:(NSString *)event params:(NSDictionary *)params { // 使用 UBA 的事件上报接口进行事件上报 return [BDAutoTrack eventV3:event params:params]; } @end
弹窗SDK 内部会默认 Finder 读取需要上报的埋点事件 , 而使用了别的 uba 之后, 需要把上报的埋点事件传入, 让弹窗SDK 内部可以正常消费事件并顺利弹窗弹窗SDK 内部会默认 Finder 读取需要上报的埋点事件 , 而使用了别的 uba 之后, 需要把上报的埋点事件传入, 让弹窗SDK 内部可以正常消费事件并顺利弹窗
// 完成自定义 UBA 类实现后,需要在 SDK 初始化时将 UBA 实例传入 GMPReachConfig GMPReachConfig *reachConfig = [[GMPReachConfig alloc] init]; reachConfig.ubaInstance = [[UBAImplement alloc] init];
[GMPPopupManager consumeEvent:event params:properties];
在某些场景下想关闭正在显示的 GMP 弹窗时,可通过以下方法进行关闭
[GMPPopupManager closeShowingPopupView];
在GMP首页,选择用户触达-消息触达-新增触达任务,选择App弹窗通道并选择在3.2中获取的弹窗应用,配置任务对应的事件及筛选条件如下图所示
Finder
在app上使用finder sdk上报对应的事件及参数
#import <RangersAppLog/BDAutoTrack.h> NSMutableDictionary *dict = [NSMutableDictionary dictionary]; dict[@"url"] = @"1111"; // 事件属性 [BDAutoTrack eventV3:@"event_name" params:dict]; // event_name 即为事件名称
其他 UBA
[GMPPopupManager consumeEvent:event params:properties];
弹窗SDK 务必在 didFinishLaunchingWithOptions 中初始化,如果您的app中涉及隐私弹窗协议,只需要在隐私弹窗协议同意之后再更新用户画像即可(见3.4)。即在隐私弹窗协议同意之后调用 GMPPopupManager.updateUUID("uuid", uuidType: "idType") 即可。
当弹窗没有按预期正常弹出时,接入方可以按照下列顺序进行排查
检查弹窗SDK是否正常初始化,是否正常触发了 xxx 接口来拉取任务列表
(xxx 为 2.1.0 以及以上:/openapi/v3/rule_engine/get_popup_rule_list;2.1.0 以下:/openapi/v1/app_window/getAppWindowTask)
抓包查看 xxx 接口是否正确下发配置的任务(如无下发则检查appId、popupAppId是否正确配置,以及当前用户是否在任务的圈选人群中)
(xxx 为 2.1.0 以及以上:/openapi/v3/rule_engine/get_popup_rule_list;2.1.0 以下:/openapi/v1/app_window/getAppWindowTask)
开启sdk调试模式,日志过滤"[GMPReachSDK]",查看是否有"开始消费事件${eventName}"对应事件的消费日志(如果没有则代表此时SDK没有进行事件消费,检查配置是否有问题)
开启sdk调试模式,日志过滤"[GMPReachSDK]",查看是否有"触发勿扰/频控"的日志(如果有则代表该任务被频控/勿扰限制无法弹窗)
开启sdk调试模式,日志过滤"[GMPReachSDK]",查看是否有"事件${eventName}满足弹窗条件"的日志(如果有则代表该事件成功匹配上某个任务且未被频控勿扰所拦截,即将进行弹窗渲染)
开启sdk调试模式,日志过滤"[GMPReachSDK]",查看是否有弹窗失败相关日志(如果有则代表弹窗渲染过程出现问题)