Vungle - iOS SDK v. 5 (Swift) 入门

目录

开始之前

  • 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 or libz.tbd
  • libsqlite3.dylib or libsqlite3.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:添加代码

创建桥接头文件

  1. 在您的项目中创建新的 Objective-C 文件(文件  新建  文件 [Objective-C 文件])。
  2. Xcode 将询问您是否要在 Objective-C 和 Swift 之间创建桥接头文件。请接受此提示。
  3. 删除新 Objective-C 文件 (${YOURPROJ}-Bridging-Header.m),但保留桥接头文件 ${YOURPROJ}-Bridging-Header.h
  4. 在桥接头文件中,通过以下添加导入 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 中,我们使用术语“激励”。

选项键

默认值/类型

说明

VunglePlayAdOptionKeyOrientations

自动旋转

UIInterfaceOrientationMaskAll

NSString 代表一个具有方向的位掩码

设置广告的方向。我们建议您允许广告自动旋转,即使您的应用程序处于纵向。这样,用户可以选择观看全尺寸视频,从而获得更好的用户体验。您可以通过在视图控制器级别(而不是项目级别)设置方向来实现此目的。

VunglePlayAdOptionKeyUser

NSString

设置您的用户 ID。这个值将被传给 Vungle 服务器,然后再通过服务器到服务器回调系统发送到您的服务器,如果有一个广告位置被设为“奖励”。

VunglePlayAdOptionKeyIncentivizedAlertTitleText

NSString

在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框标题的字符串。

VunglePlayAdOptionKeyIncentivizedAlertBodyText

“确定要跳过此广告吗?如果这么做,您可能无法获得奖励”

NSString

在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框正文文本的字符串。

VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText

“关闭”

NSString

在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框关闭按钮文本的字符串标题。

VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText

“继续”

NSString

在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框关闭按钮文本的字符串标题。

示例代码:

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;

还有其它问题?提交请求

评论