H5 广告接入手册

给 H5 前端工程师的接入说明：初始化 SDK，并按场景调用插屏、横幅、信息流、详情插入和视频贴片。

开始前

先在媒体控制台完成域名验证，并创建好要接入的广告位。每个广告位有自己的编号。

mediaId、apiKey 和各广告位的 slotId 从控制台「接入代码」复制。下面的示例只用占位符，不要把占位符直接发到线上。

全站只初始化一次，再按场景调用广告方法。
页面内容先出来。只有插屏和视频贴片这类需要停一下的场景，才挡住后续操作。
脚本只用平台地址，不要把旧文件长期托管在自己的网站上。

引入与初始化

<script src="https://flowadx.com/sdk/flowadx-sdk.js"></script>
<script>
  FlowAdx.init({
    mediaId: 'YOUR_MEDIA_ID',
    rtBaseUrl: 'https://flowadx.com/api/rt/v1',
    apiKey: 'YOUR_API_KEY',
  });
</script>

请求里的广告类型、出现时机、位置和样式，要么不传，由服务端使用后台登记值；要么与后台完全一致。不一致时请求会失败。

场景对照

插屏：showInterstitial。适合翻页、章节结束、关卡切换。不需要自己准备容器。
横幅：loadAd，slotFormat 为 banner。放在页面里的一个 div 中。
信息流：loadAd，slotFormat 为 feed。放在列表中间的插槽里。
详情插入：loadAd，slotFormat 为 detail_insert。放在正文段落之间。
视频前贴：showVideoPreroll。正片播放前，挂在播放器上的叠层容器里。
视频暂停贴：仍调用 showVideoPreroll，slotFormat 为 pause_roll。使用另一个叠层容器。
国内 H5 不要接激励视频。需要看完再继续时，使用插屏广告位。

插屏

在切集、解锁、返回、读完或关卡结算这类节点调用。关闭、失败或没有广告时，都要让页面继续往下走。

FlowAdx.preloadInterstitial({ slotId: 'YOUR_INTERSTITIAL_SLOT_ID' }).catch(function () {});

function showThenContinue(next) {
  FlowAdx.showInterstitial({
    slotId: 'YOUR_INTERSTITIAL_SLOT_ID',
    onClose: function () {
      next();
    },
  })
    .then(function (result) {
      if (result && result.filled === false) next();
    })
    .catch(function () {
      next();
    });
}

必须做到：只调用 showInterstitial。同一页再次展示时，继续调用这个方法。
不要这样做：不要绕过 FlowAdx SDK，自己在页面上贴广告代码。
怎样算接好：第一次能展示或明确没有广告；关掉之后再打开，仍然能展示或明确没有广告，并且业务没有卡住。

横幅

进入带横幅的页面时挂载一次，离开页面时卸掉。容器默认不要预留大块高度。

<div id="my-banner"></div>

<script>
FlowAdx.loadAd({
  containerId: '#my-banner',
  slotId: 'YOUR_BANNER_SLOT_ID',
  slotFormat: 'banner',
  mountMode: 'immediate',
}).then(function (result) {
  var filled = !!(result && result.rendered && result.rendered.filled);
  if (!filled) {
    document.getElementById('my-banner').style.display = 'none';
  }
});
</script>

必须做到：有广告时按素材高度显示；没有广告时收起容器。
不要这样做：不要用固定的大高度占位等待广告，也不要把信息流或详情位的类型传成 banner。
怎样算接好：有广告时不顶出大片空白；没有广告时上下内容紧挨在一起。

信息流

列表渲染后，在固定位置插入容器再调用 loadAd。重新进入列表时，先卸掉旧容器，再用新的容器编号挂载。

FlowAdx.loadAd({
  containerId: '#news-feed-ad',
  slotId: 'YOUR_FEED_SLOT_ID',
  slotFormat: 'feed',
  mountMode: 'immediate',
});

必须做到：信息流要比横幅等得更久。确认没有广告之后再收起，避免列表闪出空白。
不要这样做：不要套用横幅那种很短的等待后就拆掉容器，也不要和横幅共用一个长期不清理的容器。
怎样算接好：有广告时稳定留在列表里；没有广告时最终不留大空白。

详情插入

文章或章节正文渲染时，在段落之间插入容器。有广告再占位，没有广告就收起。类型必须与后台登记一致。

FlowAdx.loadAd({
  containerId: '#article-mid-ad',
  slotId: 'YOUR_DETAIL_INSERT_SLOT_ID',
  slotFormat: 'detail_insert',
  mountMode: 'immediate',
});

视频前贴

用户点播资讯或视频、正片开始播放之前，在播放器上层的容器里调用。短剧自己的播放器不要用这套贴片。贴片结束或没有广告之后，再播放正片。

<div class="player">
  <video id="content-video" playsinline></video>
  <div class="preroll-layer">
    <div id="preroll-mount"></div>
  </div>
</div>

<script>
FlowAdx.showVideoPreroll({
  containerId: '#preroll-mount',
  slotId: 'YOUR_PREROLL_SLOT_ID',
  mountMode: 'overlay',
}).then(function () {
  document.getElementById('content-video').play();
});
</script>

必须做到：使用叠层容器，mountMode 为 overlay。广告卡片保持居中。手机浏览器里展示贴片时，把正片视频降到广告下面。
不要这样做：不要把广告卡片强制拉满播放器，否则会裁掉关闭按钮。不要在贴片结束前就自动播放正片。
怎样算接好：点播时先出贴片，或明确没有广告后进入正片。换下一条视频可以再次请求。

视频暂停贴

正片播放中用户暂停时调用，仍使用 showVideoPreroll。slotFormat 设为 pause_roll，用来和前贴分开。容器编号要和前贴不同。若另外传入广告类型、时机或位置，必须与后台登记一致；常见的广告类型登记是 video_preroll。

FlowAdx.showVideoPreroll({
  containerId: '#pause-roll-mount',
  slotId: 'YOUR_PAUSE_ROLL_SLOT_ID',
  slotFormat: 'pause_roll',
  mountMode: 'overlay',
});

必须做到：前贴没有填充时，暂停贴仍然可以展示。展示时隐藏正片视频。继续播放后收起。
不要这样做：不要和前贴共用同一个容器。不要把暂停贴拉成铺满播放器的大卡片。
怎样算接好：暂停后出现带关闭按钮的居中卡片；继续播放后收起；再次暂停可以再请求。

对照与支持

可以打开 Demo 多媒体站对照短剧、小说、资讯、工具和游戏页面上的广告位置：https://flowadx.com/demo/

广告无法展示时，先在控制台确认请求是否到达、域名是否验证通过、广告位是否启用。仍需帮助时，请邮件联系 support@flowadx.com，并附上媒体编号、广告位编号、页面地址和发生时间。

给 H5 前端工程师的接入说明：初始化 SDK，并按场景调用插屏、横幅、信息流、详情插入和视频贴片。