文档中心

iOS SDK集成

最近更新时间：2024.03.25 14:16:58

首次发布时间：2022.10.31 09:54:30

一、简介

App 弹窗是 GMP ReachSDK 提供的弹窗触达功能。

二、SDK 集成

1 配置应用鉴权信息

需提供 iOS 应用包名和开发者 team id，然后在 GMP 后台配置(管理中心-消息管理-客户端SDK-鉴权配置)，需保证与 app 的实际信息一致，可联系您的客户端开发人员获取。该项配置用于接口的安全鉴权校验，不会用于其他用途。
示例如下：

team id：55XXXX22XX

bundle id：com.example.gmp

在 GMP 控制台中配置 APP 的鉴权信息
alt

iOS 鉴权所需的配置信息以及获取方式如下

1.1 team id 获取

team id 需要在苹果开发者后台上获取，在账号页面下滑，找到会员资格详细信息，其中的团队 ID 就是 team id
alt

1.1 bundle id 获取

iOS 工程上的 bundl identifier
alt

2 集成 SDK

注意

弹窗 SDK 集成 Demo，可参考 https://www.volcengine.com/docs/6315/1130446
Demo 需要在初始化时配置对应的参数才能获取到对应的数据

2.1 集成 Finder SDK

弹窗 SDK 依赖 Finder SDK 进行数据回流，在使用弹窗 SDK 前，请确保已经集成了 Finder SDK，并且 Finder SDK 版本在 6.15.2 以上。

Finder iOS SDK接入指南地址：Finder接入

2.2 集成弹窗 SDK

cocoapods 引入方式（推荐）

推荐使用 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 库，还需下载以下文件，并且解压后拖入到项目工程中

SDWebImage.framework.zip

303.35KB

3. 初始化 SDK

3.1 获取初始化必备 id

3.1.1 获取项目 id 和应用 id

在gmp首页，点击右上角头像-项目管理，即可进入项目后台页查看对应项目的项目id和应用id（项目id是初始化弹窗sdk的appid，应用id是用于初始化Finder SDK的appid）

3.1.2 获取主帐号 id（SaaS版本）

进入火山引擎控制台，点击右上角头像 icon，红框中的账号 ID 即是主帐号 id

3.1.3 获取弹窗应用 id

在GMP首页，选择管理中心-通道管理-App弹窗-应用管理即可打开弹窗应用列表，最左侧一栏为弹窗应用id，将所选应用的弹窗应用id传入sdk初始化即可

3.2 初始化

首先您需要初始化 Finder SDK，具体可参考：初始化 Finder SDK - 火山引擎
在初始化的地方导入 GMPReachSDK.h，建议在 appdelegate.m 的 didFinishLaunchingWithOptions 方法中进行弹窗 SDK 的初始化。

#import <GMPReachSDK/GMPReachSDK.h>

3.2.1 初始化示例（私有化版本）

swift

#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

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let reachConfig = GMPReachConfig()
    reachConfig.appId = "{{APPID}}"      // GMP 项目ID
    reachConfig.host = "{{host}}"        // 私有化部署域名
    reachConfig.enableLog = true          // 是否打开日志
    reachConfig.teamId = "XXXXXXXX"      // 开发者账号 teamid，从苹果开发者后台获取，请确保与 GMP 平台上配置的一致
		// 如果项目支持自动登陆，用户画像已经存在，需要提前设置上
		reachConfig.uuid = "uuid"
    reachConfig.uuidType = "uuid_type"
    GMPPopupManager.shared().delegate = self
    GMPPopupManager.start(withAppId: "popup appid", config: reachConfig)
}

3.2.2 初始化示例（SaaS版本）

swift

#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;
}

#import GMPReachSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let reachConfig = GMPReachConfig()
    reachConfig.appId = "{{APPID}}"      // GMP 项目ID
    reachConfig.enableLog = true          // 是否打开日志
    reachConfig.teamId = "XXXXXXXX"      // 开发者账号 teamid，从苹果开发者后台获取，请确保与 GMP 平台上配置的一致
    reachConfig.mainAccountId = "{{MainAccountId}}" // SaaS 火山引擎账号 id
    // 如果项目支持自动登陆，用户画像已经存在，需要提前设置上
		reachConfig.uuid = "uuid"
    reachConfig.uuidType = "uuid_type"
    GMPPopupManager.shared().delegate = self
    GMPPopupManager.start(withAppId: "popup appid", config: reachConfig)
}

3.2.3 参数详情

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 则不进行轮询

3.3 更新用户画像

如您的产品中有账户体系，请在用户登录后立即设置 uuid，以保证用户登录前后口径一致性。Finder SDK 登陆态变化可参考：Finder SDK 登陆态变化

除此之外，您还需要及时通知弹窗SDK用户画像的变化

警告

在SDK版本 >= 2.1.0 之后，更新用户画像只能通过手动更新，旧版升级上来的请改成手动更新模式
注意 : 务必在 BDAutoTrack.setCurrentUserUniqueID 设置前调用手动更新

2.1.0 以下版本需要为 ReachConfig 增加以下配置：

swift

GMPReachConfig *reachConfig = [[GMPReachConfig alloc] init];
// 设置自动更新 uuid 为关闭
reachConfig.isAutoUpdateUserId = NO; 
...省略其他配置...
[GMPPopupManager startWithAppId:@"your popup appid" config:config];

let reachConfig = GMPReachConfig()
// 设置自动更新 uuid 为关闭
reachConfig.isAutoUpdateUserId = false      
...省略其他配置...
GMPPopupManager.start(withAppId: "popup appid", config: reachConfig)

以下配置在各个SDK版本均要配置
登录用户

swift

// uuid: 自有账号体系 id
// uuidType: 自有账号体系 id 类型，需要在 CDP 平台上查看对应的 id code
[GMPPopupManager updateUUID:@"uuid" uuidType:@"uuidType"];

退出登录

swift

// uuid , uuid type 填空字符串
[GMPPopupManager updateUUID:@"" uuidType:@""];
[BDAutoTrack clearUserUniqueID];

3.4 弹窗状态监听

接入方可以通过实现 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;

4. 其他可选配置

4.1 弹窗预览

点击预览弹窗后，接入方可以通过扫一扫获取到弹窗的id，将其传入SDK的预览接口可以在当前页面立刻弹出对应弹窗，调用SDK预览接口示例如下

swift

[GMPPopupManager testPopupWithTestId:@"test id"];

在gmp平台管理中心-通道管理-app弹窗，找到需要预览的弹窗扫码即可获取到对应弹窗的 testId

4.2 禁用弹窗

在某些沉浸式场景(如视频播放)或已弹窗场景可以禁止弹窗SDK的弹窗以避免对用户的体验带来干扰（关闭后需要在允许弹窗的场景再次调用来重新启用弹窗功能）

swift

// 设置为不允许弹窗
[GMPPopupManager setPopupEnable:NO];

// 设置为不允许弹窗，同时关闭正在弹出的弹窗
[GMPPopupManager setPopupEnable:NO closeShowingPopupView:YES];

4.3 图片预加载

4.3.1 图片预加载等级

为了降低弹窗弹出的时延，弹窗SDK支持对即将弹出的弹窗中的图片进行预加载，接入方可以根据自身需求设置不同等级的图片预加载
通过设置 [GMPPopupManager sharedManager].imagePrefetchType 控制图片预加载策略，默认是只预加载背景图片。

字段	说明	类型
ImagePreLoadLevel	弹窗SDK图片预加载等级，默认值 ONLY_BACKGROUND 可选项： GMPPopupImagePrefetchNone：不对任何图片进行预加载 GMPPopupImagePrefetchOnlyBackground：对弹窗或蒙层的背景图片进行预加载(默认) GMPPopupImagePrefetchOnlyComponent：对图片/按钮控件的图片进行预加载 GMPPopupImagePrefetchAll：对所有图片进行预加载	enum

字段

说明

类型

ImagePreLoadLevel

弹窗SDK图片预加载等级，默认值 ONLY_BACKGROUND
可选项：

GMPPopupImagePrefetchNone：不对任何图片进行预加载
GMPPopupImagePrefetchOnlyBackground：对弹窗或蒙层的背景图片进行预加载(默认)
GMPPopupImagePrefetchOnlyComponent：对图片/按钮控件的图片进行预加载
GMPPopupImagePrefetchAll：对所有图片进行预加载

enum

swift

GMPPopupManager.sharedManager.imagePrefetchType = GMPPopupImagePrefetchAll;

4.4 设置弹窗补偿（版本>=2.1.0）

APP弹窗是事件触发型的通道,在客户端本地完成弹窗的触发,「app弹窗」的触发可能在以下场景下触发失败;

触发弹窗时命中勿扰配置;
触发弹窗时用户侧为弱网不境;触发弹窗时遭遇其他未知异常。

当前触发失败后本次触达任务就结束了,因此在触发弹窗时允许设置补偿机制使本次触发失败的弹窗任务在下一次事件触发时尝试进行弹窗。
设置弹窗补偿的示例代码如下

swift

GMPPopupManager.sharedManager.enableCompensate = YES;

4.5 设置轮询间隔（版本>=2.1.0）

最新版本的弹窗 SDK 是通过轮询的方式来更新弹窗规则的，默认的轮询间隔是 300 秒。如果您对弹窗任务实时性有着更高事实性的要求，可以在初始化弹窗 SDK 时传入 pollingInterval 自定义轮询的时间间隔。

swift

// pollingInterval 默认为 300 秒，若设置为 0，则 SDK 不会轮询请求规则，仅在初始化时以及应用前后台切换、uuid 变更时重新请求
[GMPPopupManager startWithAppId:@"your popup appid" config:reachConfig pollingInterval:300];

// pollingInterval 默认为 300 秒，若设置为 0，则 SDK 不会轮询请求规则，仅在初始化时以及应用前后台切换、uuid 变更时重新请求
GMPPopupManager.start(withAppId: "", config: reachConfig, pollingInterval: 300)

4.6 其他平台 UBA 配置

若使用 Finder SDK 进行数据上报，则无需关注此部分。若确认不使用 Finder SDK 上报数据，而是使用自己的 UBA 库进行数据上报，则需自行实现 UBA 上报能力，并注入到 SDK 中

4.6.1 实现 GMPUBAInterface 接口

swift

// 首先需要实现 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

// 首先需要实现 GMPUBAInterface 接口

class UBAImplement: NSObject, GMPUBAInterface {

	  override init() {
	      // 在 UBA 事件发生时应调用 GMPPopupManager consumeEvent 方法通知事件发生
        BDAutoTrack.shared().setEventHandler({ type, event, params in
            GMPPopupManager.consumeEvent(event, params: params)
            return .accept
        }, forTypes: .all)
        super.init()
    }

    func getCommonParams() -> [AnyHashable : Any]? {
        // 返回 UBA 额外参数，会附加于 SDK 请求中，需传入 appid 即可
        return ["finder_app_id": BDAutoTrack.appID]
    }

    func getDid() -> String? {
        // 返回 UBA 的唯一设备标识，若无返回 nil 即可
        return BDAutoTrack.rangersDeviceID
    }

    func getBaseId() -> String? {
				// 返回 UBA 的唯一用户标识，若无返回 nil 即可
        return BDAutoTrack.ssID
    }

    func eventV3(_ event: String, params: [AnyHashable : Any]?) -> Bool {
				// 使用 UBA 的事件上报接口进行事件上报
        BDAutoTrack.eventV3(event, params: params)
    }
}

4.6.2 设置 ubaInstance

弹窗SDK 内部会默认 Finder 读取需要上报的埋点事件 , 而使用了别的 uba 之后, 需要把上报的埋点事件传入, 让弹窗SDK 内部可以正常消费事件并顺利弹窗弹窗SDK 内部会默认 Finder 读取需要上报的埋点事件 , 而使用了别的 uba 之后, 需要把上报的埋点事件传入, 让弹窗SDK 内部可以正常消费事件并顺利弹窗

swift

// 完成自定义 UBA 类实现后，需要在 SDK 初始化时将 UBA 实例传入 GMPReachConfig
GMPReachConfig *reachConfig = [[GMPReachConfig alloc] init];
reachConfig.ubaInstance = [[UBAImplement alloc] init];

4.6.3 传入埋点事件

swift

[GMPPopupManager consumeEvent:event params:properties];

4.7 关闭正在显示的 GMP 弹窗

在某些场景下想关闭正在显示的 GMP 弹窗时，可通过以下方法进行关闭

swift

[GMPPopupManager closeShowingPopupView];

5. 触发弹窗

5.1 配置弹窗任务

在GMP首页，选择用户触达-消息触达-新增触达任务，选择App弹窗通道并选择在3.2中获取的弹窗应用，配置任务对应的事件及筛选条件如下图所示

5.2 客户端上报事件

Finder
在app上使用finder sdk上报对应的事件及参数

swift

#import <RangersAppLog/BDAutoTrack.h>

NSMutableDictionary *dict = [NSMutableDictionary dictionary];
dict[@"url"] = @"1111";    // 事件属性
[BDAutoTrack eventV3:@"event_name" params:dict];    // event_name 即为事件名称

其他 UBA

swift

[GMPPopupManager consumeEvent:event params:properties];

6. 合规处理（隐私政策初始化的处理）

弹窗SDK 务必在 didFinishLaunchingWithOptions 中初始化，如果您的app中涉及隐私弹窗协议，只需要在隐私弹窗协议同意之后再更新用户画像即可(见3.4)。即在隐私弹窗协议同意之后调用 GMPPopupManager.updateUUID("uuid", uuidType: "idType") 即可。

三、常见问题

1.弹窗没有正常弹出

当弹窗没有按预期正常弹出时，接入方可以按照下列顺序进行排查

检查弹窗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]"，查看是否有弹窗失败相关日志（如果有则代表弹窗渲染过程出现问题）

四、埋点说明

GMP弹窗SDK埋点说明文档

★版本记录

iOS 弹窗、资源位SDK 版本记录

增长营销平台

iOS SDK集成

1 配置应用鉴权信息

1.1 team id 获取

1.1 bundle id 获取

2 集成 SDK

2.1 集成 Finder SDK

2.2 集成弹窗 SDK

cocoapods 引入方式（推荐）

手动引入方式

3. 初始化 SDK

3.1 获取初始化必备 id

3.1.1 获取项目 id 和应用 id

3.1.2 获取主帐号 id（SaaS版本）

3.1.3 获取弹窗应用 id

3.2 初始化

3.2.1 初始化示例（私有化版本）

3.2.2 初始化示例（SaaS版本）

3.2.3 参数详情

3.3 更新用户画像

3.4 弹窗状态监听

4. 其他可选配置

4.1 弹窗预览

4.2 禁用弹窗

4.3 图片预加载

4.3.1 图片预加载等级

4.4 设置弹窗补偿（版本>=2.1.0）

4.5 设置轮询间隔（版本>=2.1.0）

4.6 其他平台 UBA 配置

4.6.1 实现 GMPUBAInterface 接口

4.6.2 设置 ubaInstance

4.6.3 传入埋点事件

4.7 关闭正在显示的 GMP 弹窗

5. 触发弹窗

5.1 配置弹窗任务

5.2 客户端上报事件

6. 合规处理（隐私政策初始化的处理）

1.弹窗没有正常弹出