google-ima-js-sdk

Coolita OS ima js sdk插件库

Google IMA SDK官方文档.

安装

yarn add @coolita-os/google-ima-js-sdk or npm install --save @coolita-os/google-ima-js-sdk

使用

$3

1、引入https://imasdk.googleapis.com/js/sdkloader/ima3.js:

``html







content="width=device-width, initial-scale=1.0, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0" />

`

2、在需要插入广告的节点添加广告节点元素和样式控制

`html

`

`css
.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; // 保持原有尺寸比例。但部分内容可能被剪切。
}
`

$3

1、创建广告播放器实例并添加相关的数据添加事件

`js
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、销毁广告播放器实例

`js
imaAdPlayerInstance.destroy()
`

3、循环播放广告，可直接使用当前实例再次发起广告请求

`js
imaAdPlayerInstance.requestAd()
`

4、监听到所有广告播放完成

`js
onAllAdsCompleted: () => {
// 所有广告播放完成
imaAdPlayerInstance.handlePlayAdComplete() // 内部执行实例定义重置
}
`

5、跳过广告

`js
imaAdPlayerInstance.skipAd()
`

6、暂停广告播放

`js
imaAdPlayerInstance.pauseAd()
`

7、 恢复广告播放

`js
imaAdPlayerInstance.resumeAd()
`

8、控制广告播放器是否静音
`js
imaAdPlayerInstance.handlePlayerIsMuted(isMute: boolean)
`

$3

1、谷歌广告/系统广告埋点公共接口部分，data为埋点上报的所有参数，sendParams为发送参数自定义的方法

`js
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为发送参数定义的方法

`ts
-- 参数传递说明：
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发送埋点数据
`

四、谷歌广告内存控制器使用

``ts
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(): void
``

SDK暴露可以使用的相关工具

`js
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暴露可以调用的异步接口

`js
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
})
``