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 を使用する方法と手動で統合する方法の 2 通りがあります。

Cocoapods

Vungle SDK は Cocoapods を通じて入手できます。次の行をプロジェクトの podfile に追加して、Vungle をプロジェクトに追加します。

 pod "VungleSDK-iOS", "5.4.0"

pod install を実行すると、プロジェクトが更新されて最新バージョンの Vungle iOS SDK が組み込まれます。この時点で下記の「手順 2. iOS ステータス バーを削除する」に進むことができます。

手動での統合

Vungle SDK v5 をダウンロードします。以前のバージョンの Vungle SDK からアップデートする場合は、新しい SDK を追加する前に、まず VungleSDK.framework ディレクトリを完全に削除してください。

展開されたファイルの中から VungleSDK.framework ディレクトリを探し、このディレクトリを Xcode の [Frameworks] の下にドラッグアンドドロップします。VungleSDK.framework フォルダーは参照 (青のフォルダー) としてではなくグループ (黄色のフォルダー) として追加してください。

その他の必要なフレームワークを追加する

Vungle SDK を使用するためには、その他にもいくつかのネイティブ フレームワークをプロジェクトにリンクする必要があります。Project Navigator でプロジェクトをクリックして、[General] → [Linked Frameworks and Libraries] に移動します。

これらのフレームワークはほとんどの 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 以前を使用してください。

また、[Linked Frameworks and Libraries] に VungleSDKVungleSDK フレームワークが表示されていることを確認してください。

“-ObjC” リンカー フラグを追加する

Project Navigator でプロジェクトをクリックして、[Build Settings] → [Linking] → [Other Linker Flags] に移動します。-ObjC[Other Linker Flags ] に追加します。

手順 2. iOS ステータス バーを削除する

この手順は必須ではありませんが、Vungle の広告の操作や提示がスムーズになるため、iOS ステータス バーを削除することを推奨します。ステータス バーを削除するには、Info.plist を開いて、キー [View controller-based status bar appearance] を追加して、[No] に設定します。

手順 3. コードを追加する

SDK を初期化する

注意: デフォルトの広告配置はアプリケーションごとに自動的に作成されます。広告配置機能を利用するかどうかにかかわらず、広告配置の参照 ID をこの初期化手順で指定する必要があります。複数の広告配置を作成する場合は、すべての参照 ID を指定してください。

自動キャッシュされる広告配置用に広告をキャッシュするための十分な時間が SDK に与えられるよう、アプリケーションが起動したらすぐに SDK を初期化してください。SDK を初期化するには、アプリケーションで使用するアプリケーション ID とすべての広告配置参照 ID が必要となります (アクティブと非アクティブの両方)。これらの ID は Vungle ダッシュボードから取得できます (「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 ダッシュボードで [Auto Cached] として選択した広告配置用の広告が自動的にキャッシュされます。閲覧回数の最も多い広告配置を自動キャッシュの対象として選択することをお勧めします。

広告が正常にキャッシュされると、[Auto Cached] で選択した広告配置と一致する広告配置参照 ID で vungleAdPlayabilityUpdate コールバック メソッドが呼び出されます (この記事の「広告が配置可能かどうかを確認する」セクションを参照してください)。

広告配置用の広告を読み込む

自動キャッシュ形式以外の広告配置の場合は、loadPlacementWithID メソッドを呼び出して広告を読み込みます。

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

サンプル コード:

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

この記事の「広告が配置可能かどうかを確認する」セクションを参照してください。

広告が配置可能かどうかを確認する

広告配置用の広告のキャッシュが完了すると、次のコールバック メソッドが呼び出されます。

- (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 をサポートするには、広告配置を構成する必要があります。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 広告を閉じることなく、動画の再生を停止することができます。これは、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 イベントの通知を受け取るための 4 つのコールバック メソッドがあります。

デリゲートのアタッチとデタッチは、次のコードを使用して行うことができます。

// Attach [[VungleSDK sharedSDK] setDelegate:yourDelegateInstance]; // Detach [[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 //Represents a BOOL whether or not the video can be considered a completed view. @property (nonatomic, readonly) NSNumber *completedView; //The time in seconds that the user watched the video. @property (nonatomic, readonly) NSNumber *playTime; //Represents a BOOL whether or not the user clicked the download button. @property (nonatomic, readonly) NSNumber *didDownload; @end 

次のメソッドは、広告の使用可能ステータスが SDK によって変更されたときに呼び出されます。isAdPlayable は、特定の placementID の新しい再生可能状態を示すブール値です。

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

この記事の「広告が配置可能かどうかを確認する」セクションを参照してください。

SDK が正常に初期化されると、次のメソッドが呼び出されます。

- (void)vungleSDKDidInitialize;

カスタマイズ オプション

これらのオプションは、広告の再生体験をカスタマイズするために使用します。

注意: 報酬対象の広告は、インセンティブ広告として参照されることがあります。どちらの場合も、同等な広告のことを示しています。SDK のコードと Reporting API では、「インセンティブ」を使用します。

オプション キー

デフォルト値/型

説明

VunglePlayAdOptionKeyOrientations

autorotate

UIInterfaceOrientationMaskAll

ビットマスクを向きで表す NSNumber。

広告の向きを設定します。作成するアプリが縦向きの場合でも広告を自動回転させることを推奨します。そうすれば、ユーザーが広告動画をフルサイズで見ることができ、ユーザー エクスペリエンスが向上します。そのためには、向きを (プロジェクト レベルではなく) ビュー コントローラー レベルで設定します。

VunglePlayAdOptionKeyUser

nil

NSString

ユーザー ID を設定します。この値は Vungle サーバーに渡された後、広告配置が「報酬対象」に設定されている場合にサーバー間コールバック システムを使用してサーバーに送られます。

VunglePlayAdOptionKeyIncentivizedAlertTitleText

nil

NSString

ユーザーが途中でインセンティブ広告を閉じたときに表示される警告ダイアログのタイトルとして使用される文字列。

VunglePlayAdOptionKeyIncentivizedAlertBodyText

「この広告をスキップしてもよろしいですか。スキップした場合、報酬の対象とはならない可能性があります」

NSString

ユーザーが途中でインセンティブ広告を閉じたときに表示される警告ダイアログの本文として使用される文字列。

VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText

「閉じる」

NSString

ユーザーが途中でインセンティブ広告を閉じたときに表示される警告ダイアログの閉じるボタンのテキスト。

VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText

「続行」

NSString

ユーザーが途中でインセンティブ広告を閉じたときに表示される警告ダイアログの閉じるボタンのテキスト。

VunglePlayAdOptionKeyFlexViewAutoDismissSeconds

Int

指定の秒数が経過したときに Flex View 広告を自動的に終了するには、このオプションを使用します。
このオプションが機能するのは、Flex View 広告の場合だけです。

VunglePlayAdOptionKeyOrdinal

Int

Vungle から序数データ レポートを受け取った場合は、このオプションを使用して媒介序数を渡します。このオプションは、ゲーム セッション内でこの広告が表示された順序を示す整数です。たとえば、現在のセッション内で 2 つの広告がすでに表示されていて、Vungle の広告が 3 番目に表示された場合は、「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 インスタンスには、サウンドを無効にして広告を再生するオプションが用意されています。muted プロパティを true に設定してから playAd() を発行できます。

サンプル コード:

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、または nil を返します。*/ - (NSData*)vungleLoadAsset:(NSString*)path; /** * 指定したパスにある有効な UIImage、または nil を返します。 */ - (UIImage*)vungleLoadImage:(NSString*)path; @end
他にご質問がございましたら、リクエストを送信してください

コメント