Skip to content

VAMP iOS API Reference

AdGeneration edited this page Apr 11, 2019 · 44 revisions

Version: v3.1.3

対応OS: 9.0以降

API Reference


VAMP Class

Methods

setTestMode

+ (void)setTestMode:(BOOL)enableTest;

収益が発生しないテスト広告が配信されるようになります。
ストアに申請する際はコメントアウトNOに設定してください(デフォルトはNO)。
以下のアドネットワークのテストモードと連動します。
対象: AdMob、AppLovin、FAN、maio、nend、UnityAds、Mintegral、MoPub
テストモードの場合はRTB案件は配信されません。

パラメーター
名前 内容
enableTest テストモードを有効にするかどうか

isTestMode

+ (BOOL)isTestMode;

テストモードに設定されているか確認できます。

戻り値

テストモードが有効の場合はYES、無効の場合はNO


setDebugMode

+ (void)setDebugMode:(BOOL)enableDebug;

ログを詳細に出力するデバッグモードを設定します(デフォルトはNO)。
以下のアドネットワークのデバッグモードと連動します。
対象:RTB、AppLovin、FAN、nend、UnityAds、Vungle、Tapjoy、MoPub

パラメーター
名前 内容
enableDebug デバッグモードを有効にするかどうか

isDebugMode

+ (BOOL)isDebugMode;

デバッグモードの設定状況を返却します。

戻り値

デバッグモードが有効な場合はYES、無効の場合はNO


isEUAccess

+ (void)isEUAccess:(void (^)(BOOL access))completionHandler;

EU圏アクセス判定をします(YESならEU圏からのアクセス)。
IPを元に以下の国からのアクセスかを判定します。
ベルギーBE, ブルガリアBG, チェコCZ, デンマークDK,ドイツDE, エストニアEE, アイルランドIE, ギリシャGR, スペインES, フランスFR, クロアチアHR, イタリアIT, キプロスCY, ラトビアLV, リトアニアLT, ルクセンブルクLU, ハンガリーHU, マルタMT, オランダNL, オーストリアAT, ポーランドPL, ポルトガルPT, ルーマニアRO, スロベニアSI, スロバキアSK, フィンランドFI, スウェーデンSE, イギリスGB、アイスランドIS、リヒテンシュタインLI、ノルウエーNO、ギアナGF、ポリネシアPF、フランス領南方・南極地域TF、サン・マルタン(フランス領)MF、シント・マールテン(オランダ領)SX、イギリス領ヴァージン諸島VG、イギリス領インド洋地域IO
※IPから国が判別できなかった場合もYESに判定されます。

パラメーター
名前 内容
completionHandler 通知を受け取るためのハンドラー。accessがYESならEU圏からのアクセス

setMediationTimeout

+ (void)setMediationTimeout:(float)timeout;

アドネットワーク側の広告取得を待つタイムアウト時間を設定します。

パラメーター
名前 内容
timeout アドネットワーク側の広告取得を待つタイムアウト時間(秒)。最小5秒、最大60秒。デフォルトは15秒。

setGender

+ (void)setGender:(VAMPGender)gender;

アドネットワークSDKのユーザ属性ターゲティング機能に性別を設定します。
対応アドネットワーク:AdMob(v7.31.0でdeprecated)、nend、Mintegral

パラメーター
名前 内容
gender 設定する性別(VAMPGender)

setBirthday

+ (void)setBirthday:(NSDate *)birthday;

アドネットワークSDKのユーザ属性ターゲティング機能に設定する誕生日です。
年、月、日を指定します。

NSDateComponents *components = [NSDateComponents new];
components.year = 1980;
components.month = 2;
components.day = 20;
NSDate *birthday = [[[NSCalendar alloc] initWithCalendarIdentifier:NSCalendarIdentifierGregorian]
dateFromComponents:components];
[VAMP setBirthday:birthday];

対応アドネットワーク:AdMob、nend、Mintegral

パラメーター
名前 内容
birthday 設定する誕生日

setUserConsent

+ (void)setUserConsent:(VAMPConsentStatus)consentStatus;

ユーザの同意ステータスを設定します。
ユーザの同意がある場合はkVAMPConsentStatusAcceptedを設定します。

パラメーター
名前 内容
consentStatus 同意ステータス(VAMPConsentStatus)

setCoppaChildDirected(deprecated)

+ (void)setCoppaChildDirected:(BOOL)childDirected;

特定の年齢未満のユーザからのアクセスかどうかを設定します。
YESに設定した場合はIDFAを送りません。
COPPA、GDPRでは特定の年齢未満のユーザに対するデータの取り扱いについていくつかの義務が課せられています。
これらの対象の国のユーザが特定の年齢未満の場合にはYESを設定してください。
以下のアドネットワークの特定の年齢未満のユーザからのアクセスかどうかを設定する機能と連動します。
(AdMob、FAN、AppLovin、Tapjoy)
※ v3.1.3からは非推奨です。代わりにsetChildDirectedを使用してください。

パラメーター

名前 内容
childDirected ユーザの年齢が特定の年齢未満かどうか

isCoppaChildDirected(deprecated)

+ (BOOL)isCoppaChildDirected;

setCoppaChildDirectedで設定した値を取得します。
※ v3.1.3からはsetChildDirectedが追加されたので非推奨です。

戻り値

setCoppaChildDirectedで設定した値。


setChildDirected

+ (void)setChildDirected:(BOOL)childDirected;

特定の年齢未満のユーザからのアクセスかどうかを設定します。
YESに設定した場合はIDFAを送りません。
COPPA、GDPRでは特定の年齢未満のユーザに対するデータの取り扱いについていくつかの義務が課せられています。
これらの対象の国のユーザが特定の年齢未満の場合にはYESを設定してください。
以下のアドネットワークの特定の年齢未満のユーザからのアクセスかどうかを設定する機能と連動します。
(AdMob、FAN、AppLovin、Tapjoy)

パラメーター

名前 内容
childDirected ユーザの年齢が特定の年齢未満かどうか

isChildDirected

+ (BOOL)isChildDirected;

setChildDirectedで設定した値を取得します。

戻り値

setChildDirectedで設定した値。


setUnderAgeOfConsent

+ (void)setUnderAgeOfConsent:(VAMPUnderAgeOfConsent)underAgeOfConsent;

GDPRの対象ユーザで特定の年齢未満であるかどうかを設定します。
以下のアドネットワークと連動します。
(AdMob、AppLovin、Tapjoy)

パラメーター

名前 内容
underAgeOfConsent 特定の年齢未満のユーザかどうか (VAMPUnderAgeOfConsent 参照)

SDKVersion

+ (NSString *)SDKVersion;

VAMPのSDKバージョンを返却します。例)v1.2.1

戻り値

VAMPのSDKバージョン


setPlacementId

- (void)setPlacementId:(NSString *)placementId;

アドジェネ広告枠IDをセットします。

パラメーター
名前 内容
placementId 広告枠ID

SupportedOSVersion

+ (float)SupportedOSVersion;

対応OSバージョンを返却。返却されたOSバージョン以上で動作します。
例)9.0

戻り値

対応OSバージョン


isSupportedOSVersion

+ (BOOL)isSupportedOSVersion;

サポート対象OSかどうか、確認できます。 ※ added on v1.2.4

戻り値

サポート対象OSならYES、対象外ならNO


getCountryCode

+ (void)getCountryCode:(void (^)(NSString *countryCode))completionHandler;

2文字の国コード(JP、USなど)を取得します。
IPから国を判別できなかった、リクエストがタイムアウトしたなど、
正常に値が返せない場合は"99"が返却されます。
一度取得した国コードは端末内で12時間キャッシュします。
UnityPluginで国判定するサンプル ※ added on v1.2.4

パラメーター
名前 内容
completionHandler 国コードを取得するためのハンドラー

setFrequencyCap

+ (void)setFrequencyCap:(NSString *)placementId; impressions:(NSUInteger)impressions minutes:(NSUInteger)minutes

特定の広告枠IDに対してフリークエンシーキャップの設定をします。

impressionsは視聴制限回数です。その回数視聴を行うと、showを呼んだ際にdidFailToShowWithErrorでVAMPErrorCodeFrequencyCappedエラーが通知されます。

minutesは制限時間です。キャップ解除後、最初の視聴からこの時間経過すると視聴回数がリセットされ、キャップにかかっていた場合はキャップが解除されます。
一度設定済みの場合には設定を上書きしません。
ここで設定した値はアプリ再起動後も保持され続けるため、値を書き換えたい場合はclearFrequencyCapを呼んでからsetFrequencyCapを呼んでください。

パラメーター
名前 内容
placementId フリークエンシーキャップを設定する広告枠ID
impressions 視聴制限回数(1以上の値で設定可能)
minutes 視聴回数がリセットされるまでの制限時間(1分〜1440分の間で設定可能)

clearFrequencyCap

+ (void)clearFrequencyCap:(NSString *)placementId;

特定の広告枠IDの現在の視聴回数をリセットします。
setFrequencyCapでフリークエンシーキャップの設定をしており、キャップにかかった場合はこのメソッドを呼ぶことでキャップを解除できます。
値を書き換えたい場合は、このメソッドを呼んでからsetFrequencyCapを呼んでください。

パラメーター
名前 内容
placementId 視聴回数をリセットする広告枠ID

isFrequencyCapped

+ (BOOL)isFrequencyCapped:(NSString *)placementId;

特定の広告枠IDにおいて、現在キャップにかかっている状態かどうか確認することができます。

パラメーター
名前 内容
placementId キャップにかかっている状態かどうか確認する広告枠ID
戻り値

キャップにかかっていればYES、かかっていなければNO


getFrequencyCappedStatus

+ (VAMPFrequencyCappedStatus *)getFrequencyCappedStatus:(NSString *)placementId;

特定の広告枠IDの現在のフリークエンシーキャップの状態(VAMPFrequencyCappedStatus)を取得します。

パラメーター
名前 内容
placementId フリークエンシーキャップの状態を取得する広告枠ID
戻り値

VAMPFrequencyCappedStatusインスタンス


resetFrequencyCap

+ (void)resetFrequencyCap:(NSString *)placementId;

特定の広告枠IDのフリークエンシーキャップ機能を無効にします。
再度フリークエンシーキャップ機能を利用する場合はsetFrequencyCapを呼んでください。

パラメーター
名前 内容
placementId フリークエンシーキャップ機能を無効にする広告枠ID

resetFrequencyCapAll

+ (void)resetFrequencyCapAll;

全ての広告枠IDのフリークエンシーキャップ機能を無効にします。


load

- (void)load;

広告の取得を開始します。
※各アドネットワークに在庫の確認、動画ファイルやエンドカード素材のダウンロードなど


preload

- (void)preload;

新規追加 v3.0〜
事前に広告を取得します。
広告を取得するのに時間がかかるため(動画ファイル、プレイアブルのダウンロード)、
事前に在庫を確保しておき、ユーザを待たせることなく広告を表示するための機能です。
loadとの違いとして、preloadを実行した結果(vampLoadResultdidFailToLoadWithErrorなど)はリスナーで受け取ることはできません。


isReady

- (BOOL)isReady;

広告を表示する準備が完了しているか確認します。
showで広告を表示する前に、load済みかどうかを確認するためのメソッドです。

戻り値

広告表示をする準備が完了していればYES、そうでなければNO


show

- (BOOL)show;

広告を表示します。※動画が再生されます。
※show実行時には、vampDidCloseを受け取るまではloadを実行しないでください。

戻り値

広告の表示開始に成功すればYES、失敗すればNO


Enumerations

VAMPError

エラーコード一覧


VAMPGender

名前 内容
kVAMPGenderUnknown 不明
kVAMPGenderMale 男性
kVAMPGenderFemale 女性

VAMPState

名前 内容
kVAMPStateIdle 初期状態
kVAMPStateLoading 広告をロードしている状態
kVAMPStateLoaded 広告のロードが完了した状態
kVAMPStateShowing 広告を表示している状態

VAMPConsentStatus

名前 内容
kVAMPConsentStatusUnknown 不明
kVAMPConsentStatusAccepted ユーザの同意がある場合
kVAMPConsentStatusDenied ユーザが拒否した場合

VAMPUnderAgeOfConsent

名前 内容
kVAMPUnderAgeOfConsentUnknown 不明
kVAMPUnderAgeOfConsentTrue 同意年齢未満のユーザに適した広告リクエストをする
kVAMPUnderAgeOfConsentFalse 同意年齢未満のユーザに適した広告リクエストをしない

VAMPDelegate Protocol

Callback Methods

vampDidReceive

- (void)vampDidReceive:(NSString *)placementId adnwName:(NSString *)adnwName;

広告表示が可能になると通知されます(優先順位よりスピード優位)。

パラメーター
名前 内容
placementId 広告枠ID
adnwName アドネットワーク名

vampDidComplete

- (void)vampDidComplete:(NSString *)placementId adnwName:(NSString *)adnwName;

インセンティブ付与が可能になると通知されます。
※ユーザが途中で再生をスキップしたり、動画視聴をキャンセルすると発生しません。
アドネットワークによって発生タイミングが異なります。
通常は動画再生が完了したタイミングで発生しますが、
UnityAds、Vungleのみエンドカードを閉じたタイミングで発生します。

パラメーター
名前 内容
placementId 広告枠ID
adnwName アドネットワーク名

vampDidClose

- (void)vampDidClose:(NSString *)placementId adnwName:(NSString *)adnwName

広告(動画プレーヤー、エンドカード)が閉じられたタイミングで通知されます。
※ユーザキャンセルなども含むので、インセンティブ付与はvampDidCompleteで判定すること

パラメーター
名前 内容
placementId 広告枠ID
adnwName アドネットワーク名

didFailToLoadWithError

- (void)vamp:(VAMP *)vamp didFailToLoadWithError:(VAMPError *)error withPlacementId:(nullable NSString *)placementId;

広告の取得に失敗すると通知されます。
広告取得時のタイムアウトや、全てのアドネットワークの在庫がない(フリクエンシーキャップ含む)場合など。
EU圏からのアクセスの場合(VAMPErrorCodeNoAdnetwork)が発生します。2018-05-23現在 ※本仕様は変更する可能性があります。

パラメーター
名前 内容
error VAMPError
placementId 広告枠ID

didFailToShowWithError

- (void)vamp:(VAMP *)vamp didFailToShowWithError:(VAMPError *)error withPlacementId:(NSString *)placementId;

広告の表示に失敗すると通知されます。

パラメーター
名前 内容
error VAMPError
placementId 広告枠ID

vampDidExpired

- (void)vampDidExpired:(NSString *)placementId;

load完了から1時間以上経過するとRTB案件が無効になる関係から、再度loadを実行してもらうために通知されます。
通知を受け取ってからisReadyを実行するとfalseが返却されます。
通知を受け取ってからshowを実行すると、didFailToShowWithErrorのVAMPErrorCodeNotLoadedAdが返却されます。


パラメーター
名前 内容
placementId 広告枠ID

vampLoadStart

- (void)vampLoadStart:(NSString *)placementId adnwName:(NSString *)adnwName;

アドネットワークごとの広告取得が開始されたときに通知されます。

パラメーター
名前 内容
placementId 広告枠ID
adnwName アドネットワーク名

vampLoadResult

- (void)vampLoadResult:(NSString *)placementId success:(BOOL)success
adnwName:(NSString *)adnwName message:(NSString *)message;

アドネットワークごとの広告取得結果を通知します。
この通知をもとにshowしないようご注意ください。
showする判定は、vampDidReceiveを受け取ったタイミングで判断ください。
※v3.0以降はvampLoadResultのsuccessで表示判定可能です。

パラメーター
名前 内容
placementId 広告枠ID
success loadに成功したかどうか
adnwName アドネットワーク名
message メッセージ

vampDidChangeState

- (void)vampDidChangeState:(VAMPState)oldState intoState:(VAMPState)newState
           withPlacementId:(nullable NSString *)placementId;

VAMPの内部状態が遷移したときに通知されます。

パラメーター
名前 内容
oldState 前のVAMPState
newState 次のVAMPState
placementId 広告枠ID

VAMPConfiguration Class

Methods

VAMPConfiguration.defaultConfiguration

+ (instancetype)defaultConfiguration

VAMPConfigurationインスタンスを取得します。

戻り値

VAMPConfigurationインスタンス


Properties

playerCancelable

@property (nonatomic, getter = isPlayerCancelable) BOOL playerCancelable

動画再生中にキャンセルを可能にするかどうかを設定します。
※この機能はVungle、RTB/APCのみ有効


playerAlertTitleText

@property (nonatomic, copy) NSString *playerAlertTitleText

キャンセル機能が有効の場合に表示するアラートダイアログのタイトルを設定します。
※この機能はVungle、RTB/APCのみ有効


playerAlertBodyText

@property (nonatomic, copy) NSString *playerAlertBodyText

キャンセル機能が有効の場合に表示するアラートダイアログの本文を設定します。
※この機能はVungle、RTB/APCのみ有効


playerAlertCloseButtonText

@property (nonatomic, copy) NSString *playerAlertCloseButtonText

キャンセル機能が有効の場合にアラートダイアログの終了ボタンのテキストを設定します。
※この機能はVungle、RTB/APCのみ有効


playerAlertContinueButtonText

@property (nonatomic, copy) NSString *playerAlertContinueButtonText

キャンセル機能が有効の場合にアラートダイアログの継続視聴ボタンのテキストを設定します。
※この機能はVungle、RTB/APCのみ有効


VAMPFrequencyCappedStatus Class

Properties

capped

@property (nonatomic, readonly, getter = isCapped) BOOL capped

キャップにかかっているかどうかを取得します。


impressionLimit

@property (nonatomic, readonly) NSUInteger impressionLimit

フリークエンシーキャップ機能が有効である場合、現在設定されている視聴制限回数を取得します。


timeLimit

@property (nonatomic, readonly) NSUInteger timeLimit

現在設定されているフリークエンシーキャップ機能の視聴回数がリセットされるまでの時間を返却します。


impressions

@property (nonatomic, readonly) NSUInteger impressions

フリークエンシーキャップ機能が有効である場合、現在の視聴回数を返却します。


remainingTime

@property (nonatomic, readonly) NSUInteger remainingTime

フリークエンシーキャップ機能が有効である場合、次に視聴回数がリセットされるまでの残り時間を返却します。


You can’t perform that action at this time.