🔥🔥🔥 Flutter 广告插件 -- 字节跳动、穿山甲(支持开屏、插屏、激励视频、全屏视频)

Overview

logo

一款优质的 Flutter 广告插件(字节跳动、穿山甲)

插件特点

  • 🔨 接入简单快速(封装原生端配置,仅需引入即可开始)
  • 📡 事件统一返回(将原生端各种重要回调事件统一返回,方便业务处理和埋点统计等需求)
  • 🎁 注重优化体验(无闪烁 Logo 开屏、权限申请、隐私跟踪申请等)
  • 🏆 极客代码封装(原生端代码不凑合,两端统一基础框架、广告事件封装抽象、易扩展新广告形式、方便开发个性化需求)

支持功能

  • ✅ 开屏广告
  • ✅ 插屏广告
    • ✅ 半插屏
    • ✅ 全屏视频(新插屏)
  • ✅ 激励视频
  • ✅ 全屏视频
  • 🔲 Banner
  • 🔲 信息流

下载体验

入门使用

引入依赖

  • 版本约定

    • 1.x.x 是非 Null Safety 版本,对应 master 分支
    • 2.x.x 是 Null Safety 版本,对应 2x 分支

    现在阶段会同时维护这 2 个版本,再往后可能仅维护一个空安全版本

  • Pub 引入

dependencies:
  flutter_pangle_ads: ^1.1.0 # 非 Null Safety 版本
  flutter_pangle_ads: ^2.1.0 # Null Safety 版本
  • Git 引入
flutter_pangle_ads:
  git: 
    url: git@github.com:FlutterAds/flutter_pangle_ads.git
    ref: master
  • 克隆后本地引入
flutter_pangle_ads:
  path: [与主项目的相对路径 | 插件的绝对路径]

初始化广告

/// [appId] 应用ID
FlutterPangleAds.initAd(appId);

设置广告事件监听

FlutterPangleAds.onEventListener((event) {
  // 普通广告事件
  String _adEvent = 'adId:${event.adId} action:${event.action}';
  if (event is AdErrorEvent) {
    // 错误事件
    _adEvent += ' errCode:${event.errCode} errMsg:${event.errMsg}';
  } else if (event is AdRewardEvent) {
    // 激励事件
        _adEvent +=
            ' rewardVerify:${event.rewardVerify} rewardAmount:${event.rewardAmount} rewardName:${event.rewardName} errCode:${event.errCode} errMsg:${event.errMsg} customData:${event.customData} userId:${event.userId}';
  }
  print('onEventListener:$_adEvent');
});

事件列表

事件 说明
onAdLoaded 广告加载成功
onAdPresent 广告填充
onAdExposure 广告曝光
onAdClosed 广告关闭(开屏计时结束或者用户点击关闭)
onAdClicked 广告点击
onAdSkip 广告跳过
onAdComplete 广告播放或计时完毕
onAdError 广告错误
onAdReward 获得广告激励

这里做了统一的抽象,iOS 和 Android 原生 SDK 名称不同,如果觉得对应不上,可以提 Issues(一定要加上 log 截图)

开屏广告

/// [posId] 广告位 id
/// [logo] 如果传值则展示底部logo,不传不展示,则全屏展示
FlutterPangleAds.showSplashAd(posId, 'flutterads_logo');
  • 全屏广告
FlutterQqAds.showSplashAd(posId);

插屏广告

/// [posId] 广告位 id
/// [width] 请求模板广告素材的尺寸宽度(对应 expressViewWidth 参数)
/// [height] 请求模板广告素材的尺寸高度(对应 expressViewWidth 参数)
FlutterPangleAds.showInterstitialAd(
    AdsConfig.interstitialId,
    width: 300,
    height: 300,
);

激励视频

/// [posId] 广告位 id
/// [customData] 设置服务端验证的自定义信息
/// [userId] 设置服务端验证的用户信息
FlutterPangleAds.showRewardVideoAd(
    AdsConfig.rewardVideoId,
    customData: 'customData',
    userId: 'userId',
);

全屏视频

  • 全屏视频
  • 新插屏
/// [posId] 广告位 id
FlutterPangleAds.showRewardVideoAd(AdsConfig.fullScreenVideoId);

其他配置

信任HTTP请求(仅 iOS)

苹果公司在iOS9中升级了应用网络通信安全策略,默认推荐开发者使用HTTPS协议来进行网络通信,并限制HTTP协议的请求。为了避免出现无法拉取到广告的情况,我们推荐开发者在info.plist文件中增加如下配置来实现广告的网络访问

  • 修改 info.plist
<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

信任HTTP请求

请求应用跟踪透明度授权(仅 iOS)

此步骤必须要做,不然上架审核时候会被拒绝

bool result = await FlutterPangleAds.requestIDFA;
  • 修改 info.plist
<key>NSUserTrackingUsageDescription</key>
<string>为了向您提供更优质、安全的个性化服务及内容,需要您允许使用相关权限</string>

请求应用跟踪透明度授权

  • 效果

预览效果

动态请求权限(仅 Android)

bool result = await FlutterPangleAds.requestPermissionIfNecessary;

原生 SDK 版本更新方法

如果是大版本,我会第一时间适配更新,小版本可以自己更新,方法如下:

  • Android

    方法1:可以给我提 Issues 提示我更新,此插件版本号 x.y.z,会更新 z 版本迭代

    方法2:可以自己指定版本,方法如下:

// build.gradle(android.app)
android{
  configurations.all {
      resolutionStrategy {
          force 'com.pangle.cn:ads-sdk:版本号'
      }
  }
}
  • iOS

    自己手动更新,自己的项目根目录下执行即可

// 可在 ios/Podfile.lock 中查看 SDK 当前版本
cd ios
rm -rf Podfile.lock
pod repo update
pod install

分支说明

分支 说明
develop 开发分支,接受 PR
master 稳定分支,非 Null Safety
2x 稳定分支,Null Safety

遇到问题

如果你遇到问题请提 Issues 给我(提问前建议先搜索尝试,没有再提问)

支持开源

支持开源项目最好的方式就是用 1 秒点个免费的 Star

FlutterAds 系列插件

Issues
  • 开屏广告添加超时参数设置 showSplashAd

    开屏广告添加超时参数设置 showSplashAd

    现在是默认时间 3.5秒,需要提供超时的参数

    opened by yy1300326388 2
  • errCode:20001 errMsg:no ads iOS 模拟器上一直没有广告显示

    errCode:20001 errMsg:no ads iOS 模拟器上一直没有广告显示

    没有合适的广告返回而导致的请求没有填充,偶尔出现属于正常情况。如果出现情况较多或者必现的话,请先检查一下广告尺寸是否填写正确,是否有使用模拟器测试广告,单个设备是否一天请求了大量广告但没有展示或者展示数极低等。排查以上问题依然没有结论可以联系技术支持同学或者提交工单(包含代码位和出现概率以及请求时间)相关同学查明后会做出回复。

    opened by yy1300326388 1
  • Update README.md

    Update README.md

    Test PR CICD

    opened by yy1300326388 1
  • 【穿山甲官方】接入文档和错误码列表

    【穿山甲官方】接入文档和错误码列表

    ##【穿山甲官方】接入文档和错误码列表

    接入文档

    常见错误码

    如果遇到问题可以先看 Log ,然后根据错误码排查常见错误

    用心开源 | 感谢有你 | 感谢 Star

    opened by yy1300326388 1
  • 集成后报 error: unexpected element <queries> found in <manifest> 错误

    集成后报 error: unexpected element found in 错误

    这个是 gradle 版本的问题,需要更新到如下及以上版本

    // build.gradle
    dependencies {
          classpath 'com.android.tools.build:gradle:3.5.4'
      }
    

    image

    Android Gradle 插件需要了解新的清单元素,尤其是清单合并过程。如果插件在清单合并中看到它无法识别的元素,它会感到困惑,抛出问题中的构建错误。

    在这种情况下,Android 11作为清单元素引入,而旧版本的 Android Gradle 插件不知道该元素。

    清单合并发生这种情况的事实意味着简单地升级依赖项可能会导致此错误。例如,如果您升级到最新版本的com.awesome:awesome-library,并且它的清单中包含一个元素,即使您的代码没有任何其他更改,您也可能会因构建中的上述错误而崩溃。

    谷歌发布了一系列 Android Gradle 插件的补丁版本来解决这个问题:

    opened by yy1300326388 0
Releases(2.2.0)
  • 2.2.0(Sep 4, 2021)

    • 增加 Banner 广告支持
    • 优化开屏广告支持超时时间设置 #3
    • 开屏 API 变更,logo 参数由位置参数变为可选命名参数,注意修改 #3
    • 升级 Android SDK 到 v3.9.0.5
    • 项目增加 CI/CD 检查和自动发布,提高项目质量

    ❤️ 用心开源,感谢 Star ⭐️

    Source code(tar.gz)
    Source code(zip)
  • 1.2.0(Sep 4, 2021)

    • 增加 Banner 广告支持
    • 优化开屏广告支持超时时间设置 #3
    • 开屏 API 变更,logo 参数由位置参数变为可选命名参数,注意修改 #3
    • 升级 Android SDK 到 v3.9.0.5
    • 项目增加 CI/CD 检查和自动发布,提高项目质量

    ❤️ 用心开源,感谢 Star ⭐️

    Source code(tar.gz)
    Source code(zip)
  • 2.1.0(Aug 27, 2021)

  • 1.1.0(Aug 27, 2021)

Owner
致力于构建优质的 Flutter 广告插件
null