Mostrar anuncios nativos en Android

Este artículo describe cómo usar NativeAdRequest y NativeAdResponse mostrar anuncios nativos en tu aplicación Android.

Información general

Los anuncios nativos te permiten representar los activos de anuncios en vistas que coincidan con el diseño de tu aplicación. Para admitir este flujo de trabajo, el SDK de Android expone las siguientes clases, interfaces y métodos:

  • NativeAdRequest Carga un anuncio para un emplazamiento y NativeAdRequestListener recibe el resultado.
  • NativeAdResponse Proporciona los recursos nativos devueltos por una solicitud correcta.
  • NativeAdSDK.registerTracking() asocia el contenedor representado con la respuesta, mientras NativeAdEventListener recibe eventos de impresión y clic.

En el flujo de SDK estándar, cree y cargue una solicitud, procese los recursos de la respuesta y, a continuación, registre el contenedor para realizar un seguimiento.

  • Conserve las referencias a la solicitud, la respuesta y el contenedor mientras se muestra el anuncio.
  • Anule el registro del contenedor antes de volver a usarlo para otro AD nativo y cuando se destruya la vista.

Para personalizar los activos devueltos en una respuesta de AD nativa, consulte Solicitar activos específicos con OpenRTB Native o Solicitar activos específicos con Native Assembly.

Nota:

Para obtener información sobre el recuento de impresiones nativo, consulte Métodos de recuento de impresiones.

Solicitar un anuncio nativo

Utilice los métodos siguientes en NativeAdRequest:

Método Descripción
NativeAdRequest(Context context, String placementId) Crea una solicitud de anuncio nativo para un identificador de emplazamiento.
void setListener(NativeAdRequestListener listener) Establece el agente de escucha que recibe el resultado de la solicitud.
void loadAd() Carga un anuncio nativo.

Acceder a los datos de respuesta nativos estándar

Para utilizar el flujo nativo estándar, cargue un NativeAdRequest sin llamar a setOpenRTBAssets(). NativeAdResponse Contiene los recursos y los metadatos relacionados disponibles para el anuncio seleccionado.

Utilice los métodos siguientes en NativeAdResponse:

Recurso Método Predeterminado Descripción
Title getTitle() Cadena vacía Devuelve el título del anuncio.
Patrocinado por getSponsoredBy() Cadena vacía Devuelve el nombre del anunciante o patrocinador.
Texto de cuerpo getDescription() Cadena vacía Devuelve la descripción del anuncio principal.
Descripción adicional getAdditionalDescription() Cadena vacía Devuelve la descripción del anuncio adicional.
Llamada a la acción getCallToAction() Cadena vacía Devuelve texto para el control de llamada a la acción.
URL de la imagen principal getImageUrl() Cadena vacía Devuelve la dirección URL para cargar la imagen principal.
Tamaño de la imagen principal getImageSize() El ancho y el alto son -1 Devuelve las dimensiones de la imagen principal.
Imagen principal getImage() null Devuelve la imagen principal precargada. Consulte Configurar la carga de imágenes.
URL de la imagen del icono getIconUrl() Cadena vacía Devuelve la dirección URL para cargar la imagen del icono.
Tamaño de imagen del icono getIconSize() El ancho y el alto son -1 Devuelve las dimensiones de la imagen del icono.
Imagen del icono getIcon() null Devuelve la imagen del icono precargado. Consulte Configurar la carga de imágenes.
Clasificación getAdStarRating() null Devuelve el valor de clasificación y la escala del producto o aplicación anunciado.
URL de privacidad getPrivacyLink() Cadena vacía Devuelve la dirección URL de la información de privacidad proporcionada para el anuncio, cuando está disponible.

Registro de seguimiento

Después de procesar los recursos desde , se usa NativeAdSDK para registrar el contenedor para el seguimiento de NativeAdResponseimpresiones y clics:

Método Descripción
void registerTracking(NativeAdResponse response, View container, NativeAdEventListener listener)Ver contenedor, void registerTracking(NativeAdResponse response, View container, NativeAdEventListener listener) Registra el contenedor representado para el seguimiento de impresiones y hace que se pueda hacer clic en el contenedor.
void registerTracking(NativeAdResponse response, View container, List<View> clickableViews, NativeAdEventListener listener)List<View> clickableViews, View container, void registerTracking(NativeAdResponse response, View container, List<View> clickableViews, NativeAdEventListener listener) Registra el contenedor representado para el seguimiento de impresiones y hace que se pueda hacer clic en las vistas enumeradas.
void registerTracking(NativeAdResponse response, View container, NativeAdEventListener listener, List<View> friendlyObstructions)NativeAdEventListener listener, Ver contenedor, void registerTracking(NativeAdResponse response, View container, NativeAdEventListener listener, List<View> friendlyObstructions) Registra el seguimiento con obstrucciones descriptivas.
void registerTracking(NativeAdResponse response, View container, List<View> clickableViews, NativeAdEventListener listener, List<View> friendlyObstructions)NativeAdEventListener listener, List<View> clickableViews, View container, void registerTracking(NativeAdResponse response, View container, List<View> clickableViews, NativeAdEventListener listener, List<View> friendlyObstructions) Registra el seguimiento con vistas específicas en las que se puede hacer clic y obstrucciones descriptivas.
void unRegisterTracking(View container) Detiene el seguimiento del contenedor registrado y completa su sesión de visibilidad.

Para obtener información sobre cómo registrar obstrucciones descriptivas, consulte Medición de visibilidad en Android.

Ejemplo

class NativeAdActivity : AppCompatActivity(), NativeAdRequestListener, NativeAdEventListener {
    private lateinit var nativeAdRequest: NativeAdRequest
    private var nativeAdResponse: NativeAdResponse? = null
    private lateinit var nativeContainer: View

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_native)

        nativeContainer = findViewById(R.id.native_ad_container)
        nativeAdRequest = NativeAdRequest(this, "123456") // Create a request for the placement ID
        nativeAdRequest.listener = this // Set the request listener
        nativeAdRequest.loadAd() // Load the ad
    }

    override fun onAdLoaded(response: NativeAdResponse) {
        nativeAdResponse = response
        val mainImageUrl = response.imageUrl // Pass the main image URL to your app's image-loading implementation
        val iconImageUrl = response.iconUrl // Pass the icon image URL to your app's image-loading implementation
        findViewById<TextView>(R.id.native_ad_title).text = response.title // Render the title
        findViewById<TextView>(R.id.native_ad_sponsored_by).text = response.sponsoredBy // Render the sponsor name
        findViewById<TextView>(R.id.native_ad_body).text = response.description // Render the body text
        response.adStarRating?.let { rating ->
            findViewById<TextView>(R.id.native_ad_rating).text = "${rating.value}/${rating.scale}" // Render the rating
        }
        val privacyUrl = response.privacyLink // Get the privacy URL
        val callToActionButton = findViewById<Button>(R.id.native_ad_call_to_action)
        callToActionButton.text = response.callToAction // Render the call-to-action text

        NativeAdSDK.unRegisterTracking(nativeContainer) // Stop tracking any previous ad in the container
        NativeAdSDK.registerTracking(
            response,
            nativeContainer,
            listOf(callToActionButton),
            this
        ) // Track impressions and CTA clicks
        nativeContainer.visibility = View.VISIBLE
    }

    override fun onAdFailed(errorCode: ResultCode, adResponseInfo: ANAdResponseInfo?) {
        Log.e("NativeAdActivity", "Native ad failed to load: ${errorCode.message}")
    }

    override fun onAdImpression() = Unit
    override fun onAdWasClicked() = Unit
    override fun onAdWasClicked(clickUrl: String, fallbackURL: String) = Unit
    override fun onAdWillLeaveApplication() = Unit
    override fun onAdAboutToExpire() = Unit
    override fun onAdExpired() = Unit

    override fun onDestroy() {
        NativeAdSDK.unRegisterTracking(nativeContainer) // Stop tracking and complete the viewability session
        nativeAdResponse = null
        super.onDestroy()
    }
}

Activos de anuncios nativos extendidos

Además del flujo de anuncios nativo estándar, la aplicación puede acceder opcionalmente a recursos extendidos a través de OpenRTB Native o Native Assembly. Si establece openRTBAssets, la solicitud nativa de OpenRTB tiene prioridad sobre la configuración de ensamblado nativo asociada con la ubicación.

Para cualquiera de los dos flujos de trabajo, la aplicación puede analizar el objeto de recurso expuesto directamente en lugar de usar los descriptores de acceso de recurso normalizados en NativeAdResponse. Conserve la NativeAdResponse instancia para registrar el contenedor representado para el seguimiento y recibir eventos de anuncios nativos.

Recurso Acceso nativo de OpenRTB Acceso a ensamblado nativo Description
Vídeo VAST getVastXml() getVastXml() Devuelve el marcado de vídeo VAST.
Me gusta getOpenRTBNative() by request ID getNativeElements() con likes Devuelve el número de Me gusta.
Descargas getOpenRTBNative() by request ID getNativeElements() con downloads Devuelve el número de descargas.
Precio getOpenRTBNative() by request ID getNativeElements() con price Devuelve el precio del producto.
Precio de venta getOpenRTBNative() by request ID getNativeElements() con saleprice Devuelve el precio del producto con descuento.
Phone getOpenRTBNative() by request ID getNativeElements() con phone Devuelve el número de teléfono del anunciante.
Dirección getOpenRTBNative() by request ID getNativeElements() con address Devuelve la dirección del anunciante.
Dirección URL de presentación getOpenRTBNative() by request ID getNativeElements() con displayurl Devuelve la dirección URL visible para el anunciante.
URL del clic getOpenRTBNative() con link.url getNativeElements() con link.url Devuelve el destino del clic principal.
Haga clic en la URL de reserva getOpenRTBNative() con link.fallback getNativeElements() con link.fallback_url Devuelve el destino del clic de reserva.
Extensión personalizada getOpenRTBNative() con ext No aplicable Devuelve datos de extensión de nivel de respuesta definidos por el asociado de demanda.

Solicitar activos específicos con OpenRTB Native

Nota:

OpenRTB Native no está disponible para todos los miembros. Ponte en contacto con el representante de tu cuenta o con el soporte técnico de Microsoft Advertising para confirmar la disponibilidad. Don't include eventtrackers in openRTBAssets; el SDK de Android agrega los rastreadores de eventos compatibles.

NativeAdRequest: Úsalo openRTBAssets para describir los activos que necesita tu aplicación según OpenRTB Native 1.2. Puede especificar tamaños de imágenes, longitudes de texto, vídeos y recursos personalizados. Asigne cada recurso para id que pueda compararlo con el valor devuelto en la respuesta. También puede agregar datos personalizados mediante ext el uso de claves y valores acordados con el asociado de demanda. Para conocer los campos y valores disponibles, consulta la Especificación 1.2 de anuncios nativos de OpenRTB de IAB. Establecer openRTBAssets antes de llamar loadAd().

Use el siguiente método en NativeAdRequest:

Método Descripción
void setOpenRTBAssets(JSONObject openRTBAssets) Establece el objeto de solicitud OpenRTB Native 1.2 que define los activos y las restricciones solicitados.

NativeAdResponse: siempre que sea posible, el SDK asigna recursos estándar a los descriptores de acceso correspondientes. La respuesta completa de OpenRTB Native también está disponible a través de getOpenRTBNative(), donde puede encontrar los activos devueltos por los ID utilizados en la solicitud.

Use el siguiente método en NativeAdResponse:

Método Descripción
JSONObject getOpenRTBNative() Devuelve la respuesta nativa de OpenRTB completa, o una respuesta vacía JSONObject cuando no está disponible.
private fun loadOpenRTBNativeAd() {
    nativeAdRequest = NativeAdRequest(this, "123456") // Create a request for the placement ID
    nativeAdRequest.listener = this // Set the request listener
    val openRTBAssets = JSONObject().apply {
        put("ver", "1.2") // Set the OpenRTB Native version
        put("privacy", 1) // Request privacy information
        put("ext", JSONObject().put("foo", "bar")) // Add a custom request extension
        put("assets", JSONArray().apply {
            put(JSONObject("""{"id":1,"required":1,"title":{"len":300}}""")) // Request title
            put(JSONObject("""{"id":2,"required":1,"data":{"type":2}}""")) // Request body text
            put(JSONObject("""{"id":3,"required":0,"data":{"type":1}}""")) // Request sponsor name
            put(JSONObject("""{"id":4,"required":0,"img":{"type":3}}""")) // Request main image
            put(JSONObject("""{"id":5,"required":0,"data":{"type":12}}""")) // Request CTA text
            put(JSONObject("""{"id":6,"required":0,"img":{"type":1,"hmin":50,"wmin":50}}""")) // Request icon
            put(JSONObject("""{"id":7,"required":0,"data":{"type":4}}""")) // Request likes
            put(JSONObject("""{"id":8,"required":0,"data":{"type":6}}""")) // Request price
            put(JSONObject("""{"id":9,"required":0,"data":{"type":11}}""")) // Request display URL
        })
    }
    nativeAdRequest.openRTBAssets = openRTBAssets // Set requested OpenRTB Native assets
    nativeAdRequest.loadAd() // Load the ad
}

override fun onAdLoaded(response: NativeAdResponse) {
    val openRTBNative = response.openRTBNative
    val responseAssets = openRTBNative.optJSONArray("assets")
    val assetsById = mutableMapOf<Int, JSONObject>()
    for (index in 0 until (responseAssets?.length() ?: 0)) {
        val asset = responseAssets?.optJSONObject(index)
        if (asset != null) {
            assetsById[asset.optInt("id")] = asset
        }
    }
    val title = response.title // Or: assetsById[1]?.optJSONObject("title")?.optString("text")
    val body = response.description // Or: assetsById[2]?.optJSONObject("data")?.optString("value")
    val mainImageUrl = response.imageUrl // Or: assetsById[4]?.optJSONObject("img")?.optString("url")
    val callToAction = response.callToAction // Or: assetsById[5]?.optJSONObject("data")?.optString("value")
    val iconImageUrl = response.iconUrl // Or: assetsById[6]?.optJSONObject("img")?.optString("url")
    val likes = assetsById[7]?.optJSONObject("data")?.optString("value") // Match request ID 7
    val price = assetsById[8]?.optJSONObject("data")?.optString("value") // Match request ID 8
    val displayUrl = assetsById[9]?.optJSONObject("data")?.optString("value") // Match request ID 9
    val customExtension = openRTBNative.optJSONObject("ext")
    val customValue = customExtension?.optString("foo") // Read a custom response extension
    val link = openRTBNative.optJSONObject("link")
    val clickUrl = link?.optString("url")
    val clickFallbackUrl = link?.optString("fallback")
}

Solicitar activos específicos con Native Assembly

NativeAdRequest: no se requiere ninguna configuración de solicitud específica de ensamblado nativo en la aplicación. Native Assembly está configurado para la colocación en Microsoft Monetize y se usa cuando openRTBAssets no se establece. Para este flujo de trabajo, el SDK usa solo las especificaciones de activos creativos del ensamblado nativo asociadas con la ubicación. El HTML, CSS y JavaScript de la pestaña Representador no se usan; La aplicación representa los recursos devueltos. El código del renderizador se aplica solo al flujo de trabajo de renderizado nativo de Banner. Para obtener más información, vea Representador de ensamblados nativos para Android. Recomendamos usar OpenRTB nativo cuando esté disponible. Para obtener instrucciones de configuración, vea Configurar un ensamblado nativo.

NativeAdResponse: obtenga el valor NativeAdResponse.NATIVE_ELEMENT_OBJECT de from , getNativeElements()compártalo en un y, a continuación, lea cada recurso por su nombre de JSONObjectcampo. Comprueba que existe un campo antes de usarlo, ya que la creatividad podría omitirlo.

Use el siguiente método en NativeAdResponse:

Método Descripción
HashMap<String, Object> getNativeElements() Devuelve todos los elementos de la respuesta de anuncio nativo.
val nativeElements = response.nativeElements[NativeAdResponse.NATIVE_ELEMENT_OBJECT] as? JSONObject
val title = response.title // Or: nativeElements?.optString("title")
val body = response.description // Or: nativeElements?.optString("desc")
val mainImageUrl = response.imageUrl // Or: nativeElements?.optJSONObject("main_img")?.optString("url")
val iconImageUrl = response.iconUrl // Or: nativeElements?.optJSONObject("icon")?.optString("url")
val callToAction = response.callToAction // Or: nativeElements?.optString("ctatext")
val likes = nativeElements?.optString("likes")
val price = nativeElements?.optString("price")
val link = nativeElements?.optJSONObject("link")
val clickUrl = link?.optString("url")
val clickFallbackUrl = link?.optString("fallback_url")

Configurar la carga de imágenes

Las respuestas de los anuncios nativos pueden incluir direcciones URL de una imagen principal y un icono. Use estas direcciones URL con la implementación de carga de imágenes de la aplicación o habilite la precarga del SDK antes de llamar loadAd() para recibir objetos descargados Bitmap . La carga previa está deshabilitada de manera predeterminada.

Utilice los métodos siguientes en NativeAdRequest:

Método Descripción
void shouldLoadImage(boolean shouldLoadImage) Establece si el SDK precarga la imagen principal.
void shouldLoadIcon(boolean shouldLoadIcon) Establece si el SDK carga previamente la imagen del icono.
nativeAdRequest.shouldLoadImage(true) // Preload the main image
nativeAdRequest.shouldLoadIcon(true) // Preload the icon image
nativeAdRequest.loadAd() // Load the ad

val mainImage = response.image // Get the preloaded main image
val iconImage = response.icon // Get the preloaded icon image