更新记录

1.0.0（2025-12-07） 下载此版本

项目初始化

平台兼容性

uni-app(4.0)

uni-app x(4.0)

x-zindex-ad

Zindex 广告 SDK 的 uni-app x 封装插件，支持 iOS 和 Android 双平台。

功能特性

• ✅ 支持 Banner 广告
• ✅ 完整的事件回调机制
• ✅ 状态管理（加载、展示、关闭）
• ✅ 自动资源释放
• ✅ 详细的日志输出
• ✅ 支持组件化和类调用两种方式
• 🚧 Android 平台支持（待实现）

安装

将 x-zindex-ad 文件夹复制到你的项目的 uni_modules 目录下。

快速开始

1. 初始化 SDK

在 App.uvue 或应用启动时初始化：

<script>
import { YJInit } from '@/uni_modules/x-zindex-ad';

export default {
  onLaunch() {
    // 初始化广告 SDK
    YJInit("你的AppID", "https://ad.lovefree.cc", (success, error) => {
      if (success) {
        console.log("广告SDK初始化成功");
      } else {
        console.error("广告SDK初始化失败:", error);
      }
    });
  }
}
</script>

2. 使用组件（推荐）

最简单的使用方式：

<template>
  <view>
    <x-zindex-ad
      posId="你的广告位ID"
      width="100%"
      height="100px"
      :autoLoad="true"
      :autoShow="true"
      @load-success="onAdLoadSuccess"
      @error="onAdError"
    />
  </view>
</template>

<script>
export default {
  methods: {
    onAdLoadSuccess() {
      console.log("广告加载成功");
    },
    onAdError(event) {
      console.error("广告错误:", event.message);
    }
  }
}
</script>

3. 手动控制广告

如需手动控制广告的加载和展示：

<template>
  <view>
    <x-zindex-ad
      ref="bannerAd"
      posId="你的广告位ID"
      :autoLoad="false"
      :autoShow="false"
    />
    <button @click="loadAd">加载广告</button>
    <button @click="showAd">展示广告</button>
  </view>
</template>

<script>
export default {
  methods: {
    loadAd() {
      const ad = this.$refs.bannerAd;
      ad.initAd();
    },
    showAd() {
      const ad = this.$refs.bannerAd;
      ad.show();
    }
  }
}
</script>

4. 使用类方式（高级）

更灵活的使用方式：

<template>
  <view>
    <view ref="adContainer" style="width: 100%; height: 100px;"></view>
  </view>
</template>

<script>
import { YJBannerAd, YJBannerAdListener } from '@/uni_modules/x-zindex-ad';

export default {
  data() {
    return {
      bannerAd: null as YJBannerAd | null
    }
  },
  mounted() {
    this.initAd();
  },
  methods: {
    initAd() {
      #ifdef APP-IOS
      const container = this.$refs.adContainer as Element;
      const view = container.getIOSView();

      // 创建监听器
      const listener: YJBannerAdListener = {
        onAdLoadSuccess: () => {
          console.log("广告加载成功");
          this.bannerAd?.show();
        },
        onAdLoadFailed: (error) => {
          console.error("广告加载失败:", error);
        },
        onAdClicked: () => {
          console.log("广告被点击");
        }
      };

      // 创建广告实例
      this.bannerAd = new YJBannerAd(view, listener);
      this.bannerAd.load("你的广告位ID");
      #endif
    }
  },
  beforeUnmount() {
    this.bannerAd?.destroy();
  }
}
</script>

API 文档

YJInit 函数

初始化广告 SDK。

function YJInit(
  appid: string,
  baseUrl?: string,
  callback?: (success: boolean, error: string | null) => void
): void

参数：

• appid: 应用ID（必填）
• baseUrl: 广告服务器地址（可选，默认为 "https://ad.lovefree.cc"）
• callback: 初始化回调函数（可选）

YJBannerAd 类

Banner 广告类。

构造函数

constructor(container: UIView, listener?: YJBannerAdListener | null)

方法

• load(posId: string): 加载广告
• show(): 展示广告
• hide(): 隐藏广告
• destroy(): 销毁广告，释放资源
• setListener(listener: YJBannerAdListener | null): 设置事件监听器
• getIsLoaded(): 获取广告是否已加载
• getIsShowing(): 获取广告是否正在展示
• getPosId(): 获取广告位ID

YJBannerAdListener 接口

广告事件监听器。

type YJBannerAdListener = {
  onAdLoadStarted?: () => void;        // 广告开始加载
  onAdLoadSuccess?: () => void;         // 广告加载成功
  onAdLoadFailed?: (error: string) => void;  // 广告加载失败
  onAdClicked?: () => void;             // 广告被点击
  onAdImpression?: () => void;          // 广告展示曝光
  onAdClosed?: () => void;              // 广告关闭
}

x-zindex-ad 组件

Props

Events

Methods

注意事项

1. 初始化时机：请在应用启动时（如 App.uvue 的 onLaunch）调用 YJInit 初始化 SDK。

2. 资源释放：使用类方式时，请在页面销毁前调用 destroy() 方法释放资源。使用组件方式会自动处理。

3. iOS 专属：当前版本仅支持 iOS 平台，Android 平台支持正在开发中。

4. 容器视图：Banner 广告需要一个容器视图，请确保容器有合适的宽高。

5. 线程安全：广告的展示、隐藏、销毁操作都会自动在主线程执行，无需手动处理。

示例项目

项目中的 pages/banner/banner.uvue 提供了完整的使用示例，包括：

• 组件方式使用
• 类方式使用
• 事件处理
• 状态管理
• 日志输出

常见问题

1. 广告加载失败？

• 检查是否调用了 YJInit 初始化 SDK
• 确认 AppID 和广告位ID 是否正确
• 查看控制台日志获取详细错误信息

2. 广告不显示？

• 确保调用了 show() 方法（或设置 autoShow="true"）
• 检查广告是否加载成功
• 确认容器视图是否有合适的宽高

3. 如何处理广告事件？

使用监听器或组件事件来处理广告生命周期：

<x-zindex-ad
  @load-success="onSuccess"
  @error="onError"
  @click="onClick"
/>

更新日志

查看 changelog.md 了解版本更新历史。

许可证

根据项目许可证使用。

技术支持

如有问题，请提交 Issue 或联系技术支持。