TeleAds SDK

一个轻量级的广告展示和数据分析 SDK。

安装

bash npm install teleads-sdk

使用方法

1. 初始化

javascript import { Analytics, Ads } from 'teleads-sdk'; // 初始化广告模块 const adInstance = Ads.Display.create({ userId: 'user_123', // 必填，用户唯一标识 platform: 'web', // 可选，平台标识 isPremium: false // 可选，是否为付费用户 }); // 初始化分析模块 await Analytics.loadUmami('your-website-id');

2. 广告位管理

javascript // 添加广告位 adInstance.addDid([ { html: '#ad-container', // DOM 选择器或 HTMLElement placeCode: 'ad_001', // 广告位唯一标识 type: 'banner', // 广告类型：mount/banner/insert mediaType: 'image', // 媒体类型：image/video loop: true, // 是否循环播放 autoPull: true, // 是否自动拉取广告 zIndex: 100, // 广告层级 // 事件回调 onStart: () => console.log('广告开始播放'), onOver: () => console.log('广告播放结束'), onClose: () => console.log('广告被关闭'), onError: (err) => console.error('广告错误', err), onClick: () => console.log('广告被点击'), } ]); // 删除广告位 adInstance.deleteDid('ad_001'); // 获取广告位实例 const ad = adInstance.getDid('ad_001'); // 获取所有广告位 const allAds = adInstance.getAllDid();

3. 数据分析

javascript // 追踪事件 Analytics.track('button_click', { buttonId: 'submit', page: '/home' }); // 设置用户属性 Analytics.identify({ userId: 'user_123', userType: 'premium' }); javascript // 追踪事件 Analytics.track('button_click', { buttonId: 'submit', page: '/home' }); // 设置用户属性 Analytics.identify({ userId: 'user_123', userType: 'premium' });

参数说明

广告位配置

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | html | string/HTMLElement | 是 | 广告容器 | | placeCode | string | 是 | 广告位唯一标识 | | type | string | 否 | 广告类型(mount/banner/insert) | | mediaType | string | 否 | 媒体类型(image/video) | | loop | boolean | 否 | 是否循环播放 | | autoPull | boolean | 否 | 是否自动拉取广告 | | zIndex | number | 否 | 广告层级 |

事件回调

| 事件名 | 触发时机 | |--------|----------| | onStart | 广告开始播放 | | onOver | 广告播放结束 | | onClose | 广告被关闭 | | onError | 广告发生错误 | | onClick | 广告被点击 | | onPull | 广告拉取完成 |

注意事项

1. 广告容器相关：

   • 确保容器元素存在且具有明确的宽高
   • 容器的 position 属性会影响广告展示
   • zIndex 设置需要考虑页面其他元素层级

2. 广告拉取：

   • autoPull 为 true 时会自动拉取广告
   • 广告拉取失败会自动重试 5 次
   • 建议处理 onError 回调避免异常

3. 事件追踪：

   • track 方法在 umami 初始化前调用无效
   • 事件数据建议使用扁平化结构
   • 避免传递敏感信息

4. 性能优化：

   • 不建议同时展示过多广告位
   • 可以通过 loop 控制广告循环播放
   • 及时清理不需要的广告位

浏览器兼容性

• Chrome >= 60
• Firefox >= 60
• Safari >= 12
• Edge >= 79

错误码说明

| 错误码 | 说明 | |--------|------| | 1 | API key 缺失 | | 2 | autoPull 参数类型错误 | | 401 | 请求认证失败 |

技术支持

如有问题请提交 Issue 或联系技术支持。

License

MIT