shenshi-h5

ShenshiH5 广告 SDK

ShenshiH5 广告 SDK 是专为移动端 H5 应用设计的轻量级广告集成解决方案，支持原生广告和插屏广告，提供简洁高效的 API 接口。

产品特性

• 极简集成 - 一行代码完成初始化，快速接入
• 智能检测 - 内置 hasAd() 函数，智能判断广告可用性
• 框架无关 - 完美支持 Vue、React、原生 JavaScript
• 性能优化 - 轻量级设计，无额外性能开销
• 生产就绪 - 完善的错误处理和重试机制

快速开始

安装

npm install shenshi-h5

基础使用

1. 初始化广告

在应用入口处初始化一次：

import { init } from 'shenshi-h5'

await init({
  nativeAdvKeys: ['YOUR_NATIVE_AD_KEY'],
  interstitialAdvKeys: ['YOUR_INTERSTITIAL_AD_KEY']
})

2. 检查并渲染广告

import { hasAd, renderNative } from 'shenshi-h5'

// 检查广告是否可用
if (hasAd('YOUR_NATIVE_AD_KEY')) {
  renderNative({
    adv_key: 'YOUR_NATIVE_AD_KEY',
    containerId: 'ad-container',
    callback: (result) => console.log(result)
  })
}

API 参考

init(options)

初始化广告 SDK。

参数：

• nativeAdvKeys (string[]): 原生广告位 key 数组
• interstitialAdvKeys (string[]): 插屏广告位 key 数组

返回值：

• Promise<void>

hasAd(adv_key)

检查指定广告是否可用。

参数：

• adv_key (string): 广告位 key

返回值：

• boolean: 广告是否可用

renderNative(options)

渲染原生广告。

参数：

• adv_key (string): 广告位 key
• containerId (string): 容器元素 ID
• callback (function): 渲染结果回调函数

renderInterstitial(adv_key, callback)

渲染插屏广告。

参数：

• adv_key (string): 广告位 key
• callback (function): 渲染结果回调函数

框架集成

Vue 集成

<template>
  <div>
    <div v-if="hasAd('AD_KEY')">
      <div id="ad-container"></div>
    </div>
  </div>
</template>

<script setup>
import { hasAd, renderNative } from 'shenshi-h5'

const showAd = () => {
  renderNative({
    adv_key: 'AD_KEY',
    containerId: 'ad-container',
    callback: (msg) => console.log(msg)
  })
}
</script>

React 集成

import { useEffect } from 'react'
import { init, hasAd, renderNative } from 'shenshi-h5'

function App() {
  useEffect(() => {
    init({
      nativeAdvKeys: ['AD_KEY'],
      interstitialAdvKeys: []
    })
  }, [])
  
  const handleShowAd = () => {
    if (hasAd('AD_KEY')) {
      renderNative({
        adv_key: 'AD_KEY',
        containerId: 'ad-container',
        callback: (msg) => console.log(msg)
      })
    }
  }
  
  return (
    <div>
      {hasAd('AD_KEY') && (
        <button onClick={handleShowAd}>显示广告</button>
      )}
      <div id="ad-container"></div>
    </div>
  )
}

最佳实践

1. 初始化策略

• 在应用启动时初始化一次
• 使用真实的广告 key
• 处理初始化错误

try {
  await init({
    nativeAdvKeys: ['KEY1', 'KEY2'],
    interstitialAdvKeys: ['KEY3']
  })
} catch (error) {
  console.error('广告初始化失败:', error)
}

2. 广告渲染策略

• 先检查广告可用性
• 提供合适的容器元素
• 处理渲染结果

if (hasAd('AD_KEY')) {
  renderNative({
    adv_key: 'AD_KEY',
    containerId: 'ad-container',
    callback: (result) => {
      if (result.includes('成功')) {
        console.log('广告渲染成功')
      } else {
        console.log('广告渲染失败:', result)
      }
    }
  })
}

3. 数据检查

// 检查所有原生广告
console.log('原生广告数据:', window.NativeData)

// 检查所有插屏广告
console.log('插屏广告数据:', window.InterstitialData)

// 检查特定广告
const isAvailable = hasAd('AD_KEY')

调试支持

检查广告状态

console.log('广告状态:', {
  native: window.NativeData,
  interstitial: window.InterstitialData
})

常见问题

Q: 广告显示失败怎么办？

A: 请检查以下几点：

• 确认广告已初始化成功
• 验证广告 key 是否正确
• 检查容器元素是否存在
• 查看控制台错误信息

Q: 如何测试广告功能？

A: 使用真实的广告 key 进行测试，确保网络连接正常，并检查浏览器控制台输出。

Q: 支持哪些广告类型？

A: 目前支持原生广告（Native）和插屏广告（Interstitial）。