BuzzAd Benefit iOS SDK 導入ガイド(JP)
本バージョンは旧版のため、日本語でのサポート対象外です。適切にサポートを受けるには2.0以上のバージョンを適用してください。iOS 2.0版に移動する
本ガイドはBuzzAd-Benefitの導入に必要な技術情報を解説するものです。
BuzzAd Benefitはアプリのエンゲージメントとそれに伴う収益化をサポートするアプリパブリッシャー向けのソリューションです。パブリッシャーはBuzzAd-Benefit SDKをiOSアプリ内に実装することで、アプリ内領域の任意の場所にリワード広告(静止画・動画)を表示させることが可能になります。
パブリッシャーが独自にカスタマイズしたレイアウトにあわせて広告コンポーネントを表示させることで、アプリ内での自然なUXを担保しつつ、収益の最大化をサポートします。
index
はじめに(Getting Started)
SDKをアプリに実装するにあたり、下記の3点が必要となります。
Buzzvil担当者を通じて取得した app_id
Buzzvil担当者を通じて取得した unit_id (配信フォーマットごとにunit_id を発行します)
Type A_Native 適用時
YOUR_NATIVE_AD_UNIT_ID
準備Type B_Feed 適用時
YOUR_FEED_UNIT_ID
準備Type C_Interstitial 適用時
YOUR_INTERSTITIAL_UNIT_ID
準備
Buzzvil サーバーからポイント付与リクエストを受信する貴社(メディア側)APIサーバー - ポイントポストバックAPI 連携文書
Postback 受信用URLを設定後、Buzzvil担当者までお知らせください。
インストール
1. CocoaPods の使用 (推奨)
Podfile
に下記コードを追加
pod 'BuzzAdBenefit', '実装するバージョン'
を入力してください。
pod 'BuzzAdBenefit', '~> 1.3.0'
2. 手動でのインポート
CocoaPodsを使用しない場合は下記の方法でインストールすることができます。
Step 1) プロジェクトにframework を追加
[プロジェクトメニュー] -> [General] -> [Embedded Binaries] セクションに次の frameworkを追加します。
BuzzAdBenefit.framework
BuzzAdBenefitNative.framework
BuzzAdBenefitInterstitial.framework (Interstitial typeを適用する場合)
BuzzAdBenefitFeed.framework (Feed typeを適用する場合)
AFNetworking.framework
SDWebImage.framework
libwebp.framework
(AFNetworking.framework, SDWebImage.framework, libwebp.frameworkは本ストレージのDependenciesフォルダからダウンロードすることができます。)
step 2) Run script を追加
[プロジェクトメニュー] -> [Build Phases] タブにて '+' ボタンをクリックし、New Run Script Phaseを追加して下記スクリプトを貼り付けます。このプロセスはuniversal frameworkにビルドされたバイナリにて不必要なarchitectureを取り除くために必要となります。
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK; do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
EXTRACTED_ARCHS=()
for ARCH in $ARCHS; do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done
echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"
echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
done
SDK Initialization
Step 1: BuzzAdBenefit
の初期化
AppDelegateの application:didFinishLaunchingWithOptions
に下記コードを追加することを推奨しますが、 初回広告リクエストよりも前の段階であればコードの位置を自由に定めることができます。
YOUR_APP_ID の部分に上記で準備したapp_idを代入
// Objective-C
BABConfig *config = [[BABConfig alloc] initWithAppId:YOUR_APP_ID];
[BuzzAdBenefit initializeWithConfig:config];
Step 2: Set UserProfile
の設定(ユーザープロフィール設定)
ユーザーが貴社アプリにログインした時点で下記の通りUserProfile
をセットします。
追加事項 : User IDおよびターゲティング情報(性別・生まれ年)は円滑なサービス運営のためにご提供いただく必要がある必須項目です。該当の値が入力された
setUserProfile
関数が呼び出されない場合、広告の配信が行われません。
userId (必須): 貴社サービスにおいてユーザーを特定できるID
特定の条件においてuserIdが変更になる可能性がある場合は、事前にBuzzvil担当者にご相談ください。(例:ユーザーがアンインストール後にアプリを再インストールするとuserIdが変わる場合など)
gender
BABUserGenderMale
: 男性BABUserGenderFemale
: 女性
birthYear: 生まれ年
追加事項 : Step 1および2を通じてセッションキーの登録が完了すると、
BABSessionRegisteredNotification
notificationが呼び出されます。セッションキーはSDKが広告をリクエストし、それを受信するために必要なサーバーAPI Keyとして機能するため、セッションキーがないと広告の読み込みを行うことができません。Step 2と広告リクエストの時間差が短い場合、このnotificationを observeしてセッションキーの登録を確認後に広告リクエストを行うことができます。
iOS 14 以上のユーザーに対してApp Tracking Transparency権限許可のポップアップダイアログを表示するにはsetUserProfile
の引数として shouldShowAppTrackingTransparencyDialog
値をtrueにして呼び出してください(SDK 1.3.3 以上)。そしてアプリのinfo.plist ファイルにNSUserTrackingUsageDescription
値を追加し、権限許可ポップアップダイアログ上でユーザーに表示するメッセージを入れます。
このポップアップはまだ権限が許可するかどうかを選択していないユーザーに限り、1回のみ表示されます。
Step 3: UserPreference
の設定(動画広告の再生設定)
ユーザーがアプリにログインした時点で UserPreference
をビルドし、BuzzAdBenefit SDKに該当値を設定します。
autoplayType: 動画広告についての自動再生オプションを設定します。
AutoplayType
の設定値は次のとおりです。BABVideoAutoPlayEnabled
: Wi-Fi / LTE 両環境において動画広告の自動再生を行うBABVideoAutoPlayOnWifi
: Wi-Fiネットワークに接続している場合に限り動画広告の自動再生を行う(デフォルト)BABVideoAutoPlayDisabled
: 動画広告の自動再生を行わない
Step 4. ユーザー設定値の削除
ユーザーがアプリからログアウトした時点で UserProfile
および UserPreferences
設定値をSDKから削除し、ユーザーの利用情報を削除します。
Step 5. 次のステップに進む
SDKのインストールおよび初期設定が完了したら、次はBuzzAd Benefit広告を表示させる枠に適合した広告タイプを選択し、各タイプに合わせて残りの実装作業を行います。
Type A_Native : アプリUIに自然な形で溶け込むカスタムレイアウト型広告
Type B_Feed : リンクやボタンを通じてリワード広告一覧ページに遷移させ、複数の広告リストを表示する
Type C_Interstitial : Buzzvil指定のレイアウトを活用したDialog(ポップアップ)またはBottomSheet形式の全画面広告(インタースティシャル)
Advanced Usage(応用設定)
広告実行のカスタマイズ
広告の実行をカスタマイズすることができます。例えば広告のランディングページの読み込み等を貴社任意のClassで実装することができます。
実装時の注意事項 : Launcherにて提供されるクリックURIを任意でデコードしてロードしないでください。この場合サーバーでの動作が変わり、広告関連の統計データが正しく集計されなくなるおそれがあります。
BABLauncher
を実装します。openUrl:object:userInfo
メソッドの引数として渡されるオブジェクトはBABAdまたはBABArticleオブジェクトが含まれています。
** 追加事項** : 多様な広告を扱う特性上、広告をクリックしたときにディープリンクが動作してアプリ内ブラウザで広告主のアプリに離脱してしまうケースが発生することがあります。したがってLauncher使用時ユーザーが広告クリック後に広告主のアプリ画面にて「戻る」ボタンをタップしたときに当初の広告が表示されていた画面に適切に戻ってこられるようアプリ内ブラウザの動作を設定する必要があります。このように広告主のアプリに離脱する可能性があるディープリンクURL広告の場合、
ad.creative.isDeeplink
の値がYES
を返すように設定してください。
BuzzAdBenefit
にLauncher
をセットします。
Custom launcher使用の際のディーブリンク広告処理ガイド
外部アプリに遷移するディーブリンク広告の場合、redirectを経て最終的にターゲットアプリ(またはGoogle Play Store)に移動します。この場合、何も設定を行わないと遷移後にユーザーが再度元のアプリに戻ってきた時にredirectが行われたアプリ内ブラウザの空ページが表示されてしまいます。
この問題を解決し、自然なUXを実現するために外部アプリに遷移する広告の場合にはアプリ内ブラウザのページを閉じ、ユーザーがアプリに戻ってきたときに白紙ページが表示されないように処理する設定が必要です。 この時下記の2つの方法のうち、いずれか1つを選択して設定してください。
アプリ内ブラウザ内で発生するredirectをモニタリングし、http/httpsではないschemeが呼び出される場合はターゲットアプリが開いた後にアプリ内ブラウザは自動で閉じるように設定します。
広告内のCreative オブジェクトが持っている isDeeplink フィールド(
ad.creative.isDeeplink
)を利用して、ユーザーがアプリ内ブラウザが開いている状態でアプリから離脱した場合、アプリ内ブラウザが自動で閉じるように設定します。Buzzvilでは各広告のタイプをあらかじめチェックし、ディープリンク広告の場合 isDeeplinkを trueに、通常のWEB LP広告の場合 isDeeplinkを falseにして配信しています。よって、isDeeplinkが trueの広告がアプリ内ブラウザで開いている状態でアプリがバックグラウンドアプリに切り替わった場合、ターゲットアプリに移動したと判断してアプリ内ブラウザを閉じる処理を実行してください。
Custom launcher 使用時におけるArticleの sourceUrl の使用法
コンテンツにおいてURLスキームによって遷移方式を変えたい場合(ex. アプリ内でブラウザを開くことなく違う画面に移動するコンテンツ) 、次のような方法で NativeArticle
オブジェクトの sourceUrl
を取得し、分岐処理を行うことができます。
広告読み込み失敗時のエラー情報確認
広告の読み込みエラー時に呼び出されるコールバックのパラメータとして渡される BABError
オブジェクトの code
プロパティを通じて該当エラーの情報を確認することができます。