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.createBanner或FSAdProvider.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 格式存放在此存储库中。请参阅参考指南。
问题
如果您有任何问题,请毫不犹豫地发电子邮件给我们.
谢谢。