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 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 una herramienta externos y los usen desde Chat.

Usa Card Builder para diseñar y obtener una vista previa de las interfaces de usuario y mensajería para 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 para tu app de Chat

Para admitir la página principal de la app, debes configurar tu app de Chat para que reciba APP_HOME eventos de interacción, 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, haz clic en el menú > APIs y servicios > APIs y servicios habilitados > API de Google Chat > Configuración. Ir a la configuración de la API de Chat
  2. En Funciones interactivas, ve a la sección Funcionalidad y selecciona Admitir la página principal de la app.
  3. Si tu app de Chat usa un servicio HTTP, ve a Configuración de conexión y especifica un extremo para el URL de la página principal de la app field. Puedes usar la misma URL que especificaste en el campo URL del extremo HTTP.
  4. Haz clic en Guardar.

Crea una tarjeta de página principal de la app

Cuando un usuario abre la página principal de la app, tu app de Chat debe controlar el APP_HOME evento de interacción mostrando una instancia de RenderActions con pushCard navegación y una 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 inicial de la página principal de la app que muestra 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 muestra una tarjeta actualizada que muestra la hora en que se creó la tarjeta actualizada.

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 que se llama después de todos los eventos de interacción APP_HOME:

En este ejemplo, se envía un mensaje de tarjeta mostrando el JSON de la 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"
      }}
    }]}}
  ]}]};
}

Responde a las interacciones de 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 mostrando una instancia de RenderActions con updateCard navegación. Para obtener más información sobre el manejo de widgets interactivos, consulta Procesa 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_CLICKEDactiva 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 mostrando el JSON de la 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: Un diálogo que le solicita a un 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 mostrando renderActions con updateCard navegación que contenga un Card objeto. 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 código de muestra, se usa CLOSE_DIALOG para cerrar un diálogo y volver a la tarjeta de la página 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 obtener información sobre cómo crear diálogos secuenciales, consulta Abre diálogos y responde a ellos.