Páginas de inicio

Las páginas principales son una nueva función de complementos de Google Workspace que permite definir una o más tarjetas no contextuales. Las tarjetas no contextuales se usan para mostrar una interfaz de usuario cuando el usuario se encuentra fuera de un contexto específico, por ejemplo, cuando mira su carpeta Recibidos de Gmail, pero no abrió un mensaje o borrador.

Las páginas principales te permiten mostrar contenido no contextual, al igual que las apps de Google en el panel lateral de acceso rápido (Keep, Calendario y Tasks). Las páginas principales también pueden ser un punto de partida inicial para cuando un usuario abra tu complemento y son útiles para enseñarles a los usuarios nuevos cómo interactuar con él.

Puedes definir una página principal para tu complemento si la especificas en el manifiesto de tu proyecto y si implementas una o más funciones homepageTrigger (consulta Configuración de la página principal).

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

La página principal del complemento se muestra cuando se cumple una de las siguientes condiciones:

• Cuando el complemento se abre por primera vez en el host (después de la autorización).
• Cuando el usuario pasa de un contexto contextual a un contexto no contextual mientras está abierto el complemento 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 lo suficiente como para mostrarse todas las demás tarjetas de las pilas internas.
• Cuando una interacción de la IU en una tarjeta no contextual genera una llamada Navigation.popToRoot().

No es obligatorio diseñar una página principal, pero es muy recomendable. Si no defines una, se usará una tarjeta genérica con el nombre del complemento cada vez que un usuario navegue de otra manera a ella.

Configuración de la página principal

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

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

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

• enabled: Indica si se deben habilitar las tarjetas de la página principal para este alcance. Este campo es opcional y su valor predeterminado es true. Si se configura en false, se inhabilitan las tarjetas de la página principal para todos los hosts (a menos que se anulen en ese host; consulta a continuación).

Nota: 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 está inhabilitado para Gmail y no mostrará una página principal (ni ninguna otra función en ese host).

Además de la configuración común, también hay anulaciones por host estructuradas de forma idéntica disponibles en la configuración de cada aplicación de host, en addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger, etcétera:

    {
      ...
      "addOns": {
        ...
        "common": {
          // By default, call 'buildHomePage' to render homepage content
          // in all hosts. Since calendar.homepageTrigger below overrides
          // this in Calendar and Drive and the homepageTrigger is disabled
          // for Gmail, this homepage function never executes.
          "homepageTrigger": { "runFunction": "buildHomePage" }
        },
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "buildDriveHomepage" }
        }
        "gmail": {
          // Disable homepage add-on content in Gmail.
          "homepageTrigger": { "enabled": false }
        },
        ...
      }
    }

Ten en cuenta que esto equivale al siguiente extracto de manifiesto:

    {
      ...
      "addOns": {
        ...
        "common": { /* ... */ }, // Omitted a default homepageTrigger specification.
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "myCalendarFunction" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "myDriveFunction" }
        }
        "gmail": { /* ... */ },
        ...
      }
    }

No se requiere ninguna de las secciones de homepageTrigger. Sin embargo, la IU que se muestra para un complemento en cualquier producto de host depende de la presencia del campo de manifiesto correspondiente y de si hay un homepageTrigger asociado. En el siguiente ejemplo, se muestra qué funciones del complemento se ejecutan (si las hay) a fin de crear una IU en la página principal para diferentes configuraciones del manifiesto:

Objetos de eventos de la página principal

Cuando se la llama, la función activadora de la página principal (runFunction) descrita anteriormente pasa un objeto de evento que contiene datos del contexto de invocación.

Los objetos de eventos de la página principal no incluyen widgets ni información contextual. La información que se pasa se limita a los siguientes campos de objetos de eventos comunes:

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale y commonEventObject.userTimezone (pero consulta Cómo acceder a la configuración regional y la zona horaria del usuario para obtener información sobre las restricciones).

Consulta Objeto de evento para obtener más detalles.

Otras tarjetas no contextuales

La IU del complemento puede contener tarjetas no contextuales adicionales que no son páginas de inicio. Por ejemplo, es posible que tu página principal tenga un botón que abra una tarjeta "Configuración" en la que el usuario puede ajustar la configuración del complemento (esta configuración, en la mayoría de los casos, sería independiente del contexto y, por lo tanto, no contextual).

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.