Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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:
-
NativeAdRequestCarga un anuncio para un emplazamiento yNativeAdRequestListenerrecibe el resultado. -
NativeAdResponseProporciona los recursos nativos devueltos por una solicitud correcta. -
NativeAdSDK.registerTracking()asocia el contenedor representado con la respuesta, mientrasNativeAdEventListenerrecibe 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( |
Registra el contenedor representado para el seguimiento de impresiones y hace que se pueda hacer clic en el contenedor. |
void registerTracking( |
Registra el contenedor representado para el seguimiento de impresiones y hace que se pueda hacer clic en las vistas enumeradas. |
void registerTracking( |
Registra el seguimiento con obstrucciones descriptivas. |
void registerTracking( |
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