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

确保 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;

自定义选项

使用这些选项来为重播自定义广告体验。

选项键

默认值/类型

说明

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;

还有其它问题？提交请求

评论