Páginas iniciais

As páginas iniciais são um novo recurso de complementos do Google Workspace que permite definir um ou mais cards não contextuais. Os cartões não contextuais são usados para exibir uma interface do usuário quando o usuário está fora de um contexto específico, como quando o usuário está visualizando a caixa de entrada do Gmail, mas não abriu uma mensagem ou um rascunho.

As páginas iniciais permitem mostrar conteúdo não contextual, assim como os apps do Google no painel lateral de acesso rápido (Keep, Agenda e Tarefas). As páginas iniciais também oferecem um ponto de partida inicial para o primeiro acesso do usuário ao complemento e são úteis para ensinar os novos usuários a interagir com ele.

Para definir uma página inicial para seu complemento, especifique-a no manifesto do projeto e implemente uma ou mais funções homepageTrigger. Consulte Configuração da página inicial.

É possível ter várias páginas iniciais, uma para cada aplicativo host que o complemento expõe. Você também pode definir uma única página inicial comum comum que seja usada em hosts em que você não especificou uma página inicial personalizada.

A página inicial dos complementos é exibida quando uma das seguintes condições é atendida:

  • Quando o complemento é aberto pela primeira vez no host (após a autorização).
  • Quando o usuário muda de um contexto contextual para um contexto não contextual, enquanto o complemento está aberto. Por exemplo, da edição de um evento da agenda para a agenda principal.
  • Quando o usuário clicar no botão "Voltar" o suficiente para remover todos os outros cartões das pilhas internas.
  • Quando uma interação da IU em um card não contextual resulta em uma chamada Navigation.popToRoot().

Projetar uma página inicial não é obrigatório, mas altamente recomendado. Se você não o definir, um cartão genérico que contenha o nome do complemento será usado sempre que um usuário navegaria para a página inicial.

Configuração da página inicial

Os complementos do Google Workspace usam o campo addOns.common.homepageTrigger para configurar o conteúdo do complemento padrão da página inicial (não contextual) para todos os aplicativos host no manifesto do complemento:

    {
      // ...
      "addOns": {
        // ...
        "common": {
          // ...
          "homepageTrigger": {
            "runFunction": "myFunction",
            "enabled": true
          }
        }
      }
    }
  • runFunction: o nome da função do Apps Script que o framework de complementos do Google Workspace invoca para renderizar os cards de complementos da página inicial. Essa é a função de gatilho da página inicial. Essa função precisa criar e retornar uma matriz de objetos Card que compõem a IU da página inicial. Se mais de um cartão for retornado, o aplicativo host exibirá os cabeçalhos de cartões em uma lista que o usuário pode selecionar. Consulte Como retornar vários cartões.

  • enabled: indica se os cards da página inicial precisam ser ativados para este escopo. Este campo é opcional, e o padrão é true. Definir como false faz com que os cards da página inicial sejam desativados para todos os hosts (a menos que sejam substituídos para esse host. Veja abaixo).

Além da configuração comum, também há modificações por host estruturadas de maneira idêntica disponíveis em cada configuração do aplicativo host, em addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger e assim por diante:

    {
      ...
      "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 }
        },
        ...
      }
    }

Isso é equivalente ao seguinte trecho do manifesto:

    {
      ...
      "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": { /* ... */ },
        ...
      }
    }

Nenhuma das seções homepageTrigger é obrigatória. No entanto, a IU exibida para um complemento em qualquer produto host depende da presença do campo de manifesto correspondente e da existência de um homepageTrigger associado. O exemplo a seguir mostra quais funções de gatilho de complementos são executadas (se houver) para criar uma IU da página inicial para diferentes configurações de manifestos:

Fluxo da página inicial

Objetos de evento da página inicial

Quando chamada, a função de gatilho da página inicial (runFunction) descrita acima recebe um objeto de evento que contém dados do contexto de invocação.

Os objetos de evento da página inicial não incluem informações de widget ou contextuais. As informações transmitidas são limitadas aos seguintes campos de objeto de evento comum:

Consulte o objeto de evento para mais detalhes.

Outros cards não contextuais

A IU dos complementos pode conter outros cards não contextuais que não são páginas iniciais. Por exemplo, sua página inicial pode ter um botão que abre um card de "Configurações" em que o usuário pode ajustar as configurações do complemento. Na maioria dos casos, essas configurações serão independentes do contexto e, portanto, não contextuais.

Os cards não contextuais são criados como qualquer outro cartão. A única diferença é que ação ou evento gera e exibe o card. Consulte Métodos de navegação para ver detalhes sobre como criar transições entre cards.