# 一、简介 GMP 资源位 SDK 是 GMP 对外提供的资源位数据管理的 SDK 。资源位 SDK 主要提供两种接入方式： * 自渲染用户调用 API 接口，获取 GMP 资源位配置数据，自行处理视图渲染、交互监听，在交互变化时通知 SDK上报埋点。 * SDK 渲染 SDK 内部完成一系列流程，包括请求配置、数据处理、视图渲染（banner 视图的样式）、图片缓存、交互监听、事件上报。 # 二、SDK 集成 ## 1. 配置应用鉴权信息需提供 Android 应用包名和应用签名然后在 GMP 后台配置(管理中心\-消息管理\-客户端SDK\-鉴权配置)，需保证与 app 的实际信息一致，可联系您的客户端开发人员获取。该项配置用于接口的安全鉴权校验，不会用于其他用途。示例如下： ```Bash # 鸿蒙包名 com.example.gmpdemo # 获取鸿蒙应用签名 SHA256 fingerprint 6918672280841579539 ``` 然后到GMP后台配置相关信息 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f14f7f4fe06a1796bb8a78e02a8c6df3.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_38d1c9f8a137c389420fd12f5adb2c59.png) ## 2. 集成 SDK ### 2.1 集成 Finder SDK 资源位 SDK 依赖 Finder SDK 进行数据回流，在使用资源位 SDK 前，请确保已经集成了 Finder SDK。并且 Finder SDK 版本在 6.16.1 及以上。如果使用多 module，请确保资源位 SDK 的 module 能引用到 Finder SDK 。 [Finder HarmonyOS Next SDK接入指南](https://www.volcengine.com/docs/84129/1362127) ### 2.2 集成资源位 SDK 引入SDK（oh\-package.json5） ```JSON "dependencies": { ... "@volcengine/gmp_resource": "0.0.1-alpha.4" } ``` ## 3.初始化 SDK ### 3.1 获取初始化必备id #### 3.1.1 获取项目id和应用id 在gmp首页，点击右上角头像\-项目管理，即可进入项目后台页查看对应项目的项目id和应用id（项目id是初始化资源位sdk的appid，应用id是用于初始化Finder SDK的appid） ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e33911e3c06e18163e5cfb2d94a76c09.png) ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f63ac0a0a98fff7ca6c060bcfb8232bb.png) #### 3.1.2 获取主账号id（Saas版本）进入火山引擎控制台，点击右上角头像 icon，红框中的账号 ID 即是主账号id ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_3e3ae20b05dcd480306c83cda8549b6b.png) ### 3.2 初始化 #### 3.2.1 初始化（私有化版本）首先您需要初始化 Finder SDK，具体可参考：[Finder HarmonyOS Next SDK初始化](https://www.volcengine.com/docs/84129/1362127#%E5%88%9D%E5%A7%8B%E5%8C%96%E5%9F%BA%E6%9C%AC%E9%85%8D%E7%BD%AE)，再初始化资源位 SDK。 ```TypeScript export default class MyAbilityStage extends AbilityStage { static appLog = new AppLog() static mGMPResourceSDKInstance: GMPResourceSDKInstance onCreate() { //初始化Finder MyAbilityStage.appLog.init(this.context, finderInitConfig) MyAbilityStage.appLog.user()?.setUserUniqueID(UUID, UUID_TYPE) MyAbilityStage.appLog.start() //GMP项目配置 const reachConfig: ReachConfig = { appLog: MyAbilityStage.appLog, appId: "your appid", appConfig: { host: "your host" }, mainAccountId: MAIN_ACCOUNT_ID, uniqueUid: UUID, uniqueUidType: UUID_TYPE, deviceIdType: DEVICE_ID_TYPE } //资源位配置 const resourceConfig = new ResourceConfig() //...按需配置 .setAutoStart(true) //初始化资源位 MyAbilityStage.mGMPResourceSDKInstance = GMPResourceSDK.newInstance(this.context, resourceConfig, reachConfig) MyAbilityStage.mGMPResourceSDKInstance.init() } } } ``` ### 参数说明 ```TypeScript interface ReachConfig { // Finder 初始化实例 appLog: AppLog // appId gmp项目id appId?: number // 域名获取接口 appConfig?: IAppConfig // uuid uniqueUid?: string // uuidType uniqueUidType?: string // 主账号 id Saas 专用 mainAccountId?: string // 设备 id的类型具体需要客户看传给 cdp 的是什么类型 id deviceIdType?: string, } ``` ### 3.3 更新用户画像如您的产品中有账户体系，请在用户登录后立即设置 uuid，以保证用户登录前后口径一致性。Finder SDK 登陆态变化可参考：[Finder SDK 登陆态变化](https://www.volcengine.com/docs/6285/1362908) 除此之外，您还需要及时通知**资源位SDK**用户画像的变化用户登录 ```TypeScript //mGMPResourceSDKInstance为 3.2 中GMPResourceSDK.newInstance的实例 mGMPResourceSDKInstance.updateUUID("your_uuid", "your_uuid_type") appLog.user()?.setUserUniqueID("your_uuid", "your_uuid_type") ``` 退出登录 ```TypeScript //mGMPResourceSDKInstance为 3.2 中GMPResourceSDK.newInstance的实例 mGMPResourceSDKInstance.updateUUID(null, null) appLog.user()?.setUserUniqueID(null, null) ``` ## 4 其他可选配置 ### 4.1 设置资源位缓存等级 :::tip 资源位SDK内置了兜底缓存 & 用户缓存的双重缓存逻辑 **（兜底缓存为gmp前端配置的兜底素材，用户缓存为上一次拉取该资源位id返回的素材）** ，其中用户缓存优先级大于兜底缓存，在网络异常gmp服务端异常时会读取本地缓存或兜底素材作为对应资源位id的返回，如果接入方本身具有兜底能力可以在接入时设置资源位的缓存等级 ::: #### 参数说明 |**缓存等级** |**策略** | |---|---| |ResourceCacheLevel.NONE_CACHE |不开启缓存 | |ResourceCacheLevel.DEFAULT_RESOURCE_CACHE |只开启兜底缓存(GMP前端配置的兜底素材) | |ResourceCacheLevel.LAST_REQUEST_CACHE |只开启用户缓存(缓存上一次请求的素材) | |ResourceCacheLevel.ALL_CACHE |开启所有缓存，**若不设置缓存等级，默认使用此策略** | ```TypeScript const resourceConfig = new ResourceConfig() // 省略其他配置..... // 设置资源位SDK缓存等级 .setResourceCacheLevel(ResourceCacheLevel.ALL_CACHE)//按需设置枚举值 ``` ## 5 合规处理（隐私政策初始化的处理）资源位SDK 务必请在 MyAbilityStage 中初始化，如果您的app中涉及隐私弹窗协议，请正确配置资源位SDK 的初始化。 ```TypeScript const resourceConfig = new ResourceConfig() // ...... 省略其他配置 // 未同意隐私协议前传入 false ，同意传入 true .setAutoStart(true) ``` # 三、SDK渲染方式接入资源位 ## 1. Banner ### 1.1 参数说明 |**字段** |**说明** |**类型** | |---|---|---| |resourceId |资源位ID |string | |instance |资源位初始化实例 |GMPResourceSDKInstance | ### 1.2 在页面中插入Banner组件 ```TypeScript import { BannerResourceView } from '@volcengine/gmp_resource' //build对应位置插入组件 BannerResourceView({ resourceId: "your resource id", instance: MyAbilityStage.mGMPResourceSDKInstance }).width('100%') .height(200) .margin({ top: 10 }) ``` ## 2 闪屏 ### 2.1 参数说明 |**字段** |**说明** |**类型** | |---|---|---| |resourceId |资源位ID |string | |instance |资源位初始化实例 |GMPResourceSDKInstance | |splashResourceViewListener |闪屏加载回调 |SplashResourceViewListener | ### 1.2 在页面中插入闪屏组件 ```TypeScript import { SplashResourceView } from "@volcengine/gmp_resource" SplashResourceView({ resourceId: KVUtil.get(SPLASH_RESOURCE_ID,""), instance: MyAbilityStage.mGMPResourceSDKInstance, splashResourceViewListener: { onResourceShowFinished: (resource: Resource) => { //倒计时完成回调，一般在这里push到应用首页 this.stack?.replacePath({ name: 'MainPage' }) }, onResourceShowSuccess: (_content, resourceId) => { //闪屏展示成功 }, onResourceShowFailed: (errCode: String, errMsg: String) => { //闪屏展示失败 }, onResourceLoadSuccess: (resources) => { //闪屏远端资源更新成功 }, onResourceLoadFailed: (errCode: String, errMsg: String) => { //闪屏远端资源更新失败 } } }).width('100%') .height('100%') .backgroundColor(Color.White) ``` # 四、自渲染方式接入资源位 ## 1. 资源位数据模型说明 ### 1.1 Resource |**属性名** |**类型** |**含义** | |---|---|---| |key |string |资源位id | |customer_material_list |Content[] |资源位下的帧位列表 | ### 1.2 Content |**属性名** |**类型** |**含义** | |---|---|---| |material_id |Long |素材id | |frame_id |Long |帧位id | |type |ContentType |素材类型(Image图片 Text文本 content_collection自定义类型 Splash 闪屏类型) | |text |string |素材文本 | |image_url |string |素材图片url | |navigate_url |string |素材点击跳转链接url | |customize_info |object[] |自定义类型资源位内容合集 | |extra |Extra |扩展json字段用于存放和具体资源位类型关系比较大的信息比如闪屏页存倒计时|\ | | |count_down?: number, //倒计时秒数|\ | | |valid_date?: number, //素材生效时间|\ | | |picture_config?: PictureConfig //图片尺寸 | |res_space_trans_data |string |服务端透传字段 | ### 1.3 CustomizeInfo |**属性名** |**类型** |**含义** | |---|---|---| |customize_type |int |自定义素材类型 | |text |string |文本 | |image_url |string |图片url | |navigate_url |string |素材点击跳转链接url | |field_name |string |素材参数名称 | |field_show_name |string |素材字段显示名称 | ## 2. 请求资源位数据 ```TypeScript onDidBuild(): void { MyAbilityStage.mGMPResourceSDKInstance.requestResourceData(["resourceId_1"]).then((data)=>{ //成功，拿到资源位数据后自己渲染，格式为 Resource[] this.data = data }).catch(()=>{ //失败 }) } ``` ## 3. 自渲染埋点上报 ```TypeScript /** * 资源位展示成功时回调 * @param content 素材数据类 * @param resourceId 资源位ID */ mGMPResourceSDKInstance.getResourceAction().onResourceShowSuccess(content: Content, resourceId: string) /** * 资源位展示失败时回调 * @param content:展示的素材 * @param errorMessage: 展示失败的原因 */ mGMPResourceSDKInstance.getResourceAction().onResourceShowFailed(content: Content, resourceId: string, errorMessage: string) /** * 素材点击时回调 * @param content:展示的素材 * @param errorMessage:错误信息 * @param isClickUrl:是否跳转链接 */ mGMPResourceSDKInstance.getResourceAction().onResourceClick(content: Content, resourceId: string, errorMessage: string, isClickUrl: boolean) /** * 上报素材的展示停留时长 * @param content:展示的素材 * @param duration: 停留时长（单位是ms） */ mGMPResourceSDKInstance.getResourceAction().onStayDuration(content: Content, resourceId: string, duration: number) ``` # 五、自渲染方式接入算法资源位 ## 1. 简介算法资源位是通过算法推荐结合用户的行为偏好数据，实现个性化的资源位物料下发 ## 2. 算法资源位数据模型说明 * RecParams（请求算法资源位的参数） |**属性名** |**类型** |**含义** | |---|---|---| |recResourceId |string |算法资源位id | |spm |string |SPM(Super Position Model)全称超级位置模型，主要用于标识行为发生的位置。SPM位置编码由A/B/C/D四段构成，各分段分别代表 A:业务， B:页面， C:页面区块， D:区块内点位。段之间用$##$分隔，即A$##$B$##$C$##$D，spm各段建议传明文。某一段为空时直接传空字符串，如第二段为空，则传“A$##$$##$C$##$D”。|\ | | |1.业务：业务名称，如今日头条|\ | | |2.页面：如首页、发现页\-推荐等|\ | | |3.页面区块：如广告位、猜你喜欢|\ | | |4.区块内点位：在区块内的具体位置|\ | | |预期上同一个位置下不同的资源位对应的spm是一致的 | |contextItemId |string |算法资源位的推荐类型为相关推荐时，传入 RecContent 的 contentId | |contextItemType |string |算法资源位的推荐类型为相关推荐时，传入 RecContent 的 recContentType | |page |int |推荐列表页数（默认为0，轮播可以不传） | |extraParams | HashMap |扩展参数 | * RecResource（请求算法资源位的返回response） |**属性名** |**类型** |**含义** | |---|---|---| |key |string |资源位id | |resource_id |string |算法回流资源位id | |type |number |个性化资源位类型推荐列表/轮播 | |ab_sdk_version |string |ab实验版本 | |rec_material_list |RecContent[] |素材列表 | |trans_data |string |透传字段 | |gmp_trans_data |string |服务端透传拓展字段 | |recParams |RecParams |请求参数 | * RecContent |**属性名** |**类型** |**含义** | |---|---|---| |material_id |string |素材id | |type |string |素材类型 | |title |string |素材标题 | |customize_info |string |个性化参数 | :::tip 算法资源位的物料是通过后端提供的openAPI同步插入的 ::: ## 3. 请求算法资源位 ```TypeScript mGMPResourceSDKInstance.requestRecResourceData({ recResourceId: "recResourceId", spm: "spm", contextItemId: "contextItemId", contextItemType: "contextItemType", extraParams: extraParams, page: 0 }).then((data) => { this.response = JSON.stringify(data) }).catch((e:Error) => { this.response = e.message }) ``` ## 4. 算法资源位埋点上报同上述自渲染埋点上报 # 六、异常错误码 |**错误码** |**错误信息** |**错误原因** | |---|---|---| |400 |param empty |参数错误，请检查 sdk 是否正常初始化，是否存在参数漏出传 | |500 |Server error |服务器异常 | |100001 |network error |设备网络异常 | |100002 |json serializa error |Json 序列化异常 | |100003 |resource id empty |请求的资源位 id 为空 | |100004 |resource is empty |资源位数据为空，请检查资源位配置和资源位 id 是否正确 | |100005 |render error |资源位 sdk 渲染错误，不支持的渲染类型 | |100006 |authorization error |鉴权失败 | |200001 |resource expire |资源位过期资源位过期 | |200002 |resource download failed |资源位素材下载失败 |

增长营销平台