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

Esta página explica cómo crear una página de inicio para tu App de Google Chat La página principal de la app es una interfaz de tarjetas personalizable que envía una app de Chat a un usuario cuando este abre un mensaje con la app de Chat.

Tarjeta de la página principal de la app con dos widgets.

Por ejemplo, puedes configurar el mensaje de la tarjeta de la página principal de la app para incluir sugerencias para interactuar con App de Chat con comandos de barra. Para los usuarios finales, la página principal de la app es disponible solo en los mensajes directos de una app de Chat desarrollador de apps habilita la función.


Usa Card Builder para diseñar mensajes de tarjetas JSON y obtener una vista previa de ellos para apps de Chat:

Abre el Creador de tarjetas

Requisitos previos

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.

Apps Script

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

Node.js

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 un app de Chat interactiva con un servicio HTTP, completa esta guía de inicio rápido.

Configura la API de Chat

Para admitir la página principal de la app, debes actualizar la configuración de la API de Chat en la consola de Google Cloud.

Python

  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. Selecciona la casilla de verificación Support App Home.

  4. Agrega una URL en el campo URL de la página principal de la app. Este valor suele ser el mismo de destino como la URL de la aplicación. Esta URL se llama Eventos APP_HOME.

  5. Haz clic en Guardar.

Apps Script

  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. Selecciona la casilla de verificación Support App Home.

  4. Haz clic en Guardar.

Node.js

  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. Selecciona la casilla de verificación Support App Home.

  4. Agrega una URL en el campo URL de la página principal de la app. Este valor suele ser el mismo de destino como la URL de la aplicación. Esta URL se llama Eventos APP_HOME.

  5. Haz clic en Guardar.

Java

  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. Selecciona la casilla de verificación Support App Home.

  4. Agrega una URL en el campo URL de la página principal de la app. Este valor suele ser el mismo de destino como la URL de la aplicación. Esta URL se llama Eventos APP_HOME.

  5. Haz clic en Guardar.

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

La tarjeta de la página principal de la app se inicia cuando un usuario abre un mensaje directo desde la App de Chat y se puede actualizar como respuesta a un evento interactivo, como un clic en un botón, el envío de un formulario o el cierre de 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 devuelve una tarjeta actualizada con la hora en que se creó la tarjeta actualizada.

Crea la tarjeta inicial para la página principal de la app

Para crear la página principal de la app, la app de Chat debe controlar Eventos de interacción APP_HOME y muestran una instancia de RenderActions con la navegación de pushCard.

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"
      }}
    }]}}
  ]}]}

Apps Script

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

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

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"
      }}
    }]}}
  ]}]};
}

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;
}

Actualiza la tarjeta de la página principal de una 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 la navegación de updateCard. Para obtener más información sobre el manejo de widgets, consulta Procesa la información que ingresan los usuarios.

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()
  }]}}}

Apps Script

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

Node.js

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

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;
}

Limitaciones

En general, navigation es no disponible para apps de Chat. No puedes devolver una pila de tarjetas. Solo se permite el uso de pushCard (para la respuesta inicial) y updateCard (para las actualizaciones) disponibles para las apps de Chat.