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 casa dell'app con due widget.
Figura 1: 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 strumento o servizio esterno da Chat.

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 lo strumento per la creazione di schede

Prerequisiti

Node.js

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

Python

Un'app Google Chat per cui sono abilitate le funzionalità interattive. Per creare un'app di 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 di 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 in modo da 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 l'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 e poi sulla scheda Configurazione.

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

    1. Seleziona la casella di controllo Ricevi messaggi 1:1.
    2. Seleziona la casella di controllo Home page dell'app di assistenza.

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

  5. Fai clic su Salva.

Creare una scheda della casa per un'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'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 home page iniziale 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 di creazione della scheda aggiornata.

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 che viene richiamata dopo tutti gli eventi di interazione APP_HOME:

Questo esempio invia un messaggio della 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 con la schermata Home 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 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 della scheda restituendo JSON della scheda. 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 su un pulsante da 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 home page iniziale dell'app Chat.
  • CLOSE_DIALOG_AND_EXECUTE: chiude la finestra di dialogo e aggiorna la scheda della casa dell'app.

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

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

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