Vungle - iOS SDK v. 6 (Swift) 入门指南

目录

GDPR:推荐实施方法

《通用数据保护条例》(GDPR) 将于 5 月 25 日在欧盟生效。为了遵守 GDPR,开发者有以下两种选择。

  • 选项 1(推荐):发布商从用户级别控制 GDPR 的同意流程,然后将用户的选择传达给 Vungle。为此,开发人员可以使用自己的机制来收集用户的同意信息,然后使用 Vungle API 更新或查询用户的同意状态。若需了解详细信息,请参阅“GDPR 推荐实施方法说明”部分。

  • 选项 2:允许 Vungle 处理相关需求。Vungle 在向欧洲用户播放广告之前会显示征求同意的对话框,并记住用户的同意或拒绝选择,以用于后续的广告。

开始之前

  • Vungle iOS SDK v. 6.x 仅支持 iOS 8+。
  • Vungle iOS SDK v. 6.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 获取。在项目的 Podfile 中添加以下行,即可将 Vungle 添加到项目中。

 pod "VungleSDK-iOS", "6.x"

之后,Pod install 快速运行应当为您的项目更新到最新版本的 iOS SDK。此时,您可以跳到“步骤 2:删除 iOS 状态栏”。

手动集成

下载 Vungle SDK v6.x。如果使用先前版本 Vungle SDK 进行更新,请先彻底删除 VungleSDK.framework 目录,然后再添加新 SDK。找到解压后的文件,然后将 VungleSDK.framework 目录拖动到 Frameworks 下的 Xcode 中。添加 VungleSDK.framework 文件夹时,请务必将其作为一个组(黄色文件夹),而不是作为参考(蓝色文件夹)。

添加其他必需的框架

Vungle SDK 需要将部分其他本地框架与您的项目进行链接,因此,请在“项目导航”中单击相应的项目,然后前往“通用 → 链接的框架和库”。以下许多框架已经包括在内,并已作为大多数 Xcode 项目的默认框架,但请务必添加以下所有尚未包括在内的框架:

  • AdSupport.framework
  • AudioToolbox.framework
  • AVFoundation.framework
  • CFNetwork.framework
  • CoreGraphics.framework
  • CoreMedia.framework
  • Foundation.framework
  • libz.dyliblibz.tbd
  • libsqlite3.dyliblibsqlite3.tbd
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework
  • UIKit.framework
  • WebKit.framework
    注意:如需部署到 iOS 7 系统,请将 WebKit.framework 状态设为“可选”。

确保 VungleSDK 框架显示在“链接的框架和库”下面。

添加“-ObjC”链接器标记

“项目导航”中单击相应的项目,前往“构建设置 → 链接 → 其他链接器标记”。将 -ObjC 添加到“其他链接器标记”

步骤 2:删除 iOS 状态栏

尽管这不是必需步骤,但我们建议您删除 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

启动应用程序后,应立即初始化 SDK;如果正在使用自动缓存的广告位置,则此操作会给 SDK 提供足够时间来为该自动缓存的广告位置缓存广告。初始化 SDK 需要 App ID。App 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 管理面板中将某个广告位置选择为自动缓存,SDK 将自动缓存该广告位置的广告。如果使用了此功能,我们建议选择观看次数最多的广告位置用于自动缓存。

广告被成功缓存后,即会调用其广告位置参考 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;

当 SDK 关闭广告后,会调用以下方法:

- func vungleDidCloseAd(with info: VungleViewInfo, placementID: String);

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

autorotate

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

注意:此选项仅适用于标准广告类型。Dynamic Template 广告的静音选项可以在管理面板中配置。

调试

如需 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;

GDPR 推荐实施方法说明

要使用 Vungle API 来更新或查询用户同意状态(参见“GDPR:推荐实施方法”选项 1 中的推荐),请使用以下函数:

//This function returns the current consent status recorded in SDK. If status is not known return 0. sdk = VungleSDK.shared() sdk?.getCurrentConsentStatus() //This function sets the current consent status recorded in the SDK sdk = VungleSDK.shared() sdk?.update(status: VungleConsentStatus) 

VungleConsentStatus 是一个包含两种状态的枚举:

  • 已接受 (VungleConsentStatus.accepted)
  • 已拒绝 (VungleConsentStatus.denied)
还有其它问题?提交请求

评论