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();

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
}