FSAdSDK 0.6.9

FSAdSDK 0.6.9

Dean ChangDev Ops 维护。



FSAdSDK 0.6.9

  • 作者:
  • Freestar - Dean Chang

Freestar

Freestar Mobile iOS SDK 集成指南

最新动态

我们很高兴宣布发布我们的 SDK! 目前支持横幅和插屏广告格式,更多即将到来。请经常查看最新发布和通知。

变更历史
版本 发布日期 描述
0.6.4 2020 年 1 月 22 日 • 支持 GMA SDK 7.53.1 兼容。
0.6.3 2020 年 1 月 9 日 • 站台兼容性发布。
0.6.2 2019 年 11 月 15 日 • 支持 Facebook Audience Network 中介。
0.6.0 2019 年 10 月 23 日 • 修复 Firebase 分析兼容性。
• 最低 iOS 部署目标 9.0。
• 支持 GMA SDK 7.50.0 兼容。
0.5.2 2019 年 10 月 15 日 • 对广告刷新率进行空值检查。
0.5.0 2019 年 9 月 23 日 • Swift 5.1 模块稳定性。
• 支持 GMA SDK 7.50.0 兼容。
0.4.7 2019 年 9 月 10 日 • 支持 MoPub 中介。
0.4.6 2019 年 8 月 26 日 • 分析远程开关。
0.4.5 2019 年 6 月 24 日 • 排队分析交付 (protobuf 消息)。
0.4.4 2019 年 6 月 12 日 • 注册重试策略。
0.4.3 2019 年 5 月 29 日 • 对横幅视图上的根视图控制器公开设置器。
0.4.2 2019 年 5 月 21 日 • 修复广告事件函数名称常量问题。
0.4.1 2019 年 5 月 20 日 • 修复横幅广告的填充率问题。
0.4.0 2019 年 5 月 16 日 • 支持 GMA SDK 7.41.0 兼容。
• 可运行时调整刷新率。
• 可空性更新。
0.3.2 2019年5月14日 • Prebid Mobile SDK 现在是一个内部依赖项,请参阅更新的 Podfile。
0.3.1 2019年2月13日 • Bundle id 覆盖,仅限测试使用。
0.3.0 2019年1月7日 • 动态 iTunes Id。
• Ad size 锁定。
0.2.0 2018年11月20日 • 分析支持。
• GMA SDK 运行时更新。
• 横幅自动刷新的暂停和继续 API。
• 事件名便利常量。
0.1.1 2018年8月13日 • 修复注册回退 URL。
0.1.0 2018年8月6日 •Interstitial 支持功能。
• 注册状态代理。
• 移除对核心框架的不必要依赖。
0.0.1 2018年6月21日 • 初次发布。
主要 API 更改
最新版
[ 0.6.0 ]
• 不再需要使用分叉的 GMA SDK,但仍然需要版本锁定。请参见下方的兼容性矩阵。

警告:从 Google Mobile Ads SDK 版本 7.42.0 开始,此步骤是必需的。如果在 Info.plist 中未添加此条目,则会导致崩溃,显示消息:“Google Mobile Ads SDK 初始化不正确。”
Info.plist

<key>GADIsAdManagerApp</key>
<true/>
旧版
[ 0.5.0 ]
需要升级到 Xcode 11+。
更新您的 Info.plist 以启用 GADIsAdManagerApp 键。
[ 0.4.7 ]
• 支持 MoPub 中介。
[ 0.4.3 ]
弃用现有的 createBanner API。
[ 0.4.0 ]
可空性 API 更新。
更新 Podfile
[ 0.2.0 ]
横幅自动刷新的 暂停和继续
横幅便利常量,用于检测事件处理程序回调参数。
插页式横幅便利常量,用于检测插页式事件处理程序回调参数。
[ 0.1.0 ]
广告提供者 createBanner 方法更改。添加了注册代理参数。支持插页式广告格式。
GMA SDK 兼容性矩阵

从 SDK 版本 0.6.0 开始,不再需要使用 GMA SDK 的分叉版本。请参阅下方的矩阵,以确定与我们的 Freestar SDK 兼容的 GMA SDK 版本。如果可能的话,始终建议使用最新版本。

FSAdSDK 版本 GMA SDK 版本 未分叉? Podfile
~> 0.6.4 7.53.1 ☑️ pod 'Google-Mobile-Ads-SDK', '7.53.1'
~> 0.6.3 7.50.0 ☑️ pod 'Google-Mobile-Ads-SDK', '7.50.0'
~> 0.5 7.50.0 pod 'Google-Mobile-Ads-SDK', :git => 'https://github.com/freestarcapital/GMA-iOS-SDK.git', :tag => '7.50.0'
~> 0.4 7.41.0 pod 'Google-Mobile-Ads-SDK', :git => 'https://github.com/freestarcapital/GMA-iOS-SDK.git', :tag => '7.41.0'
<= 0.3.2 7.24.1 ☑️ pod 'Google-Mobile-Ads-SDK', '~> 7.24.1'

最低要求

  • 运行 macOS 10.13.2 或更高版本的 Mac
  • XCode 9
  • Cocoapods
  • 设备
    • iOS 9.0+

入门指南


以下是要下载并将 SDK 链接到您的项目的必要基本步骤。尽管有多种方法,但我们强烈建议您使用 Cocoapods 方法。

使用 Cocoapods

Freestar Ad SDK 通过 Cocoapods 提供,这是 iOS 项目的实际依赖项管理器。以下是下载并将 SDK 集成到您项目中的必要步骤。强烈建议使用 Cocoapods,因为这是使用我们的 SDK 快速启动和运行的最快方法。

1. 更新您的 Podfile,以下是一个示例

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '9.0'
use_frameworks!

target "YourAppTarget" do
    pod 'FSAdSDK/Banner'
    pod 'Google-Mobile-Ads-SDK', '7.53.1'
end

2. 运行 "pod install" 或 "pod update"。
3. SDK 链接工作完成了!要继续,请跳到本文件的 代码集成 部分,按照那些步骤完成集成过程。

或手动,使用 Git

请联系我们获取详细信息。

代码集成

为了能够展示来自所有需求源的广告,正确将 SDK 集成到您的应用程序中非常重要。

横幅广告

要查看工作示例,此代码仓库中包含一个示例横幅广告应用项目。请参阅横幅广告示例

1.AppDelegate.didFinishLaunchingWithOptions()中使用Freestar注册您的应用

import UIKit
import FSAdSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?    

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    ...

    // Freestar app registration
    FSRegistration.register() // ensure your bundle identifier
    return true
}

2.ViewController.viewDidLoad()中创建您的横幅广告对象

import UIKit
import FSAdSDK
import GoogleMobileAds

class ViewController: UIViewController {    
    let adUnitID = "/your_dfp_adunit_ID/placement_id"   // DFP Ad Unit ID
    let adIdentifier = "your_freestar_ad_identifier"    // Freestar Ad Identifier
    var bannerView: (UIView & FSBanner)?                // banner

    override func viewDidLoad() {
        super.viewDidLoad()

        bannerView = FSAdProvider.createBanner(withIdentifier: adIdentifier,
                                               size: kGADAdSizeBanner,       
                                               adUnitId: adUnitID,
                                               registrationDelegate: self,
                                               eventHandler:nil)

        bannerView?.rootViewController = self
        let request: DFPRequest? = DFPRequest()
        bannerView?.load(request)
        addToView(bannerView) // for layout, see banner sample
    }
    ...
}

3. 可选,为接收注册状态,实现FSRegistrationDelegate。如果是这样,请记住将self传递给广告提供商便利构造函数作为registrationDelegate参数。

class ViewController: UIViewController, FSRegistrationDelegate {
  ...
  func didRegister(forIdentifier identifier: String) {
    print("didRegister: \(identifier)")
  }

  func didFailToRegister(forIdentifier identifier: String) {
    print("didFailToRegister: \(identifier)")
  }
}
横幅广告自动刷新、暂停和恢复

1. 可选,要暂停或恢复横幅广告自动刷新,请调用resumeRefresh()pauseRefresh()。在横幅广告仍然在窗口中但位于其他视图之后的情况下,建议暂停自动刷新。同时,确保在适当的时候恢复刷新。

override func viewWillDisappear(_ animated: Bool) {
  bannerView!.pauseRefresh()
}

override func viewWillAppear(_ animated: Bool) {
  bannerView!.resumeRefresh()
}
插屏广告

要查看工作示例,此代码仓库中包含一个示例插屏广告应用项目。请参阅插屏广告示例

1.AppDelegate.didFinishLaunchingWithOptions()中使用Freestar注册您的应用

import UIKit
import FSAdSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  var window: UIWindow?    

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  ...

  // Freestar app registration
  FSRegistration.register() // ensure your bundle identifier
  return true
}

2.ViewController.viewDidLoad()中创建您的插屏广告对象

import UIKit
import FSAdSDK
import GoogleMobileAds

class ViewController: UIViewController {
  let adUnitID = "/your_dfp_adunit_ID/placement_id"   // DFP Ad Unit ID
  let adIdentifier = "your_freestar_ad_identifier"    // Freestar Ad Identifier
  var interstitial: FSInterstitial?  // interstitial

  override func viewDidLoad() {
     super.viewDidLoad()

     interstitial = FSAdProvider.createInterstitial(withIdentifier: adIdentifier, adUnitId: adUnitID, registrationDelegate: nil, eventHandler: nil)
     let request: DFPRequest? = DFPRequest()
     interstitial?.load(request)
   }
   ...
}

3. 准备使用时,请显示您的插屏广告。请确保您在主线程上调用此方法。

class ViewController: UIViewController {

 func someMethod() {
   ...
   self.presentInterstitial()  // main thread
 }

 func presentInterstitial() {
      if (interstitial!.isReady) {
          interstitial?.present(fromRootViewController: self)
      }
  }
  ...
}

4. 可选,为接收注册状态,实现FSRegistrationDelegate。如果是这样,请记住将self传递给广告提供商便利构造函数作为registrationDelegate参数。

class ViewController: UIViewController, FSRegistrationDelegate {
...
  func didRegister(forIdentifier identifier: String) {
    print("didRegister: \(identifier)")
  }

  func didFailToRegister(forIdentifier identifier: String) {
    print("didFailToRegister: \(identifier)")
  }
}

事件处理器

通常情况下,需要接收广告事件回调,例如在收到广告或广告加载失败时。这些回调通过事件处理器方法参数(参见图引用指南)处理,与FSAdProvider.createBannerFSAdProvider.createInterstitial相关。

警告:开发者自行决定如何处理这些事件,以下代码片段仅是通用示例。请不要直接将这些代码片段添加到代码中,而应进行修改。

横幅事件处理器

eventHandler: { [weak self] (methodName: String!, params: [ String : Any]) in...

事件处理器闭包表达式传递了两个参数,一个是方法名(字符串类型),另一个是参数信息(键值对类型)。以下是一些常见的广告事件及其处理方法的示例。

adViewDidReceiveAd

为了响应用户接收广告,事件处理器必须检查是否有匹配的方法名参数。在这个例子中,方法是名为 adViewDidReceiveAd:。以下是一个示例,当接收到广告时将其添加到父视图中。

bannerView = FSAdProvider.createBanner(withIdentifier: adIdentifier,
                                       size: kGADAdSizeMediumRectangle,
                                       adUnitId: adUnitID,
                                       rootViewController: self,
                                       registrationDelegate: nil,
                                       eventHandler: { [weak self] (methodName: String!, params: [ String : Any]) in
                                            // create a reference to the banner
                                            let banner: UIView? = params["bannerView"] as? UIView
                                            if (methodName == DFPEventNameBanner.adViewDidReceiveAd.rawValue) {
                                                // convenience method to add the banner to self.view
                                                self?.addToView(banner)
                                            }
                                    })

横幅广告事件矩阵

以下图表列出了所有与横幅相关的广告事件及其描述。

广告事件 常量 参数键(s) 描述
-adViewDidReceiveAd DFPEventNameBannerAdViewDidReceiveAd bannerView 广告请求成功接收广告。
-adView:didFailToReceiveAdWithError DFPEventNameBannerAdViewDidFailToReceiveAd bannerView, error 广告请求失败,或者没有可用的广告。
-adViewWillPresentScreen DFPEventNameBannerAdViewWillPresentFullScreen bannerView 用户点击后将展示全屏视图以响应用户点击。
-adViewWillDismissScreen DFPEventNameBannerAdViewWillDismissScreen bannerView 全屏视图将关闭。
-adViewDidDismissScreen DFPEventNameBannerAdViewDidDismissScreen bannerView 全屏视图已关闭。
-adViewWillLeaveApplication DFPEventNameBannerAdViewWillLeaveApplication bannerView 用户点击将打开另一个应用,使当前应用进入后台。

横幅广告事件矩阵

广告事件(方法名) 常量 参数键(s) 描述
-interstitialDidReceiveAd DFPEventNameInterstitialDidReceiveAd interstitial 横幅广告请求成功。
-interstitial:didFailToReceiveAdWithError DFPEventNameInterstitialDidFailToReceiveAdWithError interstitial, error 横幅广告请求完成,但无横幅可展示。
-interstitialWillPresentScreen DFPEventNameInterstitialWillPresentScreen interstitial 横幅将动画显示在屏幕上。
-interstitialDidFailToPresentScreen DFPEventNameInterstitialDidFailToPresentScreen interstitial 横幅显示失败。
-interstitialWillDismissScreen DFPEventNameInterstitialWillDismissScreen interstitial 横幅将被动画移出屏幕。
-interstitialDidDismissScreen DFPEventNameInterstitialDidDismissScreen interstitial 横幅广告已从屏幕上消失。
-interstitialWillLeaveApplication DFPEventNameInterstitialWillLeaveApplication interstitial 由于用户点击了将启动另一个应用的广告,应用程序将进入后台或终止。

定向参数

为了能够支持我们对各种需求合作伙伴的定向,使用Prebid Mobile API非常重要。通过使用这个API,开发者可以确保所有与Prebid相关的广告对象都将设置定向。

用户位置

默认情况下,iOS Prebid Mobile SDK不会自动发送位置信息。为了使Prebid Mobile能够使用位置信息进行定向,应用程序开发者必须显式地将位置信息传递给Prebid Mobile API。

注意:开发者应确保在共享位置信息前获得足够的同意。开发者可以控制SDK是否收集和发送位置信息。

在这个片段中,我们创建了一个位置管理器属性,定义了一个setupLocationManager()方法并实现了CLLocationManagerDelegate代理。

import UIKit
import CoreLocation
import PrebidMobileFS

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, CLLocationManagerDelegate {
  var locationManager: CLLocationManager = CLLocationManager()

  ...

  func setupLocationManager() {
    // guard to ensure minimum iOS level
    guard #available(iOS 8, *) else {
        return
    }

    locationManager.delegate = self
    locationManager.distanceFilter = kCLDistanceFilterNone
    locationManager.desiredAccuracy = kCLLocationAccuracyKilometer
    locationManager.requestWhenInUseAuthorization()
    locationManager.startUpdatingLocation()
  }


  func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
    PBTargetingParams.sharedInstance().location = locations.last
  }
}

年龄和性别

import UIKit
import PrebidMobileFS

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  var window: UIWindow?    

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {\
    PBTargetingParams.sharedInstance().age = 24;
    PBTargetingParams.sharedInstance().gender = PBTargetingParamsGender.female;
  }
}

iTunes Id覆盖

目前,需求合作伙伴使用iTunes Track Id来标识iOS应用。通常,iTunes Id是自动设置的(0.3.0+),但是这提供了一种覆盖iTunes Id的方法。

import UIKit
import PrebidMobileFS

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  var window: UIWindow?    

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    PBTargetingParams.sharedInstance().itunesID = "123456789"
  }
}

用于AdX的不适宜内容

为了避免被AdX列入黑名单,如果应用中因GAM(Google Ad Manager)的内容限制指南而有不适宜内容,则必须传递一个额外的定向参数。

  let request = DFPRequest()
  request.customTargeting = ["campaign" : "NSFW"]

GDPR 同意

Prebid Mobile 支持以下 IAB 的 GDPR 建议:GDPR 透明度与同意框架。关于 Prebid Mobile 对于 GDPR 的一般概述,请参阅 Prebid Mobile 指南:欧洲广告库存及提供通知、透明度和选择

启用或禁用提供同意的能力。默认情况下,GDPR 设置为 false

  PBTargetingParams.sharedInstance().subjectToGDPR = true

注意:如果 GDPR 主题设置为 true,则需要设置同意字符串。

  PBTargetingParams.sharedInstance().gdprConsentString = "sample_consent_string"

Prebid Mobile 还会检查指定的 IAB NSUserDefaults 键中是否存在这些值。如果这些对象中也设置了这些值,它们将随 OpenRTB 请求对象传递。

自定义关键词

自定义关键词用于将任意的键/值对附加到广告调用中。使用键/值对将用户添加到段中,如下所示

  PBTargetingParams.sharedInstance().setUserKeywords("foo", withValues: ["bat"])
  PBTargetingParams.sharedInstance().setUserKeywords("foo", withValues: ["bee"])
  PBTargetingParams.sharedInstance().setUserKeywords("foo", withValues: ["bar"])

如果为现有关键词设置了值,则该键的值将用新值替换。在前面的示例中,键 foo 将有一个值为 bar,这是与该键关联的最新值。

您可以使用以下 API 将键设置为具有值数组的键

  PBTargetingParams.sharedInstance().setUserKeywords("foo", withValues: ["bat", "bee", "bar"])

前面的命令将导致以下请求 JSON 主体结构

user = {
  keywords = "foo=bat,foo=bee,foo=bar";
};

分析

默认情况下禁用 Prebid 分析。但是,如果需要详细的报告,请在您的 AppDelegate 中使用 PBAnalyticsManager 启用分析。以下是如何启用分析的示例

import FSAdSDK

...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  FSAdSDK.setAnalyticsEnabled(true)  
}

调谐

要启用对第三方广告网络的代理支持,请遵循以下 Cocoapods 集成指南。每个代理伙伴都需要在 Podfile 中添加一个条目。下面的代理适配器模块已与我们的 SDK 进行了兼容性测试。不需要额外的代码集成。

注意:另外,您还可以将自定义中介适配器添加到项目中,但需要注意 impression 跟踪和广告位大小的正确设置。

MoPub

要启用您的项目中的 MoPub 需求(通过中介),请将此条目添加到您的 Podfile 中

target "YourAppTarget" do
  pod 'FSAdSDK/Mediation/MoPub'
  ...
end

带 MoPub 的完整 Podfile 示例

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '9.0'
use_frameworks!

target "YourAppTarget" do
    pod 'FSAdSDK/Mediation/MoPub'
    pod 'FSAdSDK/Banner'
    pod 'Google-Mobile-Ads-SDK', '7.53.1'
end

Facebook Audience Network

要启用您的项目中 Facebook Audience Network 需求(通过中介),请将此条目添加到您的 Podfile 中

target "YourAppTarget" do
  pod 'FSAdSDK/Mediation/Facebook'
  ...
end

带 Facebook 的完整 Podfile 示例

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '9.0'
use_frameworks!

target "YourAppTarget" do
    pod 'FSAdSDK/Mediation/Facebook'
    pod 'FSAdSDK/Banner'
    pod 'Google-Mobile-Ads-SDK', '7.53.1'
end

参考指南

SDK 的 API 参考指南以 HTML 格式存放在此存储库中。请参阅参考指南


问题

如果您有任何问题,请毫不犹豫地发电子邮件给我们.
谢谢。