You need to enable JavaScript to run this app.
导航
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初始化参数

参数名参数类型说明
hoststring请求的资源位所处域名(GMP部署域名)
appidstringGMP 项目ID,获取方式见2.5
uuidstring用户唯一id,当出现登录/登出时需要及时更新
idTypestringid类型
onEventfunction事件上报函数,回调参数为(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

参数名参数类型说明
Keystring资源位id
CustomerMaterialListResourceItem[]素材列表

3.1.2 ResourceItem

参数名参数类型说明
ResourceIdstring对应资源位id
FrameIdstring帧位id
MaterialIdstring素材id
TypeResourceItemType素材类型
Textstring文本内容
ImageUrlstring图片下载链接
NavigateUrlstring跳转链接

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 参数说明

参数名参数类型说明
fontSizenumber字体大小,仅文本资源位生效
fontColorstring字体颜色,仅文本资源位生效
showPaginationboolean是否展示分页面器
autoScrollboolean是否自动轮播
autoScrollTimeIntervalboolean自动轮播间隔
backgroundSizestring图片填充模式
paginationColorActivestring定位符颜色(选中)
paginationColorNormalstring定位符颜色(未选中)
paginationWidthNormalnumber定位符宽度(未选中)
paginationHeightNormalnumber定位符高度(未选中)
paginationWidthActivenumber定位符宽度(选中)
paginationHeightActivenumber定位符高度(选中)
pageIndicatorSpacingnumber定位符边距
onLoadSuccessfunction资源位数据加载成功回调
onLoadFailedfunction资源位数据加载失败回调
onClickfunction点击回调,回调参数(item,index)其中item为3.1.2说明的ResourceItem类型,index为item在轮播图中对应的下标(从0开始)
onShowfunction曝光回调,回调参数(item,index)其中item为3.1.2说明的ResourceItem类型,index为item在轮播图中对应的下标(从0开始)

3.3.5 事件上报

以sdk渲染方式接入资源位,事件上报均由sdk侧进行,接入方无需进行额外的事件上报

4. 算法资源位接入

4.1 简介

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

4.2. 算法资源位数据模型说明

  • RecResource
属性名类型含义
keystring资源位id
rec_material_listResourceItem[]素材列表

type

RecResourceType(枚举)

算法资源位类型(BANNER:轮播 RECOMMENDED_LIST:推荐列表)

  • RecResourceItem
属性名类型含义
resourceIdstring资源位id
requestParamsRecRequestParams请求算法资源位参数
material_idstring素材id
frame_idstring帧位id
titlestring资源位素材标题,对应物料上传的item_title
resource_typestring资源位素材类型,对应物料上传的itemType
customize_infoJSONObject资源位素材数据,对应物料上传的json内容

resource_type

RecResourceType(枚举)

算法资源位类型(BANNER:轮播 RECOMMENDED_LIST:推荐列表)

resource_idstring资源位标识,用于算法回流
  • RecRequestParams(请求算法资源位的参数)
属性名类型含义
resourceIdstring算法资源位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是一致的

contextItemIdstring相关推荐素材id, 如1111
contextItemTypestring相关推荐素材类型, 如理财基金
pageint推荐列表页数(默认为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))
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