BuzzAd Benefit iOS SDK 導入ガイド(JP)

本ガイドはBuzzAd-Benefitの導入に必要な技術情報を解説するものです。

BuzzAd Benefitはアプリのエンゲージメントとそれに伴う収益化をサポートするアプリパブリッシャー向けのソリューションです。パブリッシャーはBuzzAd-Benefit SDKをiOSアプリ内に実装することで、アプリ内領域の任意の場所にリワード広告(静止画・動画)を表示させることが可能になります。

パブリッシャーが独自にカスタマイズしたレイアウトにあわせて広告コンポーネントを表示させることで、アプリ内での自然なUXを担保しつつ、収益の最大化をサポートします。

index

はじめに(Getting Started)

SDKをアプリに実装するにあたり、下記の3点が必要となります。

1. Buzzvil担当者を通じて取得した app_id

2. 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 準備

3. 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];

// Swift
let config = BABConfig(appId: YOUR_APP_ID)
BuzzAdBenefit.initialize(with: config)

Step 2: Set UserProfile の設定(ユーザープロフィール設定)

ユーザーが貴社アプリにログインした時点で下記の通りUserProfile をセットします。

追加事項 : User IDおよびターゲティング情報(性別・生まれ年)は円滑なサービス運営のためにご提供いただく必要がある必須項目です。該当の値が入力された setUserProfile 関数が呼び出されない場合、広告の配信が行われません。

• userId (必須): 貴社サービスにおいてユーザーを特定できるID

  • 特定の条件においてuserIdが変更になる可能性がある場合は、事前にBuzzvil担当者にご相談ください。(例：ユーザーがアンインストール後にアプリを再インストールするとuserIdが変わる場合など)

• gender

  • BABUserGenderMale: 男性

  • BABUserGenderFemale: 女性

• birthYear: 生まれ年

// Objective-C
BABUserProfile *userProfile = [[BABUserProfile alloc] initWithUserId:YOUR_SERVICE_USER_ID birthYear:1985 gender:BABUserGenderMale];
[BuzzAdBenefit setUserProfile:userProfile];

// Swift
let userProfile = BABUserProfile(userId: YOUR_SERVICE_USER_ID, birthYear: 1985, gender: BABUserGenderMale)
BuzzAdBenefit.setUserProfile(userProfile)

追加事項 : Step 1および2を通じてセッションキーの登録が完了すると、 BABSessionRegisteredNotification notificationが呼び出されます。セッションキーはSDKが広告をリクエストし、それを受信するために必要なサーバーAPI Keyとして機能するため、セッションキーがないと広告の読み込みを行うことができません。Step 2と広告リクエストの時間差が短い場合、このnotificationを observeしてセッションキーの登録を確認後に広告リクエストを行うことができます。

// Objective-C
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(loadBABAd) name:BABSessionRegisteredNotification object:nil];

// Swift
NotificationCenter.default.addObserver(self, selector: #selector(loadBABAd), name: NSNotification.Name.BABSessionRegistered, object: nil)

Step 3: UserPreference の設定(動画広告の再生設定)

ユーザーがアプリにログインした時点で UserPreferenceをビルドし、BuzzAdBenefit SDKに該当値を設定します。

• autoplayType: 動画広告についての自動再生オプションを設定します。 AutoplayType の設定値は次のとおりです。

  • BABVideoAutoPlayEnabled: Wi-Fi / LTE 両環境において動画広告の自動再生を行う

  • BABVideoAutoPlayOnWifi: Wi-Fiネットワークに接続している場合に限り動画広告の自動再生を行う(デフォルト)

  • BABVideoAutoPlayDisabled: 動画広告の自動再生を行わない

// Objective-C
BABUserPreference *userPreference = [[BABUserPreference alloc] initWithAutoPlayType:BABVideoAutoPlayEnabled];
[BuzzAdBenefit setUserPreference:userPreference];

// Swift
let userPreference = BABUserPreference(autoPlayType: BABVideoAutoPlayEnabled)
BuzzAdBenefit.setUserPreference(userPreference)

Step 4. ユーザー設定値の削除

ユーザーがアプリからログアウトした時点で UserProfile および UserPreferences 設定値をSDKから削除し、ユーザーの利用情報を削除します。

// Objective-C
[BuzzAdBenefit setUserProfile:nil];
[BuzzAdBenefit setUserPreference:nil];

// Swift
BuzzAdBenefit.setUserProfile(nil)
BuzzAdBenefit.setUserPreference(nil)

Step 5. 次のステップに進む

SDKのインストールおよび初期設定が完了したら、次はBuzzAd Benefit広告を表示させる枠に適合した広告タイプを選択し、各タイプに合わせて残りの実装作業を行います。

• Type A_Native : アプリUIに自然な形で溶け込むカスタムレイアウト型広告

• Type B_Feed : リンクやボタンを通じてリワード広告一覧ページに遷移させ、複数の広告リストを表示する

• Type C_Interstitial : Buzzvil指定のレイアウトを活用したDialog(ポップアップ)またはBottomSheet形式の全画面広告(インタースティシャル)

Advanced Usage(応用設定)

広告実行のカスタマイズ

広告の実行をカスタマイズすることができます。例えば広告のランディングページの読み込み等を貴社任意のClassで実装することができます。

実装時の注意事項 : Launcherにて提供されるクリックURIを任意でデコードしてロードしないでください。この場合サーバーでの動作が変わり、広告関連の統計データが正しく集計されなくなるおそれがあります。

1. BABLauncher を実装します。 openUrl:object:userInfo メソッドの引数として渡されるオブジェクトはBABAdまたはBABArticleオブジェクトが含まれています。

// Objective-C
@interface BABCustomLauncher : NSObject <BABLauncher>
@end

@implementation BABCustomLauncher
- (void)openUrl:(NSURL *)url object:(id)object userInfo:(nullable NSDictionary *)userInfo {
  if ([object isKindOfClass:BABAd.class]) {
    BABAd *ad = object;
    NSString *unitId = ad.unitId;
    NSString *title = ad.creative.title;
  }
  ...

  [UIApplication.sharedApplication openURL:url options:@{} completionHandler:nil];
}
@end

// Swift
class BABCustomLauncher: NSObject, BABLauncher {
  func open(_ url: URL, object: Any?, userInfo: [AnyHashable : Any]? = nil) {
    if let ad = object as? BABAd {
      let unitId = ad.unitId
      let title = ad.creative.title
    }
    ...

    UIApplication.shared.open(url, options: nil, completionHandler: nil)
  }
}

** 追加事項** : 多様な広告を扱う特性上、広告をクリックしたときにディープリンクが動作してアプリ内ブラウザで広告主のアプリに離脱してしまうケースが発生することがあります。したがってLauncher使用時ユーザーが広告クリック後に広告主のアプリ画面にて「戻る」ボタンをタップしたときに当初の広告が表示されていた画面に適切に戻ってこられるようアプリ内ブラウザの動作を設定する必要があります。このように広告主のアプリに離脱する可能性があるディープリンクURL広告の場合、ad.creative.isDeeplinkの値が YESを返すように設定してください。

1. BuzzAdBenefitに Launcherをセットします。

// Objective-C
BABCustomLauncher *launcher = [[BABCustomLauncher alloc] init];
[BuzzAdBenefit setLauncher:launcher];

// Swift
let adLauncher = BABCustomLauncher()
BuzzAdBenefit.setLauncher(launcher)

Custom launcher使用の際のディーブリンク広告処理ガイド

外部アプリに遷移するディーブリンク広告の場合、redirectを経て最終的にターゲットアプリ(またはGoogle Play Store)に移動します。この場合、何も設定を行わないと遷移後にユーザーが再度元のアプリに戻ってきた時にredirectが行われたアプリ内ブラウザの空ページが表示されてしまいます。

この問題を解決し、自然なUXを実現するために外部アプリに遷移する広告の場合にはアプリ内ブラウザのページを閉じ、ユーザーがアプリに戻ってきたときに白紙ページが表示されないように処理する設定が必要です。 この時下記の2つの方法のうち、いずれか1つを選択して設定してください。

1. アプリ内ブラウザ内で発生するredirectをモニタリングし、http/httpsではないschemeが呼び出される場合はターゲットアプリが開いた後にアプリ内ブラウザは自動で閉じるように設定します。

2. 広告内のCreative オブジェクトが持っている isDeeplink フィールド(ad.creative.isDeeplink)を利用して、ユーザーがアプリ内ブラウザが開いている状態でアプリから離脱した場合、アプリ内ブラウザが自動で閉じるように設定します。Buzzvilでは各広告のタイプをあらかじめチェックし、ディープリンク広告の場合 isDeeplinkを trueに、通常のWEB LP広告の場合 isDeeplinkを falseにして配信しています。よって、isDeeplinkが trueの広告がアプリ内ブラウザで開いている状態でアプリがバックグラウンドアプリに切り替わった場合、ターゲットアプリに移動したと判断してアプリ内ブラウザを閉じる処理を実行してください。
   

Custom launcher 使用時におけるArticleの sourceUrl の使用法

コンテンツにおいてURLスキームによって遷移方式を変えたい場合(ex. アプリ内でブラウザを開くことなく違う画面に移動するコンテンツ) 、次のような方法で NativeArticle オブジェクトの sourceUrlを取得し、分岐処理を行うことができます。

- (void)openUrl:(NSURL *)url object:(id)object userInfo:(nullable NSDictionary *)userInfo {
  if ([object isKindOfClass:BABArticle.class]) {
    BABArticle *article = object;
    NSString *sourceUrl = article.sourceUrl;
    ...
  }
}
func open(_ url: URL, object: Any?, userInfo: [AnyHashable : Any]? = nil) {
    if let article = object as? BABArticle {
      let sourceUrl = article.sourceUrl
      ...
    }
}

広告読み込み失敗時のエラー情報確認

広告の読み込みエラー時に呼び出されるコールバックのパラメータとして渡される BABError オブジェクトの code プロパティを通じて該当エラーの情報を確認することができます。

typedef enum {
  BABUnknownError = 0,
  BABServerError,
  BABInvalidRequest,
  BABRequestTimeout,
  BABEmptyResponse
} BABErrorCode;