Google está compilando una plataforma integrada en el dispositivo que organiza las apps de los usuarios por verticales y que permite ofrecer una nueva experiencia envolvente para el descubrimiento y el consumo de contenido personalizado en las apps. Esta experiencia de pantalla completa brinda a los socios desarrolladores la oportunidad de mostrar su mejor contenido enriquecido en un canal dedicado fuera de su app.
En esta guía, se ofrecen instrucciones para que los socios desarrolladores integren su contenido de comida con el SDK de Engage para completar esta nueva área de la plataforma y las plataformas de Google existentes.
Información detallada sobre la integración
Terminología
Esta integración incluye los siguientes cinco tipos de clústeres: Recommendation, Featured, Food Shopping Cart, Food Shopping List y Reorder.
Los clústeres de Recommendation muestran sugerencias personalizadas relacionadas con comida de un socio desarrollador individual. Estas recomendaciones se pueden personalizar para el usuario o generalizar (por ejemplo, si incluye artículos nuevos a la venta). Úsalos para mostrar recetas, tiendas, platos, comestibles y mucho más cuando lo creas conveniente.
- Un clúster de Recommendation puede estar formado por fichas de
ProductEntity
,StoreEntity
oRecipeEntity
, pero no por una combinación de distintos tipos de entidades.
- Un clúster de Recommendation puede estar formado por fichas de
El clúster de Featured muestra una selección de entidades de varios socios desarrolladores en una agrupación de IU. Habrá un solo clúster de Featured, que aparecerá cerca de la parte superior de la IU, con una ubicación de prioridad por sobre todos los clústeres de Recommendation. Cada socio desarrollador podrá transmitir hasta 10 entidades en el clúster de Featured.
El clúster de Food Shopping Cart muestra un adelanto de carritos de compras de comestibles de muchos socios desarrolladores en una agrupación de IU, lo que les indica a los usuarios que completen sus carritos pendientes. Hay un solo clúster de Food Shopping Cart.
El clúster de Food Shopping Cart debe mostrar la cantidad total de artículos del carrito y también puede incluir imágenes de determinados artículos en el carrito del usuario.
El clúster de Food Shopping List muestra un adelanto de las listas de compras de comestibles de muchos socios desarrolladores en una agrupación de IU, lo que les indica a los usuarios que vuelvan a la app correspondiente para actualizar y completar sus listas. Hay un solo clúster de Food Shopping List.
El clúster de Reorder muestra un adelanto de los pedidos anteriores de muchos socios desarrolladores en una agrupación de IU, lo que les indica a los usuarios que vuelvan a hacer un pedido. Hay un solo clúster de Reorder.
El clúster de Reorder debe mostrar la cantidad total de artículos del pedido anterior del usuario y también debe incluir una de las siguientes opciones:
- Imágenes de determinados artículos del pedido anterior del usuario
- Etiquetas de determinados artículos del pedido anterior del usuario
Trabajo previo
Nivel de API mínimo: 19
Agrega la biblioteca com.google.android.engage:engage-core
a tu app:
dependencies {
// Make sure you also include that repository in your project's build.gradle file.
implementation 'com.google.android.engage:engage-core:1.5.2'
}
Resumen
El diseño se basa en una implementación de un servicio vinculado.
Los datos que un cliente puede publicar están sujetos a los siguientes límites para diferentes tipos de clústeres:
Tipo de clúster | Límites del clúster | Límites máximos de entidades en un clúster |
---|---|---|
Clústeres de Recommendation | 5 como máximo | 25 como máximo (ProductEntity , RecipeEntity o StoreEntity ) |
Clúster de Featured | 1 como máximo | 10 como máximo (ProductEntity , RecipeEntity o StoreEntity ) |
Clúster de Food Shopping Cart | 1 como máximo | 1 entidad ShoppingCartEntity como máximo |
Clúster de Food Shopping List | 1 como máximo | 1 entidad ShoppingListEntity como máximo |
Clúster de Food Reorder | 1 como máximo | 1 entidad ReorderEntity como máximo |
Paso 1: Proporciona los datos de la entidad
El SDK definió distintas entidades para representar cada tipo de elemento. Admitimos las siguientes entidades para la categoría Comida:
ProductEntity
StoreEntity
RecipeEntity
FoodShoppingCart
FoodShoppingList
FoodReorderCluster
En los gráficos siguientes, se describen los atributos y requisitos disponibles para cada tipo.
ProductEntity
El objeto ProductEntity
representa un elemento individual (como un artículo de supermercado, un plato de un restaurante o una promoción) que los socios desarrolladores quieren publicar.
Atributo | Requisito | Descripción | Formato |
---|---|---|---|
Imágenes de pósteres | Obligatorio | Se debe proporcionar al menos una imagen. | Consulta la sección Especificaciones de imagen para obtener más información. |
URI de acción | Obligatorio |
Es el vínculo directo a la página en la app, que muestra detalles del producto. Nota: Puedes usar vínculos directos para la atribución. Consulta estas Preguntas frecuentes. |
URI |
Título | Opcional | Es el nombre del producto. | Texto libre Tamaño de texto recomendado: Menos de 90 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Precio (actual) | Condicionalmente obligatorio | Es el precio actual del producto. Se debe brindar si se proporciona el precio tachado. |
Texto libre |
Precio (tachado) | Opcional | Es el precio original de la entidad, que aparece tachado en la IU. | Texto libre |
Texto destacado | Opcional | Es el texto destacado para mostrar una promoción, un evento o una actualización del producto, si está disponible. | Texto libre Tamaño de texto recomendado: Menos de 45 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Condiciones del texto destacado | Opcional | Son las condiciones para el texto destacado. | Texto libre Tamaño de texto recomendado: Menos de 45 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Calificación (opcional): Nota: Todas las calificaciones se muestran con nuestro sistema de calificación por estrellas estándar. | |||
Calificación: Valor máximo | Opcional | Es el valor máximo de la escala de calificación. Se debe brindar si también se proporciona el valor actual de la calificación. |
Número >= 0.0 |
Calificación: Valor actual | Opcional | Es el valor actual de la escala de calificación. Se debe proporcionar si también se proporciona el valor máximo de la calificación. |
Número >= 0.0 |
Calificación: Cantidad | Opcional | Es el recuento de las calificaciones del producto. Nota: Proporciona este campo si tu app controla cómo se muestra el recuento a los usuarios. Usa una cadena concisa. Por ejemplo, si el recuento es 1,000,000, considera usar una abreviatura como 1 M para que el recuento no se trunque en pantallas de tamaños más pequeños. |
String |
Calificación: Valor de recuento | Opcional | Es el recuento de las calificaciones del producto. Nota: Proporciona este campo si no controlas la lógica de la abreviatura de visualización por tu cuenta. Si tanto Count como Count Value están presentes, se muestra Count a los usuarios. |
Largo |
DisplayTimeWindow (opcional): Establece un período para que un contenido se muestre en la superficie | |||
Fecha y hora de inicio | Opcional |
Es la marca de tiempo de época a partir de la cual se debe mostrar el contenido en la superficie. Si no la estableces, el contenido será apto para mostrarse en la superficie. |
Marca de tiempo de época en milisegundos |
Fecha y hora de finalización | Opcional |
Es la marca de tiempo de época a partir de la cual el contenido ya no se mostrará en la superficie. Si no la estableces, el contenido será apto para mostrarse en la superficie. |
Marca de tiempo de época en milisegundos |
StoreEntity
El objeto StoreEntity
representa una tienda individual que los socios desarrolladores quieren publicar, como un restaurante o una tienda de comestibles.
Atributo | Requisito | Descripción | Formato |
---|---|---|---|
Imágenes de pósteres | Obligatorio | Se debe proporcionar al menos una imagen. | Consulta la sección Especificaciones de imagen para obtener más información. |
URI de acción | Obligatorio | Es el vínculo directo a la página en la app, que muestra detalles de la tienda. Nota: Puedes usar vínculos directos para la atribución. Consulta estas Preguntas frecuentes |
URI |
Título | Opcional | Es el nombre de la tienda. | Texto libre Tamaño de texto recomendado: Menos de 45 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Ubicación | Opcional | Es la ubicación de la tienda. | Texto libre Tamaño de texto recomendado: Menos de 45 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Texto destacado | Opcional | Es el texto destacado para mostrar una promoción, un evento o una actualización de la tienda, si está disponible. | Texto libre Tamaño de texto recomendado: Menos de 45 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Condiciones del texto destacado | Opcional | Son las condiciones para el texto destacado. | Texto libre Tamaño de texto recomendado: Menos de 45 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Descripción | Opcional | Es una descripción de la tienda. | Texto libre Tamaño de texto recomendado: Menos de 90 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Nota: Todas las calificaciones se muestran con nuestro sistema estándar de calificación por estrellas. | |||
Calificación: Valor máximo | Opcional | Es el valor máximo de la escala de calificación. Se debe brindar si también se proporciona el valor actual de la calificación. |
Número >= 0.0 |
Calificación: Valor actual | Opcional | Es el valor actual de la escala de calificación. Se debe proporcionar si también se proporciona el valor máximo de la calificación. |
Número >= 0.0 |
Calificación: Cantidad | Opcional | Es la cantidad de calificaciones de la tienda. Nota: Proporciona este campo si tu app desea controlar cómo se muestra a los usuarios. Proporciona la cadena concisa que se puede mostrar al usuario. Por ejemplo, si el recuento es de 1,000,000, considera usar abreviaturas como 1M para que no se corte en tamaños de visualización más pequeños. |
String |
Calificación: Valor de recuento | Opcional | Es el recuento de las calificaciones de la tienda. Nota: Proporciona este campo si no quieres controlar la lógica de abreviatura de pantalla por tu cuenta. Si tanto Count como Count Value están presentes, usaremos Count para mostrarlo a los usuarios. |
Largo |
RecipeEntity
El objeto RecipeEntity
representa un elemento de receta que los socios desarrolladores quieren publicar.
Atributo | Requisito | Descripción | Formato |
---|---|---|---|
Imágenes de pósteres | Obligatorio | Se debe proporcionar al menos una imagen. | Consulta la sección Especificaciones de imagen para obtener más información. |
URI de acción | Obligatorio | Es el vínculo directo a la página en la app, que muestra detalles de la receta. Nota: Puedes usar vínculos directos para la atribución. Consulta estas Preguntas frecuentes. |
URI |
Título | Opcional | Es el nombre de la receta. | Texto libre Tamaño de texto recomendado: Menos de 45 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Autor | Opcional | Es el autor de la receta. | Texto libre Tamaño de texto recomendado: Menos de 45 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Tiempo de cocción o preparación | Opcional | Es el tiempo de cocción de la receta. | Texto libre Tamaño de texto recomendado: Menos de 45 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Texto destacado | Opcional | Es el texto destacado para mostrar una promoción, un evento o una actualización de la receta, si está disponible. | Texto libre Tamaño de texto recomendado: Menos de 45 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Categoría | Opcional | Es la categoría de la receta. | Texto libre Tamaño de texto recomendado: Menos de 45 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Descripción | Opcional | Es una descripción de la receta. | Texto libre Tamaño de texto recomendado: Menos de 90 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Nota: Todas las calificaciones se muestran con nuestro sistema estándar de calificación por estrellas. | |||
Calificación: Valor máximo | Opcional | Es el valor máximo de la escala de calificación. Se debe brindar si también se proporciona el valor actual de la calificación. |
Número >= 0.0 |
Calificación: Valor actual | Opcional | Es el valor actual de la escala de calificación. Se debe proporcionar si también se proporciona el valor máximo de la calificación. |
Número >= 0.0 |
Calificación: Cantidad | Opcional | Es el recuento de las calificaciones de la receta. Nota: Proporciona este campo si tu app desea controlar cómo se muestra a los usuarios. Proporciona la cadena concisa que se puede mostrar al usuario. Por ejemplo, si el recuento es de 1,000,000, considera usar abreviaturas como 1M para que no se corte en tamaños de visualización más pequeños. |
String |
Calificación: Valor de recuento | Opcional | La cantidad de calificaciones de la receta. Nota: Proporciona este campo si no quieres controlar la lógica de la abreviatura de visualización por tu cuenta. Si están presentes Count y Count Value, usaremos Count para mostrarlos a los usuarios |
Largo |
FoodShoppingCart
Atributo | Requisito | Descripción | Formato |
---|---|---|---|
URI de acción | Obligatorio |
Es el vínculo directo al carrito de compras en la app del socio. Nota: Puedes usar vínculos directos para la atribución. Consulta estas Preguntas frecuentes |
URI |
Cantidad de artículos | Obligatorio | Es la cantidad de artículos (no solo la cantidad de productos) en el carrito de compras. Por ejemplo, si hay 3 naranjas y 1 manzana en el carrito, la cantidad debe ser 4. |
Número entero >= 1 |
Título | Opcional | Es el título del carrito (por ejemplo, Tu carrito). Si el desarrollador no brinda ningún título, el valor predeterminado es Tu carrito. |
Texto libre Tamaño de texto recomendado: Menos de 25 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Texto de acción | Opcional |
Es el texto del llamado a la acción del botón del carrito de compras (por ejemplo, Tu bolsa de compras). Si el desarrollador no proporciona texto de acción, el valor predeterminado es View Cart. Este atributo es compatible con la versión 1.1.0 y posteriores. |
Cadena |
Imágenes del carrito | Opcional | Son las imágenes de cada producto en el carrito. Se pueden brindar hasta 10 imágenes en orden de prioridad. La cantidad real de imágenes que se muestran depende del factor de forma del dispositivo. |
Consulta la sección Especificaciones de imagen para obtener más información. |
Etiquetas de artículos | Opcional | Es la lista de etiquetas de los artículos en la lista de compras. La cantidad real de etiquetas que se muestran depende del factor de forma del dispositivo. |
Lista de etiquetas de texto libre Tamaño de texto recomendado: Menos de 20 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
DisplayTimeWindow (opcional): Establece un período para que un contenido se muestre en la superficie | |||
Fecha y hora de inicio | Opcional |
Es la marca de tiempo de época a partir de la cual se debe mostrar el contenido en la superficie. Si no la estableces, el contenido será apto para mostrarse en la superficie. |
Marca de tiempo de época en milisegundos |
Fecha y hora de finalización | Opcional |
Es la marca de tiempo de época a partir de la cual el contenido ya no se mostrará en la superficie. Si no la estableces, el contenido será apto para mostrarse en la superficie. |
Marca de tiempo de época en milisegundos |
FoodShoppingList
Atributo | Requisito | Descripción | Formato |
---|---|---|---|
URI de acción | Obligatorio |
Es el vínculo directo a la lista de compras en la app del socio. Nota: Puedes usar vínculos directos para la atribución. Consulta estas Preguntas frecuentes. |
URI |
Cantidad de artículos | Obligatorio | Es la cantidad de artículos en la lista de compras. | Número entero >= 1 |
Título | Opcional |
Es el título de la lista (por ejemplo, Tu lista de compras). Si el desarrollador no brinda ningún título, el valor predeterminado es Lista de compras. |
Texto libre Tamaño de texto recomendado: Menos de 25 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Etiquetas de artículos | Obligatorio | Es la lista de etiquetas de los artículos en la lista de compras. Se debe proporcionar al menos 1 etiqueta y hasta 10 en orden de prioridad. La cantidad real de etiquetas que se muestran depende del factor de forma del dispositivo. |
Lista de etiquetas de texto libre Tamaño de texto recomendado: Menos de 20 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
FoodReorderCluster
Atributo | Requisito | Descripción | Formato |
---|---|---|---|
URI de acción | Obligatorio |
Es el vínculo directo para volver a hacer un pedido en la app del socio. Nota: Puedes usar vínculos directos para la atribución. Consulta estas Preguntas frecuentes. |
URI |
Texto de acción | Opcional |
Es el texto del llamado a la acción del botón que aparece en Reorder (por ejemplo, Order again). Si el desarrollador no proporciona texto de acción, el valor predeterminado es Reorder. Este atributo es compatible con la versión 1.1.0 y posteriores. |
Cadena |
Cantidad de artículos | Obligatorio |
Es la cantidad de artículos (no solo la cantidad de productos) del pedido anterior. Por ejemplo, si hay 3 cafés pequeños y 1 medialuna en el pedido anterior, la cantidad debe ser 4. |
Número entero >= 1 |
Título | Obligatorio | Es el título del artículo que se volvió a pedir. | Texto libre Tamaño de texto recomendado: Menos de 40 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Etiquetas de artículos | Opcional (Si no se proporcionan, se deben brindar imágenes de pósteres) |
Es la lista de etiquetas de los artículos del pedido anterior. Se pueden brindar hasta 10 etiquetas en orden de prioridad. La cantidad real de etiquetas que se muestran depende del factor de forma del dispositivo. |
Lista de texto libre Tamaño de texto recomendado por etiqueta: Menos de 20 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Imágenes de pósteres | Opcional (Si no se proporcionan, se deben brindar las etiquetas de artículos) |
Son las imágenes de los artículos del pedido anterior. Se pueden brindar hasta 10 imágenes en orden de prioridad. La cantidad real de imágenes que se muestran depende del factor de forma del dispositivo. |
Consulta la sección Especificaciones de imagen para obtener más información. |
Especificaciones de imagen
A continuación, se indican las especificaciones obligatorias para los recursos de imagen:
Relación de aspecto | Píxeles mínimos | Píxeles recomendados |
---|---|---|
Formato cuadrado (1 x 1) Preferido |
300 x 300 | 1,200 x 1,200 |
Formato horizontal (1.91 x 1) | 600 x 314 | 1,200 x 628 |
Formato vertical (4 x 5) | 480 x 600 | 960 x 1,200 |
Formatos de archivo
PNG, JPG, GIF estático, WebP
Tamaño máximo de los archivos
5120 KB
Recomendaciones adicionales
- Área segura para la imagen: Coloca el contenido importante en el 80% central de la imagen.
- Usa un fondo transparente para que la imagen se muestre correctamente cuando se configure el tema oscuro o claro.
Paso 2: Proporciona los datos de los clústeres
Se recomienda que el trabajo de publicación de contenido se ejecute en segundo plano (por ejemplo, con WorkManager) y se programe con frecuencia o en eventos (por ejemplo, cada vez que el usuario abre la app o cuando acaba de agregar algo a su carrito).
AppEngageFoodClient
es responsable de publicar clústeres de comidas.
Hay cinco APIs para publicar clústeres en el cliente:
isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishFoodShoppingCart
publishFoodShoppingList
publishReorderCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteFoodShoppingCartCluster
deleteFoodShoppingListCluster
deleteReorderCluster
deleteUserManagementCluster
deleteClusters
isServiceAvailable
Esta API se usa para verificar si el servicio está disponible para la integración y si el contenido se puede presentar en el dispositivo.
Kotlin
client.isServiceAvailable.addOnCompleteListener { task -> if (task.isSuccessful) { // Handle IPC call success if(task.result) { // Service is available on the device, proceed with content publish // calls. } else { // Service is not available, no further action is needed. } } else { // The IPC call itself fails, proceed with error handling logic here, // such as retry. } }
Java
client.isServiceAvailable().addOnCompleteListener(task - > { if (task.isSuccessful()) { // Handle success if(task.getResult()) { // Service is available on the device, proceed with content publish // calls. } else { // Service is not available, no further action is needed. } } else { // The IPC call itself fails, proceed with error handling logic here, // such as retry. } });
publishRecommendationClusters
Esta API se usa para publicar una lista de objetos RecommendationCluster
.
Un objeto RecommendationCluster
puede tener los siguientes atributos:
Atributo | Requisito | Descripción |
---|---|---|
Lista de ProductEntity, StoreEntity o RecipeEntity | Obligatorio | Es una lista de las entidades que conforman las recomendaciones para este clúster de Recommendation. Las entidades en un solo clúster deben ser del mismo tipo. |
Título | Obligatorio | Es el título del clúster de Recommendation (por ejemplo, Ahorros importantes en el menú del Día de Acción de Gracias). Tamaño de texto recomendado: Menos de 25 caracteres (el texto demasiado largo puede mostrar puntos suspensivos) |
Subtítulo | Opcional | Es el subtítulo del clúster de Recommendation. |
URI de acción | Opcional |
Es el vínculo directo a la página en la app del socio en la que los usuarios pueden ver la lista completa de recomendaciones. Nota: Puedes usar vínculos directos para la atribución. Consulta estas Preguntas frecuentes |
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Big savings on Thanksgiving menu") .build()) .build())
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( new RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Big savings on Thanksgiving menu") .build()) .build());
Cuando el servicio recibe la solicitud, se realizan las siguientes acciones en una transacción:
- Se quitan todos los datos existentes del clúster de Recommendation.
- Los datos de la solicitud se analizan y se almacenan en clústeres de Recomendación nuevos.
En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
publishFeaturedCluster
Esta API se usa para publicar un objeto FeaturedCluster
.
Kotlin
client.publishFeaturedCluster( PublishFeaturedClusterRequest.Builder() .setFeaturedCluster( FeaturedCluster.Builder() ... .build()) .build())
Java
client.publishFeaturedCluster( new PublishFeaturedClusterRequest.Builder() .setFeaturedCluster( new FeaturedCluster.Builder() ... .build()) .build());
Cuando el servicio recibe la solicitud, se realizan las siguientes acciones en una transacción:
- Se quitan los datos existentes de
FeaturedCluster
del socio desarrollador. - Los datos de la solicitud se analizan y se almacenan en el clúster de Featured actualizado.
En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
publishFoodShoppingCart
Esta API se usa para publicar un objeto FoodShoppingCart
.
Kotlin
client.publishFoodShoppingCart( PublishFoodShoppingCartClusterRequest.Builder() .setShoppingCart( FoodShoppingCart.Builder() ... .build()) .build())
Java
client.publishFoodShoppingCart( new PublishFoodShoppingCartClusterRequest.Builder() .setShoppingCart( new FoodShoppingCart.Builder() ... .build()) .build());
Cuando el servicio recibe la solicitud, se realizan las siguientes acciones en una transacción:
- Se quitan los datos existentes de
FoodShoppingCart
del socio desarrollador. - Los datos de la solicitud se analizan y se almacenan en el clúster de Shopping Cart actualizado.
En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
publishFoodShoppingList
Esta API se usa para publicar un objeto FoodShoppingList
.
Kotlin
client.publishFoodShoppingList( PublishFoodShoppingListRequest.Builder() .setFoodShoppingList( FoodShoppingListEntity.Builder() ... .build()) .build())
Java
client.publishFoodShoppingList( new PublishFoodShoppingListRequest.Builder() .setFoodShoppingList( new FoodShoppingListEntity.Builder() ... .build()) .build());
Cuando el servicio recibe la solicitud, se realizan las siguientes acciones en una transacción:
- Se quitan los datos existentes de
FoodShoppingList
del socio desarrollador. - Los datos de la solicitud se analizan y se almacenan en el clúster de Shopping List actualizado.
En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
publishReorderCluster
Esta API se usa para publicar un objeto FoodReorderCluster
.
Kotlin
client.publishReorderCluster( PublishReorderClusterRequest.Builder() .setReorderCluster( FoodReorderCluster.Builder() ... .build()) .build())
Java
client.publishReorderCluster( new PublishReorderClusterRequest.Builder() .setReorderCluster( new FoodReorderCluster.Builder() ... .build()) .build());
Cuando el servicio recibe la solicitud, se realizan las siguientes acciones en una transacción:
- Se quitan los datos existentes de
FoodReorderCluster
del socio desarrollador. - Los datos de la solicitud se analizan y se almacenan en el clúster Reorder actualizado.
En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
publishUserAccountManagementRequest
Esta API se usa para publicar una tarjeta de acceso. La acción de acceso dirige a los usuarios a la página de acceso de la app para que esta pueda publicar contenido (o proporcionar contenido más personalizado).
Los siguientes metadatos forman parte de la tarjeta de acceso:
Atributo | Requisito | Descripción |
---|---|---|
URI de acción | Obligatorio | Vínculo directo a la acción (p. ej., navega a la página de acceso de la app) |
Imagen | Opcional: En caso de que no se proporcione el título, debes brindar uno. |
Imagen que se muestra en la tarjeta Imágenes con una relación de aspecto de 16 × 9, con una resolución de 1264 × 712 |
Título | Opcional: En caso de que no se proporcione la imagen, debes brindar una. | Título en la tarjeta |
Texto de acción | Opcional | Texto que se muestra en la CTA (p. ej., Acceder) |
Subtítulo | Opcional | Subtítulo opcional en la tarjeta |
Kotlin
var SIGN_IN_CARD_ENTITY = SignInCardEntity.Builder() .addPosterImage( Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(500) .setImageWidthInPixel(500) .build()) .setActionText("Sign In") .setActionUri(Uri.parse("http://xx.com/signin")) .build() client.publishUserAccountManagementRequest( PublishUserAccountManagementRequest.Builder() .setSignInCardEntity(SIGN_IN_CARD_ENTITY) .build());
Java
SignInCardEntity SIGN_IN_CARD_ENTITY = new SignInCardEntity.Builder() .addPosterImage( new Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(500) .setImageWidthInPixel(500) .build()) .setActionText("Sign In") .setActionUri(Uri.parse("http://xx.com/signin")) .build(); client.publishUserAccountManagementRequest( new PublishUserAccountManagementRequest.Builder() .setSignInCardEntity(SIGN_IN_CARD_ENTITY) .build());
Cuando el servicio recibe la solicitud, se realizan las siguientes acciones en una transacción:
- Se quitan los datos existentes de
UserAccountManagementCluster
del socio desarrollador. - Los datos de la solicitud se analizan y se almacenan en el clúster de UserAccountManagementCluster actualizado.
En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
updatePublishStatus
Si, por algún motivo empresarial interno, no se publica ninguno de los clústeres, te recomendamos que actualices el estado de publicación a través de la API de updatePublishStatus. A continuación, explicamos por qué es importante:
- Proporcionar el estado en todas las situaciones, incluso cuando el contenido está publicado (STATUS == PUBLISHED), es fundamental para propagar los paneles que usan este estado explícito para transmitir el estado y otras métricas de tu integración.
- Si no se publica contenido pero el estado de integración no está roto (STATUS == NOT_PUBLISHED), Google puede evitar activar alertas en los paneles de estado de la app. Confirma que el contenido no se publicó debido a una situación prevista desde el punto de vista del proveedor.
- Ayuda a los desarrolladores a proporcionar estadísticas sobre cuándo se publican los datos y cuándo no.
- Google puede usar los códigos de estado para sugerir al usuario que realice determinadas acciones en la app de modo que pueda ver el contenido de la app o superarlo.
La lista de códigos de estado de publicación aptos es la siguiente:
// Content is published
AppEngagePublishStatusCode.PUBLISHED,
// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,
// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,
// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,
// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,
// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,
// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,
// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,
// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER
Si el contenido no se publica debido a que un usuario no accedió, te recomendamos que publiques la tarjeta de acceso. Si, por algún motivo, los proveedores no pueden publicar la tarjeta de acceso, recomendamos que llames a la API de updatePublishStatus con el código de estado NOT_PUBLISHED_REQUIRES_SIGN_IN.
Kotlin
client.updatePublishStatus( PublishStatusRequest.Builder() .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN) .build())
Java
client.updatePublishStatus( new PublishStatusRequest.Builder() .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN) .build());
deleteRecommendationClusters
Esta API se usa para borrar el contenido de los clústeres de Recommendation.
Kotlin
client.deleteRecommendationClusters()
Java
client.deleteRecommendationClusters();
Cuando el servicio recibe la solicitud, quita los datos existentes de los clústeres de Recommendation. En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
deleteFeaturedCluster
Esta API se usa para borrar el contenido del clúster de Featured.
Kotlin
client.deleteFeaturedCluster()
Java
client.deleteFeaturedCluster();
Cuando el servicio recibe la solicitud, quita los datos existentes del clúster de Featured. En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
deleteFoodShoppingCartCluster
Esta API se usa para borrar el contenido del clúster de Food Shopping Cart.
Kotlin
client.deleteFoodShoppingCartCluster()
Java
client.deleteFoodShoppingCartCluster();
Cuando el servicio recibe la solicitud, quita los datos existentes del clúster de Food Shopping Cart. En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
deleteFoodShoppingListCluster
Esta API se usa para borrar el contenido del clúster de Food Shopping List.
Kotlin
client.deleteFoodShoppingListCluster()
Java
client.deleteFoodShoppingListCluster();
Cuando el servicio recibe la solicitud, quita los datos existentes del clúster de Food Shopping List. En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
deleteReorderCluster
Esta API se usa para borrar el contenido de FoodReorderCluster.
Kotlin
client.deleteReorderCluster()
Java
client.deleteReorderCluster();
Cuando el servicio recibe la solicitud, quita los datos existentes del clúster de Reorder. En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
deleteUserManagementCluster
Esta API se usa para borrar el contenido del clúster de UserAccountManagement.
Kotlin
client.deleteUserManagementCluster()
Java
client.deleteUserManagementCluster();
Cuando el servicio recibe la solicitud, quita los datos existentes del clúster de UserAccountManagement. En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
deleteClusters
Esta API se usa para borrar el contenido de un tipo de clúster determinado.
Kotlin
client.deleteClusters( DeleteClustersRequest.Builder() .addClusterType(ClusterType.TYPE_FEATURED) .addClusterType(ClusterType.TYPE_RECOMMENDATION) ... .build())
Java
client.deleteClusters( new DeleteClustersRequest.Builder() .addClusterType(ClusterType.TYPE_FEATURED) .addClusterType(ClusterType.TYPE_RECOMMENDATION) ... .build());
Cuando el servicio recibe la solicitud, quita los datos existentes de todos los clústeres que coincidan con los tipos de clúster especificados. Los clientes pueden optar por pasar uno o varios tipos de clústeres. En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.
Manejo de errores
Te recomendamos que escuches el resultado de la tarea de las APIs de publicación, de manera que se pueda realizar una acción de seguimiento para recuperar y volver a enviar una tarea con éxito.
client.publishRecommendationClusters(
new PublishRecommendationClustersRequest.Builder()
.addRecommendationCluster(...)
.build())
.addOnCompleteListener(
task -> {
if (task.isSuccessful()) {
// do something
} else {
Exception exception = task.getException();
if (exception instanceof AppEngageException) {
@AppEngageErrorCode
int errorCode = ((AppEngageException) exception).getErrorCode();
if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
// do something
}
}
}
});
El error se muestra como una AppEngageException
con la causa incluida como un código de error.
Código de error | Nombre del error | Nota |
---|---|---|
1 |
SERVICE_NOT_FOUND |
El servicio no está disponible en el dispositivo determinado. |
2 |
SERVICE_NOT_AVAILABLE |
El servicio está disponible en el dispositivo determinado, pero no en el momento de la llamada (por ejemplo, está inhabilitado explícitamente). |
3 |
SERVICE_CALL_EXECUTION_FAILURE |
No se pudo ejecutar la tarea debido a problemas con los subprocesos. En este caso, se puede volver a intentar. |
4 |
SERVICE_CALL_PERMISSION_DENIED |
El llamador no tiene permiso para realizar la llamada de servicio. |
5 |
SERVICE_CALL_INVALID_ARGUMENT |
La solicitud contiene datos no válidos (por ejemplo, una cantidad de clústeres mayor que la permitida). |
6 |
SERVICE_CALL_INTERNAL |
Hay un error en el servicio. |
7 |
SERVICE_CALL_RESOURCE_EXHAUSTED |
La llamada de servicio se realiza con demasiada frecuencia. |
Paso 3: Controla los intents de transmisión
Además de realizar llamadas a las APIs de publicación de contenido a través de un trabajo, también se requiere configurar un BroadcastReceiver
para recibir la solicitud de publicación de contenido.
El objetivo de los intents de transmisión es principalmente reactivar apps y forzar la sincronización de datos. Los intents de transmisión no están diseñados para enviarse con mucha frecuencia. Solo se activan cuando el servicio de Engage determina que el contenido puede estar inactivo (por ejemplo, si es de hace una semana). De esa manera, será más probable que el usuario tenga una experiencia de contenido actualizada, incluso si la aplicación no se ejecutó durante un período prolongado.
El BroadcastReceiver
debe configurarse de las siguientes dos maneras:
- Registra de forma dinámica una instancia de la clase
BroadcastReceiver
conContext.registerReceiver()
. Esto permite la comunicación desde aplicaciones que aún están activas en la memoria.
class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received
// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
// Trigger shopping cart cluster publish when PUBLISH_FOOD_SHOPPING_CART
// broadcast is received
// Trigger shopping list cluster publish when PUBLISH_FOOD_SHOPPING_LIST
// broadcast is received
// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
// received
}
public static void registerBroadcastReceivers(Context context) {
context = context.getApplicationContext();
// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION));
// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));
// Register Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART));
// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_LIST));
// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_REORDER_CLUSTER));
}
- Declara de forma estática una implementación con la etiqueta
<receiver>
en tu archivoAndroidManifest.xml
. Esto permite que la aplicación reciba intents de transmisión cuando no está en ejecución y que la aplicación publique el contenido.
<application>
<receiver
android:name=".AppEngageBroadcastReceiver"
android:exported="true"
android:enabled="true">
<intent-filter>
<action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER" />
</intent-filter>
</receiver>
</application>
El servicio enviará los siguientes intents:
com.google.android.engage.action.PUBLISH_RECOMMENDATION
Te recomendamos que inicies una llamada apublishRecommendationClusters
cuando recibas este intent.com.google.android.engage.action.PUBLISH_FEATURED
Te recomendamos que inicies una llamada apublishFeaturedCluster
cuando recibas este intent.com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART
Te recomendamos que inicies una llamada apublishFoodShoppingCart
cuando recibas este intent.com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST
Te recomendamos que inicies una llamada apublishFoodShoppingList
cuando recibas este intent.com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER
Te recomendamos que inicies una llamada apublishReorderCluster
cuando recibas este intent.
Flujo de trabajo de integración
Si deseas obtener una guía paso a paso para verificar la integración una vez que esta se complete, consulta Flujo de trabajo de integración para desarrolladores de Engage.
Preguntas frecuentes
Consulta Preguntas frecuentes sobre el SDK de Engage para ver preguntas frecuentes.
Contacto
Comunícate con engage-developers@google.com si tienes preguntas durante el proceso de integración. Nuestro equipo te responderá lo antes posible.
Próximos pasos
Después de completar esta integración, sigue estos pasos:
- Envía un correo electrónico a engage-developers@google.com y adjunta el APK integrado que está listo para que Google lo pruebe.
- Google realizará una verificación y una revisión interna para garantizar que la integración funcione según lo previsto. En caso de que se necesiten cambios, Google se comunicará contigo con todos los detalles necesarios.
- Cuando se completen las pruebas y no se necesiten cambios, Google se comunicará contigo para notificarte que puedes comenzar a publicar el APK integrado y actualizado en Play Store.
- Después de que Google confirme que tu APK actualizado se publicó en Play Store, los clústeres de Recommendation, Featured, Shopping Cart, Shopping List y Reorder se publicarán y serán visibles para los usuarios.