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 los mensajes directos con una app de chat.

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

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

Abre el Creador de tarjetas

Requisitos previos

Node.js

Una app de Google Chat habilitada para funciones interactivas. Si quieres 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 una 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 Si quieres 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 que reciba 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 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 para configurar 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 página principal de la app, tu app de Chat debe controlar el evento de interacción APP_HOME mostrando una instancia de RenderActions con navegación pushCard y 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 app principal 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ó.

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 APP_HOME:

En este ejemplo, se muestra el JSON de la tarjeta para enviar un mensaje 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"
      }}
    }]}}
  ]}]};
}

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, la app de Chat debe controlar los eventos de interacción relacionados y mostrar una instancia de RenderActions con la navegación updateCard. Para obtener más información sobre cómo controlar 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 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 el JSON de la tarjeta para enviar un mensaje 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()
  }]}}};
}

Cómo 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 mostrando renderActions con la navegación updateCard que contiene un objeto Card. En el siguiente ejemplo, una app de Chat responde a un clic en un botón desde la tarjeta de la página principal de una 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 la tarjeta principal inicial de la app de Chat.
  • CLOSE_DIALOG_AND_EXECUTE: Cierra el diálogo y actualiza la tarjeta principal de la app.

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 obtener información sobre cómo compilar diálogos secuenciales, consulta Cómo abrir y responder diálogos.