Zbieranie kontaktów w Google Chat i zarządzanie nimi

W tym samouczku pokazujemy, jak utworzyć aplikację Google Chat, która pomaga użytkownikom Google Chat zarządzać kontaktami osobistymi i służbowymi. Do zbierania informacje, aplikacja Google Chat prosi użytkowników o podanie formularza kontaktowego w komunikatach i oknach dialogowych.

Zobacz, jak działa aplikacja Google Chat:

Wymagania wstępne

• Firmy lub przedsiębiorstwa Konto Google Workspace z dostępem do Google Chat.

Cele

• Projektowanie i tworzenie interfejsów użytkownika jako obiekty card i wyświetlać interfejsy użytkownika w komunikatach i oknach.
• Otrzymywanie i przetwarzanie informacji przesyłanych przez użytkowników za pomocą widżety do wprowadzania danych.
• Reaguj na polecenia po ukośniku, wysyłając wiadomości zawierające tekst, karty i widżety akcesoriów.

Architektura

Wbudowana aplikacja Google Chat Google Apps Script i zastosowania zdarzenia interakcji do przetworzenia i odpowiadać użytkownikom Google Chat.

Poniżej widać, jak użytkownik zwykle może wchodzić w interakcję z Aplikacja do obsługi czatu:

1. użytkownik otworzy czat w aplikacji Google Chat, doda aplikację Google Chat do istniejącego pokoju.

2. Aplikacja Google Chat prosi użytkownika o dodanie kontaktu tworząc formularz kontaktowy, card obiektu. Aby wyświetlić formularz kontaktowy, aplikacja Google Chat odpowiada użytkownikom w następujący sposób:

   • odpowiada na @wzmianki i wiadomości bezpośrednie za pomocą wiadomości z kartą zawierającą formularz kontaktowy.
   • Odpowiada na polecenie po ukośniku /addContact, otwierając okno ze za pomocą formularza kontaktowego.
   • Odpowiada na polecenie po ukośniku /about za pomocą wiadomości tekstowej ze znakiem Przycisk Dodaj kontakt, który użytkownicy mogą kliknąć, aby otworzyć okno z formularza kontaktowego.

3. Gdy użytkownik zobaczy formularz kontaktowy, wprowadzi w nim informacje kontaktowe w tych polach i widżetach:

   • Imię i nazwisko: widżet textInput, który akceptuje ciągi znaków.
   • Data urodzenia: dateTimePicker widżet, który akceptuje tylko daty.
   • Typ kontaktu: selectionInputwidżet przycisków opcji, który umożliwia użytkownikom wybranie i przesłanie pojedynczej wartości ciągu znaków (Personal lub Work).
   • Przycisk Sprawdź i prześlij: buttonList tabele z elementem button, który użytkownik klika, aby przesłać wprowadzone przez siebie wartości.

4. Aplikacja Google Chat obsługuje zdarzenie interakcji CARD_CLICKED do przetwarzania wartości wprowadzonych przez użytkownika i wyświetlania ich w polu kartę potwierdzenia.

5. Użytkownik przegląda kartę potwierdzenia i klika przycisk Prześlij. by podać dane kontaktowe.

6. Aplikacja Google Chat wysyła prywatną wiadomość tekstową, która potwierdza przesłanie.

Przygotowywanie środowiska

W tej sekcji dowiesz się, jak utworzyć i skonfigurować projekt Google Cloud dla platformy aplikacja Google Chat.

Utwórz projekt Google Cloud

Google Cloud Console

1. W konsoli Google Cloud kliknij Menu menu> Administracja > Utwórz projekt.

   Otwórz stronę Utwórz projekt

2. W polu Project Name (Nazwa projektu) wpisz opisową nazwę projektu.

   Opcjonalnie: aby edytować identyfikator projektu, kliknij Edytuj. Identyfikatora projektu nie można zmienić po jego utworzeniu, wybierz więc identyfikator, który odpowiada potrzebom od początku w projektach AI.

3. W polu Lokalizacja kliknij Przeglądaj, aby wyświetlić potencjalne lokalizacje projektu. Następnie kliknij Wybierz.
4. Kliknij Utwórz. Konsola Google Cloud przejdzie do strony Panelu, a Twój projekt zostanie utworzony w ciągu kilku minut.

interfejs wiersza poleceń gcloud

W jednym z tych środowisk programistycznych uzyskaj dostęp do Google Cloud Interfejs wiersza poleceń (gcloud):

• Cloud Shell: aby korzystać z terminala online z już skonfigurowanym interfejsem gcloud CLI, aktywuj Cloud Shell.
  Aktywuj Cloud Shell
• Local Shell (Powłoka lokalna): aby użyć lokalnego środowiska programistycznego, instalacja oraz zainicjuj w gcloud CLI.
  Aby utworzyć projekt Cloud, użyj polecenia gcloud projects create:

  gcloud projects create PROJECT_ID

  Zastąp PROJECT_ID identyfikatorem projektu, który chcesz utworzyć.

Konfigurowanie uwierzytelniania i autoryzacji

Aplikacje Google Chat wymagają skonfigurowania ekran akceptacji OAuth, użytkownicy mogą autoryzować Twoją aplikację w aplikacjach Google Workspace, w tym Google Chat.

W tym samouczku wdrożysz aplikację Google Chat, która jest przeznaczona tylko dla do testów wewnętrznych i do użytku wewnętrznego, można więc używać informacji zastępczych dla parametru ekranu zgody. Zanim opublikujesz aplikację Google Chat, zastąp symboli zastępczych zawierających prawdziwe informacje.

1. W konsoli Google Cloud kliknij Menu menu > Interfejsy API i usługi > Ekran zgody OAuth.

   Otwórz ekran zgody OAuth

2. W sekcji Typ użytkownika wybierz Wewnętrzny i kliknij Utwórz.

3. W polu Nazwa aplikacji wpisz Contact Manager.

4. W polu Adres e-mail użytkownika wybierz swój adres e-mail lub odpowiednią grupę Google.

5. W sekcji Dane kontaktowe dewelopera wpisz swój adres e-mail.

6. Kliknij Zapisz i kontynuuj.

7. Na stronie Zakresy kliknij Zapisz i kontynuuj. (aplikacja Chat nie wymaga żadnych zakresów OAuth).

8. Sprawdź podsumowanie i kliknij Powrót do panelu.

Tworzenie i wdrażanie aplikacji Google Chat

W następnej sekcji skopiujesz i zaktualizujesz cały Projekt Apps Script zawierający całą wymaganą aplikację do aplikacji Google Chat, więc nie musisz kopiować wklej każdy plik.

Opcjonalnie możesz wyświetlić cały projekt na GitHubie.

Wyświetl w GitHubie

Oto omówienie poszczególnych plików:

main.gs

Obsługuje całą logikę aplikacji, w tym zdarzenia interakcji dotyczące wysyłania przez użytkowników do aplikacji Google Chat, klikaj przyciski wiadomość w aplikacji Google Chat oraz otwieranie i zamykanie okien.

Wyświetl kod aplikacji main.gs

apps-script/contact-form-app/main.gs

Wyświetl w GitHubie

/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Responds to a MESSAGE interaction event in Google Chat.
 *
 * @param {Object} event the MESSAGE interaction event from Chat API.
 * @return {Object} message response that opens a dialog or sends private
 *                          message with text and card.
 */
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1:
        // If the slash command is "/about", responds with a text message and button
        // that opens a dialog.
        return {
          text: "Manage your personal and business contacts 📇. To add a " +
                  "contact, use the slash command `/addContact`.",
          accessoryWidgets: [{ buttonList: { buttons: [{
            text: "Add Contact",
            onClick: { action: {
              function: "openDialog",
              interaction: "OPEN_DIALOG"
            }}
          }]}}]
        }
      case 2:
        // If the slash command is "/addContact", opens a dialog.
        return openDialog(event);
    }
  }

  // If user sends the Chat app a message without a slash command, the app responds
  // privately with a text and card to add a contact.
  return {
    privateMessageViewer: event.user,
    text: "To add a contact, try `/addContact` or complete the form below:",
    cardsV2: [{
      cardId: "addContactForm",
      card: {
        header: { title: "Add a contact" },
        sections:[{ widgets: CONTACT_FORM_WIDGETS.concat([{
          buttonList: { buttons: [{
            text: "Review and submit",
            onClick: { action: { function : "openNextCard" }}
          }]}
        }])}]
      }
    }]
  };
}

/**
 * Responds to CARD_CLICKED interaction events in Google Chat.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @return {Object} message responses specific to the dialog handling.
 */
function onCardClick(event) {
  // Initial dialog form page
  if (event.common.invokedFunction === "openDialog") {
    return openDialog(event);
  // Second dialog form page
  } else if (event.common.invokedFunction === "openNextCard") {
    return openNextCard(
      event.user,
      fetchFormValue(event, "contactName"),
      fetchFormValue(event, "contactBirthdate"),
      fetchFormValue(event, "contactType"),
      event.isDialogEvent
    );
  // Dialog form submission
  } else if (event.common.invokedFunction === "submitForm") {
    const userInputs = event.common.parameters;
    return submitForm(event.user, userInputs, event.dialogEventType);
  }
}

/**
 * Extracts form input value for a given widget.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @param {String} widgetName a unique ID for the widget, specified in the widget's name field.
 * @returns the value inputted by the user, null if no value can be found.
 */
function fetchFormValue(event, widgetName) {
  const formItem = event.common.formInputs[widgetName][""];
  // For widgets that receive StringInputs data, the value input by the user.
  if (formItem.hasOwnProperty("stringInputs")) {
    const stringInput = event.common.formInputs[widgetName][""].stringInputs.value[0];
    if (stringInput != null) {
      return stringInput;
    }
  // For widgets that receive dateInput data, the value input by the user.
  } else if (formItem.hasOwnProperty("dateInput")) {
    const dateInput = event.common.formInputs[widgetName][""].dateInput.msSinceEpoch;
     if (dateInput != null) {
       return dateInput;
     }
  }

  return null;
}

/**
 * Opens a dialog that prompts users to add details about a contact.
 *
 * @return {Object} a message with an action response to open a dialog.
 */
function openDialog() {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { dialog: { body: { sections: [{
      header: "Add new contact",
      widgets: CONTACT_FORM_WIDGETS.concat([{
        buttonList: { buttons: [{
          text: "Review and submit",
          onClick: { action: { function: "openNextCard" }}
        }]}
      }])
    }]}}}
  }};
}

/**
 * Returns a dialog or card message that displays a confirmation of contact
 * details before users submit.
 *
 * @param {String} user the user who submitted the information.
 * @param {String} contactName the contact name from the previous dialog or card.
 * @param {String} contactBirthdate the birthdate from the previous dialog or card.
 * @param {String} contactType the contact type from the previous dialog or card.
 * @param {boolean} fromDialog whether the information was submitted from a dialog.
 *
 * @return {Object} returns a dialog or private card message.
 */
function openNextCard(user, contactName, contactBirthdate, contactType, fromDialog) {
  const name = contactName ?? "<i>Not provided</i>";
  const birthdate = contactBirthdate ?? "<i>Not provided</i>";
  const type = contactType ?? "<i>Not provided</i>";
  const cardConfirmation = {
    header: "Your contact",
    widgets: [{
      textParagraph: { text: "Confirm contact information and submit:" }}, {
      textParagraph: { text: "<b>Name:</b> " + name }}, {
      textParagraph: {
        text: "<b>Birthday:</b> " + convertMillisToDateString(birthdate)
      }}, {
      textParagraph: { text: "<b>Type:</b> " + type }}, {
      buttonList: { buttons: [{
        text: "Submit",
        onClick: { action: {
          function: "submitForm",
          parameters: [{
            key: "contactName", value: name }, {
            key: "contactBirthdate", value: birthdate }, {
            key: "contactType", value: type
          }]
        }}
      }]}
    }]
  };

  // Returns a dialog with contact information that the user input.
  if (fromDialog) {
    return { action_response: {
      type: "DIALOG",
      dialogAction: { dialog: { body: { sections: [ cardConfirmation ]}}}
    }};
  }

  // Updates existing card message with contact information that the user input.
  return {
    actionResponse: { type: "UPDATE_MESSAGE" },
    privateMessageViewer: user,
    cardsV2: [{
      card: { sections: [cardConfirmation]}
    }]
  }
}

/**
  * Submits information from a dialog or card message.
  *
  * @param {Object} user the person who submitted the information.
  * @param {Object} userInputs the form input values from event parameters.
  * @param {boolean} dialogEventType "SUBMIT_DIALOG" if from a dialog.
  * @return {Object} a message response that opens a dialog or posts a private
  *                  message.
  */
function submitForm(user, userInputs, dialogEventType) {
  const contactName = userInputs["contactName"];
  // Checks to make sure the user entered a contact name.
  // If no name value detected, returns an error message.
  if (!contactName) {
    const errorMessage = "Don't forget to name your new contact!";
    if (dialogEventType === "SUBMIT_DIALOG") {
      return { actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "INVALID_ARGUMENT",
          userFacingMessage: errorMessage
        }}
      }};
    } else {
      return {
        privateMessageViewer: user,
        text: errorMessage
      };
    }
  }

  // The Chat app indicates that it received form data from the dialog or card.
  // Sends private text message that confirms submission.
  const confirmationMessage = "✅ " + contactName + " has been added to your contacts.";
  if (dialogEventType === "SUBMIT_DIALOG") {
    return {
      actionResponse: {
        type: "NEW_MESSAGE",
        dialogAction: { actionStatus: {
          statusCode: "OK",
          userFacingMessage: "Success " + JSON.stringify(contactName)
        }}
      },
      privateMessageViewer: user,
      text: confirmationMessage
    }
  } else {
    return {
      actionResponse: { type: "NEW_MESSAGE" },
      privateMessageViewer: user,
      text: confirmationMessage
    };
  }
}

/**
 * Converts date in milliseconds since epoch to user-friendly string.
 *
 * @param {Object} millis the milliseconds since epoch time.
 * @return {string} Display-friend date (English US).
 */
function convertMillisToDateString(millis) {
  const date = new Date(millis);
  const options = { year: 'numeric', month: 'long', day: 'numeric' };
  return date.toLocaleDateString('en-US', options);
}

contactForm.gs

Zawiera widżety, które odbierają dane formularzy od użytkowników. Te widżety formularza są wyświetlane na kartach w wiadomościach i dialogach.

Wyświetl kod contactForm.gs

apps-script/contact-form-app/contactForm.gs

Wyświetl w GitHubie

/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

appsscript.json

Plik manifestu Apps Script, który definiuje i konfiguruje projekt Apps Script na potrzeby aplikacji Google Chat.

Wyświetl kod aplikacji appsscript.json

apps-script/contact-form-app/appsscript.json

Wyświetl w GitHubie

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {}
}

Znajdowanie numeru i identyfikatora projektu Cloud

1. W konsoli Google Cloud otwórz swój projekt Cloud.

   Otwórz konsolę Google Cloud

2. Kliknij Ustawienia i narzędziamore_vert > Ustawienia projektu.

3. Zwróć uwagę na wartości w polach Numer projektu i Identyfikator projektu. Ty jak je wykorzystać w kolejnych sekcjach.

Tworzenie projektu Apps Script

Aby utworzyć projekt Apps Script i połączyć go ze swoim Projekt w chmurze:

1. Kliknij przycisk poniżej, aby otworzyć projekt Apps Script Zarządzanie kontaktami w Google Chat.
   Otwórz projekt
2. Kliknij info_outline Przegląd.
3. Na stronie Przegląd kliknij Utwórz kopię.

4. Nazwij kopię projektu Apps Script:

   1. Kliknij Kopia Menedżera kontaktów w Google Chat.

   2. W polu Tytuł projektu wpisz Contact Manager - Google Chat app.

   3. Kliknij Zmień nazwę.

Ustawianie projektu Cloud w projekcie Apps Script

1. W projekcie Apps Script kliknij Ustawienia projektu.
2. W sekcji Projekt Google Cloud Platform (GCP) kliknij Zmień projekt.
3. W polu Numer projektu GCP wklej numer swojego projektu Cloud.
4. Kliknij Set project (Ustaw projekt). Projekt Cloud i Apps Script projekty są teraz połączone.

Tworzenie wdrożenia Apps Script

Po umieszczeniu całego kodu w odpowiednim miejscu wdróż skrypt Apps Script w projektach AI. Identyfikator wdrożenia służy do konfigurowania Aplikacja Google Chat w Google Cloud.

1. W Apps Script otwórz w projektach AI.

   Otwórz Apps Script

2. Kliknij Wdróż > Nowe wdrożenie.

3. Jeśli opcja Dodatek nie jest jeszcze wybrana, obok pozycji Wybierz typ, kliknij typy wdrożenia i wybierz Dodatek.

4. W polu Opis wpisz opis wersji, na przykład Test of Contact Manager

5. Kliknij Wdróż. Raporty Apps Script zostały przesłane wdrożenie i udostępnia jego identyfikator.

6. Kliknij content_copy Kopiuj, aby skopiować identyfikator wdrożenia i kliknij Gotowe.

Konfigurowanie aplikacji Google Chat w konsoli Google Cloud

Z tej sekcji dowiesz się, jak skonfigurować interfejs Google Chat API w konsoli Google Cloud. z informacjami o aplikacji Google Chat, w tym Identyfikator wdrożenia utworzonego przed chwilą z poziomu Apps Script w projektach AI.

1. W konsoli Google Cloud kliknij Menu menu > Więcej usług > Google Workspace > Biblioteka usług > Interfejs API Google Chat > Zarządzaj > Konfiguracja.

   Otwórz konfigurację interfejsu Chat API

2. W polu Nazwa aplikacji wpisz Contact Manager.

3. W polu URL awatara wpisz https://developers.google.com/chat/images/contact-icon.png.

4. W polu Opis wpisz Manage your personal and business contacts.

5. Kliknij przełącznik Włącz funkcje interaktywne, aby ustawić go w pozycji włączenia.

6. W sekcji Funkcje zaznacz pola wyboru Odbieranie wiadomości 1:1 i Dołączanie do pokoi i rozmów grupowych.

7. W sekcji Ustawienia połączenia wybierz Apps Script.

8. W polu Deployment ID (Identyfikator wdrożenia) wklej identyfikator wdrożenia Apps Script. skopiowaną w poprzedniej sekcji podczas tworzenia Wdrożenie Apps Script.

9. W sekcji Polecenia po ukośniku skonfiguruj polecenia /about i ukośniki po ukośniku /addContact:

   1. Aby skonfigurować pierwsze polecenie po ukośniku, kliknij Dodaj polecenie po ukośniku.
   2. W polu Nazwa wpisz /about.
   3. W polu Identyfikator polecenia wpisz 1.
   4. W polu Opis wpisz Learn how to use this Chat app to manage your contacts
   5. Wybierz Otwiera okno.
   6. Kliknij Gotowe.
   7. Aby skonfigurować kolejne polecenie po ukośniku, kliknij Dodaj polecenie po ukośniku.
   8. W polu Nazwa wpisz /addContact.
   9. W polu Identyfikator polecenia wpisz 2.
   10. W polu Opis wpisz Submit information about a contact.
   11. Wybierz Otwiera okno.
   12. Kliknij Gotowe.

10. W sekcji Widoczność wybierz Pole wyboru Udostępnij tę aplikację do obsługi czatu określonym osobom i grupom w YOUR DOMAIN i wpisz swój adres e-mail.

11. W sekcji Logi wybierz Rejestruj błędy w usłudze Logging.

12. Kliknij Zapisz. Pojawi się komunikat o zapisaniu konfiguracji.

Aplikacja Google Chat jest gotowa do zainstalowania i przetestowania Czat.

Testowanie aplikacji Google Chat

Aby przetestować aplikację Google Chat, otwórz pokój czatu z aplikację Google Chat i wyślij wiadomość:

1. Otwórz Google Chat za pomocą konta Google Workspace, którego używasz dodane podczas dodawania siebie jako zaufanego testera.

   Otwórz Google Chat

2. Kliknij add Nowy czat.
3. W polu Dodaj co najmniej 1 osobę wpisz nazwę aplikacji Google Chat.

4. Z wyników wybierz aplikację Google Chat. A Direct

1. W nowym czacie w aplikacji Google Chat wpisz /addContact i naciśnij Enter.

2. W wyświetlonym oknie wpisz informacje kontaktowe:

   1. W polu tekstowym Imię i nazwisko wpisz imię i nazwisko.
   2. W selektorze daty Data urodzenia wybierz datę.
   3. W sekcji Typ kontaktu kliknij przycisk radiowy Praca lub Osobiście.

3. Kliknij Sprawdź i prześlij.

4. W oknie potwierdzenia przejrzyj przesłane informacje i kliknij Prześlij. Aplikacja Google Chat odpowie tekstem: ✅ CONTACT NAME has been added to your contacts..

5. Opcjonalnie możesz też przetestować i przesłać formularz kontaktowy w następujący sposób: sposoby:

   • Użyj polecenia po ukośniku /about. Aplikacja do czatu odpowiada wiadomością tekstową i przyciskiem widżetu akcesoria z napisem Add a contact. Możesz kliknąć ten przycisk, aby otworzyć okno z przyciskiem formularza kontaktowego.
   • wysyłać wiadomości na czacie do aplikacji Google Chat bez po ukośniku, np. Hello. aplikacja Google Chat, odpowiada tekstem i kartą zawierającą formularz kontaktowy.

Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud opłatami za używanych w tym samouczku, zalecamy usunięcie Projekt w chmurze.

1. W konsoli Google Cloud otwórz stronę Zarządzanie zasobami. Kliknij Menu menu > Uprawnienia Administracja > Zarządzaj zasobami.

   Otwórz Menedżera zasobów

2. Na liście projektów wybierz projekt, który chcesz usunąć, a potem kliknij Usuń delete.
3. W oknie wpisz identyfikator projektu i kliknij Wyłącz, aby go usunąć. nad projektem.

Powiązane artykuły

• Reagowanie na polecenia po ukośniku
• Zbieranie i przetwarzanie informacji od użytkowników Google Chat
• Otwieranie interaktywnych okien dialogowych
• Zobacz inne przykłady aplikacji Google Chat