En esta guía, se explica cómo agregar transacciones digitales a tu acción de conversación para que los usuarios puedan comprar tus artículos digitales no consumibles.
Términos clave: un artículo digital no consumible es una unidad de almacenamiento (SKU) que solo se puede comprar una vez, como el acceso pagado a contenido adicional en una acción o una app para Android. Este tipo de producto es diferente de un artículo digital consumible que se puede comprar, usar y volver a comprar.
Para obtener más información sobre los productos únicos no consumibles, consulta la documentación de Android sobre las funciones específicas de productos únicos.
Flujo de transacciones
En esta guía, se describe cada paso de desarrollo a medida que ocurren en un flujo de transacción de artículos digitales. Cuando tu Acción controla transacciones de artículos digitales, usa el siguiente flujo:
- Configura un cliente de la API de compras digitales: Tu Acción usa la API de compras digitales para comunicarse con tu inventario de Google Play y realizar transacciones. Antes de que tu Acción haga cualquier otra cosa, crea un cliente de JWT con una clave de servicio para comunicarse con la API de compras digitales.
- Recopilar información: Tu Acción recopila información básica sobre el usuario y tu inventario de Google Play a fin de preparar una transacción.
- Valida los requisitos de las transacciones: Tu Acción usa el asistente de requisitos de transacciones digitales al comienzo del flujo de compra para garantizar que el usuario pueda realizar la transacción.
- Reúne el inventario disponible: Tu Acción verifica tu inventario de Google Play e identifica los elementos que están disponibles para la compra en ese momento.
- Crea el pedido: Tu Acción presenta los artículos digitales disponibles al usuario para que pueda seleccionar uno y comprarlo.
- Completar la compra: Tu Acción usa la API de compras digitales para iniciar una compra con la selección del usuario en Google Play Store.
- Controla el resultado: Tu Acción recibe un código de estado para la transacción y notifica al usuario que la compra se realizó correctamente (o que requiere pasos adicionales).
Restricciones y lineamientos para la revisión
Se aplican políticas adicionales a las Acciones con transacciones. Es posible que tardemos algunas semanas en revisar las Acciones que incluyen transacciones, así que ten en cuenta ese tiempo cuando planifiques tu programa de lanzamientos. Para facilitar el proceso de revisión, asegúrate de cumplir con las políticas y los lineamientos para las transacciones antes de enviar la acción a revisión.
Las acciones que venden artículos digitales solo se pueden implementar en los siguientes países:
- Australia
- Brasil
- Canadá
- Indonesia
- Japón
- México
- Rusia
- Singapur
- Tailandia
- Turquía
- Reino Unido
- Estados Unidos
Requisitos previos
Antes de incorporar transacciones digitales en tu Acción, necesitas los siguientes requisitos previos:
Una cuenta de desarrollador y una cuenta de comerciante en Google Play para administrar tus artículos digitales en Google Play Console
Un dominio web que esté verificado en Google Search Console No es necesario que este dominio esté asociado a un sitio web que se haya lanzado públicamente; solo necesitamos hacer referencia a tu dominio web.
Una app para Android con el permiso
com.android.vending.BILLINGen Google Play Console Tus artículos digitales estarán asociados a las "compras directas desde la aplicación" en Google Play Console.También debes crear una versión en Play Console con esta app, pero si no quieres que sea pública, puedes crear una versión alfa cerrada.
Si aún no tienes una app para Android, sigue las instrucciones para asociar una app para Android.
Uno o más productos administrados en Google Play Console, que son artículos digitales que vendes con tu Acción Ten en cuenta que no puedes crear productos administrados en Play Console hasta que configures el requisito previo de la app para Android.
Si aún no tienes productos administrados, sigue las instrucciones para crear tus artículos digitales.
Asocia una app para Android
Si actualmente no tienes una app para Android con el permiso de facturación en Google Play Console, sigue estos pasos:
- En Android Studio o en el IDE de Android que prefieras, crea un proyecto nuevo. Elige opciones en las instrucciones de configuración del proyecto para crear una app muy básica.
- Asígnale al proyecto un nombre de paquete, como
com.mycompany.myapp. No dejes este nombre como predeterminado, ya que no puedes subir paquetes que incluyancom.examplea Play Console. - Abre el archivo
AndroidManifest.xmlde tu app. Agrega la siguiente línea de código dentro del elemento
manifest:<uses-permission android:name="com.android.vending.BILLING" />Tu archivo
AndroidManifest.xmldebería verse como el siguiente bloque de código:<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" package="com.mycompany.myapp"> <uses-permission android:name="com.android.vending.BILLING" /> <application android:allowBackup="true" android:icon="@mipmap/ic_launcher" android:label="@string/app_name" android:roundIcon="@mipmap/ic_launcher_round" android:supportsRtl="true" android:theme="@style/AppTheme" /> </manifest>Compila tu app como un APK firmado. En Android Studio, sigue estos pasos:
- Ve a Build, Generate Signed Bundle / APK.
- Presiona Siguiente.
- En Ruta de acceso al almacén de claves, haz clic en Crear nueva.
- Completa todos los campos y haz clic en Aceptar. Toma nota de la contraseña del almacén de claves y la contraseña de la clave, y almacénalas en un lugar seguro, ya que las usarás más adelante.
- Presiona Siguiente.
- Selecciona versión.
- Selecciona V1 (JAR Signature).
- Haz clic en Finish.
- Después de unos segundos, Android Studio genera un archivo
app-release.apk. Ubica este archivo para usarlo más adelante.
En Google Play Console, crea una aplicación nueva.
Ve a Versiones de la app.
En Segmentos cerrados, ve a Administrar y, luego, a Alfa.
Haz clic en el botón Crear versión.
En Permite que Google administre y proteja tu clave de firma, ingresa la información de tu clave de firma.
Sube el archivo APK.
Haz clic en Guardar.
Crea tus artículos digitales
Si actualmente no tienes artículos digitales en Play Console, sigue estos pasos:
- En Google Play Console, ve a Productos integrados en la aplicación y, luego, a Productos administrados. Si ves una advertencia, sigue las instrucciones anteriores para crear una app para Android o haz clic en el vínculo para crear un perfil de comercio.
- Haz clic en Crear producto administrado.
- Completa los campos de tu producto digital. Toma nota del ID del producto, que es la forma en que harás referencia a este producto desde tu Acción.
- Haz clic en Guardar.
- Repite los pasos 2 a 4 para cada producto que desees vender.
Prepara tu proyecto de acciones
Con tus artículos digitales configurados en Google Play Console, debes habilitar las transacciones digitales y asociar tu proyecto de Acciones con tu app de Play.
Configuración
Para activar las transacciones de artículos digitales en tu proyecto de Acciones, sigue estos pasos:
- En la Consola de Actions, abre tu proyecto o crea uno nuevo.
- Ve a Implementar y, luego, a Información del directorio.
- En Información adicional y Transacciones, marca la casilla Sí en ¿Tus acciones usan la API de compra digital para realizar transacciones de artículos digitales?
- Haz clic en Guardar.
Crea una clave de API para artículos digitales
Para enviar solicitudes a la API de artículos digitales, debes descargar una clave de cuenta de servicio JSON asociada con tu proyecto de la Consola de Actions.
Para recuperar la clave de tu cuenta de servicio, sigue estos pasos:
- En la Consola de Actions, haz clic en el ícono de tres puntos en la esquina superior derecha y, luego, en Configuración del proyecto.
- Busca el ID del proyecto de tu Acción.
- Sigue este vínculo y reemplaza “
<project_id>” por el ID de tu proyecto:https://console.developers.google.com/apis/credentials?project=project_id - En la navegación principal, ve a Credenciales.
- En la página que aparece, haz clic en Crear credenciales y, luego, en Clave de cuenta de servicio.
- Ve a Cuenta de servicio y haz clic en Nueva cuenta de servicio.
- Asigna un nombre como digitaltransactions a la cuenta de servicio.
- Haz clic en Crear.
- Establece el Rol en Proyecto > Propietario.
- Haz clic en Continuar.
- Haga clic en Crear clave.
- Selecciona el tipo de clave JSON.
- Haz clic en Crear clave y descarga la clave de cuenta de servicio JSON.
Guarda esta clave de cuenta de servicio en un lugar seguro. Usarás esta clave en tu entrega a fin de crear un cliente para la API de compras digitales.
Conéctate a tu inventario de Play
Para acceder a tus artículos digitales desde un proyecto de Acciones, asocia tu dominio web y la app con tu proyecto como propiedades conectadas.
Para conectar el dominio web y la app de Play Console a tu proyecto de Acciones, sigue estos pasos:
- En la Consola de Actions, ve a Implementar y, luego, a Verificación de marca.
Si no conectaste ninguna propiedad, primero conecta un sitio web:
- Haz clic en el botón de propiedad web (</>).
- Ingresa la URL de tu dominio web y haz clic en Conectar.
Google envía un correo electrónico con más instrucciones a la persona que tiene la verificación de ese dominio web en Google Search Console. Una vez que el destinatario de este correo electrónico siga esos pasos, el sitio web debería aparecer en Verificación de marca.
Una vez que tengas al menos un sitio web conectado, sigue estos pasos para conectar tu app para Android:
- En la Consola de Actions, ve a Implementar y, luego, a Verificación de marca.
- Haz clic en Conectar app.
En la página que aparece, sigue las instrucciones para verificar tu dominio web en Play Console. Selecciona la app de Play que contiene tus artículos digitales y, luego, ingresa la URL del dominio web exactamente como se muestra en la página Verificación de marca.
Una vez más, Google envía un correo electrónico de verificación al propietario verificado del dominio. Una vez que se apruebe la verificación, tu app de Play debería aparecer en Verificación de marca.
Habilita Acceder a compras en Play.
Crea tu flujo de compra
Con tu proyecto de Acciones y tu inventario de artículos digitales preparados, crea un flujo de compra de artículos digitales en tu webhook de entrega de conversaciones.
1. Cómo configurar un cliente de API de compras digitales
En el webhook de entrega de conversaciones, crea un cliente de JWT con la clave JSON de tu cuenta de servicio y el alcance https://www.googleapis.com/auth/actions.purchases.digital.
El siguiente código de Node.js crea un cliente JWT para la API de compras digitales:
const serviceAccount = {'my-file.json'};
const request = require('request');
const {google} = require('googleapis');
const jwtClient = new google.auth.JWT(
serviceAccount.client_email, null, serviceAccount.private_key,
['https://www.googleapis.com/auth/actions.purchases.digital'],
null
);
2. Recopila información
Antes de que el usuario pueda realizar una compra, tu Acción recopila información sobre su capacidad para realizar compras y qué productos están disponibles en tu inventario.
2. a. Valida los requisitos de compras digitales
Se recomienda asegurarse de que la cuenta del usuario esté configurada para realizar transacciones antes de darle la opción de realizar una compra. Debes hacer la transición a una escena DigitalPurchaseCheck, que verifica que el usuario esté verificado, que esté realizando la transacción en una plataforma permitida (pantalla inteligente, bocina inteligente o Android) y que se encuentre en una configuración regional donde se admitan transacciones digitales.
Para crear una escena de controles de compras digitales, sigue estos pasos:
- En la pestaña Scenes, agrega una nueva escena con el nombre
DigitalPurchaseCheck. - En Relleno de ranuras, haz clic en + para agregar un espacio nuevo.
- En Select type, selecciona
actions.type.DigitalPurchaseCheckResultcomo el tipo de ranura. - En el campo del nombre del espacio, asígnale el nombre
DigitalPurchaseCheck. - Habilita la casilla de verificación Customize slot value writeback (habilitada de forma predeterminada).
- Haz clic en Guardar.
Un cheque de compra digital dará uno de los siguientes resultados:
- Si se cumplen los requisitos, el parámetro de sesión se establece con una condición de éxito y puedes proceder a permitir que el usuario compre artículos digitales.
- Si no se pueden cumplir uno o más de los requisitos, el parámetro de sesión se establece con una condición de falla. En este caso, debes alejar la conversación de la experiencia transaccional o finalizar la conversación.
Para administrar el resultado de una verificación de compra digital, sigue estos pasos:
- En la pestaña Scenes, selecciona la escena
DigitalPurchaseCheckque acabas de crear. - En Condición, haz clic en + para agregar una condición nueva.
En el campo de texto, ingresa la siguiente sintaxis de condición para verificar la condición de éxito:
scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"Coloca el cursor sobre la condición que acabas de agregar y haz clic en la flecha hacia arriba para colocarla antes de
if scene.slots.status == "FINAL".Habilita Send prompts y proporciona un mensaje simple que informe al usuario que está listo para realizar una transacción:
candidates: - first_simple: variants: - speech: >- You are ready to purchase digital goods.En Transition, selecciona otra escena para que el usuario continúe la conversación y realice una transacción.
Selecciona la condición
else if scene.slots.status == "FINAL".Habilita Send prompts y proporciona un mensaje simple para informar al usuario que no puede realizar una transacción:
candidates: - first_simple: variants: - speech: Sorry you cannot perform a digital purchase.En Transition, selecciona End conversation para finalizar la conversación.
2. b. Reunir el inventario disponible
Usa la API de compras digitales para solicitar tu inventario de Play Store disponible actualmente y, luego, compílalo en un array de objetos JSON para cada producto. Más adelante, harás referencia a este array para mostrarle al usuario qué opciones están disponibles para la compra.
Cada uno de tus artículos digitales está representado como un SKU en formato JSON. En el siguiente código de Node.js, se describe el formato esperado de cada SKU:
body = {
skus: [
skuId: {
skuType: one of "SKU_TYPE_IN_APP" or "SKU_TYPE_SUBSCRIPTION"
id: string,
packageName: string
}
formattedPrice: string,
title: string,
description: string
]
}
Envía una solicitud POST al extremo https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet, en el que {packageName} es el nombre del paquete de tu app en Google Play Console (por ejemplo, com.myapp.digitalgoods), y dale formato al resultado en un array de objetos SKU.
Para recuperar solo artículos digitales específicos en el array resultante, enumera los IDs de los productos para artículos digitales (como se muestra en cada producto integrado en la aplicación en Google Play Console) que desees que estén disponibles para la compra en body.ids.
El siguiente código de Node.js solicita una lista de productos disponibles de la API de compras digitales y da formato al resultado como un array de SKU:
return jwtClient.authorize((err, tokens) => {
if (err) {
throw new Error(`Auth error: ${err}`);
}
const packageName = 'com.example.projectname';
request.post(`https://actions.googleapis.com/v3/packages/${packageName}/skus:batchGet`, {
'auth': {
'bearer': tokens.access_token,
},
'json': true,
'body': {
'conversationId': conv.session.id,
'skuType': 'SKU_TYPE_IN_APP',
// This request is filtered to only retrieve SKUs for the following product IDs
'ids': ['nonconsumable.1']
},
}, (err, httpResponse, body) => {
if (err) {
throw new Error(`API request error: ${err}`);
}
console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
console.log(JSON.stringify(body));
});
});
});
3. Arma el pedido
Para iniciar la compra digital del usuario, presenta una lista de tus artículos digitales disponibles para la compra. Puedes usar una variedad de tipos de respuestas enriquecidas para representar tu stock y pedirle al usuario que seleccione una opción.
El siguiente código de Node.js lee un array de inventario de objetos SKU y crea una respuesta de lista con un elemento de lista para cada uno:
const items = [];
const entries = [];
skus.forEach((sku) => {
const key = `${sku.skuId.skuType},${sku.skuId.id}`
items.push({
key: key
});
entries.push({
name: key,
synonyms: [],
display: {
title: sku.title,
description: `${sku.description} | ${sku.formattedPrice}`,
}
});
});
conv.session.typeOverrides = [{
name: 'type_name',
mode: 'TYPE_REPLACE',
synonym: {
entries: entries
}
}];
conv.add(new List({
title: 'List title',
subtitle: 'List subtitle',
items: items,
}));
Crear compra a partir de la selección del usuario
Una vez que el usuario seleccione un artículo, podrás crear el pedido. Para ello, en la ranura asociada con el elemento seleccionado, puedes llamar a tu webhook para crear el pedido. Desde tu entrega, guarda los datos del pedido en un parámetro de sesión. El objeto de orden se usa en todos los escenarios de la misma sesión.
conv.session.params.purchase = {
"@type": "type.googleapis.com/google.actions.transactions.v3.CompletePurchaseValueSpec",
"skuId": {
"skuType": "<SKU_TYPE_IN_APP>",
"id": "<SKU_ID>",
"packageName": "<PACKAGE_NAME>"
},
"developerPayload": ""
};
En su lugar, en Actions Builder, puedes usar el editor de JSON para configurar el espacio con el objeto de orden anterior. Ambas implementaciones usan el mismo formato para CompletePurchaseValueSpec, que puedes encontrar en la referencia de la carga útil del webhook de JSON.
4. Completa la compra
Una vez que el usuario selecciona un artículo, puedes completar la compra. Una vez que llenes la ranura asociada con el elemento seleccionado, debes realizar la transición a una escena que realice una compra completa.
Crea una escena de compra completa
- En la pestaña Scenes, agrega una escena nueva con el nombre
CompletePurchase. - En Relleno de ranuras, haz clic en + para agregar un espacio nuevo.
- En Seleccionar tipo, selecciona
actions.type.CompletePurchaseValuecomo el tipo de ranura. - En el campo del nombre del espacio, asígnale el nombre
CompletePurchase. - Habilita la casilla de verificación Customize slot value writeback (habilitada de forma predeterminada).
- En Configure slot, selecciona
Use session parameteren el menú desplegable. - En Configurar ranura, ingresa el nombre del parámetro de sesión que se usa para almacenar el pedido en el campo de texto (es decir,
$session.params.purchase).
- Haz clic en Guardar.
5. Controla el resultado
Un espacio con el tipo actions.type.CompletePurchaseValue puede tener los siguientes resultados:
PURCHASE_STATUS_OK: La compra se realizó correctamente. La transacción se completó en este punto, así que sal del flujo transaccional y vuelve a la conversación.PURCHASE_STATUS_ALREADY_OWNED: La transacción falló porque el usuario ya es propietario de ese elemento. Para evitar este error, revisa las compras anteriores del usuario y adapta los artículos que se muestran para que no tenga la opción de volver a comprar los que ya posee.PURCHASE_STATUS_ITEM_UNAVAILABLE: No se pudo realizar la transacción porque el elemento solicitado no está disponible. Para evitar este error, revisa los SKU disponibles más cerca del momento de la compra.PURCHASE_STATUS_ITEM_CHANGE_REQUESTED: No se pudo realizar la transacción porque el usuario decidió comprar otro producto. Vuelve a preguntar en la creación de tu pedido para que el usuario pueda tomar otra decisión de inmediato.PURCHASE_STATUS_USER_CANCELLED: La transacción falló porque el usuario canceló el flujo de compra. Dado que el usuario salió del flujo antes de tiempo, pregúntale si quiere volver a intentar la transacción o salir de ella por completo.PURCHASE_STATUS_ERROR: No se pudo realizar la transacción por un motivo desconocido. Infórmale al usuario que se produjo un error en la transacción y pregúntale si desea volver a intentarlo.PURCHASE_STATUS_UNSPECIFIED: La transacción falló por un motivo desconocido, lo que generó un estado desconocido. Para solucionar este estado de error, infórmale al usuario que falló la transacción y pregúntale si desea volver a intentarlo.
Debes controlar cada uno de estos resultados desde tu escena CompletePurchase.
- En la pestaña Scenes, selecciona la escena
CompletePurchaseque acabas de crear. - En Condición, haz clic en + para agregar una condición nueva.
En el campo de texto, ingresa la siguiente sintaxis de condición para verificar la condición de éxito:
scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"Coloca el cursor sobre la condición que acabas de agregar y haz clic en la flecha hacia arriba para colocarla antes de
if scene.slots.status == "FINAL".Habilita Send prompts y proporciona un mensaje simple que informe al usuario que está listo para realizar una transacción:
candidates: - first_simple: variants: - speech: >- Your purchase was successful.En Transición, selecciona Finalizar conversación.
Repite los pasos anteriores para cada tipo de resultado de compra que desees admitir.
Reflejar las compras del usuario
Cuando un usuario consulta tu Acción, el objeto user de la solicitud JSON incluye una lista de sus compras. Verifica esta información y cambia la respuesta de tu Acción según el contenido que haya pagado el usuario.
En el siguiente código de ejemplo, se muestra el objeto user de una solicitud que incluye packageEntitlements de las compras directas desde la aplicación que realizaron anteriormente para el paquete com.digitalgoods.application:
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "actions.intent.MAIN",
"params": {},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {}
},
"session": {
"id": "example_session_id",
"params": {},
"typeOverrides": []
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
"packageEntitlements": [
{
"packageName": "com.digitalgoods.application",
"entitlements": [
{
"sku": "non-consumable.1",
"skuType": "SKU_TYPE_IN_APP"
}
{
"sku": "consumable.2",
"skuType": "SKU_TYPE_IN_APP"
}
]
},
{
"packageName": "com.digitalgoods.application",
"entitlements": [
{
"sku": "annual.subscription",
"skuType": "SKU_TYPE_SUBSCRIPTION",
"inAppDetails": {
"inAppPurchaseData": {
"autoRenewing": true,
"purchaseState": 0,
"productId": "annual.subscription",
"purchaseToken": "12345",
"developerPayload": "HSUSER_IW82",
"packageName": "com.digitalgoods.application",
"orderId": "GPA.233.2.32.3300783",
"purchaseTime": 1517385876421
},
"inAppDataSignature": "V+Q=="
}
}
]
}
]
}
},
"homeStructure": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Cómo probar tu proyecto
Cuando pruebas tu proyecto, puedes habilitar el modo de zona de pruebas en la Consola de Actions para probar tu acción sin cobrar a una forma de pago. Para habilitar el modo de zona de pruebas, sigue estos pasos:
- En la Consola de Actions, haz clic en Test, en el menú de navegación.
- Haz clic en Configuración.
- Habilita la opción Zona de pruebas de desarrollo.