文档中心

H5 SDK集成

最近更新时间：2022.11.28 11:27:28

首次发布时间：2022.10.10 10:43:43

接入 GMP H5 资源位功能，需要在每个需要使用该功能的页面上引入 GMP 的资源位 SDK 文件，并且进行初始化配置。

版本记录

版本	说明
https://unpkg.com/gmp-resource-sdk@0.0.2-alpha.17/dist/gmp-resource-sdk.js	初始版本

1. 引入 SDK

在页面中引入以下 js 文件：

<script src="最新版本的js文件见版本记录"></script>

2. 初始化配置

本节将引导接入方正确接入资源位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页的地址信息来解决可能存在的跨域问题(具体配置方式可联系部署同学)。

3. 请求资源位

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. 算法资源位接入

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”。 1.业务：业务名称，如今日头条 2.页面：如首页、发现页-推荐等 3.页面区块：如广告位、猜你喜欢 4.区块内点位：在区块内的具体位置预期上同一个位置下不同的资源位对应的spm是一致的
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 事件上报

// 拼接算法回流参数方法
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))

5. 接入方CheckList

是否在需要使用资源位的页面正确接入H5 SDK并完成初始化配置
如需使用数据洞察是否正确接入uba并在对应时机上报埋点
使用SDK渲染功能时是否在对应页面下引入父容器，父容器是否指定宽/高，父容器的class是否与请求资源位中传入的一致
查看网络请求确认接口请求是否正常，返回内容是否存在素材
请求资源位使用的id是否与对应资源位圈选的人群一致

6. 常见问题

6.1 SDK渲染出错

在SDK渲染时出现下列错误

Uncaught (in promise) TypeError: Cannot read properties of null (reading 'hasChildNodes')

这是因为在发起资源位请求中设置的容器无法找到，请检查是否在对应页面正确引入了一个用于承载资源位的父容器

6.2 SDK渲染图片未显示

按照下列步骤检查：

查看日志是否有报错提示，如有报错提示则根据提示进行修改
查看网络请求，确认请求是否成功，并且该请求是否有素材下发
在GMP检查对应资源位是否配置素材，如果配置了但没有下发检查发送请求的id是否命中了创建资源位时指定的人群，如无则推荐更换id后重试/配置兜底素材
检查是否在css中正确指定父容器的宽/高，不能指定auto

增长营销平台