Compras con el SDK de Engage: Instrucciones de integración técnica de terceros

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.

Esta guía contiene instrucciones para que los socios desarrolladores integren su contenido de compras con el SDK de Engage para propagar esta nueva área de la plataforma y las plataformas existentes de Google, como Entertainment Space.

Información detallada sobre la integración

A continuación, encontrarás los detalles de la integración:

Terminología

Esta integración incluye los siguientes cinco tipos de clústeres: Recommendation, Featured, Shopping Cart, Shopping List y Reorder.

• Los clústeres de Recommendation muestran sugerencias de compras personalizadas de un socio desarrollador individual. Estas recomendaciones se pueden personalizar para el usuario o generalizar (por ejemplo, si incluyen artículos en tendencia). Úsalas para mostrar productos, eventos, ofertas, promociones y suscripciones cuando lo creas conveniente.

  Tus recomendaciones tienen la siguiente estructura:

  • Clúster de Recommendation: Es una vista de la IU que contiene un grupo de recomendaciones del mismo socio desarrollador.

  • ShoppingEntity: Es un objeto que representa un solo elemento en un clúster.

• El clúster de Featured muestra el hero ShoppingEntity elegido entre muchos 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 puede publicar una sola ShoppingEntity en el clúster de Featured.

• El clúster de Shopping Cart muestra un adelanto de carritos de compra de muchos socios desarrolladores en una agrupación de IU, lo que sugiere a los usuarios que completen sus carritos pendientes. Hay un solo clúster de Shopping Cart, que se muestra cerca de la parte superior de la IU, con una ubicación de prioridad sobre todos los clústeres de Recommendation. Cada socio desarrollador podrá transmitir un único elemento ShoppingCart en el clúster de Shopping Cart.

  Tu carrito de compras tiene la siguiente estructura:

  • Clúster de Shopping Cart: Es una vista de la IU que contiene un grupo de vistas previas del carrito de compras de muchos socios desarrolladores.

  • ShoppingCart: Es un objeto que representa la vista previa del carrito de compras de un solo socio desarrollador, que se mostrará en el clúster de Shopping Cart. El elemento ShoppingCart debe mostrar la cantidad total de artículos en el carrito y también puede incluir imágenes de algunos artículos en el carrito del usuario.

• El clúster de Shopping List muestra un adelanto de las listas de compras 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 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.play:engage 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.4.0'
}

Para obtener más información, consulta Visibilidad de paquetes en Android 11.

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 elementos ShoppingEntity como máximo
Clúster de Featured	1 como máximo	1 elemento ShoppingEntity como máximo
Clúster de Shopping Cart	1 como máximo	1 elemento ShoppingCart como máximo
Clúster de Shopping List	1 como máximo	1 elemento ShoppingListEntity como máximo
Clúster de Shopping 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. Las siguientes entidades son compatibles con la categoría Compras:

1. ShoppingEntity
2. ShoppingCart
3. ShoppingList
4. Reorder

En los gráficos siguientes, se describen los atributos y requisitos disponibles para cada tipo.

ShoppingEntity

El objeto ShoppingEntity representa un producto, una promoción, una oferta, una suscripción o un evento que los socios desarrolladores desean publicar.

ShoppingEntity

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 entidad. Nota: Puedes usar vínculos directos para la atribución. Consulta estas Preguntas frecuentes	URI
Títulos	Opcional	Es el nombre de la entidad.	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 de la entidad. Se debe brindar si se proporciona el precio tachado.	Texto libre
Precio (tachado)	Opcional	Es el precio original de la entidad, que aparecerá tachado en la IU.	Texto libre
Texto destacado	Opcional	Es el texto destacado para mostrar una promoción, un evento o una actualización de la entidad, 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 estándar.
Calificación: Valor máximo	Obligatorio	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	Obligatorio	Es el valor actual de la calificación de la entidad. 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 entidad.	Cadena
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 muestra en la superficie. Si no la estableces, el contenido será apto para mostrarse en la superficie.	Marca de tiempo de época en milisegundos

ShoppingCart

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 camisas idénticas y 1 sombrero en el carrito, la cantidad debe ser 4.	Número entero >= 1
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 será View Cart. Este atributo es compatible con la versión 1.1.0 y posteriores.	Cadena
Títulos	Opcional	Es el título del carrito (por ejemplo, Tu bolsa de compras). 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)
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 muestra en la superficie. Si no la estableces, el contenido será apto para mostrarse en la superficie.	Marca de tiempo de época en milisegundos

ShoppingList

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ítulos	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)

ShoppingReorderCluster

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 será 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ítulos	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 para clústeres que no son de Featured	300 x 300	1,200 x 1,200
Formato horizontal (1.91 x 1) Preferido para clústeres de Featured	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).

AppEngageShoppingClient es responsable de publicar clústeres de compras.

Las siguientes APIs se exponen para publicar clústeres en el cliente:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishShoppingCart
• publishShoppingList
• publishShoppingReorderCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteShoppingCartCluster
• deleteShoppingListCluster
• deleteShoppingReorderCluster
• 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.
    }
});

Nota: Te recomendamos que mantengas en ejecución un trabajo periódico para comprobar si el servicio se vuelve disponible más adelante. La disponibilidad del servicio puede cambiar con las actualizaciones de versiones de Android, las actualizaciones de apps, las instalaciones y las desinstalaciones. Cuando se realizan verificaciones de trabajo periódico en un intervalo determinado, se pueden publicar los datos una vez que el servicio esté disponible.

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 ShoppingEntity	Obligatorio	Es una lista de objetos ShoppingEntity que conforman las recomendaciones para este clúster de Recommendation.
Títulos	Obligatorio	Es el título del clúster de Recommendation. Tamaño de texto recomendado: Menos de 25 caracteres (el texto demasiado largo puede mostrar puntos suspensivos)
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

Importante: Las APIs de Publication son APIs de inserción y actualización, es decir que reemplazan el contenido existente. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente.

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .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.

Importante: Las APIs de publicación son APIs de inserción y actualización. Reemplazan el contenido existente. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente.

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.

publishShoppingCart

Esta API se usa para publicar un objeto ShoppingCartCluster.

Importante: Las APIs de publicación son APIs de inserción y actualización. Reemplazan el contenido existente. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente.

Kotlin

client.publishShoppingCart(
            PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    ShoppingCart.Builder()
                        ...
                        .build())
                .build())

Java

client.publishShoppingCart(
            new PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    new ShoppingCart.Builder()
                        ...
                        .build())
                .build())

Cuando el servicio recibe la solicitud, se realizan las siguientes acciones en una transacción:

• Se quitan los datos existentes de ShoppingCart 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.

publishShoppingList

Esta API se usa para publicar un objeto FoodShoppingList.

Importante: Las APIs de publicación son APIs de inserción y actualización. Reemplazan el contenido existente. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente.

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.

publishShoppingReorderCluster

Esta API se usa para publicar un objeto ShoppingReorderCluster.

Importante: Las APIs de publicación son APIs de inserción y actualización. Reemplazan el contenido existente. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente.

Kotlin

client.publishShoppingReorderCluster(
            PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishShoppingReorderCluster(
            new PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    new ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build());

Cuando el servicio recibe la solicitud, se realizan las siguientes acciones en una transacción:

• Se quitan los datos existentes de ShoppingReorderCluster 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ítulos	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

Importante: Las APIs de Publication son APIs de inserción y actualización. Reemplazan el contenido existente. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente.

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.

Importante: Solo se debe llamar a las APIs de Delete cuando no hay contenido para publicar. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente. Comunícate con engage-developers@ antes de usar las APIs de Delete.

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.

Nota: Esta API está disponible desde la versión 1.1.0 en adelante.

deleteFeaturedCluster

Esta API se usa para borrar el contenido del clúster de Featured.

Importante: Solo se debe llamar a las APIs de Delete cuando no hay contenido para publicar. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente. Comunícate con engage-developers@ antes de usar las APIs de Delete.

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.

Nota: Esta API está disponible desde la versión 1.1.0 en adelante.

deleteShoppingCartCluster

Esta API se usa para borrar el contenido del clúster de Shopping Cart.

Importante: Solo se debe llamar a las APIs de Delete cuando no hay contenido para publicar. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente. Comunícate con engage-developers@ antes de usar las APIs de Delete.

Kotlin

client.deleteShoppingCartCluster()

Java

client.deleteShoppingCartCluster();

Cuando el servicio recibe la solicitud, quita los datos existentes del clúster de Shopping Cart. En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.

Nota: Esta API está disponible desde la versión 1.1.0 en adelante.

deleteShoppingListCluster

Esta API se usa para borrar el contenido del clúster de Shopping List.

Importante: Solo se debe llamar a las APIs de Delete cuando no hay contenido para publicar. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente. Comunícate con engage-developers@ antes de usar las APIs de Delete.

Kotlin

client.deleteShoppingListCluster()

Java

client.deleteShoppingListCluster();

Cuando el servicio recibe la solicitud, quita los datos existentes del clúster de Shopping List. En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.

Nota: Esta API está disponible desde la versión 1.1.0 en adelante.

deleteShoppingReorderCluster

Esta API se usa para borrar el contenido del clúster de Shopping Reorder.

Importante: Solo se debe llamar a las APIs de Delete cuando no hay contenido para publicar. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente. Comunícate con engage-developers@ antes de usar las APIs de Delete.

Kotlin

client.deleteShoppingReorderCluster()

Java

client.deleteShoppingReorderCluster();

Cuando el servicio recibe la solicitud, quita los datos existentes del clúster de Shopping Reorder. En caso de error, se rechaza la solicitud completa y se mantiene el estado existente.

Nota: Esta API está disponible desde la versión 1.1.0 en adelante.

deleteUserManagementCluster

Esta API se usa para borrar el contenido del clúster de UserAccountManagement.

Importante: Solo se debe llamar a las APIs de Delete cuando no hay contenido para publicar. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente. Comunícate con engage-developers@ antes de usar las APIs de Delete.

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.

Nota: Esta API está disponible desde la versión 1.1.0 en adelante.

deleteClusters

Esta API se usa para borrar el contenido de un tipo de clúster determinado.

Importante: Solo se debe llamar a las APIs de Delete cuando no hay contenido para publicar. No llames a las APIs de Delete y Publication posteriormente para reemplazar el contenido, ya que las APIs de Publication lo hacen de forma inherente. Comunícate con engage-developers@ antes de usar las APIs de Delete.

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.

Kotlin

client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

Java

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	Nota
SERVICE_NOT_FOUND	El servicio no está disponible en el dispositivo determinado.
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).
SERVICE_CALL_EXECUTION_FAILURE	No se pudo ejecutar la tarea debido a problemas con los subprocesos. En este caso, se puede volver a intentar.
SERVICE_CALL_PERMISSION_DENIED	El llamador no tiene permiso para realizar la llamada de servicio.
SERVICE_CALL_INVALID_ARGUMENT	La solicitud contiene datos no válidos (por ejemplo, una cantidad de clústeres mayor que la permitida).
SERVICE_CALL_INTERNAL	Hay un error en el servicio.
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 con Context.registerReceiver(). Esto permite la comunicación desde aplicaciones que aún están activas en la memoria.

Kotlin

class AppEngageBroadcastReceiver : 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_SHOPPING_CART broadcast
  // is received
  // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast
  // is received
  // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
  // received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Shopping Cart Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART))

// Register Shopping List Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_LIST))

// Register Reorder Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_REORDER_CLUSTER))
}

Java

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_SHOPPING_CART broadcast is
// received

// Trigger shopping list cluster publish when PUBLISH_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.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_CART));

// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_LIST));

// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_REORDER_CLUSTER));

}

• Declara de forma estática una implementación con la etiqueta <receiver> en tu archivo AndroidManifest.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.shopping.PUBLISH_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER" />
      </intent-filter>
   </receiver>
</application>

El servicio envía los siguientes intents:

• com.google.android.engage.action.PUBLISH_RECOMMENDATION Te recomendamos que inicies una llamada a publishRecommendationClusters cuando se recibe este intent.
• com.google.android.engage.action.PUBLISH_FEATURED Te recomendamos que inicies una llamada a publishFeaturedCluster cuando se recibe este intent.
• com.google.android.engage.action.shopping.PUBLISH_SHOPPING_CART Te recomendamos que inicies una llamada a publishShoppingCart cuando se recibe este intent.
• com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST Te recomendamos que inicies una llamada a publishShoppingList cuando se recibe este intent.
• com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER Te recomendamos que inicies una llamada a publishReorderCluster cuando se recibe 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 [e-mail] si tienes preguntas durante el proceso de integración. Nuestro equipo responde lo antes posible.

Próximos pasos

Después de completar esta integración, sigue estos pasos:

• Envía un correo electrónico a [e-mail] y adjunta el APK integrado que está listo para que Google lo pruebe.
• Google realiza una verificación y revisiones internas para asegurarse de que la integración funcione según lo previsto. Si se necesitan cambios, Google se comunica contigo con 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 y Shopping Cart podrán publicarse y ser visibles para los usuarios.