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

En esta página, se explica cómo compilar una página principal para los mensajes directos con tu app de Google Chat. Una página principal, a la que se hace referencia como 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 página principal de la app con dos widgets.
Figura 1: Ejemplo de una página principal que aparece en los mensajes directos con una app de chat.

Puedes usar la página principal de la app para compartir sugerencias para interactuar con la app de Chat o permitir que los usuarios accedan a un servicio o herramienta externos y los usen desde Chat.

Usa Card Builder para diseñar y obtener una vista previa de las interfaces de usuario y los mensajes de las apps de Chat:

Abrir Card Builder

Requisitos previos

Node.js

Una app de Google Chat que recibe eventos de interacción y responde a ellos. 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 que recibe eventos de interacción y responde a ellos. Para crear una app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.

Java

Una app de Google Chat que recibe eventos de interacción y responde a ellos. 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 que recibe eventos de interacción y responde a ellos. Para crear una app de Chat interactiva en Apps Script, completa esta guía de inicio rápido.

Configura la página principal de la app de Chat

Para admitir la página principal de la app, debes configurar tu app de Chat para que reciba eventos de interacción de 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 con la app de Chat.

Para actualizar la 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 y selecciona Admitir la página principal de la app.

  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 de la página 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 la app

Cuando un usuario abre la página 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 una experiencia interactiva, la tarjeta puede contener widgets interactivos, como botones o entradas de 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 de página principal inicial que indica la hora en que se creó la tarjeta y un botón. Cuando un usuario hace clic en el botón, la app de Chat devuelve 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
@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() {
  return new GoogleAppsCardV1Card()
    .setSections(List.of(new GoogleAppsCardV1Section()
      .setWidgets(List.of(
        new GoogleAppsCardV1Widget()
          .setTextParagraph(new GoogleAppsCardV1TextParagraph()
            .setText("Here is the app home 🏠 It's " + new Date())),
        new GoogleAppsCardV1Widget()
          .setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
            .setText("Update app home")
            .setOnClick(new GoogleAppsCardV1OnClick()
              .setAction(new GoogleAppsCardV1Action()
                .setFunction("updateAppHome"))))))))));
}

Apps Script

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

En este ejemplo, se envía un mensaje de tarjeta devolviendo JSON de tarjeta. También puedes usar el 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"
      }}
    }]}}
  ]}]};
}

Cómo responder a las interacciones en la página principal de la app

Si la tarjeta inicial de la página principal de la 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 control de widgets interactivos, consulta Cómo procesar la información que ingresan los usuarios.

En el ejemplo anterior, la tarjeta inicial de la página principal 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 de la página 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 envía un mensaje de tarjeta devolviendo JSON de tarjeta. También puedes usar el 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

Tu app de Chat también puede responder a las interacciones en la página principal de la app abriendo diálogos.

Un diálogo con una variedad de widgets diferentes.
Figura 3: 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 devolviendo renderActions con una navegación updateCard que contenga un objeto Card. En el siguiente ejemplo, una app de Chat responde a un clic en un botón de una tarjeta de la página principal 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 vuelve a la tarjeta inicial de la página principal de la app de Chat.
  • CLOSE_DIALOG_AND_EXECUTE: Cierra el diálogo y actualiza la tarjeta de la página principal de la app.

En el siguiente ejemplo 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 crear diálogos secuenciales, consulta Cómo abrir diálogos y responder a ellos.