Vungle - iOS SDK v. 5 入门

目录

开始之前

  • 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
还有其它问题?提交请求

评论