Páginas de inicio

Las páginas principales son una función de los complementos de Google Workspace que permite definir una o más tarjetas no contextuales. Las tarjetas no contextuales muestran una interfaz de usuario cuando el usuario está fuera de un contexto específico, por ejemplo, cuando ve su carpeta Recibidos de Gmail sin un mensaje o borrador abierto.

Las páginas principales te permiten mostrar contenido no contextual, similar a las apps de Google en el panel lateral de acceso rápido (Google Keep, Calendario de Google y Google Tasks). Las páginas principales también pueden proporcionar un punto de partida inicial cuando un usuario abre tu complemento por primera vez y son útiles para enseñar a los usuarios nuevos a interactuar con él.

Define una página principal para tu complemento especificándola en el manifiesto del proyecto y, luego, implementa una o más funciones homepageTrigger (consulta Configuración de la página principal). Si tu complemento extiende Google Chat, su página principal aparece en la pestaña Página principal de un mensaje directo 1:1 con la app de Chat y se configura en la consola de Google Cloud en lugar del manifiesto (consulta Cómo configurar una página principal para Chat).

Puedes tener varias páginas principales, una para cada aplicación host que extienda tu complemento. También puedes definir una sola página principal predeterminada común que se use en los hosts en los que no especificaste una página principal personalizada.

La página principal de tu complemento se muestra en los siguientes casos:

  • Cuando se abre el complemento por primera vez en el host (después de la autorización) o cuando un usuario abre la pestaña Página principal en un mensaje directo 1:1 con tu app de Chat en Chat.
  • Cuando el usuario cambia de un contexto contextual a uno no contextual mientras el complemento está abierto. Por ejemplo, desde la edición de un evento del Calendario hasta el Calendario principal.
  • Cuando el usuario hace clic en el botón Atrás las veces suficientes para quitar todas las demás tarjetas de las pilas internas.
  • Cuando una interacción de la IU en una tarjeta no contextual genera una llamada a Navigation.popToRoot

Se recomienda diseñar una página principal. Si no defines ninguna, se usará una tarjeta genérica que contiene el nombre de tu complemento cada vez que un usuario navegue a la página principal.

Configuración de la página principal

Los complementos de Google Workspace usan el campo addOns.common.homepageTrigger para configurar el contenido predeterminado de la página principal (no contextual) del complemento para las aplicaciones host en el manifiesto del complemento:

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

  • runFunction: Es el nombre de la función de Google Apps Script que invoca el framework de complementos de Google Workspace para renderizar las tarjetas de complementos de la página principal. Esta función es la función de activación de la página principal. Esta función debe compilar y devolver un array de objetos Card que componen la IU de la página principal. Si se devuelve más de una tarjeta, la aplicación host muestra los encabezados de las tarjetas en una lista de la que el usuario puede seleccionar (consulta Cómo devolver varias tarjetas).

  • enabled: Indica si se deben habilitar las tarjetas de la página principal para este alcance. Este campo es opcional y el valor predeterminado es true. Si se establece en false, se inhabilitan las tarjetas de la página principal para todos los hosts (a menos que se anule para ese host; consulta la configuración específica del host).

Para que un host use la página principal común, tanto addOns.common.homepageTrigger como el recurso de nivel superior del host deben estar presentes en el manifiesto del complemento. Por ejemplo, si addOns.gmail no está presente en el manifiesto, el complemento se inhabilitará para Gmail y no mostrará una página principal ni ninguna otra funcionalidad en ese host.

Además de la configuración común, las anulaciones por host con estructura idéntica están disponibles en la configuración de cada aplicación host, en addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger y otros activadores específicos del host.

En el siguiente ejemplo, se muestra un manifiesto en el que se define un activador de página principal común, pero se anula con funciones personalizadas para Calendar y Drive, y se inhabilita para Gmail. En esta configuración, la función buildHomePage común nunca se ejecuta porque se anula o el host está inhabilitado.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

El siguiente fragmento del manifiesto es equivalente al ejemplo anterior, aunque se omiten la configuración predeterminada de homepageTrigger y la configuración de Gmail:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

Ninguna de las secciones homepageTrigger es obligatoria. La IU que se muestra para un complemento en un producto host depende de la presencia del campo de manifiesto correspondiente y de si hay un homepageTrigger asociado. En el siguiente ejemplo, se muestran las diferentes funciones de activación de complementos que se ejecutan para crear una IU de página principal para diferentes configuraciones del manifiesto:

Diagrama que muestra el flujo de ejecución de la función de activación de la página principal del complemento

Cómo configurar una página principal para Chat

A diferencia de otras aplicaciones host de Google Workspace, los complementos que extienden Chat no muestran una página principal en el panel de acceso rápido del lado derecho ni usan addOns.common.homepageTrigger en el manifiesto. En cambio, Chat muestra tu página principal como una tarjeta en la pestaña Página principal de un mensaje directo 1:1 con la app de Chat.

Para habilitar y configurar un activador de página principal de la app para tu complemento de Chat en la consola de Google Cloud, haz lo siguiente:

  1. En la consola de Google Cloud, ve a Menú > APIs y servicios > APIs y servicios habilitados > API de Google Chat > Configuración.

    Ir a la configuración de la API de Google Chat

  2. En Funciones interactivas, asegúrate de que Habilitar funciones interactivas esté activado y, luego, selecciona la casilla de verificación Admitir la página principal de la app.

  3. En Connection settings > Triggers, especifica el controlador de la página principal de la app en el campo App home según la arquitectura de tu complemento:

    • HTTP: Ingresa la URL del extremo HTTPS que controla las solicitudes de la página principal de la app (o déjala en blanco para que la URL del extremo HTTP común reciba todos los eventos).
    • Google Apps Script: Ingresa el nombre de la función de devolución de llamada de Google Apps Script que compila y devuelve la tarjeta de la página principal (el valor predeterminado es onAppHome).

  4. Haz clic en Guardar.

Cuando un usuario abre la pestaña Página principal de un mensaje directo con tu app de Chat, Chat envía un evento de activación de página principal de la app a tu extremo o función. Para renderizar la página principal, devuelve un objeto RenderActions con una acción de navegación pushCard (o usa updateCard cuando actualices la página principal en respuesta a un clic en un botón de la tarjeta de la página principal):

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Script

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

Para obtener más detalles sobre el control de los activadores de chat y las acciones de devolución, consulta Cómo recibir y responder a las interacciones del usuario.

Objetos de eventos de la página principal

Cuando se llama, la función de activación de la página principal (runFunction) o el extremo de la página principal de la app que se describió anteriormente reciben un objeto de evento que contiene datos del contexto de invocación.

Los objetos de eventos de la página principal no incluyen información contextual ni de widgets. La información que se pasa incluye los siguientes campos del objeto de evento común:

En Chat, el objeto del evento de la página principal de la app también incluye el campo chat con información sobre el usuario y el momento de la interacción:

  • chat.user: Es el usuario de Chat que abrió la pestaña Inicio.
  • chat.eventTime: Es la marca de tiempo en la que el usuario abrió la pestaña Principal.

Consulta Objeto Event para obtener más detalles.

Otras tarjetas no contextuales

La IU del complemento puede contener tarjetas adicionales no contextuales que no sean páginas principales. Por ejemplo, tu página principal podría tener un botón que abra una tarjeta de "Configuración" para ajustar la configuración de complementos (esta configuración suele ser independiente del contexto).

Las tarjetas no contextuales se crean como cualquier otra tarjeta. La única diferencia es qué acción o evento genera y muestra la tarjeta. Consulta Métodos de navegación para obtener detalles sobre cómo crear transiciones entre tarjetas.