神蓍H5广告SDK

上海神蓍信息科技有限公司2025年8月12日大约 4 分钟

神蓍H5广告SDK

专为移动端H5应用设计的轻量级广告SDK，支持原生广告和插屏广告展示。本文档采用对外文档风格，并与 src/index.ts 的实际 API 保持一致。

✨ 特性

🎯 多种广告类型：支持原生广告与插屏广告
📱 移动端优化：面向 H5 场景的轻量实现
🔧 框架兼容：可用于 Vue、React、Angular、原生 HTML
📦 轻量级：按需加载第三方脚本
🛡️ TypeScript 支持：完整类型提示
⚡ 异步加载：不阻塞页面渲染
🔄 自动清理：提供销毁方法，清理脚本与容器

📦 安装

使用 npm

npm install shenshi-h5

使用 yarn

yarn add shenshi-h5

使用 CDN（UMD，全局变量 `ShenshiH5`）

<script src="https://unpkg.com/shenshi-h5@latest/dist/index.umd.js"></script>

🎯 API 参考（与 `src/index.ts` 一致）

核心方法

方法	参数	返回值	描述
`init`	`(options: { nativeAdvKey: string[]; interstitialAdvKey: string; callback: Function })`	`Promise<void>`	初始化并加载平台脚本与配置
`renderNativeAd`	`({ containerId: string[], callback: Function })`	`void`	渲染原生广告到指定容器
`renderInterstitialAd`	`(callback: Function)`	`void`	渲染插屏广告
`destroyAd`	`()`	`void`	清理广告状态、脚本与容器

参数说明

nativeAdvKey: 原生广告位密钥数组（与容器顺序对应）
interstitialAdvKey: 插屏广告位密钥
containerId: 原生广告容器的 DOM 元素 ID 数组
callback: 广告状态回调函数（加载/展示成功或失败都会触发）

📖 使用指南

ES 模块（推荐）

import { init, renderNativeAd, renderInterstitialAd, destroyAd } from 'shenshi-h5';

const NATIVE_KEYS = ['your_native_key_1', 'your_native_key_2'];
const INTERSTITIAL_KEY = 'your_interstitial_key';

async function bootstrap() {
  await init({
    nativeAdvKey: NATIVE_KEYS,
    interstitialAdvKey: INTERSTITIAL_KEY,
    callback: (message) => console.log('广告状态:', message),
  });
}

function showNative() {
  renderNativeAd({
    containerId: ['native-ad-1', 'native-ad-2'],
    callback: (message) => console.log('原生广告:', message),
  });
}

function showInterstitial() {
  renderInterstitialAd((message) => console.log('插屏广告:', message));
}

function cleanup() { destroyAd(); }

bootstrap();

CommonJS

const { init, renderNativeAd, renderInterstitialAd, destroyAd } = require('shenshi-h5');
// 注意：SDK 面向浏览器环境，Node.js 仅用于打包/类型检查

UMD（浏览器全局变量）

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>神蓍H5广告SDK示例</title>
    <style>
      .ad-container { min-height: 160px; border: 1px dashed #ccc; margin: 10px 0; }
    </style>
  </head>
  <body>
    <div id="native-ad-1" class="ad-container"></div>
    <div id="native-ad-2" class="ad-container"></div>

    <button onclick="initAds()">初始化</button>
    <button onclick="renderNative()">渲染原生广告</button>
    <button onclick="renderInterstitial()">渲染插屏广告</button>
    <button onclick="cleanup()">销毁广告</button>

    <script src="https://unpkg.com/shenshi-h5@latest/dist/index.umd.js"></script>
    <script>
      function log(msg) { console.log('[广告]', msg); }

      function initAds() {
        ShenshiH5.init({
          nativeAdvKey: ['your_native_key_1', 'your_native_key_2'],
          interstitialAdvKey: 'your_interstitial_key',
          callback: (m) => log(m),
        });
      }

      function renderNative() {
        ShenshiH5.renderNativeAd({
          containerId: ['native-ad-1', 'native-ad-2'],
          callback: (m) => log(m),
        });
      }

      function renderInterstitial() {
        ShenshiH5.renderInterstitialAd((m) => log(m));
      }

      function cleanup() { ShenshiH5.destroyAd(); }

      window.addEventListener('beforeunload', cleanup);
    </script>
  </body>
</html>

🖼️ 框架集成示例

Vue 3（组合式 API）

<template>
  <div>
    <div id="native-ad-1" class="ad-container"></div>
    <div id="native-ad-2" class="ad-container"></div>
    <button @click="showNative">加载原生广告</button>
    <button @click="showInterstitial">加载插屏广告</button>
    <button @click="cleanup">清理广告</button>
  </div>
  
</template>

<script setup>
import { onUnmounted } from 'vue';
import { init, renderNativeAd, renderInterstitialAd, destroyAd } from 'shenshi-h5';

await init({
  nativeAdvKey: ['your_native_key_1', 'your_native_key_2'],
  interstitialAdvKey: 'your_interstitial_key',
  callback: (m) => console.log(m),
});

const showNative = () => {
  renderNativeAd({ containerId: ['native-ad-1', 'native-ad-2'], callback: (m) => console.log(m) });
};
const showInterstitial = () => { renderInterstitialAd((m) => console.log(m)); };
const cleanup = () => destroyAd();

onUnmounted(cleanup);
</script>

<style>
.ad-container { min-height: 160px; border: 1px dashed #ccc; margin: 10px 0; }
</style>

React（Hooks）

import React, { useEffect } from 'react';
import { init, renderNativeAd, renderInterstitialAd, destroyAd } from 'shenshi-h5';

export default function AdDemo() {
  useEffect(() => {
    (async () => {
      await init({
        nativeAdvKey: ['your_native_key_1', 'your_native_key_2'],
        interstitialAdvKey: 'your_interstitial_key',
        callback: (m) => console.log(m),
      });
    })();
    return () => destroyAd();
  }, []);

  return (
    <div>
      <div id="native-ad-1" className="ad-container" />
      <div id="native-ad-2" className="ad-container" />
      <button onClick={() => renderNativeAd({ containerId: ['native-ad-1', 'native-ad-2'], callback: (m) => console.log(m) })}>加载原生</button>
      <button onClick={() => renderInterstitialAd((m) => console.log(m))}>加载插屏</button>
      <button onClick={() => destroyAd()}>清理</button>
    </div>
  );
}

Angular（组件）

import { Component, OnDestroy } from '@angular/core';
import { init, renderNativeAd, renderInterstitialAd, destroyAd } from 'shenshi-h5';

@Component({
  selector: 'app-ad',
  template: `
    <div>
      <div id="native-ad-1" class="ad-container"></div>
      <div id="native-ad-2" class="ad-container"></div>
      <button (click)="showNative()">加载原生广告</button>
      <button (click)="showInterstitial()">加载插屏广告</button>
      <button (click)="cleanup()">清理广告</button>
    </div>
  `,
  styles: [`.ad-container { min-height: 160px; border: 1px dashed #ccc; margin: 10px 0; }`]
})
export class AdComponent implements OnDestroy {
  async ngOnInit() {
    await init({
      nativeAdvKey: ['your_native_key_1', 'your_native_key_2'],
      interstitialAdvKey: 'your_interstitial_key',
      callback: (m) => console.log(m),
    });
  }
  showNative() { renderNativeAd({ containerId: ['native-ad-1', 'native-ad-2'], callback: (m) => console.log(m) }); }
  showInterstitial() { renderInterstitialAd((m) => console.log(m)); }
  cleanup() { destroyAd(); }
  ngOnDestroy() { this.cleanup(); }
}

🔧 TypeScript 支持

// InitOptions 类型
type InitOptions = {
  nativeAdvKey: string[];
  interstitialAdvKey: string;
  callback: (message: string) => void;
};

declare function init(options: InitOptions): Promise<void>;
declare function renderNativeAd(args: { containerId: string[]; callback: (message: string) => void }): void;
declare function renderInterstitialAd(callback: (message: string) => void): void;
declare function destroyAd(): void;

⚠️ 注意事项

原生广告容器数量与顺序需与返回数据一致
使用有效的广告密钥，并确保网络环境正常
页面或组件卸载时调用 destroyAd() 清理资源

🐛 故障排除

广告不显示：检查密钥、网络、容器是否存在
回调未触发：确认已调用 init() 且平台脚本成功加载（Network 面板）

📞 支持

官网：https://www.shenshiads.com