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 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.dylib 或 libz.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
还有其它问题？提交请求

评论