BuzzAd-Benefit 2.0 SDK: Type A - Native Ads

本ドキュメントは BuzzAd-Benefit SDKのType A- Native Ads(インフィード型ネイティブ広告)を実装する際に必要な技術情報をまとめた文書です。

※ 注意事項

1. Native Adsタイプの実装を行う前に、導入ガイドの内容がすべて適用されているかどうかを確認してください。

2. Nativeタイプの広告が表示されるページにはActivityまたはFragmentが実装されている必要があります。もし適用されていない場合はBuzzvil担当者に事前にご相談ください。

Index

基本設定 Basic Usage

Step 1: NativeAdLoader で広告をリクエスト 必須

1. NativeAdLoader オブジェクトをインスタンス化する

   • YOUR_NATIVE_AD_UNIT_ID を代入

2. loadAd() を呼び出す

Step 2: 広告レイアウトの生成 必須

アプリ内領域に広告レイアウトを生成し、広告コンポーネントを関連ビューに紐付けます。

• BuzzAd Benefit 広告レイアウトのRootは com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView になるよう設定します。

  • NativeAdView クラスは1つの広告に対応する ViewGroup の一種です。広告を表示させるための下位コンポーネントは必ずこのオブジェクトのchildとして登録する必要があります。

• 広告素材を表示させるビューには com.buzzvil.buzzad.benefit.presentation.media.MediaViewが必ず含まれるようにしてください。

下位コンポーネントの一覧表

Step 3: NativeAd オブジェクトでレイアウトを構成 必須

Step 1 の onAdLoaded で取得した NativeAd オブジェクトを利用して広告Viewを作成します。

1. 上のStep 2で生成した広告コンポーネントViewにNativeAd.getAd() を通じて取得した広告の各要素をセットします。

2. clickableViews listを生成し、広告クリックが可能になるように設定する領域を指定します。該当Viewをクリックすると、広告ランディングページに遷移します。

3. NativeAdView に clickableViews, MediaView, NativeAd をセットします。

4. 広告の参加完了後、UI切り替えのため NativeAdView に OnNativeAdEventListener を登録し、 onParticipated コールバックにより該当の広告にはすでに参加済みであることを表示します。

    

   public void populateAd(final NativeAd nativeAd) { final NativeAdView view = findViewById(R.id.native_ad_view); final Ad ad = nativeAd.getAd(); final Creative.Type creativeType = ad.getCreative() == null ? null : ad.getCreative().getType(); final MediaView mediaView = view.findViewById(R.id.mediaView); final TextView titleTextView = view.findViewById(R.id.textTitle); final ImageView iconView = view.findViewById(R.id.imageIcon); final TextView descriptionTextView = view.findViewById(R.id.textDescription); final CtaView ctaView = view.findViewById(R.id.ctaView); final CtaPresenter ctaPresenter = new CtaPresenter(ctaView); // CtaView should not be null ctaPresenter.bind(nativeAd); // 1) Assign Ad Properties. if (mediaView != null) { mediaView.setCreative(ad.getCreative()); mediaView.setVideoEventListener(new VideoEventListener() { // Override and implement methods }); } if (titleTextView != null) { titleTextView.setText(ad.getTitle()); } if (iconView != null) { ImageLoader.getInstance().displayImage(ad.getIconUrl(), iconView); } if (descriptionTextView != null) { descriptionTextView.setText(ad.getDescription()); } // 2) Create a list of clickable views. final List<View> clickableViews = new ArrayList<>(); clickableViews.add(ctaView); clickableViews.add(mediaView); clickableViews.add(titleTextView); clickableViews.add(descriptionTextView); // 3) Register ClickableViews, MediaView and NativeAd to NativeAdView. nativeAdView.setClickableViews(clickableViews); nativeAdView.setMediaView(mediaView); nativeAdView.setNativeAd(nativeAd); // Advanced : 広告ViewをScaleして使用する場合に限り適用 // nativeAdView.setScaleValue(SCALE_X_VALUE, SCALE_Y_VALUE); // 4) Add OnNativeAdEventListener to NativeAdView and implement participated UI. nativeAdView.addOnNativeAdEventListener(new NativeAdView.OnNativeAdEventListener() { @Override public void onImpressed(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) { } @Override public void onClicked(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) { // アクション型広告についてのCTA処理 ctaPresenter.bind(nativeAd); } @Override public void onRewardRequested(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) { // 企画内容に応じてリワード読み込み画像を表示する等の処理 } @Override public void onRewarded(@NonNull NativeAdView view, @NonNull NativeAd nativeAd, @Nullable RewardResult rewardResult) { // リワード付与結果(RewardResult) SUCCESS, ALREADY_PARTICIPATED, MISSING_REWARD 等に応じて適切なユーザーへの通知を行う処理 } @Override public void onParticipated(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) { // 企画内容に応じたUI処理 ctaPresenter.bind(nativeAd); } }); }

5. (オプション) 広告のステータス別コールバックに対する多様なカスタマイズが可能です。 (コールバックの定義及び動作の詳細は本ページを参照してください。)

6. (オプション) 広告のデザインをカスタマイズする場合は下記のデザインのカスタマイズ方法を参照してください。

Advanced Usage

デザインのカスタマイズ

CtaView (ボタン)のカスタマイズ 任意

CtaView(リワードを表示するボタン)のカスタマイズは次のように行います。 

複数の広告読み込み 任意

NativeAdLoader の loadAds(NativeAdLoader.OnAdsLoadedListener listener, int count)を使用して複数のネイティブ広告を読み込むことができます。 

Feed entry pointを追加する 必須

Feedモジュールはクリック時にFeed Activityを開く NavigateToFeedLayout classを提供します。このclassを追加することで、NativeからFeedに移動するentry pointを簡単に実装することができます。

Open

NavigateToFeedLayoutはデフォルトで onClickListener()が設定されているhorizontal orientation의 LinearLayout です。 NavigateToFeedLayoutを実装するには下記の手順で進めてください。

1.NavigateToFeedLayoutを使用するには BuzzAdBenefit.init() 時点で feedConfigを追加します。

2. NavigateToFeedLayout viewを構成し、該当のviewを使用するlayoutファイルに追加します。

3. example_layout.xmlを使用するview class(例: activity, fragment)にて NavigateToFeedLayout.setUnitId(YOUR_FEED_UNIT_ID)を呼び出し navigateToFeedLayoutをセットします。この時の YOUR_FEED_UNIT_IDは step 1で feedConfigを設定する時に使用したYOUR_FEED_UNIT_ID値と一致させてください。

4. (Optional) ユーザーがFeedに入る際に追加で付与されるポイント数を表記することで注意を促し、参加率を高めることができます。BuzzAdBenefit.getBaseRewardManager()を通じて BaseRewardManager オブジェクトを呼び出し BaseRewardManager.getAvailableFeedBaseReward() 関数を呼び出すとユーザーがFeedに入る際にもらえるポイントを事前に知ることができます。

動画広告のエラー発生時のリスナー登録

MediaViewにて動画再生エラーが発生した場合にリスナーを登録することができます。

広告参加ステータスに応じたCTAボタン表示の分岐処理

Buzzvil Benefit SDKを通じて配信される広告は基本的にすべてリワードが割り当てられています。 ただし、広告ごとにリワードの付与間隔(通常1〜2時間に1回程度)がそれぞれ設定されており、ユーザーが次回のリワード付与タイミングよりも前に同一の広告に再度参加した場合はリワードが付与されません。よって、広告レンダリング時に次の方法で分岐処理を行い、適切なUIを用いて該当の広告がリワード付与の対象かどうかをユーザーに知らせる必要があります。

例えばある広告のIPU(1時間あたりの最大表示数上限)を無制限にし、リワード付与間隔が1時間の場合、最初の広告参加時にはリワードが付与されます。しかし、その後1時間以内に同じ広告が表示された場合には同じ広告に参加してもリワードが付与されません。その旨をユーザーに知らせるため、CTA等のUIを「参加済み」または「0P(0ポイント)」と表示し、ユーザーにリワードが付与されない旨を適切に通知する必要があります。 

• UI分岐処理の際に使用されるフィールド

  • 広告オブジェクトのreward_status: Buzzvilサーバーにて広告を割り当てる際に、該当の広告についてリワード付与周期内にユーザーの付与履歴がすでに存在する場合"received" という戻り値を返します。(注意: reward_statusが"received"であってもrewardの値にはもともとリワード金額がそのまま記録されています。)

  • 広告オブジェクトのis_participated: 現在割り当てられている広告の参加ステータスを同期化するためのパラメータです。広告参加が行われると該当の広告及びメモリ上の同一広告のis_participated値がtrueに変わり、onParticipateコールバックが呼び出されます。
    (注意: reward_statusが"received"であっても今回の割当においては再度参加する前まで is_participatedは "false" に設定されています。rewardの値にはもともとリワード額がそのまま記録されています。)

• 分岐処理の例と疑似コード(pseudo code)