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

目次

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

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

  • 方法 1 (推奨): パブリッシャーが、ユーザー レベルで GDPR 同意プロセスを管理し、ユーザーによる選択内容を Vungle に伝える。これを行うには、開発者が独自のメカニズムを使用してユーザーから同意を取得し、Vungle API を使用して、ユーザーの同意状況の更新や照会を実行します。詳しくは、「GDPR に準拠するための推奨手順」を参照してください。

  • 方法 2: 広告を表示するための要件の処理を Vungle に委任する。この方法の場合、欧州のユーザーに広告を表示する前に、同意ダイアログが表示されます。それ以降は、ユーザーが広告の表示に同意したか拒否したかがシステムに記憶されることになります。

はじめに

  • Vungle iOS SDK v. 6.x では、iOS 8 以降がサポートされます。
  • Vungle iOS SDK v. 6.x では、32 ビット アプリケーションと 64 ビット アプリケーションの両方がサポートされます。
  • 統合には、Vungle アカウントが必要です。アカウントをお持ちでない場合は、先に進む前にアカウントを作成してください。
  • 最新の iOS SDK (v. 4.0.8 以降) は最新の Xcode 8.0 に基づいて開発されました。スムーズな統合を可能にするため、必ず Xcode 8.0 以降を使用してください。
  • ここに掲載されているソース コードは、GitHub にある当社の公開リポジトリから入手できます。

 

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

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

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

Cocoapods

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

 pod "VungleSDK-iOS", "6.x"

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

手動での統合

Vungle SDK v6.x をダウンロードします。旧バージョンの Vungle SDK をアップデートする場合は、最初に VungleSDK.framework ディレクトリを完全に削除してから、新しい SDK を追加します。次に、展開後のファイルで 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
  • libsqlite3.dylib または libsqlite3.tbd
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework
  • UIKit.framework
  • WebKit.framework
    注: デプロイメント環境で iOS を使用する場合は、WebKit.framework[Status] を [Optional] に設定してください。

また、[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. コードを追加する

ブリッジ ヘッダー ファイルを作成する

  1. 新しい Objective-C ファイルを作成します ([File] → [New] → ファイル [Objective-C File])。
  2. Objective-C と Swift の間にブリッジ ヘッダー ファイルを作成するかどうか尋ねるプロンプトが表示されますので、これを承諾します。
  3. 新しい Objective-C ファイル (${YOURPROJ}-Bridging-Header.m) を削除しますが、ブリッジ ヘッダー ファイル ${YOURPROJ}-Bridging-Header.h は保持します。
  4. ブリッジ ヘッダー ファイルで、次を追加することで Vungle SDK をインポートします。
    #import <VungleSDK/VungleSDK.h> 

SDK を初期化する

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

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

サンプル コード:

let appID = "Your_AppID_Here";
var placementIDsArray:Array<String> = ["<Your_PlacementID_1>", "<Your_PlacementID_2>", "<Your_PlacementID_3>"];

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.start(withAppId: appID, placements: placementIDsArray)
}
catch let error as NSError {
print("Error while starting VungleSDK : \(error.domain)")
return;
}

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

- (void)vungleSDKDidInitialize;

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

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

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

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

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

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

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

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.loadPlacement(withID: <Your_PlacementID>)
}
catch let error as NSError {
print("Unable to load placement with reference ID :\(<Your_PlacementID>), Error: \(error)")

return
}

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

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

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

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

サンプル コード:

func vungleAdPlayabilityUpdate(_ isAdPlayable: Bool, placementID: String?) {
if (placementID == <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;

サンプル コード:

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.playAd(self, options: nil, placementID: kVungleTestPlacementID01)
}
catch let error as NSError {
print("Error encountered playing ad: + \(error)");
}

デリゲート コールバック

VungleSDKDelegate を使用して、SDK からのコールバックを受け取ることができます。デリゲートには、SDK イベントの通知を受け取るための 4 つのコールバック メソッドがあります。

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

var sdk:VungleSDK = VungleSDK.shared()
// Attach
sdk.delegate = <yourDelegateInstance> as VungleSDKDelegate
// Detach
sdk.delegate = nil

注意: メモリ リークを防ぐため、不要になった登録済みデリゲートはクリアしてください。

SDK が動画広告を再生する直前に、次のメソッドが呼び出されます。このメソッドは、ゲームのプレイ、音響効果、アニメーションなどを一時停止する場所として適しています。

- (void)vungleWillShowAdForPlacementID:(nullable NSString *)placementID; 

SDK が広告を閉じる直前に、次のメソッドが呼び出されます。このメソッドは、ユーザーに報酬を与え、ゲームのプレイ、音響効果、アニメーションなどを再開する場所として適しています。

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

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

- func vungleDidCloseAd(with info: VungleViewInfo, placementID: String);

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:(NSString *)placementID;

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

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

- (void)vungleSDKDidInitialize;

カスタマイズ オプション

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

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

オプション キー

デフォルト値/型

説明

VunglePlayAdOptionKeyOrientations

autorotate

UIInterfaceOrientationMaskAll

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

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

VunglePlayAdOptionKeyUser

nil

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertTitleText

nil

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertBodyText

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

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText

「閉じる」

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText

「続行」

NSString

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

サンプル コード:

let options: NSDictionary = NSDictionary(dictionary: [VunglePlayAdOptionKeyUser: "test_user_id",
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!"])
do {
try self.sdk.playAd(self, options: (options as! [AnyHashable : Any]), placementID: PlacementID)
}
catch let error as NSError {
print("Error encountered playing ad: + \(error)");
}

ミュート オプション

Vungle SDK インスタンスには、サウンドを無効にして広告を再生するオプションが用意されています。muted プロパティを true に設定してから playAd() を発行できます。

サンプル コード:

var sdk:VungleSDK = VungleSDK.shared()
sdk.muted = true

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

デバッグ

SDK 情報が必要な場合は、次のプロパティを使用して取得できます。

- (NSDictionary *)debugInfo;

SDK にログを出力させるには、次のメソッドを使用します。

- (void)setLoggingEnabled:(BOOL)enable;

VungleSDKLogger プロトコル

@protocol VungleSDKLogger - (void)vungleSDKLog:(NSString*)message; @end

VungleSDK シングルトンは、VungleSDKLogger プロトコルに準拠したアタッチ済みクラスにロギング イベントを送信します。ログ イベントには NSString 値が含まれており、この値はコンソールにも出力されます (ロギングが有効になっている場合)。ロガーをアタッチするには、以下のコードを使用します。

- (void)attachLogger:(id<VungleSDKLogger>)logger;

前述したように、不要になったロガーは必ず Vungle SDK からクリアしてください。ロガーをデタッチするには、以下のコードを使用します。

- (void)detachLogger:(id<VungleSDKLogger>)logger;

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

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

//This function returns the current consent status recorded in SDK. If status is not known return 0. sdk = VungleSDK.shared() sdk?.getCurrentConsentStatus() //This function sets the current consent status recorded in the SDK sdk = VungleSDK.shared() sdk?.update(status: VungleConsentStatus) 

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

  • accepted (VungleConsentStatus.accepted)
  • denied (VungleConsentStatus.denied)
他にご質問がございましたら、リクエストを送信してください

コメント