@coolita-os/google-ima-js-sdk
v1.3.1
Published
A library for coolita os loading the Google IMA SDK with static typing for the SDK
Keywords
Readme
google-ima-js-sdk
Coolita OS ima js sdk插件库
安装
yarn add @coolita-os/google-ima-js-sdk or npm install --save @coolita-os/google-ima-js-sdk
使用
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" href="/favicon.ico" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport"
content="width=device-width, initial-scale=1.0, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="pragma" content="no-cache" />
<meta http-equiv="Cache-Control" content="no-cache, must-revalidate" />
<!-- 1.3.1版本后改为的自研SDK，不用引入官方SDK -->
<!-- <script type="text/javascript" src="https://imasdk.googleapis.com/js/sdkloader/ima3.js" async></script> -->
<title>google-ima-js-sdk</title>
</head>
<body>
<div id="app"></div>
</body>
</html>2、在需要插入广告的节点添加广告节点元素和样式控制
<div class="ad-ui" style="opacity: 0" id="ad-ui"></div>
<div class="ad-player-wrap">
<video
style="display: none;"
class="ad-video"
id="ad-video">
</video>
<div class="ad-container" id="ad-container"></div>
</div> .ad-player-wrap {
width: 100%;
height: 100%;
position: relative;
}
.ad-video,
.ad-container {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
}
.ad-video {
width: 100%;
height: 100%;
object-fit: cover; // 保持原有尺寸比例。但部分内容可能被剪切。
}二、JavaScript/TypeScript 调用实现部分
1、创建广告播放器实例并添加相关的数据添加事件
import ImaAdPlayer from '@coolita-os/google-ima-js-sdk'
// 创建广告播放器实例，内部实现自动调用requestAd()发起广告请求等其他逻辑
let imaAdPlayerInstance = new ImaAdPlayer({
adVideoElement: document.getElementById('ad-video'), // 广告节点元素
contentElement: null, // 内容推荐位节点元素video/div，没有传null
adContainerElement: document.getElementById('ad-container'), // 广告UI容器元素
adUIElement: document.getElementById('ad-ui'), // 广告UI元素/没有传null
adTagUrl: '', // 广告请求tagUrl
bitrate: 300, // 广告比特率
muted: true, // 是否静音，默认静音
observeVideoSize: true, // 是否监听视频窗口大小变化做处理
instanceApi: { // 实例需要实现的所有回调函数
onLoad: (ad) => { // 请求后有广告返回
},
onContentPauseRequested: () => {
// 正片是video，触发了暂停请求
},
onImpression: () => {
// 开始曝光
},
onStarted: () => {
// 即将开始播放
},
onFirstQuartile: () => {
// 播放了1/4
},
onMidpoint: () => {
// 播放了1/2
},
onThirdQuartile: () => {
// 播放了3/4
},
onComplete: () => {
// 广告100%播放完成，有多个广告将播放下一个，并再次触发onLoad
},
onSkipStateChange: () => {
// 广告播放过程中，返回可跳过状态
},
onAllAdsCompleted: () => {
// 所有广告播放完成
imaAdPlayerInstance.handlePlayAdComplete() // 内部执行实例定义重置
},
onClick: () => {
// 广告触发了点击
},
onAdProgress: (adEvent) => {
// 广告发生进度更新，可以得到当前广告的进度数据、时间等信息
},
onAdErrorEvent: (errorData) => {
// 广告发生异常，内部已经做了自动处理异常
// 正片是图片或者页面跳转等其他逻辑的话要自己在下面处理
}
}
})
2、销毁广告播放器实例
imaAdPlayerInstance.destroy()3、循环播放广告，可直接使用当前实例再次发起广告请求
imaAdPlayerInstance.requestAd()4、监听到所有广告播放完成
onAllAdsCompleted: () => {
// 所有广告播放完成
imaAdPlayerInstance.handlePlayAdComplete() // 内部执行实例定义重置
}5、跳过广告
imaAdPlayerInstance.skipAd()6、暂停广告播放
imaAdPlayerInstance.pauseAd()7、 恢复广告播放
imaAdPlayerInstance.resumeAd()8、控制广告播放器是否静音
imaAdPlayerInstance.handlePlayerIsMuted(isMute: boolean)三、埋点实现相关接口
1、谷歌广告/系统广告埋点公共接口部分，data为埋点上报的所有参数，sendParams为发送参数自定义的方法
import {
setAdSkipBuried,
setAdPercentBuried,
setAdClickBuried,
setAdErrorBuried,
setAdRequestBuried,
setAdResponseBuried,
setAdDownloadBuried
} from '@coolita-os/google-ima-js-sdk'
setAdSkipBuried(data: any, sendParams: Function): void // 按back键/home键跳过
setAdPercentBuried(data: any, sendParams: Function): void // 广告播放进度
setAdClickBuried(data: any, sendParams: Function): void // 广告点击
setAdErrorBuried(data: any, sendParams: Function): void // 广告播放异常
setAdRequestBuried(data: any, sendParams: Function): void // 发起广告请求
setAdResponseBuried(data: any, sendParams: Function): void // 接收到广告平台返回信息
setAdDownloadBuried(data: any, sendParams: Function): void // 接收到广告完成下载，即将开始播放2、仅谷歌广告可使用的埋点公共接口部分，data为埋点上报的所有参数，sendParams为发送参数定义的方法
-- 参数传递说明：
const currentAdParams: object = { // 如下为必须包含的参数
adType: string // 广告类型
eventId: string | number // 广告事件唯一id
strategyId: string | number, //广告策略id
strategyName: string, // 广告策略名称
positionId: string | number, // 【首页】广告id
positionPid: string, // 【首页】广告位置
adServer: string | number// 广告请求方：1：Google，2：Spring Serve
}
const currTabData: object = { // 如下为必须包含的参数，目前仅使用page_id
page_id: string | number // 版面id
}
const adData: object // 谷歌广告返回的响应的整个数据结构
const sendParams: // 发送埋点数据时，自己定义的上报方法
const schedule: number // 上报的播放进度值，如：25
const code: any // 广告请求返回的错误码， 如：303、400
const mode: string | number // 静音:Mute; 取消静音:Unmute;音量+键:Volume+; 音量-键:Volume-
-- 埋点上报接口使用&&传参：
import {
setGoogleAdRequestBuried,
setGoogleAdResponseBuried,
setGoogleAdDownloadBuried,
setGoogleAdPercentBuried,
setGoogleAdClickBuried,
setGoogleAdErrorBuried,
setGoogleAdSkipBuried,
setGoogleAdUnmuteBuried
} from '@coolita-os/google-ima-js-sdk'
setGoogleAdRequestBuried({
currentAdParams
}, sendParams: Function): void // 发起广告请求，内部直接调用setAdRequestBuried
setGoogleAdResponseBuried({
currentAdParams,
adData
}, sendParams: Function): void // 谷歌广告返回的响应数据，内部直接调用setAdResponseBuried
setGoogleAdDownloadBuried({
currentAdParams,
adData
}, sendParams: Function): void // 谷歌广告完成下载，内部直接调用setAdDownloadBuried
setGoogleAdPercentBuried({
currentAd,
adData,
currentAdParams,
currTabData
},
schedule: number,
sendParams: Function): void // 谷歌广告进度数据上报，通过传过来的sendParams发送进度数据
setGoogleAdClickBuried({
currentAdParams,
adData
}, sendParams: Function): void // 谷歌广告点击，内部直接调用setAdClickBuried
setGoogleAdErrorBuried({
adData,
currentAdParams
},
code: any,
sendParams: Function): void // 谷歌广告发生异常，内部直接调用setAdErrorBuried
setGoogleAdSkipBuried({
adData,
currentAdParams
}, sendParams: Function): void
setGoogleAdUnmuteBuried({// 按静音键或音量+-键控制，广告是否静音
adData,
currentAdParams,
mode
}: any, sendParams: Function): void // 按静音键或音量+-键，通过传过来的sendParams发送埋点数据四、谷歌广告内存控制器使用
import { googleAdMemoryManager } from '@coolita-os/google-ima-js-sdk'
const initIMA: Function // 广告初始化的方法
const adParams: {} // 广告相关的参数
const adTypeStr: '' // 广告类型自定义字符串，主要用于打印过滤数据，如：recommendAds
const deinitIMA: Function // 卸载广告的方法
const handleReplayAd: Function // 广告执行轮询请求的方法
// 第一次请求广告时调用initIMA判断内存是否充足，内存充足返回true，内存不足自动5s执行一次initIMA
googleAdMemoryManager.createInitIMATimer(initIMA, adParams, adTypeStr): boolean
// 广告请求成功后，每隔5s查询一次内存数据，当查询了5次内存不足后，调用传入的deinitIMA，强制刷新页面URL，释放内存
googleAdMemoryManager.createQueryMemoryTimer(deinitIMA, adTypeStr): void
// 广告轮询，每次请求的所有广告播放结束，再次判断内存释放充足，内存不足自动5s执行一次
googleAdMemoryManager.createReplayAdTimer(handleReplayAd, adTypeStr): void
// 清除广告轮询定时器
googleAdMemoryManager.clearReplayAdTimer(): void
// 清除每隔5s查询一次内存数据
googleAdMemoryManager.clearQueryMemoryTimer(): void
// 清除第一次请求广告的定时器
googleAdMemoryManager.clearInitIMATimer(): void
// 清除所有定时器
googleAdMemoryManager.clearAllTimer(): voidSDK暴露可以使用的相关工具
import { utilsBySDK } from '@coolita-os/google-ima-js-sdk'
utilsBySDK.generateUniqueRandom() // 通过时间戳生成13位的唯一随机数
let timer = new utilsBySDK.Timer(function () {}, 5) // 创建一个5s定时器
timer.start() // 执行定时器
timer.clear() // 清除定时器
timer = null
SDK暴露可以调用的异步接口
import { ajaxBySDK } from '@coolita-os/google-ima-js-sdk'
ajaxBySDK.getNodeUrl(node: number) // 没有板子的场景，需要根据节点域名类型去获取并更新services.json
ajaxBySDK.sendAjaxRequest({ // 发起一个ajax请求
headers, // 请求头参数
method, // 请求方法，默认GET
url, // 请求地址
data // POST请求的body参数，GET请求为null
})