BuzzAd Benefit SDK: Native Ads

This documentation provides a guideline for integrating native ads for BuzzAd Benefit.

※ Note

1. Please proceed with the following process only after BuzzAd Benefit SDK integration is complete.

2. The placement in which the native ads will be exposed should be implemented as Activity or Fragment. If otherwise, please consult with the BD manager.

Index

Basic Usage

Step 1: Ad request with NativeAdLoader

1. Instantiate the NativeAdLoader

   • Insert unit_id in place of YOUR_NATIVE_AD_UNIT_ID

2. Call loadAd()

Step 2: Creating an ad layout

Create a layout for the ad components and link them to the relevant views. 

• Root layout should be set to com.buzzvil.buzzad.benefit.presentation.nativead.NativeAdView

  • NativeAdView is a ViewGroup that corresponds to a single ad. Subcomponents for displaying an ad must be registered as children of this object.

• The view responsible for showing the creative must include com.buzzvil.buzzad.benefit.presentation.media.MediaView

Subcomponents

Step 3: Constructing the layout with the NativeAd

Draw an ad view using the NativeAd received from the onAdLoaded in Step 1:

1. Set each ad property obtained via NativeAd.getAd() to the components created in Step 2.

2. Create a clickableViews list to specify the areas where you want to make the ad clickable. Clicking the view area will lead to a landing page of an ad.

3. Set clickableViews, MediaView and NativeAd to a NativeAdView.

4. Register OnNativeAdEventListener in the NativeAdView to change the UI and indicate ad participation in the onParticipated callback after the user opts into an ad.

5. (Optional) Implement necessary customizations for the state-specific callbacks for the ad. (Refer to the document for event definitions and actions)

6. (Optional) If you want to customize the design of your ad, see Advanged Usage - Customizing Design.
   
   
   

   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 : Applicable only when using Ad View with 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) { } @Override public void onRewardRequested(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) { // Show loading image for reward } @Override public void onRewarded(@NonNull NativeAdView nativeAdView, @NonNull NativeAd nativeAd, @Nullable RewardResult rewardResult) { // Result of reward processing (RewardResult): SUCCESS, ALREADY_PARTICIPATED, MISSING_REWARD, etc. Appropriate user communication needed accordingly. } @Override public void onParticipated(@NonNull NativeAdView view, @NonNull NativeAd nativeAd) { // Display appropriate UI ctaPresenter.bind(nativeAd); } }); }

    

Advanced Usage

Design Customization

CtaView (Button) Customization

To implement the CtaView differently from the default view, please proceed as follows.

Loading multiple native ads

Multiple native ads can be loaded by using loadAds(NativeAdLoader.OnAdsLoadedListener listener, int count) in the NativeAdLoader

Adding Feed entry point

The Feed module provides NavigateToFeedLayoutclass that opens Feed Activity when it is clicked. By adding this class, you can create an entry point from Native to Feed.

Open

NavigateToFeedLayout is a LinearLayout in horizontal orientation with default onClickListener()set. The following steps are required to integrate NavigateToFeedLayout.

1. In order to use NavigateToFeedLayout, feedConfig must be added at the time of BuzzAdBenefit.init().

2. Configure the NavigateToFeedLayout view the way you want, and add that view to the layout file to use.

3. Set navigateToFeedLayoutby calling NavigateToFeedLayout.setUnitId(YOUR_FEED_UNIT_ID)in view class (e.g. activity, fragment) using example_layout.xml. At this time, YOUR_FEED_UNIT_ID should be the same as YOUR_FEED_UNIT_ID value used when setting feedConfig in step 1.

4. (Optional)You can draw more attention from your users by displaying the potential reward points that can be received when entering the Feed. (Optional)

You can call the BaseRewardManager through BuzzAdBenefit.getBaseRewardManager(), and call the BaseRewardManager.getAvailableFeedBaseReward() function to know what points the user can get when entering the Feed.

Total 158 points now available >

Registering a listener for video events

Set a video event listener for video ads to MediaView as shown below.

Support for image-type ads

To maximize ad allocation, ads designed for Buzzscreen (hereinafter referred to as "Image-type ads") can be utilized after some processing. (See the picture below for implementation details.)

• Image-type ads do not have an icon, title, or description, unlike regular native ads. As the size of the image is not suitable for native placements, a new method in NativeAdLoader is needed for cropping the image.

Open

1. Adjusting the height of the ad view: 
   Since the height of an image-type ad is longer than that of mediaView, please apply wrap_content to all ad views and remove logic that fixes the height of the view if any.

2. Modifying the ad view layout: 
   For image-type ads, please remove the layouts for title and description. If a separate layout has been implemented for the advertiser icon, this has to be removed as well.
   
   
   

   
   
   

3. Loading ads: 
   Image-type ads can be loaded by setting the imageTypeEnabled parameter as true in NativeAdLoader as shown below.
   
   
   

    

Handling the UI based on the user’s ad engagement

All ads served via BuzzAd Benefit SDK are rewarded ads. Each ad has “reward period,” a period of time required for users to earn extra reward for participating in the same ad, of 2 hours by default. Thus, there should be a UI displaying whether user is eligible for earning reward for the particular ad engagement.

For example, if the IPU (hourly impression per user) is set to be unlimited and the reward period is set to an hour, even with multiple engagement of the same ad, a user will receive reward only for the first engagement only in an hour. Thus, after the first engagement, a UI like “Already participated” or “0P” needs to be displayed to the user.

• Parameters to distinguish user’s ad engagement:

  • reward_status: If there is a history of user receiving reward in a reward period, “received” value is passed. (Note: even if reward_status is received, reward value remains the same)

  • is_participated: This parameter is to sync the engagement status of the currently allocated ads. When ad engagement occurs, the value of is_participated changes to true for all the same ads that have been allocated and onParticipate callback is called. (Note: even if ad is allocated with reward_status of received, until the user has an engagement with an ad is_participated stays false.)
    
    

• Sample pseudo code