BuzzAd Benefit 2 Android SDK 導入ガイド
本ガイドではBuzzAd-Benefit SDKの導入に必要な技術情報を解説します。
BuzzAd Benefitはアプリの収益化とエンゲージメント向上をサポートするアプリパブリッシャー向けのソリューションです。パブリッシャーはBuzzAd Benefit SDKをAndroidアプリ内に実装することで、アプリ内領域の任意の場所にリワード広告(静止画・動画)を表示させることが可能になります。
パブリッシャーが独自にカスタマイズしたレイアウトにあわせて広告コンポーネントを表示させることで、アプリ内での自然なUXを担保しつつ、収益の最大化をサポートします。
Index
- 1 実装に必要なもの
- 2 実装を始める前に
- 3 インストール
- 3.1 ADN連携について(推奨)
- 4 SDKの初期化
- 5 More details
実装に必要なもの
SDKをアプリに実装するにあたり、下記の3点が必要となります。
Buzzvil担当者を通じて取得した app_id
Buzzvil担当者を通じて取得した unit_id (配信枠ごとにunit_id を発行します)
Type A Native 適用時
NATIVE AD UNIT_ID
準備Type B Feed 適用時
FEED UNIT_ID
準備Type C_Interstitial 適用時
INTERSTITIAL UNIT_ID
を準備Type D_Pop 適用時
すでにBenefit SDKが実装済みの場合、
POP UNIT_ID
を準備初めてBenefit SDKの実装を行う場合で、POP単独での実装を行う場合はBuzzAdPopに移動
Buzzvil サーバーからポイント付与リクエストを受信する貴社(メディア側)APIサーバー - ポイントポストバックAPI 連携文書
Postback 受信用URLを設定後、Buzzvil担当者までお知らせください。
実装を始める前に
AndroidXの使用についての文書を参照し、プロジェクトをAndroid Xに移行(Migration)してください。
インストール
githubにてサンプルコードを公開しているので、実装の際の参考資料としてご活用ください。
build.gradle
の dependencies 部分に下記のコードを追加
“com.buzzvil:buzzad-benefit:実装するバージョン”
を入力してください。
repositories {
maven { url "https://dl.buzzvil.com/public/maven" }
}
...
dependencies {
// 2.19 バージョンの最新版が適用されます。
implementation ("com.buzzvil:buzzad-benefit:2.19.+") {
ADN連携について(推奨)
ノンリワード型のADN広告を併用することで収益を安定させることができます。ADNを連携するには下記の要領でSDKを実装します。インストール時にあわせて設定してください。
Requirements:
feedタイプ(FeedまたはPop feed)のみ対応
バージョン2.9以上から対応
build.gradle
のdependencies部分に下記コードを追加します。
// Outbrain
implementation("com.buzzvil.mediation:sdk-outbrain:$mediationOutbrainVersion")
// Five (Benefit 2.13.x or higher)
implementation('com.buzzvil.mediation:sdk-five:1.1.0')
BuzzAdBenefit 2.9.0 バージョンより画像ライブラリをUILからPicassoに変更しました。
(FAQ) ビルドするときに問題が発生した場合は?(クリックして展開)
SDKの初期化
Step 1: Initialize BuzzAdBenefit
AndroidManifest.xmlに下記の通りmeta_dataを追加
app-pub-000000000000
の数字部分に上記で準備したapp_idを代入
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.buzzvil.packagename">
<application>
...
<!-- Caution: Replace `000000000000` with Your AppKey -->
<meta-data
android:name="com.buzzvil.APP_KEY"
android:value="app-pub-000000000000" />
</application>
</manifest>
Application Classの onCreate
に下記コードを追加することを推奨しますが、初回広告リクエストよりも前の段階であればコードの位置を自由に定めることができます。
Step 2: UserProfile
の設定(ユーザープロフィール設定)
ユーザーが貴社アプリにログインした時点で下記の通りUserProfile
をセットします。設定値を修正する際は既存のuser profileを呼び出して修正することが可能です。
注意 : User IDおよびターゲティング情報(性別・生まれ年)は円滑なサービス運営のために必要な必須情報のため、必ずご提供いただく必要がある必要があります。 該当の値が入力された setUserProfile関数が呼び出されない場合、広告の配信が行われません。
userId : 貴社サービスにおいてユーザーを特定できるID
特定の条件においてuserIdが変更になる可能性がある場合は、事前にBuzzvil担当者にご相談ください。(例:ユーザーがアンインストール後にアプリを再インストールするとuserIdが変わる場合など)
gender
UserProfile.Gender.MALE
: 男性UserProfile.Gender.FEMALE
: 女性
birthYear: 生まれ年
追加事項 : Step 1および2を通じてセッションキーの登録が完了すると、
SessionReady
Broadcastが送信されます。セッションキーはSDKが広告をリクエストし、それを受信するために必要なサーバーAPI Keyとして機能するため、セッションキーがないと広告の読み込みを行うことができません。Step 2と広告リクエストの時間差が短い場合、下記の方法で SessionReadyに対するbroadcastを受信し、セッションキーの登録を確認後に広告リクエストを行うことができます。
Step 3: UserPreferences
の設定(動画広告の再生設定)
ユーザーがアプリにログインした時点で UserPreferences
をビルドし、BuzzAdBenefit SDKに該当値を設定します。
autoplayType(AutoplayType autoplayType)
: 動画広告についての自動再生オプション設定
AutoplayType
の設定値は下記の通りです。設定しない場合、デフォルト値のAutoplayType.ON_WIFI
が適用されます。AutoplayType.ENABLED
: Wi-Fi / LTE 両環境において動画広告の自動再生を行うAutoplayType.ON_WIFI
: Wi-Fiネットワークに接続している場合に限り動画広告の自動再生を行う(デフォルト)AutoplayType.DISABLED
: 動画広告の自動再生を行わない
Step 4. ユーザー設定値の削除
ユーザーがアプリからログアウトした時点で UserProfile
および UserPreferences
設定値をSDKから削除し、ユーザーの利用情報を削除します。
Step 5. 次のステップに進む
SDKのインストールおよび初期設定が完了したら、次はBuzzAd Benefitを表示させる位置に適した広告タイプを選択し、各タイプに合わせて残りの実装作業を行います。
Type A - Native Ads : インフィード型のカスタムレイアウト型広告
Type B - Feed : アプリ内リンクやボタンのクリックによりリワード広告/コンテンツが一覧表示されるフィード(リスト型)を表示する
Type C - Interstitial : 画面遷移時の任意のタイミングで表示させるポップアップ型の全画面広告(インタースティシャル)。Buzzvil提供のレイアウトを活用するため、少ない工数で実装できるのが特徴。
Type D - Pop : Androidの画面上に表示されるチャットヘッド型アイコンのタップによりリワード広告/コンテンツが一覧表示されるフィード(リスト型)を表示する
More details
(重要) 個人情報の取り扱いに関する方針
個人情報保護法およびGoogleのポリシーに対応するため、Buzzvilが提供する広告プロダクトの画面に入る際に個人情報の収集および利用についての同意を求めるUIが表示されます。ユーザーはページを移動することなく個人情報の収集および利用についての詳細を確認することができます。
ユーザーが個人情報の収集及び利用に同意してはじめて広告への参加が可能になるため、この画面で「同意しない」を選択した場合はBuzzvilの広告プロダクトを利用することができなくなります。
個人情報の収集および利用への同意は bottom-sheet 型のUIで表示され、APIで呼び出し可能です。
<個人情報の取得同意画面 bottom-sheet>
<同意しない場合のFeed>
個人情報の取り扱いに関する方針と関連して次のAPIを使用することができます。
(重要) もし上記のAPIを使用しない場合は、Buzzvilへの個人情報収集についての同意を得るUIを直接実装する必要があります。
同意しないを選択した状態でFeedに入った時
同意しないを選択した状態でPop Iconをクリックする時
その他Buzzvilのプロダクト表示に同意する段階
(重要) アクション型広告を配信する
アクション型広告とは、広告クリック後に用意された指定の条件(アクション)を達成することでユーザーにリワードが付与される広告を指します。広告枠内でアクション型広告を掲載する場合、下記の条件を満たす必要があります。
(デフォルトのCTAボタンを使用する場合はすでに適用済み)
(カスタムランチャーを使用しない場合はスキップできます)
[1] 参加ステータスに応じたCTAボタンUIの変化 必須
アクション型広告もディスプレイ型と同様、付与完了コールバックが適用されます。
ステータスの区分は参加前 →参加状況確認中(is clicked) → 参加済み(is participated)の3段階に分かれています。なお、2.2.3バージョン以上でデフォルトのCTAボタンを使用する(=CTAボタンをCustom classで実装しない)場合、この設定はデフォルトで適用されます。
[2] アクション型広告に関するユーザー問い合わせページの使用 必須
BuzzAd Benefit SDKは動画視聴完了・アプリインストール・Facebookへのいいね!など多様なアクションに対してリワードを付与する広告を提供しています。そしてこのような広告の場合、リワード未付与などの理由によるユーザーからの問い合わせが発生することがあります。
このような問い合わせをスムーズに処理するために、SDKにて専用問い合わせページを提供しています。この問い合わせページは実装するアプリ単位で照会可能なため、Unitごとに設定する必要はありません。また、問い合わせページの位置はパブリッシャーが自由に設定することができます。
次の手順でこの機能を利用することができます。
問い合わせページを開くためのIcon/Tabをデザインします。
1番のIcon/Tabがクリックされた時点で
BuzzAdBenefit.getInstance().showInquiryPage(context)
を呼び出します。特定のUnitについてのみ問い合わせページを表示したい場合、
showInquiryPage(Context context, @Nullable final String unitId)
を使用して、表示対象とするUnitのUnit Id を入力します。Unit Id が null の場合アプリ全体が照会対象になります。
Interstitial, Feed タイプの場合、問い合わせ用のアイコンがSDKに含まれているので、これをそのまま使用してもかまいません。(下記をクリックして画像および適用方法を確認できます。)
[3] カスタムアプリ内ブラウザの適用 該当時のみ適用
カスタムランチャーを使用していない場合はこの項目はスキップできます。
カスタムランチャーを使用する場合は下記の内容に従ってカスタムアプリ内ブラウザを必ず実装してください。
BuzzAd Benefit Productsにテーマを適用する
AppThemeにBuzzvilより適用されるattributeを定義すると簡単にBuzzAd Benefit UIのカスタマイズを行うことができます。
attribute (type) | child attribute (type) | カスタマイズされるUI |
---|---|---|
| N/A |
|
|
|
|
| N/A |
|
| N/A |
|