目录
开始之前
- 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
orlibz.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 中,我们使用术语“激励”。
选项键 |
默认值/类型 |
说明 |
|
自动旋转
一个 NSNumber 代表一个具有方向的位掩码 |
设置广告的方向。我们建议您允许广告自动旋转,即使您的应用程序处于纵向。这样,用户可以选择观看全尺寸视频,从而获得更好的用户体验。您可以通过在视图控制器级别(而不是项目级别)设置方向来实现此目的。 |
|
无
|
设置您的用户 ID。这个值将被传给 Vungle 服务器,然后再通过服务器到服务器回调系统发送到您的服务器,如果有一个广告位置被设为“奖励”。 |
|
无
|
在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框标题的字符串。 |
|
“确定要跳过此广告吗?如果这么做,您可能无法获得奖励”
|
在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框正文文本的字符串。 |
|
“关闭”
|
在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框关闭按钮文本的字符串标题。 |
|
“继续”
|
在用户过早关闭奖励推广的广告体验时,用作呈现的警告对话框关闭按钮文本的字符串标题。 |
示例代码:
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
评论