diandeng-ad
v1.0.1
Published
点灯AD广告交易平台客户端SDK
Readme
ADX SDK 接入文档
简介
ADX SDK 是广告交易平台的客户端SDK，支持H5、小程序、APP等多种媒体类型接入，提供广告请求、展示、点击、转化等完整功能。
快速开始
1. 引入SDK
H5页面
方式一：NPM 安装（推荐，适用于 Vue/React/Webpack/Vite 等）
npm install diandeng-adimport ADX from 'diandeng-ad'
// apiUrl 由构建时 sdk.config.js 注入，无需传入
const adx = new ADX({
appId: 'your-app-id',
appSecret: 'your-app-secret',
mediaId: 1
})
adx.loadAd('#ad-container', 'slot1abc123', { deviceInfo: { ... } })详细说明见 NPM_USAGE.md
方式二：Script 标签引入
<script src="https://your-domain.com/sdk/adx-sdk.min.js"></script>小程序（NPM 方式）
# 1. 在项目根目录安装
npm install diandeng-ad
# 2. 微信开发者工具: 工具 -> 构建 npmconst ADX = require('diandeng-ad')2. 初始化SDK
基础配置（仅自有广告）
// apiUrl 由构建时配置注入，默认 https://s.jifenshop.cn/api
const adx = new ADX({
appId: 'your-app-id', // 从后台获取的AppID
appSecret: 'your-app-secret', // 从后台获取的AppSecret
mediaId: 1, // 媒体ID
slotId: 'slot1abc123' // 广告位ID
})启用第三方广告（优量汇）
SDK会自动从后端获取第三方广告配置，无需手动配置。只需在后台管理界面配置第三方广告源即可。
const adx = new ADX({
appId: 'your-app-id',
appSecret: 'your-app-secret',
mediaId: 1,
slotId: 'slot1abc123',
fallbackToThirdParty: true // 默认启用第三方广告fallback
})第三方广告支持：
- SDK会自动从后端获取第三方广告配置，无需手动配置
- 第三方广告配置在后台管理界面进行管理（"第三方广告源"菜单）
- 如果后端没有配置第三方广告源，SDK会自动fallback到自有广告
- 第三方广告由第三方SDK负责渲染，SDK在事件回调中自动上报展示和点击
- 支持的第三方广告源：优量汇、穿山甲（穿山甲适配器待实现）
3. 加载并渲染广告（推荐方式）
最简单的接入方式，SDK会自动处理请求、渲染和上报：
// 使用loadAd方法，需要传入广告位ID
adx.loadAd('#ad-container', 'slot1abc123', {
deviceInfo: {
platform: 'web', // 平台：web, ios, android
os: 'windows', // 操作系统
deviceId: 'device123', // 设备ID
region: '北京', // 地区（可选）
city: '北京' // 城市（可选）
}
}).then(ad => {
if (ad) {
console.log('广告加载成功:', ad.title)
// SDK已自动渲染并上报展示
} else {
console.log('暂无可用广告')
}
}).catch(err => {
console.error('加载失败:', err)
})4. 手动请求和渲染（高级用法）
如果需要更精细的控制，可以分别调用：
// 请求广告（需要传入广告位ID）
adx.requestAd('slot1abc123', {
deviceInfo: {
platform: 'web',
os: navigator.platform,
deviceId: getDeviceId()
}
}).then(ad => {
if (ad) {
// 手动渲染
adx.renderAd(ad, '#ad-container')
}
})5. 上报展示和点击
注意：使用 loadAd 方法时，展示和点击会自动处理，无需手动调用。
如果需要手动控制，可以调用：
// 广告展示后调用
adx.reportImpression(impressionId)
// 用户点击广告时调用
adx.reportClick(impressionId).then(() => {
// 跳转到落地页
window.open(ad.landingUrl)
})6. 上报转化
// 用户完成转化行为时调用
adx.reportConversion(clickId, {
conversionType: 'purchase', // 转化类型：register, purchase, download, other
conversionValue: 99.00 // 转化价值（可选）
})API参考
构造函数
new ADX(options)参数：
options.apiUrl(string, 可选): API服务器地址，不传则使用构建时配置（sdk.config.js）options.appId(string, 必需): AppIDoptions.appSecret(string, 必需): AppSecretoptions.mediaId(number, 必需): 媒体IDoptions.slotId(string, 必需): 广告位ID
requestAd(options)
请求广告
参数：
options.deviceInfo(object): 设备信息platform(string): 平台类型（web/ios/android）os(string): 操作系统deviceId(string): 设备IDregion(string, 可选): 地区city(string, 可选): 城市
options.userInfo(object, 可选): 用户信息age(number, 可选): 年龄gender(string, 可选): 性别（male/female）
返回： Promise<AdObject | null>
AdObject结构：
{
id: 1, // 广告ID
title: '广告标题', // 广告标题
description: '广告描述', // 广告描述
adType: 'image', // 广告类型：image, video, banner, feed
materialUrl: '...', // 素材URL
landingUrl: '...', // 落地页URL
width: 320, // 宽度
height: 50, // 高度
impressionId: '...' // 展示ID（用于上报）
}reportImpression(impressionId)
上报广告展示
参数：
impressionId(string): 展示ID（从requestAd返回）
返回： Promise
reportClick(impressionId)
上报广告点击
参数：
impressionId(string): 展示ID
返回： Promise - 返回点击ID（用于上报转化）
reportConversion(clickId, options)
上报转化
参数：
clickId(string): 点击ID（从reportClick返回）options(object): 转化信息conversionType(string): 转化类型（register/purchase/download/other）conversionValue(number, 可选): 转化价值
返回： Promise
完整示例
H5示例（推荐方式）
最简单的接入方式，SDK自动处理渲染和上报：
<!DOCTYPE html>
<html>
<head>
<title>ADX SDK示例</title>
</head>
<body>
<div id="ad-container"></div>
<script src="https://your-domain.com/sdk/adx-sdk.min.js"></script>
<script>
// 初始化SDK（apiUrl 由构建时配置注入）
const adx = new ADX({
appId: 'your-app-id',
appSecret: 'your-app-secret',
mediaId: 1
})
// 加载并渲染广告（SDK自动处理渲染和上报）
adx.loadAd('#ad-container', 'slot1abc123', {
deviceInfo: {
platform: 'web',
os: navigator.platform,
deviceId: getDeviceId()
}
}).then(ad => {
if (ad) {
console.log('广告加载成功:', ad.title)
// SDK已自动渲染并上报展示
} else {
console.log('暂无可用广告')
}
}).catch(err => {
console.error('加载失败:', err.message)
})
function getDeviceId() {
let deviceId = localStorage.getItem('adx_device_id')
if (!deviceId) {
deviceId = 'device_' + Math.random().toString(36).substr(2, 9)
localStorage.setItem('adx_device_id', deviceId)
}
return deviceId
}
</script>
</body>
</html>小程序示例（NPM 方式）
npm install diandeng-ad
# 微信开发者工具: 工具 -> 构建 npm// app.js
const ADX = require('diandeng-ad')
App({
onLaunch() {
this.adx = new ADX({
appId: 'your-app-id',
appSecret: 'your-app-secret',
mediaId: 1
})
}
})
// pages/index/index.js
const app = getApp()
Page({
data: {
ad: null
},
onLoad() {
this.loadAd()
},
loadAd() {
const slotId = 'slot1abc123' // 广告位ID，从后台获取
// 小程序环境，需要手动处理渲染
app.adx.requestAd(slotId, {
deviceInfo: {
platform: 'miniprogram',
os: 'wechat',
deviceId: app.getDeviceId()
}
}).then(ad => {
if (ad) {
if (ad.source === 'ylh') {
// 第三方广告：返回ad组件配置
this.setData({
adConfig: {
unitId: ad.adUnitId,
appId: ad.appId
}
})
// 第三方广告的展示和点击由ad组件自动处理
} else {
// 自有广告：需要手动渲染
this.setData({
ad: ad
})
// 上报展示
app.adx.reportImpression(ad.impressionId)
}
}
})
},
onAdClick() {
const ad = this.data.ad
if (ad) {
app.adx.reportClick(ad.impressionId).then(() => {
wx.navigateTo({
url: `/pages/webview/index?url=${encodeURIComponent(ad.landingUrl)}`
})
})
}
}
})错误处理
SDK会在以下情况抛出错误：
- 网络错误：请求失败时会抛出错误
- 参数错误：必填参数缺失时抛出错误
- 认证错误：AppID或AppSecret错误时抛出错误
建议使用 try-catch 或 Promise.catch 处理错误：
adx.requestAd(options).catch(err => {
console.error('请求广告失败:', err.message)
// 处理错误，例如显示默认内容
})注意事项
- 设备ID: 建议使用持久化的设备ID，避免频繁变化影响频次控制
- 展示上报: 广告真正展示给用户后再调用
reportImpression - 点击上报: 用户实际点击广告时再调用
reportClick - 转化上报: 在用户完成转化行为时调用
reportConversion - 错误处理: 建议实现错误重试机制，提高广告填充率
技术支持
如有问题，请联系技术支持或查看文档：https://your-docs-domain.com