iOS SDK集成

GMP 资源位 SDK 是 GMP 对外提供的资源位数据管理的 SDK 。
资源位 SDK 主要提供两种接入方式

• 自渲染

用户调用 API 接口，获取 GMP 资源位配置数据，自行处理视图渲染、交互监听，在交互变化时通知 SDK。

• SDK 渲染

SDK 内部完成一系列流程，包括 请求配置、数据处理、视图渲染（banner 视图的样式）、图片缓存、交互监听、事件上报。

1 配置应用鉴权信息

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

team id：55XXXX22XX

bundle id：com.example.gmp

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

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

1.1 team id 获取

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

1.1 bundle id 获取

iOS 工程上的 bundl identifier

2 集成 SDK

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 获取 mainAccountId

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

3.2 初始化

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

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

#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 平台上配置的一致
    // 设置资源位的缓存等级
    GMPResourceManager.sharedManager.cacheLevel = GMPResourceCacheLevelAllCache;
    [GMPResourceManager startWithConfig:reachConfig];
}

#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 平台上配置的一致
    // 设置资源位的缓存等级
		GMPResourceManager.shared().cacheLevel = .allCache  
    GMPResourceManager.start(with: reachConfig)
}

3.2.2 初始化示例（SaaS版本）

#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.mainAccountId = @"{{MainAccountId}}"; // SaaS 火山引擎账号 id
    reachConfig.teamId = @"XXXXXXXX";      // 开发者账号 teamid，从苹果开发者后台获取，请确保与 GMP 平台上配置的一致
    // 设置资源位的缓存等级
    GMPResourceManager.sharedManager.cacheLevel = GMPResourceCacheLevelAllCache;
    [GMPResourceManager startWithConfig:reachConfig];
}

#import GMPReachSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let reachConfig = GMPReachConfig()
    reachConfig.appId = @"{{APPID}}"      // GMP 项目ID
    reachConfig.enableLog = true          // 是否打开日志
    reachConfig.mainAccountId = @"{{MainAccountId}}"; // SaaS 火山引擎账号 id
    reachConfig.teamId = @"XXXXXXXX"      // 开发者账号 teamid，从苹果开发者后台获取，请确保与 GMP 平台上配置的一致
    // 设置资源位的缓存等级
		GMPResourceManager.shared().cacheLevel = .allCache  
    GMPResourceManager.start(with: reachConfig)
}

3.2.3 参数详情

ReachConfig 详细配置如下

以下是资源位 SDK 需要传入的参数

3.3 更新用户画像

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

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

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

GMPReachConfig *reachConfig = [[GMPReachConfig alloc] init];
// 设置自动更新 uuid 为关闭
reachConfig.isAutoUpdateUserId = NO; 
// ...省略其他配置...
[GMPResourceManager startWithConfig:reachConfig];;

let reachConfig = GMPReachConfig()
// 设置自动更新 uuid 为关闭
reachConfig.isAutoUpdateUserId = false      
// ...省略其他配置...
GMPResourceManager.start(with: reachConfig)

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

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

// uuid: 自有账号体系 id
// uuidType: 自有账号体系 id 类型，需要在 CDP 平台上查看对应的 id code
GMPResourceManager.updateUUID(“uuid”, uuidType: “uuidType”)

退出登录

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

// uuid , uuid type 填空字符串
GMPResourceManager.updateUUID(“”, uuidType: “”)
BDAutoTrack.clearUserUniqueID()

4 其他可选配置

4.1 其他平台 UBA 配置

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

4.1.1 实现 GMPUBAInterface 接口

// 首先需要实现 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.1.2 设置 ubaInstance

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

// 完成自定义 UBA 类实现后，需要在 SDK 初始化时将 UBA 实例传入 GMPReachConfig
let reachConfig = GMPReachConfig()
reachConfig.ubaInstance = UBAImplement()

4.2 设置资源位缓存等级

代码示例

// 设置资源位的缓存等级
GMPResourceManager.sharedManager.cacheLevel = GMPResourceCacheLevelAllCache;

// 设置资源位的缓存等级
GMPResourceManager.shared().cacheLevel = .allCache  

通过 SDK 生成资源位视图，并根据 resourceId 填充资源位数据，视图的位置尺寸由用户定义

1 banner

1.1 参数说明

1.2 初始化资源位视图

在需要的位置调用资源位视图的初始化方法并加载指定资源位 id，示例

#import <GMPReachSDK/GMPReachSDK.h>

GMPResourceView *resourceView = [[GMPResourceView alloc] init];
resourceView.delegate = self;
[resourceView loadResource:@"resource_id"];

import GMPReachSDK

let resourceView = GMPResourceView()
resourceView.delegate = self
resourceView.loadResource("resource_id")

加载资源位数据方法介绍

/** 
 * 加载资源位数据
 * @param  resourceID 资源位 id 
 */
- (void)loadResource:(nonnull NSString *)resourceID;

资源位回调方法
在创建资源位视图后，设置资源位视图的代理 resourceView.delegate = self，可在代理中实现以下代理方法监听，resourceView 的数据请求状态，resourceView 的交互行为。

/** 
 * 资源位数据加载成功
 *
 * @param  resourceView 资源位视图
 */
- (void)resourceDataLoadSuccess:(GMPResourceView *)resourceView;

/**
 * 资源位数据加载失败
 *
 * @param  resourceView 资源位视图
 * @param  error 错误对象
 */
- (void)resourceDataLoadFailed:(GMPResourceView *)resourceView error:(NSError *)error;

/**
 * 资源位帧位展示
 *
 * @param  resourceView 资源位视图 
 * @param  index 展示到第几个帧位
 */
- (void)resourceView:(GMPResourceView *)resourceView didScrollToIndex:(NSInteger)index;

/**
 * 资源位点击
 *
 * @param  resourceView 资源位视图
 * @param  navigateUrl 跳转链接
 */
- (BOOL)resourceView:(GMPResourceView *)resourceView didClickNavigateUrl:(NSString *)navigateUrl;

2 闪屏

2.1 参数说明

2.2 初始化闪屏视图

#import <GMPReachSDK/GMPReachSDK.h>

GMPSplashView *splashView = [[GMPSplashView alloc] initWithRootViewController:rootVC];
splashView.delegate = self;
[splashView loadResource:@"resource_id"];

import GMPReachSDK

let splashView = GMPSplashView(rootViewController: rootViewController)
splashView.delegate = self
rsplashView.loadResource("resource_id")

闪屏页方法回调

@protocol GMPSplashViewDelegate <NSObject>
/**
 * 启动页数据加载成功
 *
 * @param  splashView 启动页视图
 * @param  resourceData 资源位数据
 */
- (void)splashView:(GMPSplashView *)splashView resourceLoadSuccess:(GMPResourceData *)resourceData;

/**
 * 启动页数据加载失败
 *
 * @param  splashView 启动页视图
 * @param  error 错误信息
 */
- (void)splashView:(GMPSplashView *)splashView resourceLoadFailed:(NSError *)error;

/**
 * 启动页点击
 *
 * @param  splashView 启动页视图
 * @param  url 跳转链接
 *
 * @return  是否自行处理跳转链接 YES：自行处理     NO：SDK 默认处理
 */
- (BOOL)splashView:(GMPSplashView *)splashView didClick:(NSString *)url;

/**
 * 启动页展示成功
 *
 * @param  splashView 启动页视图
 * @param  resourceData 素材数据
 */
- (void)splashView:(GMPSplashView *)splashView showSuccess:(GMPResourceData *)resourceData;

/**
 * 启动页展示成功
 *
 * @param  splashView 启动页视图
 * @param  error 错误信息
 */
- (void)splashView:(GMPSplashView *)splashView showFailed:(NSError *)error;

/**
 * 启动页展示成功
 *
 * @param  splashView 启动页视图
 * @param  resourceData 资源位数据
 */
- (void)splashView:(GMPSplashView *)splashView showFinished:(GMPResourceData *)resourceData;

仅提供资源位数据

1 资源位数据模型说明

1.1 GMPResourceData

1.2 GMPResourceItem

1.3 GMPResourceCustomizeInfo

2 请求资源位数据

在需要拉取资源位数据的页面导入对应的 .h 文件
根据 resourceId（资源位id）获取对应的资源位数据，相关 api 如下

/**
 * 请求单个资源位数据
 *
 * @param  resourceID 资源位 id
 * @param  success 请求成功回调
 * @param  failure 请求失败回调
 */
+ (void)resourceDataWithResourceID:(NSString *)resourceID success:(void(^)(GMPResourceData *resourceData))success failure:(void(^)(NSError *error))failure;

/**
 * 请求多个资源位数据
 *
 * @param  resourceIDs 一组资源位 id
 * @param  success 请求成功回调
 * @param  failure 请求失败回调
 */
+ (void)resourceDataWithResourceIDs:(NSArray<NSString *> *)resourceIDs success:(void(^)(NSArray<GMPResourceData *> *resourceDatas))success failure:(void(^)(NSError *error))failure;

使用示例

// 请求资源位数据
[GMPResourceManager resourceDataWithResourceID:@"resourceID" success:^(GMPResourceData* resourceData) {
    // 请求数据成功回调

} failure:^(NSError* error) {
    // 请求数据失败回调

}];

GMPResourceManager.resourceData(withResourceID: "resourceID") { resourceData in
    // 请求数据成功回调
} failure: { error in
    // 请求数据失败回调
}

3 自渲染接入闪屏页

下列为 GMPResourceItem 类获取闪屏页配置的方法

使用示例

NSInteger countDown = [resourceItem getCountDown];// 获取倒计时 
double validDate = [resourceItem getValidDate];// 获取素材失效时间戳 

if (vaildDate != -1 && vaildDate < [[NSDate date] timeIntervalSince1970] * 1000) { // 素材失效 

}
//素材未失效 
if(countDown != -1) { 
	// 设置倒计时数据 
}

let countDown = resourceItem.getCountDown() // 获取倒计时
let validDate = resourceItem.getVaildDate() // 获取素材失效时间戳

if validDate != -1 && validDate < Date().timeIntervalSince1970 * 1000 {
    // 素材失效                
}
// 素材未失效
if countDown != -1 {
    // 设置倒计时
}

4 自渲染埋点上报

埋点上报相关方法，请在对应的资源位帧位展示成功、失败和点击时调用 GMPBannerTracker 对应的类方法进行上报。

#import <GMPReachSDK/GMPReachSDK.h>

/// 资源位展示成功埋点
/// @param  resourceItem 展示成功的帧位对象
+ (void)trackerForResourceShowSuccess:(GMPResourceItem *)resourceItem;

/// 资源位展示失败埋点
/// @param  resourceItem 展示失败的帧位对象
/// @param  errorMessage 错误信息
+ (void)trackerForResourceShowFailed:(GMPResourceItem *)resourceItem errorMessage:(NSString *)errorMessage;

/// 素材点击埋点
/// @param  resourceItem 被点击素材的帧位对象
/// @param  errorMessage 错误信息
/// @param  isClickUrl 是否跳转链接
+ (void)trackerForItemClick:(GMPResourceItem *)resourceItem errorMessage:(NSString *)errorMessage isClickUrl:(BOOL)isClickUrl;

示例：

#import <GMPReachSDK/GMPReachSDK.h>

/// 资源位展示成功埋点
[GMPResourceTracker trackerForResourceShowSuccess:resourceItem];

/// 资源位展示失败埋点
[GMPResourceTracker trackerForResourceShowFailed:resourceItem errorMessage:errorMessage];

/// 素材点击埋点
[GMPResourceTracker trackerForItemClick:resourceItem errorMessage:errorMessage isClickUrl:YES];

1 简介

算法资源位是通过算法推荐结合用户的行为偏好数据，实现个性化的资源位物料下发

2 算法资源位数据模型说明

• GMPRecParams（请求算法资源位的参数）

• • GMPRecResourceData（请求算法资源位的返回response）

• GMPRecResourceItem

3 请求算法资源位数据

• 创建资源位参数

GMPRecParams *params = [[GMPRecParams alloc] init];
params.resourceId = @"currentRecListId";
params.contextItemId = @"contextItemId";
params.contextItemType = @"currentRecType";
params.spm = @"spm";
params.page = 1;

let params = GMPRecParams()
params.resourceId = "currentRecListId"
params.contextItemId = "contextItemId"
params.contextItemType = "currentRecType"
params.spm = "spm"
params.page = 1

• 发起算法资源位请求

[GMPResourceManager getRecResource:params success:^(GMPRecResourceData * _Nonnull resourceData) {
    // 成功回调
} failure:^(NSError * _Nonnull error) {
    // 失败回调
}];

GMPResourceManager.getRecResource(params) { resourceData in
    // 成功回调
} failure: { error in
    // 失败回调
}

• 请求下一页的素材

GMPRecParams *params = [[GMPRecParams alloc] init];
params.resourceId = @"currentRecListId";
params.contextItemId = @"contextItemId";
params.contextItemType = @"currentRecType";
params.spm = @"spm";
params.page = newpage;,
[GMPResourceManager getRecResource:params success:^(GMPRecResourceData * _Nonnull resourceData) {
    // 成功回调
} failure:^(NSError * _Nonnull error) {
    // 失败回调
}];

let params = GMPRecParams()
params.resourceId = "currentRecListId"
params.contextItemId = "contextItemId"
params.contextItemType = "currentRecType"
params.spm = "spm"
params.page = newpage
GMPResourceManager.getRecResource(params) { resourceData in
    // 成功回调
} failure: { error in
    // 失败回调
}

4 算法资源位埋点上报

埋点上报相关方法，请在对应的资源位帧位展示成功、失败和点击时调用 GMPBannerTracker 对应的类方法进行上报。

#import <GMPReachSDK/GMPReachSDK.h>

/// 资源位展示成功埋点
/// @param  resourceItem 展示成功的帧位对象
+ (void)trackerForResourceShowSuccess:(id<GMPResourceBaseItem>)resourceItem;

/// 资源位展示失败埋点
/// @param  resourceItem 展示失败的帧位对象
/// @param  errorMessage 错误信息
+ (void)trackerForResourceShowFailed:(id<GMPResourceBaseItem>)resourceItem errorMessage:(NSString *)errorMessage;

/// 素材点击埋点
/// @param  resourceItem 被点击素材的帧位对象
/// @param  errorMessage 错误信息
/// @param  isClickUrl 是否跳转链接
+ (void)trackerForItemClick:(id<GMPResourceBaseItem>)resourceItem errorMessage:(NSString *)errorMessage isClickUrl:(BOOL)isClickUrl;

/// 素材停留时长
/// @param  resourceItem 帧位对象
/// @param  duration 停留时长
+ (void)trackerForStayDuration:(id<GMPResourceBaseItem>)resourceItem duration:(NSInteger)duration;

示例：

#import <GMPReachSDK/GMPReachSDK.h>

/// 资源位展示成功埋点
[GMPResourceTracker trackerForResourceShowSuccess:resourceItem];

/// 资源位展示失败埋点
[GMPResourceTracker trackerForResourceShowFailed:resourceItem errorMessage:errorMessage];

/// 素材点击埋点
[GMPResourceTracker trackerForItemClick:resourceItem errorMessage:errorMessage isClickUrl:YES];

/// 素材停留时长
[GMPResourceTracker trackerForStayDuration:resourceItem duration:duration];

• FinderSDK 是否正确接入，在资源位初始化前是否完成 FinderSDK 的初始化，日志过滤"BDAutotrack"可查看 FinderSDK 初始化相关日志。
• 检查是否完成了资源位初始化的必选参数配置，日志过滤"GMPResource"查看相关日志。
• 检查配置的域名是否正确，可抓包查看请求是否正常

1 如何判断是否初始化成功？

日志过滤"GMPResource"查看是否有资源位初始化完成日志

2 发起资源位请求后无资源

检查初始化配置是否正确，可在日志中过滤"GMPResource"查看错误日志，或者抓包查看请求是否成功响应

3 SDK 缓存说明

• 闪屏类型资源位：SDK 内部会一直缓存拉取成功的闪屏素材，展示前判断是否过期，过期则不展示
• SDK 内部会按照 网络请求返回数据>缓存数据>兜底数据 的优先级返回资源位数据，其中缓存数据与兜底数据往往会在网络异常的情况下返回，在极端情况下若这两类数据都无法正常返回会回调 failure，这种情况下接入方可根据自己的业务逻辑添加容错数据

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