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 9.0 或更高版本。

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

将 VungleSDK.framework 添加到项目中

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

Cocoapods

Vungle SDK 可通过 Cocoapods 获取。在项目的 Podfile 中添加以下行,即可将 Vungle 添加到项目中。

 pod "VungleSDK-iOS", "5.4.0"

之后,Pod install 快速运行应当为您的项目更新到最新版本的 iOS SDK。此时,您可以跳到“步骤 2:删除 iOS 状态栏”。

手动集成

下载 Vungle SDK v5。如果使用先前版本 Vungle SDK 进行更新,请先彻底删除 VungleSDK.framework 目录,然后再添加新 SDK。

找到解压后的文件,然后将 VungleSDK.framework 目录拖动到 Frameworks 下的 Xcode 中。添加 VungleSDK.framework 文件夹时,请务必将其作为一个组(黄色文件夹),而不是作为参考(蓝色文件夹)。

添加其他必需的框架

Vungle SDK 需要将部分其他本地框架与您的项目进行链接,因此,请在“项目导航”中单击相应的项目,然后前往“通用 → 链接的框架和库”

以下许多框架已经包括在内,并已作为大多数 Xcode 项目的默认框架,但请务必添加以下所有尚未包括在内的框架:

  • AdSupport.framework
  • AudioToolbox.framework
  • AVFoundation.framework
  • CFNetwork.framework
  • CoreGraphics.framework
  • CoreMedia.framework
  • Foundation.framework
  • libz.dyliblibz.tbd
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework
  • UIKit.framework
  • WebKit.framework
    注意:Vungle SDK V.5 不支持 iOS 7。如需部署到 iOS 7 系统,请使用 Vungle iOS SDK v.4.1 或更低版本。

确保 VungleSDK 框架显示在“链接的框架和库”下面。

添加“-ObjC”链接器标记

“项目导航”中单击相应的项目,前往“构建设置 → 链接 → 其他链接器标记”。将 -ObjC 添加到“其他链接器标记”

步骤 2:删除 iOS 状态栏

尽管这不是必需步骤,但我们建议您删除 iOS 状态栏,以确保 Vungle 广告互动和演示顺利进行。要删除状态栏,请打开 Info.plist,添加关键的“查看基于控制器的状态栏外观”,并将其设置为 No

步骤 3:添加代码

初始化 SDK

注意:系统会自动为每个应用程序创建一个默认广告位置。无论是否打算利用该广告位置功能,您都必须在此初始化步骤中提供其广告位置参考 ID。如果创建了多个广告位置,请提供所有参考 ID。

启动应用程序后,应立即初始化 SDK,以便为 SDK 提供足够时间对自动缓存的广告位置进行广告缓存。初始化 SDK 时,您需要应用程序 ID 和想要在应用程序中使用的所有广告位置的参考 ID(包括活动的和非活动的)。您可以在 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 函数。此函数仅适用于 Flex Feed 和 Flex View 广告。请注意,此函数不会影响广告位置,只会关闭当前正在播放的本机广告。

函数概览:

/** * 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 包括以下属性,用于检查广告播放效果:

@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

autorotate

UIInterfaceOrientationMaskAll

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

设置广告的方向。建议您允许广告自动旋转,即使您的应用程序处于纵向状态。这样,用户就可以选择观看全尺寸视频,享受更优质的用户体验。您可以在视图控制器级别(而不是项目级别)设置方向来实现此目标。

VunglePlayAdOptionKeyUser

NSString

设置您的用户 ID。这个值将被发送至 Vungle 服务器,然后通过“服务器到服务器”回调系统发送到您的服务器(如果有广告位置被设为“奖励式”)。

VunglePlayAdOptionKeyIncentivizedAlertTitleText

NSString

标题字符串:用于在用户过早关闭激励式广告体验时所显示的警告对话框标题。

VunglePlayAdOptionKeyIncentivizedAlertBodyText

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

NSString

正文文本的字符串:用于在用户过早关闭激励式广告体验时所显示的警告对话框正文。

VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText

“关闭”

NSString

“关闭”按钮文本的字符串标题:用于在用户过早关闭激励式广告体验时所显示的警告对话框按钮。

VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText

“继续”

NSString

“关闭”按钮文本的字符串标题:用于在用户过早关闭激励式广告体验时所显示的警告对话框按钮。

VunglePlayAdOptionKeyFlexViewAutoDismissSeconds

Int

使用此选项可让 Flex View 广告在指定秒数后自动消失。
此功能仅适用于 Flex View 广告。

VunglePlayAdOptionKeyOrdinal

Int

如果收到来自 Vungle 的有序数据报告,则使用此字段来传递调解序数。这是一个整数,表示此广告在游戏会话中的显示顺序(例如,如果此会话中已显示了两个广告,且 Vungle 的这个广告会在第三个显示,则传递“3”)。单击此处详细了解有序数据。


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!"}; // Pass in dict of options, play ad 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;

注意:此选项仅适用于标准广告类型。Dynamic Template 广告的静音选项可以在管理面板中配置。

调试

如需 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*)vungleLoadAsset:(NSString*)path; /** * 应返回指定路径的有效 UIImage 或返回“零”。*/ - (UIImage*)vungleLoadImage:(NSString*)path; @end
还有其它问题?提交请求

评论