Vungle - iOS SDK v. 5 入门

Avatar
Julia Randall
关注

目录

开始之前

  • Vungle iOS SDK v. 5 支持 iOS 8+。
  • Vungle iOS SDK v. 5 已使用 iOS 11 beta/GM Seed 进行测试。
  • Vungle iOS SDK v. 5 支持 32 位和 64 位的应用程序。
  • 您需要拥有一个 Vungle 帐户来进行集成。如果您还没有帐户，请在开始之前先创建一个。
  • iOS SDK 支持 Xcode 8.0 和 9.0。请确保您使用 Xcode 8.0 或更高版本，以便顺利集成。

步骤 1：添加 Vungle 框架到您的 Xcode 项目

添加 VungleSDK.framework 到您的项目

有两种方法可以将 Vungle 添加到 Xcode 项目中：使用 Cocoapods 或手动集成。

Cocoapods

Vungle SDK 可通过 Cocoapods 提供。通过添加以下几行到您项目的配置文件，添加 Vungle 到您的项目。

 pod "VungleSDK-iOS", "5.3.0"

之后，pod install 快速运行应当为您的项目更新到最新版本的 iOS SDK。此时，您可以跳到“步骤 2：删除 iOS Status Bar”。

手动集成

下载 Vungle SDK v5。如果您从先前版本的 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
  • 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：添加代码

初始化 SDK

注：系统自动为每个应用程序创建一个默认广告位置。您必须在初始化步骤中提供其广告位置参考 ID，无论您是否计划利用该广告位置功能。如果您创建多个广告位置，请提供所有的参考 ID。

一旦您的应用程序启动，尽快初始化 SDK，以便给予 SDK 足够的时间来为自动缓存的广告位置缓存广告。您将需要应用程序 ID 和您想在应用程序里面使用的所有广告位置参考 ID（包括有效的和无效的）来初始化 SDK。您可以在 Vungle 仪表板中找到这些 ID（请参阅 在 Vungle 仪表板中设置广告位置）。

- (BOOL)startWithAppId:(nonnull NSString *)appID placements:(nonnull NSArray *)placements error:(NSError **)error;

示例代码：

#import <VungleSDK/VungleSDK.h>
...
NSError* error;
NSString* appID = @"Your_AppID_Here";
NSArray* placementIDsArray = @[@"<Your_PlacementID_1>", @"<Your_PlacementID_2>", @"<Your_PlacementID_3>"];
VungleSDK* sdk = [VungleSDK sharedSDK];
[sdk startWithAppId:appID placements:placementIDsArray error:&error];

一旦 SDK 成功初始化，以下回调方法将被调用：

- (void)vungleSDKDidInitialize;

请参阅本文章的“委派回调”部分。

您还可以通过以下属性来检查 SDK 初始化的状态：

@property (atomic, readonly, getter=isInitialized) BOOL initialized;

SDK 初始化之后，它将自动为您在 Vungle 仪表板中选为自动缓存的广告位置缓存广告。我们建议选择观看次数最多的广告位置用于自动缓存。

一旦广告缓存成功，拥有匹配您的自动缓存广告位置的广告位置参考 ID 的 vungleAdPlayabilityUpdate 回调方法将被调用。（请参阅本文章的“检查广告位置的广告可用性”部分。）

为广告位置加载广告

对于自动缓存广告位置之外的广告位置，请调用 loadPlacementWithID 方法来加载广告。

- (BOOL)loadPlacementWithID:(NSString *)placementID error:(NSError **)error;

示例代码：

NSError* error;
VungleSDK* sdk = [VungleSDK sharedSDK];
[sdk loadPlacementWithID:"<Your_PlacementID>" error:&error];

请参阅本文章的“检查广告位置的广告可用性”部分。

检查广告位置的广告可用性

一旦 SDK 完成一个广告位置的广告缓存，以下回调方法将被调用：

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(nullable NSString *)placementID; 

示例代码：

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID {
    if([placementID isEqualToString:@"<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;

示例代码：

VungleSDK* sdk = [VungleSDK sharedSDK];
NSError *error;
[self.sdk playAd:self options:nil placementID:@"<Your_PlacementID_1>" error:&error];
if (error) {
    NSLog(@"Error encountered playing ad: %@", error);
}

Flex Feed 广告

Vungle SDK v.5.3 现在支持 Flex Feed 广告。这是首个不需要全屏的广告格式；相反，发布商在其应用程序内确定广告容器的确切维度和位置。这些广告容器可以位于集合视图或表视图内。

加载 Flex Feed 广告

加载 Flex Feed 广告与加载全屏广告相同；但是，必须将广告位置配置为支持 Flex Feed。请联系您的 Vungle 客户经理来为广告位置启用 Flex Feed。

显示 Flex Feed 广告

显示 Flex Feed 广告与显示全屏广告不同。使用 Flex Feed 广告，您必须先为广告创建容器。此容器是一个UIView.您可以将上述UIView 放在屏幕上的任何位置。广告将缩放到容器的任何尺寸，但是请记住，如果分辨率非常低，广告可视度会比较低。然后您必须调用addAdViewToView 函数来将容器与 Flex Feed 广告关联。

函数概览：


/**
 * Pass in an UIView which acts as a container for the ad experience. This view container may be placed in random positions.
 * @param publisherView container view in which an ad will be displayed
 * @param options A reference to an instance of NSDictionary with customized ad playback options
 * @param placementID The placement defined on the Vungle dashboard
 * @param error An optional double reference to an NSError. In case this method returns `NO` it will be non-nil
 * @return YES/NO in case of success/error while presenting an AdUnit
 */
- (BOOL)addAdViewToView:(UIView *)publisherView withOptions:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:( NSError *__autoreleasing _Nullable *_Nullable)error;

示例代码：


NSError *error;
NSDictionary *options = @{};
VungleSDK* sdk = [VungleSDK sharedSDK];
[sdk addAdViewToView:_FlexFeedViewArea withOptions:options placementID: error:&error];
if (error) 
{
        NSLog(@"Error encountered while playing an ad: %@", error);
}

关闭 Flex Feed 广告

由于 Flex Feed 广告的性质，用户可以在不关闭广告的情况下停止观看视频。因此，您必须在广告不再出现在屏幕上时告知 SDK 摒弃该广告。若要实现此目的，请调用finishedDisplayingAd 函数。

函数概览：


/**
 * This method must be called when the publisher is confident that they are finished displaying the ad unit.
 * This signals to the SDK that a new ad may be fetched or a different ad may be displayed. This will
 * be called in conjunction with `addViewToView:containedInViewController:withOptions:placementID:error:`
 */
- (void)finishedDisplayingAd;

示例代码：


//Ad is no longer on screen
VungleSDK* sdk = [VungleSDK sharedSDK];
[sdk finishedDisplayingAd];

委派回调

您可以通过 VungleSDKDelegate 来接收来自 SDK 的回调。 在通知您 SDK 事件的委托中有四种回调方法。

如要附加和分离您的委托，您可以使用：

// Attach
[[VungleSDK sharedSDK] setDelegate:yourDelegateInstance];
// 分离
[[VungleSDK sharedSDK] setDelegate:nil];

注：为了避免内存泄漏，一旦不再需要注册的委托时，请记得将其清除。

当 SDK 即将播放视频广告时，以下方法将被调用。这是暂停广告情节、声音效果、动画等的极好位置。

- (void)vungleWillShowAdForPlacementID:(nullable NSString *)placementID;

当 SDK 即将关闭广告时，以下方法将被调用。这是奖励用户和恢复广告情节、声音效果、动画等的极好位置。


- (void)vungleWillCloseAdWithViewInfo:(VungleViewInfo *)info placementID:(NSString *)placementID;

VungleViewInfo includes the following properties for you to check a result of ad play:

@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

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

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

VunglePlayAdOptionKeyUser

无

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertTitleText

无

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertBodyText

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

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText

“关闭”

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText

“继续”

NSString

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

示例代码：

NSDictionary *options = @{VunglePlayAdOptionKeyOrientations: @(UIInterfaceOrientationMaskLandscape),
                          VunglePlayAdOptionKeyUser: @"userGameID",
                          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!"};

// 进入选项词典，播放广告
NSError *error;
[self.sdk playAd:self options:options placementID: error:&error];

if (error) {
    NSLog(@"Error encountered playing ad: %@", error);
}

静音选项

Vungle SDK 示例提供以静音方式播放广告的选项。您可以在发布 playAd() 之前将静音属性设为 true。

示例代码：

VungleSDK* sdk = [VungleSDK sharedSDK];
self.sdk.muted = true;

注：此选项仅适用于标准广告类型。动态模板广告的静音选项可在仪表板上进行配置。

调试

如果您需要 SDK 信息，您要以使用此属性来获取：

- (NSDictionary *)debugInfo;

如果您想要 SDK 输出日志，请使用以下方法：

- (void)setLoggingEnabled:(BOOL)enable;

VungleSDKLogger 协议

@protocol VungleSDKLogger
- (void)vungleSDKLog:(NSString*)message;
@end

VungleSDK 单例模式会将日志记录事件发送到任何符合 VungleSDKLogger 协议的附加类。日志事件包含 NSString 值，该值也将被打印到控制台（如果日志记录已被启用）。如要附加记录器，请使用以下命令：

[sdk attachLogger:yourLoggerInstance];

如上所述，务必从 Vungle SDK 清除附加的记录器。可以使用以下方法清除记录器：

[sdk detachLogger:yourLoggerInstance];

assetLoader 协议

@protocol VungleAssetLoader
/**
 * 应当返回一个有效 NSData，这个 NSData 含有指定路径的一个图像的（原始）数据，或者返回 nil 。*/
- (NSData*)vungleLoadAsset:(NSString*)path;

/**
 * 应当返回指定路径的有效 UIImage，或者 nil。
 */
- (UIImage*)vungleLoadImage:(NSString*)path;
@end
还有其它问题？提交请求

评论