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, indicata come home page dell'app nell'API Google Chat, è un'interfaccia di schede personalizzabile visualizzata nella scheda Home degli spazi dei messaggi diretti 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 sull'interazione con o consentire agli utenti di accedere a un'app servizio o strumento esterno da Chatta.

Utilizza lo strumento per la creazione di schede per progettare e visualizzare l'anteprima di interfacce utente e messaggistica per le app di chat:

Apri il generatore di schede

Prerequisiti

Node.js

Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un app di Chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.

Python

Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un'app Chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.

Java

Un'app di Google Chat abilitata per le funzionalità interattive. Per creare un'app Chat interattiva utilizzando un servizio HTTP, completa questa guida rapida.

Apps Script

Un'app Google Chat per cui sono abilitate le funzionalità interattive. Per creare un'app Chat interattiva in Apps Script, completa questa guida rapida.

Configurare la home page dell'app per l'app Chat

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

Per aggiornare le impostazioni di configurazione nella console Google Cloud, segui questi passaggi:

  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, quindi sulla scheda Configurazione.

  3. In Funzionalità interattive, vai alla sezione Funzionalità per configura la home page dell'app:

    1. Seleziona la casella di controllo Ricevi messaggi 1:1.
    2. Seleziona la casella di controllo Support App Home.

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

  5. Fai clic su Salva.

Crea una scheda Home dell'app

Quando un utente apre la home page dell'app, la tua 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 un'esperienza interattiva, la scheda può contenere widget interattivi, come pulsanti o input di testo che l'app di chat è in grado di elaborare rispondi con altre schede 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
 *
 * @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;
}

Apps Script

Implementa la funzione onAppHome che viene chiamata dopo tutti gli eventi di interazione APP_HOME:

Questo esempio invia un messaggio di una scheda restituendo JSON card. Puoi utilizzare anche 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 con la home page dell'app

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

Nell'esempio precedente, la scheda Home dell'app iniziale 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 della casa dell'app, come mostrato nel codice seguente:

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 di una scheda restituendo JSON card. Puoi anche utilizzare il servizio di schede di Apps Script.

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

Aprire finestre di dialogo

L'app Chat può anche rispondere alle interazioni nella home page dell'app aprendo le finestre di dialogo.

Una finestra di dialogo con una serie di widget diversi.
Figura 3: una finestra di dialogo che chiede all'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 contenente un oggetto Card. Nel seguente esempio, 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 casa dell'app Chat.
  • CLOSE_DIALOG_AND_EXECUTE: chiude la finestra di dialogo e aggiorna la home page dell'app .

Il seguente esempio di codice utilizza CLOSE_DIALOG per chiudere una finestra di dialogo e tornare a scheda della home page dell'app:

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

Per raccogliere informazioni dagli utenti, puoi anche creare dialoghi sequenziali. A per imparare a creare finestre di dialogo sequenziali, consulta Apri e rispondi alle finestre di dialogo.