Vinculación de cuentas con Acceso con Google

El Acceso con Google para el Asistente proporciona la experiencia del usuario más sencilla y fácil a los usuarios y a los desarrolladores en la vinculación y creación de cuentas. Tu acción puede solicitar acceso al perfil de Google del usuario durante una conversación, incluidos el nombre, la dirección de correo electrónico y la foto de perfil del usuario.

La información del perfil se puede usar para crear una experiencia del usuario personalizada en tu acción. Si tienes apps en otras plataformas y usan el Acceso con Google, también puedes buscar y vincular la cuenta de un usuario existente, crear una cuenta nueva y establecer un canal directo de comunicación con el usuario.

A fin de realizar la vinculación de una cuenta con el Acceso con Google, le pides al usuario que dé su consentimiento para acceder a su perfil de Google. Luego, utiliza la información de su perfil, por ejemplo, su dirección de correo electrónico, para identificar al usuario en tu sistema.

Implementa la vinculación de cuentas de Acceso con Google

Sigue los pasos que se indican en las siguientes secciones para agregar la vinculación de cuentas de Acceso con Google a tu acción.

Nota: Si implementas la vinculación de cuentas para manejar información financiera, ten en cuenta que se pueden aplicar políticas adicionales a tu acción. La revisión de una Acción con vinculación de cuentas para obtener información financiera puede demorar hasta seis semanas, por lo que debes tener en cuenta ese tiempo cuando planifiques tu programación de lanzamientos. Para facilitar el proceso de revisión, asegúrate de cumplir con las Políticas de Servicios Financieros antes de enviar tu Acción para revisión.

Configura el proyecto

Para configurar tu proyecto de modo que utilice la vinculación de cuentas de Acceso con Google, sigue estos pasos:

1. Abre la Consola de Actions y selecciona un proyecto.
2. Haga clic en la pestaña Desarrollar y seleccione Vinculación de cuentas.
3. Habilite la opción Vinculación de la cuenta.
4. En la sección Creación de cuentas, seleccione Sí.

5. En Tipo de vinculación, selecciona Acceso con Google.

   

6. Abre la Información del cliente y anota el valor del ID del cliente emitido por Google para tus Acciones.

7. Haz clic en Guardar.

Diseña la interfaz de usuario de voz para el flujo de autenticación

Advertencia: No les das a los usuarios un mensaje de vinculación de cuenta obligatorio al comienzo de la conversación con tu acción. En su lugar, brinda a los usuarios no autenticados un flujo de invitado para mostrar cómo funciona tu acción y, luego, solicita la vinculación de la cuenta solo si es necesario para continuar. Si los usuarios abandonan la acción de manera constante debido a problemas con la vinculación de la cuenta, Google no la promocionará de forma activa, lo que puede disminuir el tráfico de usuarios de la acción.

Nota: Debes usar Actions Builder para crear una acción que implemente la vinculación de cuentas.

Verifica si el usuario está verificado y comienza el flujo de vinculación de cuentas

1. Abre tu proyecto de Actions Builder en Actions Console.
2. Crea una escena nueva para iniciar la vinculación de cuentas en tu acción:
   1. Haz clic en Escenas.
   2. Haga clic en el ícono de agregar (+) para agregar una escena nueva.
3. En la escena recién creada, haz clic en el ícono de agregar para Condiciones.
4. Agrega una condición que verifique si el usuario asociado con la conversación es un usuario verificado. Si la verificación falla, tu acción no podrá realizar la vinculación de cuentas durante la conversación y debería recurrir a proporcionar acceso a una funcionalidad que no requiera la vinculación de cuentas.
   1. En el campo Enter new expression, en Condition, ingresa la siguiente lógica: user.verificationStatus != "VERIFIED"
   2. En Transition, selecciona una escena que no requiere vinculación de cuentas o una escena que es el punto de entrada a la funcionalidad solo para invitados.

1. Haz clic en el ícono de agregar en Condiciones.
2. Agrega una condición para activar un flujo de vinculación de cuentas si el usuario no tiene una identidad asociada.
   1. En el campo Enter new expression en Condición, ingresa la siguiente lógica: user.verificationStatus == "VERIFIED"
   2. En Transition, selecciona la escena del sistema Vinculación de cuentas.
   3. Haz clic en Guardar.

Después de guardar, se agrega a tu proyecto una escena nueva del sistema de vinculación de cuentas llamada <SceneName>_AccountLinking.

Cómo personalizar la escena de vinculación de cuentas

1. En Scenes, selecciona la escena del sistema de vinculación de cuentas.
2. Haz clic en Send prompts y agrega una oración corta para describir al usuario por qué la acción necesita acceder a su identidad (por ejemplo, "Para guardar tus preferencias").
3. Haz clic en Guardar.

1. En Condiciones, haga clic en Si el usuario completa correctamente la vinculación de la cuenta.
2. Configura cómo debe proceder el flujo si el usuario acepta vincular su cuenta. Por ejemplo, llama al webhook para procesar cualquier lógica empresarial personalizada necesaria y volver a la escena de origen.
3. Haz clic en Guardar.

1. En Condiciones, haz clic en Si el usuario cancela o descarta la vinculación de cuentas.
2. Configura cómo debe proceder el flujo si el usuario no acepta vincular su cuenta. Por ejemplo, envía un mensaje de confirmación y redirecciona a las escenas que proporcionen una funcionalidad que no requiera la vinculación de cuentas.
3. Haz clic en Guardar.

1. En Condiciones, haz clic en Si se produce un error de sistema o de red.
2. Configura cómo debe proceder el flujo si no se puede completar el flujo de vinculación de cuentas debido a errores del sistema o de la red. Por ejemplo, envía un mensaje de confirmación y redirecciona a las escenas que proporcionen una funcionalidad que no requiera la vinculación de cuentas.
3. Haz clic en Guardar.

Cómo acceder a la información del perfil en tu backend

Después de que el usuario autorice tu acción para acceder a su perfil de Google, recibirás un token de ID de Google que contendrá la información del perfil de Google del usuario en cada solicitud posterior a tu acción.

Para acceder a la información del perfil del usuario, primero debes validar y decodificar el token de la siguiente manera:

1. Usa una biblioteca de decodificación de JWT para tu lenguaje a fin de decodificar el token y usa las claves públicas de Google (disponibles en formato JWK o PEM) a fin de verificar la firma del token.
2. Verifica que la entidad emisora del token (campo iss en el token decodificado) sea https://accounts.google.com y que el público (campo aud en el token decodificado) sea el valor del ID de cliente que Google emitió para tus acciones, que se asigna a tu proyecto en la Consola de Actions.

El siguiente es un ejemplo de un token decodificado:

{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

Si usas la biblioteca de entregas de Actions on Google para Node.js, se encarga de validar y decodificar el token, y te brinda acceso al contenido del perfil, como se muestra en los siguientes fragmentos de código.

...
const app = conversation({
  // REPLACE THE PLACEHOLDER WITH THE CLIENT_ID OF YOUR ACTIONS PROJECT
  clientId: CLIENT_ID,
});
...
// Invoked on successful completion of account linking flow, check if we need to
// create a Firebase user.
app.handle('linkAccount', async conv => {
  let payload = conv.headers.authorization;
  if (payload) {
  // Get UID for Firebase auth user using the email of the user
    const email = payload.email;
    if (!conv.user.params.uid && email) {
      try {
        conv.user.params.uid = (await auth.getUserByEmail(email)).uid;
      } catch (e) {
        if (e.code !== 'auth/user-not-found') {
          throw e;
        }
        // If the user is not found, create a new Firebase auth user
        // using the email obtained from Google Assistant
        conv.user.params.uid = (await auth.createUser({email})).uid;
      }
    }
  }
});

Controlar solicitudes de acceso a datos

Para manejar la solicitud de acceso a los datos, solo debes verificar que el usuario que haya declarado el token de ID de Google ya esté en tu base de datos. En el siguiente fragmento de código, se muestra un ejemplo de cómo verificar si ya existen pedidos para un usuario en una base de datos de Firestore:

...
app.handle('Place_Order', async conv => {
  const order = conv.session.params.order;
  const userDoc = dbs.user.doc(conv.user.params.uid);
  const orderHistory = userDoc.collection("orderHistory");
  if (orderHistory) {
    // Order history exists, so the user already placed an order.
    // Update counter for order type.
    await orderHistory.doc(order).update({ count: admin.firestore.FieldValue.increment(1)});
  } else {
    // First order they place
    await orderHistory.doc(order).set({ option: order, count: 1});
    options.forEach(opt => {
      if (opt != order) {
        orderHistory.doc(opt).set({ option: opt, count: 0});
      }
    });
  }
  return conv.add(`Your ${order} has been placed. ` +
      'Thanks for using Boba Bonanza, see you soon!');
});