Vungle スタート ガイド - iOS SDK v. 5

コンテンツ

始める前に

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

Cocoapods

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

 pod "VungleSDK-iOS", "5.3.0"

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

手動での統合

Vungle SDK v5 をダウンロード します。以前のバージョンの Vungle SDKからアップデートする場合は、新しいSDKを追加する前に、まず Vungle SDK .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 or libz.tbd
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework
  • UIKit.framework
  • WebKit.framework
    注意: 開発ターゲットが WebKit.framework iOS 7 の場合、状態 を「オプション」に設定してください。

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

“-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 フィード広告

Vungle SDK v.5.3 は、Flex フィード広告をサポートするようになりました。これは、フルスクリーンを必要としない最初の広告フォーマットです。代わりに、パブリッシャーがアプリ内の広告コンテナの正確な大きさと位置を決定します。広告コンテナは、一連のビューまたはテーブル ビューのどちらかです。

Flex フィード広告を読み込む

Flex フィード広告の読み込みは、フルスクリーン広告の読み込みと同様です。Flex フィードをサポートするには、広告配置を構成する必要があります。Flex フィードの広告配置を利用可能にするには、アカウント マネージャーにお問合せください。

Flex フィード広告を表示する

Flex フィード広告の表示は、フルスクリーン広告の表示とは異なります。Flex フィード広告では、まず広告コンテナを作成する必要があります。このコンテナはUIView.これをUIView と呼び、画面でも設置できます。広告はどのサイズのコンテナにもスケールできますが、解像度が低い場合、広告がうまく表示されないことを念頭に置いてください。次にaddAdViewToView 関数を呼び、コンテナを Flex フィード広告と関連付ける必要があります。

関数の概要:


/**
 * 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 フィード広告を閉じる

Flex フィード広告の特性として、ユーザーは広告を閉じずにビデオの再生を停止することができます。そのため、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 イベントの通知を受け取るための 4 つのコールバック メソッドがあります。

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

// 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のコードと Reporting API では、「インセンティブ」を使用します。

オプション キー

デフォルト値/型

説明

VunglePlayAdOptionKeyOrientations

autorotate

UIInterfaceOrientationMaskAll

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

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

VunglePlayAdOptionKeyUser

nil

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertTitleText

nil

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 インスタンスには、サウンドを無効にして広告を再生するオプションが用意されています。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
他にご質問がございましたら、リクエストを送信してください

コメント