优聚智汇

简体中文

English

简体中文

English

外观

H5 SDK 准备工作 ​

概述 ​

优聚智汇 H5 广告 SDK（@uju/adx-h5-sdk）是一个面向 Web 应用的轻量化广告聚合 SDK，基于 ADX 协议实现广告请求、渲染与事件上报。SDK 运行时零依赖，支持现代浏览器环境。

当前版本：v0.1.0（内部预览版） SDK 源码位于 h5/src/，构建产物为 UMD + ESM 双格式。

环境要求 ​

浏览器支持 ​

  • Chrome 90+ / Edge 90+ / Firefox 88+ / Safari 14+
  • 支持移动端浏览器（iOS Safari 14+ / Android Chrome 90+）
  • 需支持 IntersectionObserver、MutationObserver、navigator.sendBeacon
  • 部署环境须为 HTTPS（部分浏览器 API 在 HTTP 环境下不可用）

开发环境 ​

  • Node.js 16+（仅在使用 npm 集成方式时需要）
  • TypeScript 5.0+（可选，用于类型提示）

获取凭证 ​

在开始集成前，请在 优聚智汇开发者后台 创建应用并获取以下凭证：

凭证说明是否必填
appId应用 ID，用于标识你的 H5 应用✅ 必填
adEndpoint广告请求服务地址，由后台分配✅ 必填
accessKeyADX 协议访问密钥，用于请求签名✅ ADX 协议必填
secretKeyADX 协议加密密钥，用于请求体加密✅ ADX 协议必填
keyEndpoint会话密钥交换地址，用于动态密钥协商❌ 可选（会话密钥模式必填）
reportEndpoint事件上报地址，用于曝光/点击/错误上报❌ 可选（默认使用广告返回的 trackers）

集成方式 ​

H5 SDK 提供两种集成方式，可根据项目架构选择。

方式一：npm 安装（推荐） ​

适用于基于构建工具（Webpack / Vite / Rollup 等）的工程项目。

bash
# 安装 SDK 依赖（包名为 @uju/adx-h5-sdk）
npm install @uju/adx-h5-sdk

在代码中引入：

javascript
// 引入 UjuAdSdk 单例（ESM 方式）
import { UjuAdSdk } from "@uju/adx-h5-sdk";

// 如果使用 TypeScript，可引入类型定义
import type { SdkConfig, AdCreateOptions } from "@uju/adx-h5-sdk";

优势：

  • 支持 Tree-shaking 与类型提示
  • 构建产物可与其他资源打包优化
  • 版本管理通过 package-lock.json 锁定

方式二：script 标签引入 ​

适用于纯静态页面或无构建工具的项目。

html
<!DOCTYPE html>
<html>
<head>
  <!-- 引入 UMD 格式 SDK，全局变量名为 UjuAdSdk -->
  <script src="https://your-cdn-host/ad-sdk.umd.js"></script>
</head>
<body>
  <script>
    // UMD 引入后，SDK 挂载到 window.UjuAdSdk
    const { UjuAdSdk } = window;
    // 后续可调用 UjuAdSdk.init() / UjuAdSdk.createAd() 等
  </script>
</body>
</html>

说明：

  • UMD 全局变量名为 UjuAdSdk（注意大小写）
  • 构建产物文件：ad-sdk.umd.js（UMD）、ad-sdk.esm.js（ESM）、index.d.ts（类型定义）
  • 请将 SDK 文件托管至你自己的 CDN 或静态资源服务器

版本信息 ​

项目值
包名@uju/adx-h5-sdk
当前版本0.1.0
协议版本3.3.0（ADX 协议）
运行时依赖无（零依赖）
构建工具Rollup 4.x
类型支持TypeScript 5.x

下一步 ​

完成 SDK 引入后，请阅读 H5 集成说明 了解完整的初始化与广告创建流程。

技术支持 ​

如在准备工作遇到问题，请联系：