目录
开始之前
- Vungle iOS SDK v. 5.x 仅支持 iOS 8+。
- Vungle iOS SDK v. 5.x 支持 32 位和 64 位的应用程序。
- 您需要拥有一个 Vungle 帐户来进行集成。如果您还没有帐户,请在开始之前先创建一个。
- 我们最新发布的 iOS SDK 版本(自 4.0.8 版本以来)支持最新的 Xcode 8.0。请确保您使用 Xcode 8.0 或更高版本,以便顺利集成。
- 这里引用的源代码可以在我们的公共 GitHub 存储库中获得。
步骤 1:添加 Vungle 框架到您的 Xcode 项目
添加 VungleSDK.framework 到您的项目
有两种方法可以将 Vungle 添加到 Xcode 项目中:使用 Cocoapods 或手动集成。
Cocoapods
Vungle SDK 可通过 Cocoapods 提供。通过添加以下几行到您项目的配置文件,添加 Vungle 到您的项目。
pod "VungleSDK-iOS", "5.x"
之后,pod install 快速运行应当为您的项目更新到最新版本的 iOS SDK。此时,您可以跳到“步骤 2:删除 iOS Status Bar”。
手动集成
下载 Vungle SDK v5.x。如果您从先前版本的 Vungle SDK 进行更新,请在添加新的 SDK 之前彻底删除VungleSDK.framework
目录。然后找到解压后的文件,并将VungleSDK.framework
目录拖放到 Frameworks 下的 Xcode 中。请务必作为一个组(黄色文件夹)来添加VungleSDK.framework
文件夹,而不是作为参考(蓝色文件夹)。
添加其他必需的框架
Vungle SDK 需要您链接一些其他本地框架到您的项目,因此请在项目导航中点击您的项目,然后前往通用 → 链接的框架和库。许多这些框架已经包括在内,因为它们是大多数 Xcode 项目的默认框架,但请务必添加以下任何尚未包含在内的框架:
AdSupport.framework
AudioToolbox.framework
AVFoundation.framework
CFNetwork.framework
CoreGraphics.framework
CoreMedia.framework
Foundation.framework
-
libz.dylib
orlibz.tbd
-
libsqlite3.dylib
orlibsqlite3.tbd
MediaPlayer.framework
QuartzCore.framework
StoreKit.framework
SystemConfiguration.framework
UIKit.framework
-
WebKit.framework
注意:如果您WebKit.framework
将 iOS 7 作为部署目标,请将状态设置为“可选”。
确保 VungleSDK 框架出现在链接的框架和库下面。
添加“ObjC”链接器标记
请在项目导航中点击您的项目,然后前往构建设置 → 链接 → 其他链接器标记。添加 ObjC 到其他链接器标记。
步骤 2:删除 iOS 状态栏
尽管这不是必需的步骤,但我们建议采取该步骤以确保 Vungle 的广告互动和演示可以顺利进行。如要删除状态栏,请打开 Info.plist
, 添加关键的查看基于控制器的状态栏外观,并将其设置为 No。
步骤 3:添加代码
创建桥接头文件
- 在您的项目中创建新的 Objective-C 文件(文件 → 新建 → 文件 [Objective-C 文件])。
- Xcode 将询问您是否要在 Objective-C 和 Swift 之间创建桥接头文件。请接受此提示。
- 删除新 Objective-C 文件
(${YOURPROJ}-Bridging-Header.m)
,但保留桥接头文件${YOURPROJ}-Bridging-Header.h
。 - 在桥接头文件中,通过以下添加导入 Vungle SDK:
#import <VungleSDK/VungleSDK.h>
初始化 SDK
注:系统自动为每个应用程序创建一个默认广告位置。您必须在初始化步骤中提供其广告位置参考 ID,无论您是否计划利用该广告位置功能。如果您创建多个广告位置,请提供所有的参考 ID。
一旦您的应用启动,尽快初始化 SDK,以便给予 SDK 足够的时间来为自动缓存的广告位置缓存广告。您将需要应用 ID 和您想在应用内使用的所有广告位置参考 ID(包括有效的和无效的)来初始化 SDK。您可以在 Vungle 仪表板中找到这些 ID(请参阅 在 Vungle 仪表板中设置广告位置)。
- (BOOL)startWithAppId:(nonnull NSString *)appID placements:(nonnull NSArray *)placements error:(NSError **)error;
示例代码:
let appID = "Your_AppID_Here";
var placementIDsArray:Array<String> = ["<Your_PlacementID_1>", "<Your_PlacementID_2>", "<Your_PlacementID_3>"];
var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.start(withAppId: appID, placements: placementIDsArray)
}
catch let error as NSError {
print("Error while starting VungleSDK : \(error.domain)")
return;
}
一旦 SDK 成功初始化,以下回调方法将被调用:
- (void)vungleSDKDidInitialize;
请参阅本文章的“委派回调”部分。
您还可以通过以下属性来检查 SDK 初始化的状态:
@property (atomic, readonly, getter=isInitialized) BOOL initialized;
SDK 初始化之后,它将自动为您在 Vungle 仪表板中选为自动缓存的广告位置缓存广告。我们建议选择观看次数最多的广告位置用于自动缓存。
一旦广告缓存成功,拥有匹配您的自动缓存广告位置的广告位置参考 ID 的 vungleAdPlayabilityUpdate
回调方法将被调用。(请参阅本文章的“检查广告位置的广告可用性”部分。)
为广告位置加载广告
对于自动缓存广告位置之外的广告位置,请调用 loadPlacementWithID
方法来加载广告。
var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.loadPlacement(withID: <Your_PlacementID>)
}
catch let error as NSError {
print("Unable to load placement with reference ID :\(<Your_PlacementID>), Error: \(error)")
return
}
请参阅本文章的“检查广告位置的广告可用性”部分。
检查广告位置的广告可用性
一旦 SDK 完成一个广告位置的广告缓存,以下回调方法将被调用:
- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(nullable NSString *)placementID;
示例代码:
func vungleAdPlayabilityUpdate(_ isAdPlayable: Bool, placementID: String?){
if (placementID == <Your_PlacementID>) {
self.playButtonPlacement1.enabled = isAdPlayable;
}
}
注意:对于自动缓存的广告位置,只有在有一个广告可用时,此回调方法才将被调用:SDK 将会一直为自动缓存的广告位置请求广告。对于其他广告位置,此回调方法将在“加载失败”(在这种情况下,isAdPlayable
返回“NO”)时被调用。您还可以通过以下属性来检查广告位置的广告可用性:
- (BOOL)isAdCachedForPlacementID:(nonnull NSString *)placementID;
播放广告
在您确定广告位置的广告已准备好时,您可以使用以下方法来播放广告:
- (BOOL)playAd:(UIViewController *)controller options:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:( NSError *__autoreleasing _Nullable *_Nullable)error;
示例代码:
var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.playAd(self, options: nil, placementID: kVungleTestPlacementID01)
}
catch let error as NSError {
print("Error encountered playing ad: + \(error)");
}
委派回调
您可以通过 VungleSDKDelegate
来接收来自 SDK 的回调。 在通知您 SDK 事件的委托中有四种回调方法。
如要附加和分离您的委托,您可以使用:
var sdk:VungleSDK = VungleSDK.shared()
// Attach
sdk.delegate = <yourDelegateInstance> as VungleSDKDelegate
// Detach
sdk.delegate = nil
注:为了避免内存泄漏,一旦不再需要注册的委托时,请记得将其清除。
当 SDK 即将播放视频广告时,以下方法将被调用。这是暂停广告情节、声音效果、动画等的极好位置。
- (void)vungleWillShowAdForPlacementID:(nullable NSString *)placementID;
当 SDK 即将关闭广告时,以下方法将被调用。这是奖励用户和恢复广告情节、声音效果、动画等的极好位置。
- (void)vungleWillCloseAdWithViewInfo:(VungleViewInfo *)info placementID:(NSString *)placementID;
VungleViewInfo
包括以下属性,供您检查广告播放的结果:
@interface VungleViewInfo : NSObject
//代表一个布尔值,即视频是否可以被认为得到了完整播放。
@property (nonatomic, readonly) NSNumber *completedView;
//用户观看视频的时间(以秒为单位)。
@property (nonatomic, readonly) NSNumber *playTime;
//代表一个布尔值,即用户是否点击了下载按钮。
@property (nonatomic, readonly) NSNumber *didDownload;
@end
当 SDK 更改了广告可用性状态时,以下方法将被调用。isAdPlayable
布尔值表示一个特定 placementID
的新可播放性。
- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID;
请参阅本文章的“检查广告位置的广告可用性”部分。
一旦 SDK 成功初始化,以下方法将被调用:
- (void)vungleSDKDidInitialize;
自定义选项
使用这些选项来为重播自定义广告体验。
注意:奖励广告有些情况下是指激励广告;这两个术语始终指的是同一类广告。在 SDK 代码和我们的报告 API 中,我们使用术语“激励”。
选项键 |
默认值/类型 |
说明 |
|
自动旋转
NSString 代表一个具有方向的位掩码 |
设置广告的方向。我们建议您允许广告自动旋转,即使您的应用程序处于纵向。这样,用户可以选择观看全尺寸视频,从而获得更好的用户体验。您可以通过在视图控制器级别(而不是项目级别)设置方向来实现此目的。 |
|
无
|
设置您的用户 ID。这个值将被传给 Vungle 服务器,然后再通过服务器到服务器回调系统发送到您的服务器,如果有一个广告位置被设为“奖励”。 |
|
无
|
在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框标题的字符串。 |
|
“确定要跳过此广告吗?如果这么做,您可能无法获得奖励”
|
在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框正文文本的字符串。 |
|
“关闭”
|
在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框关闭按钮文本的字符串标题。 |
|
“继续”
|
在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框关闭按钮文本的字符串标题。 |
示例代码:
let options: NSDictionary = NSDictionary(dictionary: [VunglePlayAdOptionKeyUser: "test_user_id",
VunglePlayAdOptionKeyIncentivizedAlertBodyText: "If the video isn't completed you won't get your reward!Are you sure you want to close early?",
VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText: "Close",
VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText: "Keep Watching",
VunglePlayAdOptionKeyIncentivizedAlertTitleText: "Careful!"])
do {
try self.sdk.playAd(self, options: (options as![AnyHashable : Any]), placementID: PlacementID)
}
catch let error as NSError {
print("Error encountered playing ad: + \(error)");
}
静音选项
Vungle SDK 示例提供以静音方式播放广告的选项。您可以在发布 playAd()
之前将静音属性设为 true。
示例代码:
var sdk:VungleSDK = VungleSDK.shared()
sdk.muted = true
注:此选项仅适用于标准广告类型。动态模板广告的静音选项可在仪表板上进行配置。
调试
如果您需要 SDK 信息,您要以使用此属性来获取:
- (NSDictionary *)debugInfo;
如果您想要 SDK 输出日志,请使用以下方法:
- (void)setLoggingEnabled:(BOOL)enable;
VungleSDKLogger 协议
@protocol VungleSDKLogger
- (void)vungleSDKLog:(NSString*)message;
@end
VungleSDK 单例模式会将日志记录事件发送到任何符合 VungleSDKLogger 协议的附加类。日志事件包含 NSString 值,该值也将被打印到控制台(如果日志记录已被启用)。如要附加记录器,请使用以下命令:
- (void)attachLogger:(id<VungleSDKLogger>)logger;
如上所述,务必从 Vungle SDK 清除附加的记录器。可以使用以下方法清除记录器:
- (void)detachLogger:(id<VungleSDKLogger>)logger;
评论