Páginas iniciais

As páginas iniciais são um recurso de 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 rascunho aberto.

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

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

É possível ter várias páginas iniciais, uma para cada aplicativo host que o 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 Navigation.popToRoot chamada.

Recomendamos criar uma página inicial. Se você não definir nenhuma, um card genérico contendo o nome do complemento será usado sempre que um usuário navegar até 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 complemento manifesto:

{
  "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 função é a função de acionador da página inicial. Essa função precisa criar e retornar uma matriz de Card objetos que compõem a interface da página inicial. Se mais de um card for retornado, o aplicativo host mostrará os cabeçalhos dos cards em uma lista que o usuário pode selecionar (consulte Retornar vários cards).

  • enabled: indica se os cards da página inicial precisam ser ativados para esse escopo. Esse campo é opcional e o padrão é true. A definição desse campo 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; consulte a configuração específica do host).

Para que um host use a página inicial comum, ambos addOns.common.homepageTrigger e 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 para o Gmail e não 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 acionadores específicos do host.

O exemplo a seguir mostra um manifesto em que um acionador de página inicial comum é definido, mas substituído por funções personalizadas para a 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 acionador 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 acionador 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 de objeto de evento comuns:

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, a página inicial pode ter um botão que abre um card "Configurações" para ajustar as configurações do complemento. 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 é qual ação ou evento gera e mostra o card. Consulte Métodos de navegação para detalhes sobre como criar transições entre cards.