Crea una página principal para una app de Google Chat

En esta página, se explica cómo crear una página principal para los mensajes directos con tu app de Google Chat. Una página principal, denominada página principal de la app en la API de Google Chat, es una interfaz de tarjeta personalizable que aparece en la pestaña Página principal de los espacios de mensajes directos entre un usuario y una app de Chat.

Tarjeta de la pantalla principal de la app con dos widgets.
Figura 1: Ejemplo de una página principal que aparece en mensajes directos con una app de Chat.

Puedes usar la página principal de la app para compartir sugerencias sobre cómo interactuar con el Chat o permitir que los usuarios accedan a una un servicio o una herramienta externos de Chat.

Usa Card Builder para diseñar y obtener una vista previa de las interfaces de usuario y mensajería para apps de Chat:

Abre el Creador de tarjetas

Requisitos previos

Node.js

Una app de Google Chat habilitada para funciones interactivas. Para crear una app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.

Python

Una app de Google Chat habilitada para funciones interactivas Para crear un app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.

Java

Una app de Google Chat habilitada para funciones interactivas. Para crear una app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.

Apps Script

Una app de Google Chat habilitada para funciones interactivas Para crear una app de Chat interactiva en Apps Script, completa esta guía de inicio rápido.

Configura la página principal de tu app de Chat

Para admitir la página principal de la app, debes configurar tu app de Chat para recibir Eventos de interacción APP_HOME, Tu app de Chat recibe este evento cada vez que un usuario hace clic en la pestaña Página principal desde un mensaje directo que contiene App de Chat

Para actualizar los parámetros de configuración en la consola de Google Cloud, haz lo siguiente:

  1. En la consola de Google Cloud, ve a Menú > Más productos > Google Workspace > Biblioteca de productos > API de Google Chat.

    Ir a la API de Google Chat

  2. Haz clic en Administrar y, luego, en la pestaña Configuración.

  3. En Funciones interactivas, ve a la sección Funcionalidad para Configura la página principal de la app:

    1. Selecciona la casilla de verificación Recibir mensajes 1:1.
    2. Selecciona la casilla de verificación Support App Home.

  4. Si tu app de Chat usa un servicio HTTP, ve a Configuración de conexión y especifica un extremo para el campo URL principal de la app. Puedes usar la misma URL que especificaste en el campo URL del extremo HTTP.

  5. Haz clic en Guardar.

Cómo compilar una tarjeta de la página principal de una app

Cuando un usuario abre la pantalla principal de la app, tu app de Chat debe controlar el evento de interacción APP_HOME devolviendo una instancia de RenderActions con navegación pushCard y un Card. Para crear un experiencia interactiva, la tarjeta puede contener widgets interactivos, como botones o texto que la app de Chat puede procesar y responder con tarjetas adicionales o un diálogo.

En el siguiente ejemplo, la app de Chat muestra una tarjeta inicial de la app principal que muestra la hora en que se creó la tarjeta un botón. Cuando un usuario hace clic en el botón, la app de Chat muestra una tarjeta actualizada que muestra la hora en que se creó.

Node.js

node/app-home/index.js
app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Python

python/app-home/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
/**
 * Process Google Chat events
 *
 * @param event Event from chat.
 * @return GenericJson
 * @throws Exception
 */
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
  textParagraph.setText("Here is the app home 🏠 It's " + new Date());

  GoogleAppsCardV1Widget textParagraphWidget = new GoogleAppsCardV1Widget();
  textParagraphWidget.setTextParagraph(textParagraph);

  GoogleAppsCardV1Action action = new GoogleAppsCardV1Action();
  action.setFunction("updateAppHome");

  GoogleAppsCardV1OnClick onClick = new GoogleAppsCardV1OnClick();
  onClick.setAction(action);

  GoogleAppsCardV1Button button = new GoogleAppsCardV1Button();
  button.setText("Update app home");
  button.setOnClick(onClick);

  GoogleAppsCardV1ButtonList buttonList = new GoogleAppsCardV1ButtonList();
  buttonList.setButtons(List.of(button));

  GoogleAppsCardV1Widget buttonListWidget = new GoogleAppsCardV1Widget();
  buttonListWidget.setButtonList(buttonList);

  GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
  section.setWidgets(List.of(textParagraphWidget, buttonListWidget));

  GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
  card.setSections(List.of(section));

  return card;
}

Apps Script

Implementa la función onAppHome a la que se llama después de todos los APP_HOME. de interacción:

En este ejemplo, se muestra un mensaje de tarjeta mediante la devolución de JSON de la tarjeta. También puedes usar Servicio de tarjetas de Apps Script.

apps-script/app-home/app-home.gs
/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Responde a las interacciones en la pantalla principal de la app

Si la tarjeta principal inicial de tu app contiene widgets interactivos, como botones o entradas de selección, tu app de Chat debe controlar los eventos de interacción relacionados devolviendo una instancia de RenderActions con navegación updateCard. Para obtener más información sobre el manejo de widgets, consulta Procesa la información que ingresan los usuarios.

En el ejemplo anterior, la tarjeta principal inicial de la app incluía un botón. Cada vez que un usuario hace clic en el botón, un evento de interacción CARD_CLICKED activa la función updateAppHome para actualizar la tarjeta principal de la app, como se muestra en el siguiente código:

Node.js

node/app-home/index.js
// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Python

python/app-home/main.py
def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

Apps Script

En este ejemplo, se muestra un mensaje de tarjeta mediante la devolución de JSON de la tarjeta. También puedes usar Servicio de tarjetas de Apps Script.

apps-script/app-home/app-home.gs
/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}

Abrir diálogos

La app de Chat también puede responder a interacciones en la pantalla principal de la app abriendo diálogos.

Un diálogo con una variedad de widgets diferentes.
Figura 3: Un diálogo que le solicita al usuario que agregue un contacto.

Para abrir un diálogo desde la página principal de la app, procesa el evento de interacción relacionado: Se muestra renderActions con la navegación updateCard que contiene un Card . En el siguiente ejemplo, una app de Chat responde a un clic en un botón de una tarjeta de inicio de la app procesando el evento de interacción CARD_CLICKED y abriendo un diálogo:

{ renderActions: { action: { navigations: [{ updateCard: { sections: [{
  header: "Add new contact",
  widgets: [{ "textInput": {
    label: "Name",
    type: "SINGLE_LINE",
    name: "contactName"
  }}, { textInput: {
    label: "Address",
    type: "MULTIPLE_LINE",
    name: "address"
  }}, { decoratedText: {
    text: "Add to favorites",
    switchControl: {
      controlType: "SWITCH",
      name: "saveFavorite"
    }
  }}, { decoratedText: {
    text: "Merge with existing contacts",
    switchControl: {
      controlType: "SWITCH",
      name: "mergeContact",
      selected: true
    }
  }}, { buttonList: { buttons: [{
    text: "Next",
    onClick: { action: { function: "openSequentialDialog" }}
  }]}}]
}]}}]}}}

Para cerrar un diálogo, procesa los siguientes eventos de interacción:

  • CLOSE_DIALOG: Cierra el diálogo y regresa a Tarjeta inicial de la app principal de la app de Chat.
  • CLOSE_DIALOG_AND_EXECUTE: Cierra el diálogo y actualiza la página principal de la app. tarjeta.

En la siguiente muestra de código, se usa CLOSE_DIALOG para cerrar un diálogo y volver a la tarjeta principal de la app:

{ renderActions: { action: {
  navigations: [{ endNavigation: { action: "CLOSE_DIALOG" }}]
}}}

Para recopilar información de los usuarios, también puedes crear diálogos secuenciales. Para aprender a compilar diálogos secuenciales, consulta Cómo abrir y responder diálogos.