m3u8-ad-js-sdk

Coolita OS Web 使用的m3u8 广告SDK插件库

安装

yarn add @coolita-os/m3u8-ad-js-sdk or npm install --save @coolita-os/m3u8-ad-js-sdk

使用

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

<video
    style="display: none;"
    class="ad-video"
    id="ad-video">
</video>

    .ad-video {
        width: 100%;
        height: 100%;
        object-fit: cover; // 保持原有尺寸比例。但部分内容可能被剪切。
    }

二、JavaScript/TypeScript 调用实现部分

import { M3u8AdPlayer } from '@coolita-os/m3u8-ad-js-sdk'

// 创建广告播放器实例，内部实现自动调用requestAd()发起广告请求等其他逻辑
let m3u8AdPlayerInstance = new M3u8AdPlayer({
    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: { // 实例需要实现的所有回调函数
        onStarted: () => { 
            // 即将开始播放
        },
        onAdErrorEvent: (errorData) => {
            // 广告播放发送异常
        }
    }
})

2、销毁广告播放器实例

    m3u8AdPlayerInstance.destroy()
    m3u8AdPlayerInstance = null

按需引入 palUtils（不打包 hls.js）

palUtils 是纯工具函数（PAL SDK 封装），不依赖 hls.js。 如果你只需要 palUtils（例如用于 PAL 广告流处理），请通过独立子路径按需引入， 这样 hls.js / M3u8AdPlayer 不会进入你的业务包：

// ✅ 推荐：按需引入，包内不含 hls.js（约 5KB）
import palUtils from '@coolita-os/m3u8-ad-js-sdk/palUtils'

palUtils.initPAL({ url, liveVideoElement, palSdkConfig })

// ❌ 避免：从主入口引入单个工具，会把 M3u8AdPlayer + 整个 hls.js（约 500KB）一起打进包
// import { palUtils } from '@coolita-os/m3u8-ad-js-sdk'

对应 package.json 中的 exports 子路径映射：

"./palUtils": {
  "types": "./dist/src/utils/palUtils.d.ts",
  "import": "./dist/palUtils.esm.js",
  "require": "./dist/palUtils.cjs.js"
}

若确实需要 m3u8 广告播放能力，再从主入口引入 M3u8AdPlayer。

Hls-free core 入口

M3u8AdPlayerCore 不内置 hls.js，由业务侧注入共享 HLS runtime，避免重复打包：

import { loadHls } from './hlsPlayer'
import { M3u8AdPlayerCore } from '@coolita-os/m3u8-ad-js-sdk/core'

const [hlsModule] = await Promise.all([loadHls()])

const player = new M3u8AdPlayerCore({
    adVideoElement: document.getElementById('ad-video'),
    adTagUrl: '',
    adUIElement: document.getElementById('ad-ui'),
    muted: true,
    staticJson: null,
    debug: false,
    instanceApi: {
        onStarted: () => {},
        onAdErrorEvent: error => {}
    },
    palSdkConfig: {},
    hlsConstructor: hlsModule.default
})

palUtils 也继续推荐从独立子路径引入：

import palUtils from '@coolita-os/m3u8-ad-js-sdk/palUtils'