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

John Mai

2024年09月17日 17:35

EU 一般データ保護規則 (GDPR) に準拠するための推奨事項

2018 年 5 月 25 日より、欧州連合で一般データ保護規則 (GDPR) が施行されました。開発者は、以下に示すいずれかの方法で GDPR に準拠する必要があります。

方法 1 (推奨): パブリッシャーが、ユーザーレベルで GDPR 同意プロセスを管理し、ユーザーによる選択内容を Vungle に伝える。これを行うには、開発者が独自のメカニズムを使用してユーザーから同意を取得し、Vungle API を使用して、ユーザーの同意状況の更新や照会を実行します。詳しくは、「GDPR に準拠するための推奨手順」を参照してください。
方法 2: 広告を表示するための要件の処理を Vungle に委任する。この方法の場合、欧州のユーザーに広告を表示する前に、同意ダイアログが表示されます。それ以降は、ユーザーが広告の表示に同意したか拒否したかがシステムに記憶されることになります。

はじめに

Vungle iOS SDK v. 6.5.1 は Xcode 11 以降をサポートしています。アプリケーションのアーカイブは Xcode 11 以降を推奨しています。Xcode 10 では "Invalid Bitcode version error" が出る場合があります。
Vungle iOS SDK v. 6.5.1 は、iOS 13.3 を使用してテストされ、64 ビットアプリケーションがサポートされています。
Vungle iOS SDK v. 6.5.1 では、iOS 9 以降がサポートされています。
統合には、Vungle アカウントが必要です。アカウントをお持ちでない場合は、先に進む前にアカウントを作成してください。

手順 1. Vungle フレームワークを Xcode プロジェクトに追加する

VungleSDK.framework をプロジェクトに追加する

Vungle を Xcode プロジェクトに追加するには、Cocoapods を使用する方法と手動で統合する方法の 2 通りがあります。

Cocoapods

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

 pod "VungleSDK-iOS", "6.5.1"

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

手動での統合

Vungle SDK v6 をダウンロードします。旧バージョンの 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
libz.dylib または libz.tbd
MediaPlayer.framework
QuartzCore.framework
StoreKit.framework
SystemConfiguration.framework

注: Vungle SDK V.6.5.1 では、iOS 8またはそれ以前のバージョンはサポートされていません。デプロイメント環境で iOS 7 を使用する場合は、V.4.1 以前の Vungle iOS SDK を使用し、以下のフレームワークをデプロイメント環境に含めてください。

UIKit.framework
WebKit.framework
Foundation.framework

また、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 を初期化する

アプリケーションを開始したら、すぐに SDK を初期化してください。自動的にキャッシュされる配置広告を使用している場合、この方法で SDK を初期化することにより、こうした広告を SDK でキャッシュするための十分な時間を確保することができます。SDK を初期化するには、アプリケーション ID が必要になります。アプリケーション ID は、Vungle ダッシュボードで確認することができます。

- (BOOL)startWithAppId:(nonnull NSString *)appID error:(NSError **)error;

サンプルコード:

#import <VungleSDK/VungleSDK.h>
...
NSError* error;
NSString* appID = @"Your_AppID_Here";
VungleSDK* sdk = [VungleSDK sharedSDK];
if (![sdk startWithAppId:appID error:&error]) {
 if (error) {
 NSLog(@"Error encountered starting the VungleSDK: %@", error);
  }
}

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

- (void)vungleSDKDidInitialize;

この記事の「デリゲートコールバック」セクションを参照してください。

SDK の初期化ステータスは次のプロパティを使用して確認することもできます。

@property (atomic, readonly, getter=isInitialized) BOOL initialized;

Vungle ダッシュボードで [Auto Cached] として広告配置を選択した場合、SDK の初期化が完了すると、その広告配置用の広告が自動的にキャッシュされます。この機能を使用する場合は、最も表示頻度の高い広告配置を自動キャッシュ用に選択することをお勧めします。

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

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

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

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

サンプルコード:

NSError* error;
VungleSDK* sdk = [VungleSDK sharedSDK]; 
NSString* placementID = @"Your_placement_ID_Here";
VungleSDK* sdk = [VungleSDK sharedSDK];
if (![sdk loadPlacementWithID:placementID error:&error]) {
 if (error) {
 NSLog(@"Error occurred when loading placement: %@", error);
 }
}

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

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

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

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

サンプルコード:

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID error:(nullable NSError *)error {
    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); 
}

In-Feed 広告

Vungle SDK v.5.3 以降、In-Feed 広告がサポートされるようになりました。これは、全画面表示する必要がない最初の広告フォーマットです。代わりに、パブリッシャー側のアプリケーションで、広告コンテナの正確なサイズと位置を指定することになります。これらの広告コンテナは、コレクションビューやテーブルビューに含めることができます。

In-Feed 広告を読み込む

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

In-Feed 広告を表示する

In-Feed 広告の表示は、フルスクリーン広告の表示とは異なります。In-Feed 広告では、まず広告コンテナを作成する必要があります。このコンテナが、UIViewになります。これは、UIView と呼ばれ、画面上の任意の場所に配置することができます。コンテナのサイズに合わせて広告のサイズを自由に調整できますが、非常に低い解像度を設定すると、広告が見にくくなることに注意してください。コンテナを作成したら、addAdViewToView 関数を呼び出してコンテナを In-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); 
}

In-Feed 広告を閉じる

ユーザーは、In-Feed 広告を閉じることなく、動画の再生を停止することができます。これは、In-Feed 広告の特性です。そのため、動画が画面上に表示されなくなたったら、広告を破棄するように SDK に指示する必要があります。これを行うには、finishedDisplayingAd 関数を呼び出します。この関数が機能するのは、In- Feed 広告と MREC 広告の場合だけです。この関数では、現在再生されているネイティブ広告が終了するだけで、配置広告については処理されないということに注意してください。

関数の概要:

/** 
* 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];
[self.tempIn-FeedFeedView removeFromSuperview];
self.tempIn-FeedFeedView = nil;

デリゲートコールバック

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;

SDK によって広告が終了すると、以下のメソッドが呼び出されます。

- (void)vungleDidCloseAdWithViewInfo:(VungleViewInfo *)info placementID:
(NSString *)placementID;

VungleViewInfo には、広告の再生結果を確認するための以下のプロパティが用意されています。

@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:(nullable NSString *)placementID error:(nullable NSError *)error;

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

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

- (void)vungleSDKDidInitialize;

DK が正常に初期化されなかった場合は、次のメソッドが呼び出されます。その場合はVungle SDKを再スタートさせる必要があります。

- (void)vungleSDKFailedToInitializeWithError:(NSError *)error;

カスタマイズオプション

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

注意: 報酬対象の広告は、インセンティブ広告として参照されることがあります。どちらの場合も、同等な広告のことを示しています。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;

注意: このオプションは SDK 6.3.1 またはそれ以前の標準の広告タイプにのみ適用されます。Dynamic Template 広告のミュートオプションはダッシュボードで設定できます。

EU 一般データ保護規則 (GDPR) に準拠するための推奨手順

「EU 一般データ保護規則 (GDPR) に準拠するための推奨事項」セクションの「方法 1」で説明したように、Vungle API を使用して、ユーザーの同意状況の更新や照会を行うことをお勧めします。そのためには、以下の関数を使用します。

// This function sets the consent status that will be recorded in Vungle SDK. Accepted values: 'VungleConsentAccepted' or 'VungleConsentDenied'.
// To set the user's consent status to opted in:
 [[VungleSDK sharedSDK] updateConsentStatus:VungleConsentAccepted];

// To set the user's consent status to opted out:
 [[VungleSDK sharedSDK] updateConsentStatus:VungleConsentDenied];

// To find out what the user's current consent status is: 
// (Check against enum values: 'VungleConsentAccepted' or 'VungleConsentDenied'.) [[VungleSDK sharedSDK] getCurrentConsentStatus];

VungleConsentStatus は、以下に示す 2 つの状態を持つ列挙型です。

VungleConsentAccepted
VungleConsentDenied

SDK には、「不明」という初期状態もあります。この状態の場合、ユーザーデータ収集のオプトインとオプトアウトを選択するための画面が表示されます。この画面が表示されるのは、欧州の IP アドレスの場合だけであることに注意してください。

デバッグ

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

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

目次

EU 一般データ保護規則 (GDPR) に準拠するための推奨事項

はじめに

手順 1. Vungle フレームワークを Xcode プロジェクトに追加する

VungleSDK.framework をプロジェクトに追加する

Cocoapods

手動での統合

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

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

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

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

SDK を初期化する

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

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

広告を再生する

In-Feed 広告

In-Feed 広告を読み込む

In-Feed 広告を表示する

In-Feed 広告を閉じる

デリゲートコールバック

カスタマイズオプション

ミュートオプション

EU 一般データ保護規則 (GDPR) に準拠するための推奨手順

デバッグ

VungleSDKLogger プロトコル

assetLoader プロトコル

Questions?

目次

EU 一般データ保護規則 (GDPR) に準拠するための推奨事項

はじめに

手順 1. Vungle フレームワークを Xcode プロジェクトに追加する

VungleSDK.framework をプロジェクトに追加する

Cocoapods

手動での統合

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

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

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

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

SDK を初期化する

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

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

広告を再生する

In-Feed 広告

In-Feed 広告を読み込む

In-Feed 広告を表示する

In-Feed 広告を閉じる

デリゲートコールバック

カスタマイズ オプション

ミュート オプション

EU 一般データ保護規則 (GDPR) に準拠するための推奨手順

デバッグ

VungleSDKLogger プロトコル

assetLoader プロトコル

Questions?

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

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

カスタマイズオプション

ミュートオプション