Creare una home page per un'app Google Chat

Questa pagina spiega come creare una home page per i messaggi diretti con la tua app Google Chat. Una home page, chiamata home page dell'app nell'API Google Chat, è un'interfaccia a schede personalizzabile che viene visualizzata nella scheda Home degli spazi di messaggistica diretta tra un utente e un'app di chat.

Scheda della home page dell'app con due widget.
Figura 1: un esempio di home page visualizzata nei messaggi diretti con un'app di chat.

Puoi utilizzare la home page dell'app per condividere suggerimenti per interagire con l'app Chat o consentire agli utenti di accedere e utilizzare un servizio o strumento esterno da Chat.

Utilizza Card Builder per progettare e visualizzare in anteprima le interfacce utente e di messaggistica per le app di chat:

Apri il generatore di schede

Prerequisiti

Node.js

Un'app Google Chat che riceve e risponde agli eventi di interazione. Per creare un'app Chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.

Python

Un'app Google Chat che riceve e risponde agli eventi di interazione. Per creare un'app Chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.

Java

Un'app Google Chat che riceve e risponde agli eventi di interazione. Per creare un'app Chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.

Apps Script

Un'app Google Chat che riceve e risponde agli eventi di interazione. Per creare un'app di chat interattiva in Apps Script, completa questa guida rapida.

Configurare la home page dell'app per l'app di chat

Per supportare la home page dell'app, devi configurare l'app di chat in modo che riceva eventi di interazione APP_HOME. L'app di chat riceve questo evento ogni volta che un utente fa clic sulla scheda Home da un messaggio diretto con l'app di chat.

Per aggiornare le impostazioni di configurazione nella console Google Cloud:

  1. Nella console Google Cloud, vai a Menu > Altri prodotti > Google Workspace > Libreria di prodotti > API Google Chat.

    Vai all'API Google Chat

  2. Fai clic su Gestisci e poi sulla scheda Configurazione.

  3. Nella sezione Funzionalità interattive, vai alla sezione Funzionalità e seleziona Supporta la home page dell'app.

  4. Se la tua app Chat utilizza un servizio HTTP, vai a Impostazioni di connessione e specifica un endpoint per il campo URL della home page dell'app. Puoi utilizzare lo stesso URL specificato nel campo URL dell'endpoint HTTP.

  5. Fai clic su Salva.

Creare una scheda della home page dell'app

Quando un utente apre la home page dell'app, l'app Chat deve gestire l'evento di interazione APP_HOME restituendo un'istanza di RenderActions con la navigazione pushCard e un Card. Per creare un'esperienza interattiva, la scheda può contenere widget interattivi come pulsanti o input di testo che l'app Chat può elaborare e a cui può rispondere con schede aggiuntive o una finestra di dialogo.

Nell'esempio seguente, l'app Chat mostra una scheda iniziale della home page dell'app che mostra l'ora di creazione della scheda e un pulsante. Quando un utente fa clic sul pulsante, l'app Chat restituisce una scheda aggiornata che mostra l'ora in cui è stata creata.

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 funzione onAppHome chiamata dopo tutti gli eventi di interazione APP_HOME:

Questo esempio invia un messaggio con scheda restituendo JSON della scheda. Puoi anche utilizzare il servizio di schede 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"
      }}
    }]}}
  ]}]};
}

Rispondere alle interazioni nella schermata Home dell'app

Se la scheda iniziale della home page dell'app contiene widget interattivi, come pulsanti o input di selezione, l'app Chat deve gestire gli eventi di interazione correlati restituendo un'istanza di RenderActions con navigazione updateCard. Per scoprire di più sulla gestione dei widget interattivi, consulta Elaborare le informazioni inserite dagli utenti.

Nell'esempio precedente, la scheda iniziale della home page dell'app includeva un pulsante. Ogni volta che un utente fa clic sul pulsante, un evento di interazione CARD_CLICKED attiva la funzione updateAppHome per aggiornare la scheda Home dell'app, come mostrato nel seguente codice:

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

Questo esempio invia un messaggio con scheda restituendo JSON della scheda. Puoi anche utilizzare il servizio di schede Apps Script.

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

Apri finestre di dialogo

L'app Chat può anche rispondere alle interazioni nella home page dell'app aprendo dialoghi.

Una finestra di dialogo con una serie di widget diversi.
Figura 3: una finestra di dialogo che chiede a un utente di aggiungere un contatto.

Per aprire una finestra di dialogo dalla home page dell'app, elabora l'evento di interazione correlato restituendo renderActions con la navigazione updateCard che contiene un oggetto Card. Nell'esempio seguente, un'app di Chat risponde a un clic sul pulsante di una scheda della home page dell'app elaborando l'evento di interazione CARD_CLICKED e aprendo una finestra di dialogo:

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

Per chiudere una finestra di dialogo, elabora i seguenti eventi di interazione:

  • CLOSE_DIALOG: chiude la finestra di dialogo e torna alla scheda iniziale della home page dell'app Chat.
  • CLOSE_DIALOG_AND_EXECUTE: chiude la finestra di dialogo e aggiorna la scheda della home page dell'app.

Il seguente esempio di codice utilizza CLOSE_DIALOG per chiudere una finestra di dialogo e tornare alla scheda Home dell'app:

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

Per raccogliere informazioni dagli utenti, puoi anche creare dialoghi sequenziali. Per scoprire come creare dialoghi sequenziali, consulta Aprire e rispondere ai dialoghi.