Páginas iniciais

As páginas iniciais são um recurso dos complementos do Google Workspace que permite definir um ou mais cards não contextuais. Os cards não contextuais mostram uma interface do usuário quando o usuário está fora de um contexto específico, como ao visualizar a caixa de entrada do Gmail sem uma mensagem ou um rascunho aberto.

As páginas iniciais permitem mostrar conteúdo não contextual, semelhante aos apps do Google no painel lateral de acesso rápido (Google Keep, Google Agenda e Google Tarefas). As páginas iniciais também podem servir como ponto de partida inicial quando um usuário abre seu complemento pela primeira vez e são úteis para ensinar novos usuários a interagir com ele.

Defina uma página inicial para seu complemento especificando-a no manifesto do projeto e implementando uma ou mais funções homepageTrigger (consulte Configuração da página inicial).

Você pode ter várias páginas iniciais, uma para cada aplicativo host que seu complemento estende. Também é possível definir uma única página inicial padrão comum que é usada em hosts em que você não especificou uma página inicial personalizada.

A página inicial do complemento é mostrada nestes casos:

  • 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 não contextual enquanto o complemento está aberto. Por exemplo, de editar um evento da Agenda para a Agenda principal.
  • Quando o usuário clica no botão "Voltar" vezes suficientes para remover todos os outros cards das pilhas internas.
  • Quando uma interação da interface em um card não contextual resulta em uma chamada Navigation.popToRoot.

Recomendamos criar uma página inicial. Se você não definir nenhum, um card genérico com o nome do complemento será usado sempre que um usuário acessar 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 padrão da página inicial (não contextual) para aplicativos host no manifesto do complemento:

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

  • runFunction: o nome da função do Google Apps Script que a estrutura de complementos do Google Workspace invoca para renderizar cards de complementos da página inicial. Essa é a função de acionamento da página inicial. Essa função precisa criar e retornar uma matriz de objetos Card que compõem a interface da página inicial. Se mais de um card for retornado, o aplicativo host vai mostrar os cabeçalhos em uma lista que o usuário pode selecionar em (consulte Retornar vários cards).

  • enabled: se os cards da página inicial precisam ser ativados para este escopo. Este campo é opcional e o padrão é true. Definir como false desativa os cards da página inicial para todos os hosts, a menos que seja substituído para esse host. Consulte a configuração específica do host.

Para que um host use a página inicial comum, tanto addOns.common.homepageTrigger quanto o recurso de nível superior do host precisam estar presentes no manifesto do complemento. Por exemplo, se addOns.gmail não estiver presente no manifesto, o complemento será desativado no Gmail e não vai mostrar uma página inicial ou outra funcionalidade nesse host.

Além da configuração comum, substituições por host com estrutura idêntica estão disponíveis na configuração de cada aplicativo host, em addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger e outros gatilhos específicos do host.

O exemplo a seguir mostra um manifesto em que um gatilho comum da página inicial é definido, mas substituído por funções personalizadas para o Google Agenda e o Drive, e desativado para o Gmail. Nessa configuração, a função buildHomePage comum nunca é executada porque é substituída ou o host está desativado.

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

O trecho de manifesto a seguir é equivalente ao exemplo anterior, mesmo que o homepageTrigger padrão e a configuração do Gmail sejam omitidos:

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

Nenhuma das seções homepageTrigger é obrigatória. A interface mostrada para um complemento em um produto host depende da presença do campo de manifesto correspondente e se há um homepageTrigger associado. O exemplo a seguir mostra quais funções de acionamento de complemento são executadas para criar uma interface da página inicial para diferentes configurações de manifesto:

Diagrama mostrando o fluxo de execução da função de acionamento da página inicial do complemento

Objetos de evento da página inicial

Quando chamada, a função de acionamento da página inicial (runFunction) descrita anteriormente 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 contextuais ou de widget. As informações transmitidas são limitadas aos seguintes campos do objeto de evento comum:

Consulte Objeto de evento para mais detalhes.

Outros cards não contextuais

A interface do complemento 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 "Configurações" para ajustar as configurações de complementos (essas configurações geralmente são independentes do contexto).

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