接入 GMP H5 资源位功能，需要在每个需要使用该功能的页面上引入 GMP 的资源位 SDK 文件，并且进行初始化配置。
| 版本 | 说明 |
|---|---|
| https://unpkg.com/gmp-resource-sdk@0.0.2-alpha.17/dist/gmp-resource-sdk.js | 初始版本 |
在页面中引入以下 js 文件：
<script src="最新版本的js文件见版本记录"></script>
本节将引导接入方正确接入资源位H5 SDK
2.1 Uba引入
H5 SDK依赖于uba用于获取用户信息及人群圈选功能，但SDK不强依赖于特定的Uba，接入方可根据实际的业务场景接入Uba并获取对应的参数传入SDK初始化。（推荐接入FinderSDK的H5版本Web JS SDK 集成 增长分析-火山引擎）
2.2 SDK初始化
接入方可以在需要用到资源位的页面实例化SDK并进行初始化配置
// 接入方需要自行维护该实例并在 const sdk = new GmpResourceSDK({ host: '', appid: 123,//该项为number uuid: '', idType: '', onEvent: , webId:'', });
2.3 SDK初始化参数
| 参数名 | 参数类型 | 说明 |
|---|---|---|
| host | string | 请求的资源位所处域名（GMP部署域名） |
| appid | string | GMP 项目ID，获取方式见2.5 |
| uuid | string | 用户唯一id，当出现登录/登出时需要及时更新 |
| idType | string | id类型 |
| onEvent | function | 事件上报函数，回调参数为(eventName, eventParams),当以SDK渲染的方式接入H5资源位时必须传入，sdk内部会回调该方法来调用您的uba事件上报方法进行事件上报 |
export interface SDKOptions { /** 服务器Host */ host: string; /** 项目 id */ appid: number; /** 用户 id */ uuid: string; /** 设备id */ webId: string; /** id 类型 */ idType: string; /** 事件回调 */ onEvent?: (eventName: string, params: {[key: string]: any}) => void }
2.4 更新用户状态
SDK内部需要获取最新的用户状态来进行人群圈选，使得不同用户能够看到不同的资源位素材，因此接入方需要在用户登录态/id发生变化时通知SDK：
/** * 接口信息 * 更新 id * @param uuid id * @param idType id 类型 */ update(uuid?: string, idType?: string) // 调用示例 sdk.update("new_uuid", "new_id_type")
2.5 获取项目ID和应用id
在gmp首页，点击右上角头像-项目管理，即可进入项目后台页查看对应项目的项目id和应用id（项目id是初始化弹窗sdk的appid，应用id是用于初始化Finder SDK的appid）
2.6 跨域信息配置
当您的H5页与配置的资源位所处域名不在同一个域名下时，您需要在GMP服务端的配置文件中写入H5页的地址信息来解决可能存在的跨域问题(具体配置方式可联系部署同学)。
H5 SDK请求资源位分为自渲染及SDK渲染两种方式。
3.1 资源位数据模型
3.1.1 ResourceData
| 参数名 | 参数类型 | 说明 |
|---|---|---|
| Key | string | 资源位id |
| CustomerMaterialList | ResourceItem[] | 素材列表 |
3.1.2 ResourceItem
| 参数名 | 参数类型 | 说明 |
|---|---|---|
| ResourceId | string | 对应资源位id |
| FrameId | string | 帧位id |
| MaterialId | string | 素材id |
| Type | ResourceItemType | 素材类型 |
| Text | string | 文本内容 |
| ImageUrl | string | 图片下载链接 |
| NavigateUrl | string | 跳转链接 |
3.1.3 ResourceItemType
| 类型名 | 说明 |
|---|---|
| text | 文本 |
| image | 图片 |
3.2 自渲染请求资源位
sdk.getResourceList([resource_id_1, resource_id_2]).then((resourceList) => { // 根据返回的资源位列表进行自渲染工作 // 回调中的resourceList为ResourceData[]类型，详见资源位数据模型3.1.1 }
3.2.1 事件上报
GMP主要消费资源位素材的曝光和点击事件，当发生资源位素材的曝光和点击时，接入方需要根据自己接入的uba上报到对应的uba域名下（具体方式可与部署同学沟通），下面以接入Finder的情况为例展示事件上报及对应属性
以下为通用参数的拼接与事件上报的示例，完整资源位埋点参数说明可见资源位预置埋点说明
// 拼接规则资源位参数方法 onParams(resourceItem) { const params = { "content_id": resourceItem.MaterialId, "item_id": resourceItem.FrameId, "banner_id": resourceItem.ResourceId, "app_id": appId, "business": "resource", "platform_type": "web", }; return params; } // 事件上报 window.collectEvent("事件名", onParams(resourceItem))
3.3 SDK渲染资源位
sdk渲染目前仅支持轮播类型，接入方可根据下列方式进行接入：
3.3.1 页面引入
<!DOCTYPE html> <html lang="en"> <head> ... </head> <body> <div class="resource_container"></div> <!-- 承载资源位的父布局class可自定义，只需要与后续请求的参数对应上即可 --> </body>
3.3.2 发送资源位请求
// 这里的".resource_container"需要与3.3.1中页面引入的父布局class一致 let resourceView = sdk.createResourceView('.resource_container', { showPagination: true, autoScroll: true, autoScrollTimeInterval: 3, backgroundSize: "cover", onClick: function(item, index) { //点击回调 item为素材数据类型 index为被点击的素材下标 }, onShow: function(item, index) { //曝光回调 item为素材数据类型 index为被曝光的素材下标 }, }); resourceView.loadResource(resourceId);
3.3.3 容器css设置
/* 配置容器属性 */ .resource_container { width: 100%; height: 180px; /* 其余属性任意，宽高属性至少指定一个，以便资源位能够正确展示 */ }
3.3.4 参数说明
| 参数名 | 参数类型 | 说明 |
|---|---|---|
| fontSize | number | 字体大小，仅文本资源位生效 |
| fontColor | string | 字体颜色，仅文本资源位生效 |
| showPagination | boolean | 是否展示分页面器 |
| autoScroll | boolean | 是否自动轮播 |
| autoScrollTimeInterval | boolean | 自动轮播间隔 |
| backgroundSize | string | 图片填充模式 |
| paginationColorActive | string | 定位符颜色（选中） |
| paginationColorNormal | string | 定位符颜色（未选中） |
| paginationWidthNormal | number | 定位符宽度（未选中） |
| paginationHeightNormal | number | 定位符高度（未选中） |
| paginationWidthActive | number | 定位符宽度（选中） |
| paginationHeightActive | number | 定位符高度（选中） |
| pageIndicatorSpacing | number | 定位符边距 |
| onLoadSuccess | function | 资源位数据加载成功回调 |
| onLoadFailed | function | 资源位数据加载失败回调 |
| onClick | function | 点击回调，回调参数(item,index)其中item为3.1.2说明的ResourceItem类型，index为item在轮播图中对应的下标(从0开始) |
| onShow | function | 曝光回调，回调参数(item,index)其中item为3.1.2说明的ResourceItem类型，index为item在轮播图中对应的下标(从0开始) |
3.3.5 事件上报
以sdk渲染方式接入资源位，事件上报均由sdk侧进行，接入方无需进行额外的事件上报
4.1 简介
算法资源位是通过算法推荐结合用户的行为偏好数据，实现个性化的资源位物料下发
4.2. 算法资源位数据模型说明
- RecResource
| 属性名 | 类型 | 含义 |
|---|---|---|
| key | string | 资源位id |
| rec_material_list | ResourceItem[] | 素材列表 |
type | RecResourceType(枚举) | 算法资源位类型(BANNER:轮播 RECOMMENDED_LIST:推荐列表) |
- RecResourceItem
| 属性名 | 类型 | 含义 |
|---|---|---|
| resourceId | string | 资源位id |
| requestParams | RecRequestParams | 请求算法资源位参数 |
| material_id | string | 素材id |
| frame_id | string | 帧位id |
| title | string | 资源位素材标题，对应物料上传的item_title |
| resource_type | string | 资源位素材类型，对应物料上传的itemType |
| customize_info | JSONObject | 资源位素材数据，对应物料上传的json内容 |
resource_type | RecResourceType(枚举) | 算法资源位类型(BANNER:轮播 RECOMMENDED_LIST:推荐列表) |
| resource_id | string | 资源位标识，用于算法回流 |
- RecRequestParams（请求算法资源位的参数）
| 属性名 | 类型 | 含义 |
|---|---|---|
| resourceId | 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”。 |
| contextItemId | string | 相关推荐素材id, 如1111 |
| contextItemType | string | 相关推荐素材类型, 如理财基金 |
| page | int | 推荐列表页数（默认为0，轮播可以不传） |
4.3 请求算法资源位数据
- 创建资源位参数
const recParams = { resourceId: "123", contextItemId: "12", contextItemType: "", spm: "123", page: "1" }
- 发起资源位请求
const data = sdk.getRecResource(recParams);
4.4 事件上报
GMP主要消费资源位素材的曝光和点击事件，当发生资源位素材的曝光和点击时，接入方需要根据自己接入的uba上报到对应的uba域名下（具体方式可与部署同学沟通），下面以接入Finder的情况为例展示事件上报及对应属性
以下为通用参数的拼接与事件上报的示例，完整资源位埋点参数说明可见资源位预置埋点说明
// 拼接算法回流参数方法 onRecParams(recResourceItem) { const params = { content_id: recResourceItem.material_id, resource_id: recResourceItem.bizId, resource_type: 1, spm: recResourceItem.requestParams.spm, trans_data: recResourceItem.requestParams.trans_data, banner_id: recResourceItem.resource_id, context_item_id: recResourceItem.contextItemId, context_item_type: recResourceItem.contextItemType, business: 'resource', app_id: this.appId, platform_type: 'web', rec_resource_type: recResourceItem.resource_type, }; if (recResourceItem.resource_type == 1) { params.item_id = recResourceItem.frame_id; } return params; } // 事件上报 window.collectEvent("事件名", onParams(recResourceItem))
是否在需要使用资源位的页面正确接入H5 SDK并完成初始化配置
如需使用数据洞察 是否正确接入uba并在对应时机上报埋点
使用SDK渲染功能时是否在对应页面下引入父容器，父容器是否指定宽/高，父容器的class是否与请求资源位中传入的一致
查看网络请求确认接口请求是否正常，返回内容是否存在素材
请求资源位使用的id是否与对应资源位圈选的人群一致
6.1 SDK渲染出错
在SDK渲染时出现下列错误
Uncaught (in promise) TypeError: Cannot read properties of null (reading 'hasChildNodes')
这是因为在发起资源位请求中设置的容器无法找到，请检查是否在对应页面正确引入了一个用于承载资源位的父容器
6.2 SDK渲染图片未显示
按照下列步骤检查：
查看日志是否有报错提示，如有报错提示则根据提示进行修改
查看网络请求，确认请求是否成功，并且该请求是否有素材下发
在GMP检查对应资源位是否配置素材，如果配置了但没有下发检查发送请求的id是否命中了创建资源位时指定的人群，如无则推荐更换id后重试/配置兜底素材
检查是否在css中正确指定父容器的宽/高，不能指定auto