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

コンテンツ

始める前に

  • Vungle iOS SDK v. 5.x は iOS 8+ をサポートしています。
  • Vungle iOS SDK v. 5.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", "5.x"

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

手動での統合

Vungle SDK v5.x をダウンロードします。以前のバージョンの 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 or libz.tbd
  • libsqlite3.dylib or libsqlite3.tbd
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework
  • UIKit.framework
  • WebKit.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. コードを追加する

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

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

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

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

SDK が初期化されると、Vungle ダッシュボードで [Auto Cached] として選択した広告配置用の広告が自動的にキャッシュされます。閲覧回数の最も多い広告配置を自動キャッシュの対象として選択することをお勧めします。

広告が正常にキャッシュされると、[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()
// アタッチ
sdk.delegate = <yourDelegateInstance> as VungleSDKDelegate
// デタッチ
sdk.delegate = 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;

カスタマイズ オプション

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

オプション キー

デフォルト値/型

説明

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;

他にご質問がございましたら、リクエストを送信してください

コメント