As páginas iniciais são um novo recurso de complementos do Google Workspace que permite definir um ou mais cards não contextuais. Cards não contextuais são usados para mostrar uma interface do usuário quando o usuário está fora de um contexto específico, como quando ele 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 servem como ponto de partida para quando um usuário abre o complemento pela primeira vez e são úteis para ensinar novos usuários a interagir com ele.
Você pode definir 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.
É possível ter várias páginas iniciais, uma para cada aplicativo host estendido pelo complemento. Também é possível definir uma única página inicial padrão comum usada em hosts em que você não especificou uma página inicial personalizada.
A página inicial do complemento será exibida quando uma das seguintes condições for atendida:
- Quando o complemento é aberto pela primeira vez no host (após a autorização).
- Quando o usuário alterna de um contexto contextual para um não contextual enquanto o complemento está aberto. Por exemplo, da edição de um evento do Google Agenda para a Agenda principal.
- Quando o usuário clica no botão "Voltar" várias vezes para retirar todos os outros cards das pilhas internas (em inglês).
- Quando uma interação da IU em um card não contextual resulta em uma
chamada
Navigation.popToRoot()
.
Criar uma página inicial não é obrigatório, mas altamente recomendado. Se você não definir nenhum, um cartão genérico contendo o nome do seu 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 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 cartões de complemento da página inicial. Essa é a função de gatilho da página inicial. Essa função precisa criar e retornar uma matriz de objetosCard
que compõem a IU da página inicial. Se mais de um cartão for retornado, o aplicativo host mostrará os cabeçalhos dos cards em uma lista que o usuário pode selecionar (consulte Como devolver vários cartões).enabled
: se os cards de página inicial precisam ser ativados para esse escopo. Esse campo é opcional, e o padrão étrue
. Definir esse valor comofalse
faz com que os cards de página inicial sejam desativados para todos os hosts, a menos que sejam substituídos por esse host. Veja abaixo.
Além da configuração comum, também há
modificações de estrutura idêntica por host disponíveis na configuração de cada 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 mostrada 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 acionamento de complementos
são executadas (se houver) para criar uma IU de página inicial para diferentes configurações
de manifesto:
Objetos de evento da página inicial
Quando chamada, a função de acionamento 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 de página inicial não incluem informações do widget ou contextuais. As informações transmitidas são limitadas aos seguintes campos do objeto de evento comum:
commonEventObject.clientPlatform
commonEventObject.hostApp
commonEventObject.userLocale
ecommonEventObject.userTimezone
(mas consulte Como acessar a localidade e o fuso horário do usuário para informações de restrição).
Consulte Objeto de evento para mais detalhes.
Outros cards não contextuais
A IU 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" em que o usuário pode ajustar as configurações do complemento. Na maioria dos casos, essas configurações são independentes do contexto e, portanto, não contextuais.
Cards não contextuais são criados como qualquer outro. A única diferença é qual ação ou evento gera e mostra o card. Consulte Métodos de navegação para ver detalhes sobre como criar transições entre cards.