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

Avatar
ZendeskVungle
关注

目录

开始之前

  • 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;

还有其它问题？提交请求

评论