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 fornecer um 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). Se o complemento estender o Google Chat, a página inicial dele vai aparecer na guia Página inicial de uma mensagem direta individual com o app Chat e será configurada no console do Google Cloud em vez do manifesto (consulte Configurar uma página inicial para o Chat).

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) ou quando um usuário abre a guia Início em uma mensagem direta individual com seu app do Chat.
  • 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 de 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 o framework de complementos do Google Workspace invoca para renderizar os cards de complementos da página inicial. Essa função é o gatilho 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 cartão 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 devem 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 para o 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 comum buildHomePage 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

Configurar uma página inicial para o Chat

Ao contrário de outros aplicativos host do Google Workspace, os complementos que estendem o Chat não mostram uma página inicial no painel de acesso rápido à direita e não usam addOns.common.homepageTrigger no manifesto. Em vez disso, o Chat mostra sua página inicial como um card na guia Início de uma mensagem direta individual com o app do Chat.

Para ativar e configurar um gatilho da página inicial do app para seu complemento do Chat no console do Google Cloud:

  1. No console do Google Cloud, acesse Menu > APIs e serviços > APIs e serviços ativados > API Google Chat > Configuração.

    Acessar a configuração da API Google Chat

  2. Em Recursos interativos, verifique se a opção Ativar recursos interativos está ativada e marque a caixa de seleção Suporte à página inicial do app.

  3. Em Configurações de conexão > Acionadores, especifique o gerenciador da página inicial do app no campo Página inicial do app com base na arquitetura do complemento:

    • HTTP: insira o URL do endpoint HTTPS que processa as solicitações da página inicial do app ou deixe em branco para que o URL do endpoint HTTP comum receba todos os eventos.
    • Google Apps Script: insira o nome da função de callback do Google Apps Script que cria e retorna o card da página inicial (o padrão é onAppHome).

  4. Clique em Salvar.

Quando um usuário abre a guia Início de uma mensagem direta com seu app do Chat, o Chat envia um evento de acionamento da página inicial do app para seu endpoint ou função. Para renderizar a página inicial, retorne um objeto RenderActions com uma ação de navegação pushCard ou use updateCard ao atualizar a página inicial em resposta ao clique em um botão no card da página inicial:

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Script

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

Para mais detalhes sobre como processar acionadores do Chat e retornar ações, consulte Receber e responder a interações do usuário.

Objetos de eventos da página inicial

Quando chamada, a função de acionamento da página inicial (runFunction) ou o endpoint da página inicial do app descrito 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 incluem os seguintes campos do objeto de evento comum:

No Chat, o objeto de evento da página inicial do app também inclui o campo chat com informações sobre o usuário e o tempo de interação:

  • chat.user: o usuário do Chat que abriu a guia Início.
  • chat.eventTime: o carimbo de data/hora em que o usuário abriu a guia Início.

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 (geralmente 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.