Native Ad Options

Native ads offer various advanced features that allow for additional customization and provide the best advertising experience. This guide explains how to use the advanced features of native ads.

Configure GfpTheme

Some ads provided through the NDA module are rendered in either a light or dark theme based on the configured GfpTheme value.

You can configure a global GfpTheme using NdaProviderOptions.Builder().setTheme(GfpTheme). However, if you want to apply a GfpTheme to a single ad only, call GfpNativeAdOptions.Builder().setTheme().

• If not set, rendering will follow the DayNight value configured on the device.
• If this option is set, rendering will follow the specified GfpTheme value.

The following example demonstrates how to configure the dark theme.

Kotlin

val nativeAdOptions = GfpNativeAdOptions.Builder()
    .setTheme(ResolvedTheme.DARK)
    .build()
val adLoader = GfpAdLoader.Builder(this, adParam)
    ...
    .withNativeAd(nativeAdOptions) { nativeAd ->
        ...
    }
    .build()

Java

GfpNativeAdOptions nativeAdOptions = new GfpNativeAdOptions.Builder()
    .setTheme(ResolvedTheme.DARK)
    .build();
GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
    ...
    .withNativeAd(nativeAdOptions, nativeAd -> {
        ...
    })
    .build();

AdChoices Placement for DFP Ads

Native ads provided through the DFP module are automatically rendered by the DFP SDK, rather than being rendered within the GfpAdChoicesView added during the layout configuration of GfpNativeAdView.

If you want to change the placement of the AdChoices icon for DFP native ads, you can select the corner where the AdChoices icon will be rendered using GfpNativeAdOptions.Builder.setAdChoicesPlacement().

• If not set, the AdChoices icon will be placed in the top-right corner by default.
• When this option is set, the AdChoices icon will be placed in the specified custom location. The possible values are as follows:
  • GfpNativeAdOptions.ADCHOICES_TOP_LEFT
  • GfpNativeAdOptions.ADCHOICES_TOP_RIGHT (default if not set)
  • GfpNativeAdOptions.ADCHOICES_BOTTOM_LEFT
  • GfpNativeAdOptions.ADCHOICES_BOTTOM_RIGHT

The following example demonstrates how to set the AdChoices icon placement to the bottom-right corner for DFP native ads.

Kotlin

val nativeAdOptions = GfpNativeAdOptions.Builder()
    .setAdChoicesPlacement(GfpNativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
    .build()
val adLoader = GfpAdLoader.Builder(this, adParam)
    ...
    .withNativeAd(nativeAdOptions) { nativeAd ->
        ...
    }
    .build()

Java

GfpNativeAdOptions nativeAdOptions = new GfpNativeAdOptions.Builder()
    .setAdChoicesPlacement(GfpNativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
    .build();
GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
    ...
    .withNativeAd(nativeAdOptions, nativeAd -> {
        ...
    })
    .build();

Configure the Use of GfpMediaView

When configuring a native ad layout without using GfpMediaView, you can set whether to use GfpMediaView through GfpNativeAdOptions.Builder.setHasMediaView().

• If not set or set to true, you must include GfpMediaView in the native ad layout and register it with GfpNativeAdView.
• If set to false, it is possible to configure a layout without GfpMediaView, and there is no need to register GfpMediaView with GfpNativeAdView.

caution

If GfpMediaView is included in the native ad layout and registered with GfpNativeAdView, but GfpNativeAdOptions.Builder.setHasMediaView() is set to false, an exception will occur.

The following example demonstrates how to configure a layout without GfpMediaView and set it to not use GfpMediaView.

Kotlin

val nativeAdOptions = GfpNativeAdOptions.Builder()
    .setHasMediaView(false)
    .build()
val adLoader = GfpAdLoader.Builder(this, adParam)
    ...
    .withNativeAd(nativeAdOptions) { nativeAd ->
        ...
    }
    .build()

Java

GfpNativeAdOptions nativeAdOptions = new GfpNativeAdOptions.Builder()
    .setHasMediaView(false)
    .build();
GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
    ...
    .withNativeAd(nativeAdOptions, nativeAd -> {
        ...
    })
    .build();

Configure GfpMediaView Background Blur

When there is empty space in GfpMediaView, you can add a blurred background to fill the empty space and create a natural background effect.

You can enable this feature by setting GfpNativeAdOptions.Builder.setEnableMediaBackgroundBlur() to true. When enabled, the empty space in GfpMediaView will be filled with a blurred background for media views with GfpMediaType of IMAGE or VIDEO.

• For IMAGE type media, the image itself is blurred and used as the background.
• For VIDEO type media, if a separate thumbnail image exists, the thumbnail image is blurred and used as the background. If no thumbnail image is available, the blur effect will not be applied.

The following example demonstrates how to enable media background blur.

Kotlin

val nativeAdOptions = GfpNativeAdOptions.Builder()
    .setEnableMediaBackgroundBlur(true)
    .build()
val adLoader = GfpAdLoader.Builder(this, adParam)
    ...
    .withNativeAd(nativeAdOptions) { nativeAd ->
        ...
    }
    .build()

Java

GfpNativeAdOptions nativeAdOptions = new GfpNativeAdOptions.Builder()
    .setEnableMediaBackgroundBlur(true)
    .build();
GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
    ...
    .withNativeAd(nativeAdOptions, nativeAd -> {
        ...
    })
    .build();

Configure GfpMediaView Lazy Loading

Starting from NAM SDK 8.17.1, you can defer loading GfpMediaView resources for Native Normal ads until render time. When GfpNativeAdOptions.Builder.setMediaViewLazyLoading() is configured, the ad load callback can be invoked first, and image download or out-stream video VAST parsing is performed when GfpMediaView is rendered.

This option applies to media views in Native Normal ads.

• GfpMediaType.IMAGE: downloads the main image at render time.
• GfpMediaType.VIDEO: performs out-stream video VAST parsing and thumbnail image loading at render time.
• For other ad formats such as Native Simple ads and banner ads, this option is ignored.

The following example demonstrates how to apply lazy loading to a regular GfpMediaView.

Kotlin

val lazyLoadingOptions = MediaViewLazyLoadingOptions(
    loading = Placeholder(
        image = null,
        background = Placeholder.Background(
            default = Color.parseColor("#F5F8FB"),
            dark = Color.parseColor("#48484B")
        )
    ),
    failure = Placeholder(
        image = Placeholder.Image(
            default = android.R.drawable.ic_menu_report_image,
            dark = null,
            size = Placeholder.Image.Size.Flexible
        ),
        background = Placeholder.Background(
            default = Color.parseColor("#FFE0B2"),
            dark = null
        )
    )
)

val lazyLoadingListener = object : MediaViewLazyLoadingListener {
    override fun onStart() {
        // Lazy loading started.
    }

    override fun onSuccess() {
        // Lazy loading succeeded.
    }

    override fun onFailure(errorMessage: String) {
        // Lazy loading failed.
    }
}

val nativeAdOptions = GfpNativeAdOptions.Builder()
    .setHasMediaView(true)
    .setMediaViewLazyLoading(lazyLoadingOptions, lazyLoadingListener)
    .build()

val adLoader = GfpAdLoader.Builder(this, adParam)
    ...
    .withNativeAd(nativeAdOptions) { nativeAd ->
        // The ad load callback can be invoked before MediaView resources finish loading.
    }
    .build()

Java

Placeholder loadingPlaceholder = new Placeholder(
        null,
        new Placeholder.Background(
                Color.parseColor("#F5F8FB"),
                Color.parseColor("#48484B")
        )
);

Placeholder failurePlaceholder = new Placeholder(
        new Placeholder.Image(
                android.R.drawable.ic_menu_report_image,
                null,
                Placeholder.Image.Size.Flexible.INSTANCE
        ),
        new Placeholder.Background(
                Color.parseColor("#FFE0B2"),
                null
        )
);

MediaViewLazyLoadingOptions lazyLoadingOptions =
        new MediaViewLazyLoadingOptions(loadingPlaceholder, failurePlaceholder);

MediaViewLazyLoadingListener lazyLoadingListener = new MediaViewLazyLoadingListener() {
    @Override
    public void onStart() {
        // Lazy loading started.
    }

    @Override
    public void onSuccess() {
        // Lazy loading succeeded.
    }

    @Override
    public void onFailure(String errorMessage) {
        // Lazy loading failed.
    }
};

GfpNativeAdOptions nativeAdOptions = new GfpNativeAdOptions.Builder()
        .setHasMediaView(true)
        .setMediaViewLazyLoading(lazyLoadingOptions, lazyLoadingListener)
        .build();

GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
        ...
        .withNativeAd(nativeAdOptions, nativeAd -> {
            // The ad load callback can be invoked before MediaView resources finish loading.
        })
        .build();

If you need to customize placeholders for media views rendered as a carousel or slot, configure GfpNativeAdOptions.Builder.setSlotMediaViewLazyLoading() as well. Media views inside slots do not provide a separate listener, and only placeholder options are applied.

Kotlin

val nativeAdOptions = GfpNativeAdOptions.Builder()
    .setHasMediaView(true)
    .setMediaViewLazyLoading(lazyLoadingOptions, lazyLoadingListener)
    .setSlotMediaViewLazyLoading(slotLazyLoadingOptions)
    .build()

Java

GfpNativeAdOptions nativeAdOptions = new GfpNativeAdOptions.Builder()
        .setHasMediaView(true)
        .setMediaViewLazyLoading(lazyLoadingOptions, lazyLoadingListener)
        .setSlotMediaViewLazyLoading(slotLazyLoadingOptions)
        .build();

Option	Description
MediaViewLazyLoadingOptions.loading	Placeholder displayed while lazy loading is in progress. If omitted, the default placeholder is used.
MediaViewLazyLoadingOptions.failure	Placeholder displayed when lazy loading fails. If null, the loading placeholder remains displayed.
Placeholder.Image.Size.Flexible	Displays the image as 100x100dp when the media view width is 220dp or wider, and 84x84dp when it is narrower than 220dp.
Placeholder.Image.Size.Fixed	Displays the image with the specified dp size.

caution

MediaViewLazyLoadingListener is called for a regular GfpMediaView. Success and failure events from media views inside slots are not delivered to the listener passed by the app.

For out-stream video, listener callbacks are based on VAST parsing success or failure. Thumbnail image download failures are not delivered through onFailure().

When disk cache loading is enabled with withDiskCache(true), the regular media view lazy loading path is not applied.

Timeout Configuration

The request timeout value for native ads can be globally configured using SdkPropertiesBuilder.unifiedAdRequestTimeout. However, if you want to set a timeout for a single ad request, you can configure it during the process of building a GfpAdLoader by using the withTimeoutMillis method, as shown in the example below.

The following example demonstrates how to set a timeout value of 10 seconds for a single ad request loaded with a specific GfpAdLoader. When the timeout value for a single ad request is set as shown below, the globally configured timeout value will be ignored.

info

If no timeout value is set in SdkProperties or GfpAdLoader, the default timeout value of 60 seconds will be applied.

Kotlin

val adLoader = GfpAdLoader.Builder(this, adParam)
    .withTimeoutMillis(10_000L)
    .withNativeAd { nativeAd ->
        // Show the native ad.
    }
    .build()

Java

GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
    .withTimeoutMillis(10_000L)
    .withNativeAd(new GfpNativeAd.OnNativeAdLoadedListener() {
        @Override
        public void onNativeAdLoaded(GfpNativeAd nativeAd) {
            // Show the native ad.
        }
    })
    .build();

Configure Icon Asset Preload

Icon assets delivered when a native ad is loaded are preloaded by default and can be used directly as Drawable. If you want to load and apply images directly without preloading icon assets, you can configure whether to enable preload using the GfpNativeAdOptions.Builder.setEnableImageAssetsPreload() method.

The following example demonstrates how to disable icon asset preload.

caution

If icon asset preload is disabled, when rendering the icon asset of a native ad, you must not use GfpNativeAd.getIcon().getDrawable() of the icon asset delivered through GfpNativeAd.getIcon(). Instead, you must load the image directly through the Uri provided by GfpNativeAd.getIcon().getUri().

Kotlin

val nativeAdOptions = GfpNativeAdOptions.Builder()
    .setEnableImageAssetsPreload(false)
    .build()
val adLoader = GfpAdLoader.Builder(this, adParam)
    ...
    .withNativeAd(nativeAdOptions) { nativeAd ->
        ...
    }
    .build()

Java

GfpNativeAdOptions nativeAdOptions = new GfpNativeAdOptions.Builder()
    .setEnableImageAssetsPreload(false)
    .build();
GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
    ...
    .withNativeAd(nativeAdOptions, nativeAd -> {
        ...
    })
    .build();

Retrieve Media Asset Information

GfpMediaView is a View designed to render images, videos, and richer Views. Starting from GFP SDK version 6.2.0, information about media to be rendered in GfpMediaView is provided through the GfpMediaData object via the GfpNativeAd.getMediaData() method.

The information provided by GfpMediaData is as follows:

Field	Description
mediaType	Returns one of the following values: IMAGE, VIDEO, RICH_MEDIA, UNKNOWN.
aspectRatio	When mediaType is IMAGE or VIDEO, returns the aspect ratio of the media. For RICH_MEDIA, the aspect ratio may vary depending on the view width. For UNKNOWN, this value is used when a specific C2S mediation network SDK does not provide type information or aspect ratio information, so the exact value cannot be determined for this type either. Therefore, -1 is returned for these two media types.

The following example demonstrates how to retrieve media type and aspect ratio through the GfpMediaData object.

Kotlin

val nativeAd: GfpNativeAd = ...
val mediaData = nativeAd.mediaData

// Check media type
when (mediaData.mediaType) {
    GfpMediaType.IMAGE -> {
        // Handle image type
        val aspectRatio = mediaData.aspectRatio
    }
    GfpMediaType.VIDEO -> {
        // Handle video type
        val aspectRatio = mediaData.aspectRatio
    }
    GfpMediaType.RICH_MEDIA -> {
        // Handle rich media type
        // Carousel ads are defined as rich media type.
    }
    GfpMediaType.UNKNOWN -> {
        // Handle unknown type
    }
}

Java

GfpNativeAd nativeAd = ...;
GfpMediaData mediaData = nativeAd.getMediaData();

// Check media type
GfpMediaType mediaType = mediaData.getMediaType();
float aspectRatio = mediaData.getAspectRatio();
if (mediaType == GfpMediaType.IMAGE) {
    // Handle image type
} else if (mediaType == GfpMediaType.VIDEO) {
    // Handle video type
} else if (mediaType == GfpMediaType.RICH_MEDIA) {
    // Handle rich media type
} else if (mediaType == GfpMediaType.UNKNOWN) {
    // Handle unknown type
}