Native Type(2.0)

Native Type(2.0)

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() を呼び出す

final String TAG = YourActivity.class.getSimpleName(); final NativeAdLoader loader = new NativeAdLoader("YOUR_NATIVE_AD_UNIT_ID"); loader.loadAd(new NativeAdLoader.OnAdLoadedListener() { @Override public void onLoadError(@NonNull AdError adError) { Log.e(TAG, "Failed to load a native ad.", adError); } @Override public void onAdLoaded(@NonNull NativeAd nativeAd) { populateAd(nativeAd); // Step 3 参照 } });

 

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

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

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

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

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

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

コンポーネント

説明

サイズ

詳細

必須/任意

コンポーネント

説明

サイズ

詳細

必須/任意

Media view

画像・動画等の広告素材

1200x627 px

  • アスペクト比の維持を推奨

  • 画像の周囲にパディング(余白)の追加が可能

必須

Title view

広告のタイトル

最大 25字

日本語の場合は最大10字

省略符号(…)で一定数以上の文字を省略可能

必須

Description view

広告の詳細説明

最大 100字

日本語の場合は最大30字

省略符号(…)で一定数以上の文字を省略可能

必須

CTA view

  • Reward text view: 広告参加時に報酬として付与されるポイント数

  • CTA text view: ユーザーに広告参加を誘導する文言

最大 15字

日本語の場合は4〜7字

 

省略符号(…)で一定数以上の文字を省略可能

必須

Icon image view

広告主のアイコン

80x80 px

アスペクト比の維持を推奨(正方形)

必須

Sponsored image/text view

広告であることを明示するテキストまたは画像

 

広告, ad, スポンサード, Sponsored 等の文言を表示

任意

文字数は1バイト基準。半角スペースも1文字とみなす

 

<com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView android:id="@+id/native_ad_view" ... > <LinearLayout ... > <com.buzzvil.buzzad.benefit.presentation.media.MediaView android:id="@+id/mediaView" ... /> <TextView android:id="@+id/textTitle" ... /> <TextView android:id="@+id/textDescription" ... /> <ImageView android:id="@+id/imageIcon" ... /> <com.buzzvil.buzzad.benefit.presentation.media.CtaView android:id="@+id/ctaView" .../> ... </LinearLayout> ... </com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView>

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

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

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

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

  3. NativeAdView に clickableViewsMediaViewNativeAd をセットします。

  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(リワードを表示するボタン)のカスタマイズは次のように行います。 

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(); ... // Viewを継承したCustomCtaView classを生成し、CtaViewをカスタマイズすることができます。 final CustomCtaView customizedCtaView = view.findViewById(R.id.customCtaView); // 下記の情報を利用してctaviewをアップデート final String callToAction = nativeAd.getAd().getCallToAction(); final int reward = nativeAd.getAd().getReward(); // 注意事項を参照 final boolean participated = nativeAd.isParticipated(); // 下記のようなfunctionをCustomCtaView classに生成してテキスト文言およびアイコンをアップデートすることができます customizedCtaView.setCtaText(callToAction); // テキスト変更 customizedCtaView.setRewardText(reward); customizedCtaView.setRewardIcon(R.drawable.your_reward_icon); customizedCtaView.setParticiapted(participated); // 広告に参加済みであることを知らせるUI customizedCtaView.setBackgroundColor(Color.parseColor(“#3976FD”)); // 変更する"カラーコード"を入力 ... final List<View> clickableViews = new ArrayList<>(); clickableViews.add(customizedCtaView); ... nativeAdView.addOnNativeAdEventListener(new NativeAdView.OnNativeAdEventListener() { ... @Override public void onParticipated(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) { // 企画内容に応じたUI処理 // カスタマイズされたCtaViewを参加ステータスにあわせてアップデート final boolean participated = nativeAd.isParticipated(); customizedCtaView.setParticipated(participated); } }); }

複数の広告読み込み 任意

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

final NativeAdLoader loader = new NativeAdLoader("YOUR_NATIVE_AD_UNIT_ID"); loader.loadAds(new NativeAdLoader.OnAdsLoadedListener() { @Override public void onLoadError(@NonNull AdError adError) { ... } @Override public void onAdsLoaded(@NonNull Collection<NativeAd> collection) { ... } }, NATIVE_ADS_COUNT);

Feed entry pointを追加する 必須

この機能を利用するにはバージョン 2.16.x 以上にアップデートしてください。

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

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に入る際にもらえるポイントを事前に知ることができます。

  • ユーザーに正確なリワード付与数を知らせるため、ActivityonStart() 時点でテキストの更新を行ってください。

  • メモリリークを防ぐため、 ActivityonStop() 時点で BaseRewardManager.clear() 関数を呼び出してください。

1.Feed Configの追加

private void initializeBuzzAdBenefit(Context context) { final FeedConfig feedConfig = new FeedConfig.Builder(context, YOUR_FEED_UNIT_ID) ... // customization code can be added .build(); final BuzzAdBenefitConfig buzzAdBenefitConfig = configBuilder .add(feedConfig) .build(); BuzzAdBenefit.init(context, buzzAdBenefitConfig); }

2.NavigateToFeedLayout viewの構成

<?xml version="1.0" encoding="utf-8"?> <androidx.constraintlayout.widget.ConstraintLayout ... <com.buzzvil.buzzad.benefit.presentation.feed.navigation.NativeToFeedLayout android:id="@+id/native_to_feed_layout" ...> <TextView ... /> <ImageView ... /> </com.buzzvil.buzzad.benefit.presentation.feed.navigation.NativeToFeedLayout> ... </androidx.constraintlayout.widget.ConstraintLayout>

3.navigateToFeedLayoutをセットする

@Override protected void onCreate(Bundle savedInstanceState) { ... NativeToFeedLayout nativeToFeedLayout = findViewById(R.id.native_to_feed_layout); nativeToFeedLayout.setUnitId(YOUR_FEED_UNIT_ID); ... }

4. Feedに入るともらえるポイント数をテキストで表示する

BaseRewardManager baseRewardManager = BuzzAdBenefit.getBaseRewardManager(); @Override public void onStart() { super.onStart(); updateNavigationTextView(); } @Override public void onStop() { super.onStop(); baseRewardManager.clear(); } private void updateNavigationTextView() { baseRewardManager.getAvailableFeedBaseReward( yourFeedUnitId, reward -> { if (reward < 1) { navigationTextView.setText("ここをクリックしてさらにポイントGET"); // string resourceに替えてください } else { navigationTextView.setText(String.format(Locale.ROOT, "%d ptGETしてさらに多くのチャンスに出会う", reward)); } } ); }

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

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

mediaView.setVideoEventListener(new VideoEventListener() { @Override public void onVideoStarted() { } @Override public void onError(@NonNull VideoErrorStatus videoErrorStatus, @Nullable String errorMessage) { if (errorMessage != null) { Toast.makeText(mediaView.getContext(), errorMessage, Toast.LENGTH_SHORT).show(); } } @Override public void onResume() { } @Override public void onPause() { } @Override public void onReplay() { } @Override public void onVideoEnded() { // 動画の再生完了時に必要な処理 } @Override public void onLanding() { // 動画広告のLP遷移時に必要な処理 } });

 

広告参加ステータスに応じた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)

    if ad.reward_status == "received" || ad.is_participated == true { // リワードは存在するが、付与周期内にすでに参加済みの広告(付与対象外) rewardLabel.text = "参加済み" // Or rewardLabel.text = "0P" } else { if ad.reward > 0 { // リワードが存在し、未参加の広告(付与対象) rewardLabel.text = ad.reward + "P" } else { // リワードが存在しない広告 (現在Benefitはリワード型広告のみを配信しているため) rewardLabel.text = "0P" } }