MDAd

MDAd.framework 用于 iOS 端移动应用广告展示。基于 Swift 语言开发。在使用广告服务的同时，我们真诚希望收到大家的反馈。

内容

• 环境支持
• 集成方式
• 项目配置
• 初始化
• 广告样式
• 常见问题
• 错误码
• 版本日志

环境支持

• 基于 Swift 5.0+ 语言开发。 如需支持 Swift 低版本的 framework，请联系我们。
• 支持 iOS 10.0+。
• 支持 Xcode 11.0+。

集成方式

1. CocoaPods 集成。创建 Podfile 并指定其内容

   source 'https://github.com/CocoaPods/Specs.git'
   platform :ios, '10.0'
   use_frameworks!
   
   target '<Your Target Name>' do
   pod 'MDAd', '~> 0.8.10'
   end

   然后执行

   $ pod install

2. 手动集成。请将仓库中 MDAd.framework 和 MDAd.bundle 手动拖入项目中。在弹出的文件选项框中，请勾选 Copy items if needed，如图所示

   

   • 在 target -> General -> Linked Frameworks and Libraries 下删除 MDAd.framework，然后在 target -> General -> Embedded Binaries 中添加 MDAd.framework。这时也会自动在 Linked Frameworks and Libraries 目录下添加一份。

   • 用法：在使用 MDAd.framework 时，在需要的文件头部 import MDAd 即可。

   注意：如果您在 OC 项目中使用该 framework，请在对应的 target -> Build Settings -> ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES 设置为 YES。

项目配置

每个广告对应的链接内容将由广告主进行配置。这些链接内容可能包含httpurl。为了尽可能显示广告链接内容，建议在项目设置中开启对http的支持。

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

初始化

在使用MDAd.framework之前，请确保已注册AppKey和AppSecret。如有疑问，请联系我们[email protected]或者查看当前github账号。如果已注册AppKey和AppSecret，请在application(_ application:, didFinishLaunchingWithOptions launchOptions:)中执行如下初始化：

RYAdMobCenter.center.setup("appKey", appSecret: "appSecret")

广告样式

MDAd.framework提供了六种广告样式，包括横幅广告、信息流广告、开屏广告、插屏广告、浮标广告以及激励视频广告。并且针对每种广告样式，开发者可以自定义。

横幅广告

横幅广告也称为Banner，通常展示在App页面的顶部或底部。Framework中提供了两种横幅广告样式：分别是纯图模式（宽高比为640.0 : 60.0）和左图右文模式（宽高比为690.0 : 100.0）。不同的广告样式对应不同的ID。在使用该广告前，您需要申请横幅广告的广告ID。集成横幅广告的简单示例如下：

1. 创建RYBannerView实例。RYBannerView是MDAd.framework中用于展示横幅广告的视图类。具体初始化代码如下：

   /// bannerView 是 RYBannerView 类的实例
   /// 在 viewDidLoad(或者其他加载视图的时机) 中配置横幅广告 ID, 并且开始请求广告
   bannerView.adsID = "820001"
   bannerView.rootViewController = self
   bannerView.delegate = self
   bannerView.loadRequest()

2. RYBannerView提供了广告请求成功或失败的代理方法。如果您想在广告数据请求成功后显示广告视图，可以采用如下方式：

   • 实现广告数据成功获取代理方法

     func adViewDidReceiveAd(_ bannerView: RYBannerView) {
           // You can show infoFlowView with animation.
           UIView.animate(withDuration: 1.0) {
              self.bannerView.alpha = 1.0
           }
     }

   • 实现广告数据成功获取代理方法

      func bannerDidFailToReceiveAd(_ bannerView: RYBannerView, error: RYError) {}
     

3. 详细代码请查看Demo中的BannerViewController类。实现效果如下：

   

信息流广告

信息流广告用于在信息流列表中展示。您可以使用RYInfoFlowView类来实现信息流广告的展示。Framework中提供了四种信息流广告样式：分别是纯图模式（宽高比为700.0 : 280.0）、左图右文模式（宽高比为690.0 : 290.0）、上文下图模式（宽高比为690.0 : 440.0）以及三图模式。在使用该广告前，您需要申请信息流广告的广告ID。集成信息流广告的示例如下：

1. 创建RYInfoFlowView 实例。RYInfoFlowView 是MDAd.framework中用于展示信息流广告的视图类。具体初始化代码如下：

   /// infoFlowView 是 RYInfoFlowView 类的实例
   /// 左图右文模式, adsID 为 850002
   /// 广告位尺寸是 690.0 : 290.0, 广告图片比例是 576: 386(请初始化 infoFlowView 初始宽高比为 690.0 : 290.0), 请在初始化是正确设置 infoFlowView 的比例为 690.0 : 290.0
   infoFlowView.adsID = "850002"
   infoFlowView.rootViewController = self
   infoFlowView.delegate = self
   infoFlowView.loadRequest()

2. RYInfoFlowViewDelegate提供了广告加载成功、失败等可选代理方法，具体使用可查看Framework中对应注释。

3. 详细代码请查看Demo中的InfoFlowViewController类。实现效果如下

   

全屏广告

全屏广告又名插页式广告。通常用于 App 启动或者从一个页面过渡到另一个页面的场景中。你可以使用 RYInterstitialView 类来实现全屏广告的展示。框架中提供全屏广告样式有两种，分别是纯图模式 (宽高比为750 : 1334) 和 上图下文模式 (宽高比为750.0 : 1143.0)。其中上图下文模式提供对不同屏幕适配方案。在使用该广告之前，你需要申请全屏广告的广告 ID。集成全屏广告的简单示例如下

1. 创建 RYInterstitialView 实例。RYInterstitialView 是 MDAd.framework 中用于展示全屏广告的视图类。具体初始化代码如下

   /// 插页式广告展示宽高比是 750.0 : 1334.0
   /// interstitialView 是 RYInterstitialView 类的实例
   interstitialView.adsID = "810001"
   interstitialView.rootViewController = self
   interstitialView.delegate = self
   interstitialView.loadRequest()

   • 上图下文模式不仅显示开屏广告图，而且可以在底部融入 App 元素如 App logo、App 名称等。

   /// Only works for interstitial ad which adsID is 810002.
     interstitialView.config(appLogo: UIImage(named: "appIcon40"), appName: "妙招助手, 活出每一个细节")
     interstitialView.logoCornerRadius = 5.0
     interstitialView.logoTextFont = UIFont(name: "PingFangSC-Regular", size: 20)
     interstitialView.logoTextColor = UIColor.darkText

2. RYInterstitialViewDelegate 提供广告加载成功、失败等可选代理方法，具体使用可查看 framework 中对应注释。

3. 详细代码请看 Demo 中 InterstitialViewController 类。实现效果如下

   

插屏广告

插屏广告用于展示插屏广告。通常用于 App 屏幕中间展示。你可以使用 RYInterstitialHalfView 类来实现插屏广告的展示。框架中提供插屏广告尺寸宽高比为 510 : 510。在使用该广告之前，你需要申请插屏广告的广告 ID。集成插屏广告的简单示例如下

1. 创建 RYInterstitialHalfView 实例。RYInterstitialHalfView 是 MDAd.framework 中用于展示插屏广告的视图类。具体初始化代码如下

   /// 插屏式广告位展示宽高值推荐为 255.0 * (255.0 + 55.0), 为保证底部 Close 按钮正常显示, 请保证高度始终大于宽度 55.0
   halfInterstitialView.adsID = "840001"
   halfInterstitialView.rootViewController = self
   halfInterstitialView.delegate = self
   halfInterstitialView.loadRequest()

2. RYInterstitialHalfViewDelegate 提供广告加载成功、失败等可选代理方法，具体使用可查看 framework 中对应注释。

3. 详细代码请看 Demo 中 InterstitialHalfViewController 类。实现效果如下

   

浮标广告

浮标广告通常展示在页面的边角位置。是五种广告中展示面积最小的一种。支持 Gif 效果。你可以使用 RYBuoyView 类来实现浮标广告的展示。框架中提供浮标广告尺寸宽高比为 110 : 110。在使用该广告之前，你需要申请浮标广告的广告 ID。集成浮标广告的示例如下

1. 创建 RYBuoyView 实例。RYBuoyView 是 MDAd.framework 中用于展示浮标广告的视图类。具体初始化代码如下

   /// 浮标式广告展示宽高比是 110 : 110
   /// buoyView 是 RYBuoyView 类的实例
   buoyView.adsID = "860001"
   buoyView.rootViewController = self
   buoyView.delegate = self
   buoyView.loadRequest()

2. RYBuoyViewDelegate 提供广告加载成功、失败等可选代理方法，具体使用可查看 framework 中对应注释。

3. 详细代码请看 Demo 中 BuoyViewController 类。实现效果如下

   

激励视频广告

激励视频广告属于视频类广告。你可以使用 RYRewardVideoViewController 类来实现激励视频广告的展示。在使用该广告之前，你需要申请激励视频广告的 ID。集成激励视频广告的示例如下

1. 创建 RYRewardVideoViewController 实例。RYRewardVideoViewController 是 MDAd.framework 中用于展示激励视频广告的控制器类。具体初始化代码如下

   let rewardVideoVC = RYRewardVideoViewController()
   rewardVideoVC.adsID = "870001"
   rewardVideoVC.delegate = self
   rewardVideoVC.loadRequest()
   present(rewardVideoVC, animated: true, completion: nil)

   • 为保证视频播放效果，可以在页面进入时 loadRequest()，用于预加载。在调用场景执行 present(rewardVideoVC, animated: true, completion: nil)。

2. RYRewardVideoViewControllerDelegate 提供广告加载成功、失败等可选代理方法，具体使用可查看 framework 中对应注释。

3. 详细演示代码请看 Demo 中 RewardVideoViewController 类。

   

自定义广告

自定义广告不是某一类广告，而是提供广告数据源供开发者自定义广告样式。MDAd.framework提供多种通用的广告类型，对于需要UI定制化的广告展示，框架提供自定义类型，开放广告展示所需的数据源给开发者，用于UI定制化。集成自定义广告的示例如下

1. 创建RYCustomAd实例。RYCustomAd是MDAd.framework中用于自定义广告的工具类。具体初始化代码如下

   /// 这里以 850008 广告位进行自定义展示
   /// 自定义广告对应的广告图片的比例. 注意: 在进行自定义广告时, 请务必保证自定义图片的比例与对应广告类型图片比例保持一致.
   self.customAd = RYCustomAd(adsID: "850008")
   customAd.rootViewController = self
   customAd.delegate = self
   customAd.loadRequest()

2. 自定义广告源在请求成功后返回。使用RYCustomAdItem类来获取广告数据。具体代码如下

   func customAdDidReceiveAd(_ customAd: RYCustomAd, receivedData item: RYCustomAdItem) {
   	 // customView 是开发者自定义视图, 用于定制展示广告数据
       customView.update(item.imageUrls?.first ?? "",
                         title: item.title,
                         desc: item.desc,
                         imageRatio: imageViewRatioForCustomAd)
   }

3. 实现与通用广告相同的广告跳转效果

   /// adTapped 是开发者自定义视图上的手势点击行为
   func adTapped() {
       // open ad link.
       // called when you add gestures, actions or other Selectors to you custom ad view
       customAd.openAdLink()
   }

4. 详细演示代码请看Demo中RYCustomAd类。

常见问题

问题：支持OC项目接入吗？
答案：支持。该SDK使用Swift开发，对OC项目做了全面的支持。

问题：为什么有时广告代理方法均未执行？
答案：出现此现象一般是两个原因导致

1. 检查appKey和appSecret配置。一般在AppDelegate中didFinishLaunchingWithOptions配置；
2. 错误初始化对应广告基类实例为局部变量。请务必在页面展示周期内持有对应的广告实例变量。

问题：加载广告为什么不显示？
答案：请检查对应广告ID是否正确。

问题：为什么出现部分广告点击后没有发生跳转？
答案：rootViewController未设置。rootViewController用来弹出落地页或者执行广告跳转操作。

问题：手动集成时为什么会发生 image not found？
答案：该错误一般发生在OC项目中接入MDAd.framework。确定MDAd.bundle已经导入，可在target -> Build Phases -> Copy Bundle Resources查看是否存在。确保MDAd.framework和MDAd.bundle同时存在项目中。确保OC项目中ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES选项设置为YES。

问题：广告样式是否可以自定义？
答案：可以。开发者只需传入需要自定义广告的ID，即可获取该广告的图片、标题和广告描述来实现广告UI的自定义。具体请使用RYCustomAd类来实现此功能。

问题：请问有OC版本的Demo吗？
答案：有的。文档以Swift代码演示，如果你正在使用Objective-C语言开发，可查看仓库中OC示例工程OCMDAdDemo。

问题：接入时出现了40006, 50001错误返回。请问这是什么错误？
答案：下面分别介绍两个错误码含义

1. 40006是当前广告位已经关闭。该错误一般发生后台重复配置删除同一广告位，进行广告展示前，请确定对应的广告位是否开启。
2. 50001表示当前广告位广告无法提供。

错误码

对于接入过程中的错误码详情，请查看错误码文档：错误码

版本日志

0.1.0：接入五种常用广告。
0.2.0：修改SDK命名规范。
0.3.0：新增横幅广告左图右文样式，信息流广告左图右文、上图下文样式。横幅、信息流、开屏、插屏和浮标广告位纯图模式广告改版。
0.3.1：修复当加载左图右文格式广告位时，左图在第三方App内显示不完整bug。
0.3.2：更改浮标广告位背景色为透明色。
0.4.0：新增信息流广告上图下文样式，浮层样式，左图右文样式新增1:1.3图片比例；新增应用内打开广告方式；浮标广告支持Gif。
0.4.1：修复自定义广告类型中adsID在OC项目中的可访问性。
0.4.2：调整广告标题和副标题长度为50位。
0.5.0：新增激励视频广告。
0.6.0：新增全屏广告上图下文样式。
0.6.1：修复tag 0.6.0未链接对应MDAd.framework和MDAd.bundle。
0.7.0：新增激励视频广告背景样式。
0.7.1：修复当全屏广告所在视图被keyWindow覆盖时，广告点击视图无法显示问题。
0.7.2: 视频预加载优化、开屏广告提供广告链接应用外打开方式及其他细节优化.
0.8.0: 新增信息流广告三图样式.
0.8.1: 优化视频播放.
0.8.2: 自定义广告返回数据使用 RYCustomAdItem 类来代替键值对返回.
0.8.3: 自定义广告增加点击和曝光支持.
0.8.3.1: 注释修正.
0.8.4: 更改 bundle 版本号为 0.8.3.1 不能打包上传问题.
0.8.5: 优化广告显示效果.
0.8.6: 优化内部广告展示.
0.8.7: 新增 webView 链接广告样式.
0.8.8: 增加互动广告展示.
0.8.9: 互动广告内部支持 Apple Store 应用内打开方式.
0.8.10: 优化初始化逻辑.