Google Chat'te kişi toplama ve yönetme

Bu eğitimde, Google Chat kullanıcılarının kişisel ve işle ilgili kişilerini yönetmelerine yardımcı olan bir Google Chat uygulamasının nasıl oluşturulacağı gösterilmektedir. Chat uygulaması, bilgi toplamak için kullanıcılardan kart mesajlarında ve iletişim kutularında bir iletişim formu doldurmalarını ister.

Chat uygulamasının nasıl çalıştığını görün:

Ön koşullar

• Google Chat'e erişimi olan bir Business veya Enterprise Google Workspace hesabı.
• Google Cloud projesi oluşturun.

Hedefler

• Kullanıcı arayüzlerini (UI) tasarlayıp oluşturun ve card nesneleri olarak mesajlarda ve iletişim kutularında gösterin.
• Kullanıcıların form girişi widget'larını kullanarak gönderdiği bilgileri alma ve işleme
• Metin, kart ve aksesuar widget'ları içeren mesajlarla komutlara yanıt verin.

Mimari

Chat uygulaması, Google Apps Komut Dosyası'nda (Google Chat'i genişleten bir Google Workspace eklentisi olarak) oluşturulur ve Chat kullanıcılarını işlemek ve yanıtlamak için kullanıcı etkileşimlerine (onMessage, onAppCommand ve openInitialDialog, openConfirmationDialog ve submitForm'ı çağıran düğme tıklamaları) yanıt verir.

Aşağıda, kullanıcının Chat uygulamasıyla nasıl etkileşim kurabileceği gösterilmektedir:

1. Bir kullanıcı, Chat uygulamasıyla doğrudan mesaj açar veya Chat uygulamasını mevcut bir alana ekler.

2. Chat uygulaması, kullanıcıya card nesnesi olarak bir iletişim formu oluşturup görüntüleyerek kişi eklemesini ister. İletişim formunu sunmak için Chat uygulaması, kullanıcılara aşağıdaki şekillerde yanıt verir:

   • @bahsetmelere ve doğrudan mesajlara (onMessage) iletişim formunu içeren bir kart mesajıyla yanıt verir.
   • Kişi formu içeren bir iletişim kutusu açarak /addContact (onAppCommand) eğik çizgi komutuna yanıt verir.
   • Kullanıcıların openInitialDialog'ı çağırmak ve iletişim formu içeren bir iletişim kutusu açmak için tıklayabileceği bir Kişi ekle düğmesi içeren bir kısa mesajla /about (onAppCommand) eğik çizgi komutuna yanıt verir.

3. Kullanıcı, iletişim formu gösterildiğinde aşağıdaki alanlara ve widget'lara iletişim bilgilerini girer:

   • Ad ve soyadı: Dizeleri kabul eden bir textInput widget'ı.
   • Doğum tarihi: Yalnızca tarihleri kabul eden bir dateTimePicker widget'ı.
   • Kişi türü: a selectionInput Kullanıcıların tek bir dize değeri (Personal veya Work) seçip göndermesine olanak tanıyan radyo düğmeleri widget'ı.
   • İncele ve gönder düğmesi: Kullanıcının girdiği değerleri göndermek için tıkladığı button widget'ını içeren bir buttonList dizi.

4. Google Chat uygulaması, kullanıcının girdiği değerleri işlemek için openConfirmationDialog işlevini çağırır ve değerleri bir onay kartında gösterir.

5. Kullanıcı, onay kartını inceler ve submitForm'ı çağırmak ve iletişim bilgilerini tamamlamak için Gönder düğmesini tıklar.

6. Google Chat uygulaması, gönderimi onaylayan özel bir kısa mesaj gönderir.

Ortamı hazırlama

Bu bölümde, Chat uygulaması için Google Cloud projesinin nasıl yapılandırılacağı gösterilmektedir.

Google API Konsolu'nda Cloud projenizi açın.

Henüz açık değilse bu örnek için kullanmayı planladığınız Cloud projesini açın:

1. Google API Konsolu'nda Proje seçin sayfasına gidin.

   Bir Cloud projesi seçin

2. Kullanmak istediğiniz Google Cloud projesini seçin. Alternatif olarak, Proje oluştur'u tıklayıp ekrandaki talimatları uygulayın. Google Cloud projesi oluşturursanız proje için faturalandırmayı etkinleştirmeniz gerekebilir.

Kimlik doğrulama ve yetkilendirme ayarlarını yapma

Google Chat uygulamaları, kullanıcıların Google Chat dahil olmak üzere Google Workspace uygulamalarında uygulamanıza yetki verebilmesi için OAuth kullanıcı rızası ekranı yapılandırmanızı gerektirir.

Bu eğitimde, yalnızca test ve dahili kullanım için bir Chat uygulaması dağıtıyorsunuz. Bu nedenle, kullanıcı rızası ekranı için yer tutucu bilgiler kullanabilirsiniz. Chat uygulamasını yayınlamadan önce yer tutucu bilgilerini gerçek bilgilerle değiştirin.

1. Google API Konsolu'nda Menü menu > Google Auth platform > Branding'e (Markalama) gidin.

   Markalama'ya gidin.

2. Google Auth platformunu daha önce yapılandırdıysanız Markalama, Kitle ve Veri Erişimi'nde aşağıdaki OAuth kullanıcı rızası ekranı ayarlarını yapılandırabilirsiniz. Google Auth platformu henüz yapılandırılmadı mesajını görürseniz Başlayın'ı tıklayın:

   1. Uygulama Bilgileri bölümündeki Uygulama adı alanına Contact Manager yazın.
   2. Kullanıcı destek e-postası bölümünde e-posta adresinizi veya uygun bir Google Grubu'nu seçin.
   3. İleri'yi tıklayın.
   4. Kitle bölümünde Şirket içi'ni seçin. Dahili'yi seçemiyorsanız Harici'yi seçin.
   5. İleri'yi tıklayın.
   6. İletişim bilgileri bölümünde, projenizde yapılan değişikliklerle ilgili bildirim alabileceğiniz bir e-posta adresi girin.
   7. İleri'yi tıklayın.
   8. Bitir bölümünde Google API Hizmetleri Kullanıcı Verileri Politikası'nı inceleyin ve kabul ediyorsanız Google API Hizmetleri: Kullanıcı Verileri Politikası'nı kabul ediyorum'u seçin.
   9. Devam'ı tıklayın.
   10. Oluştur'u tıklayın.
   11. Kullanıcı türü için Harici'yi seçtiyseniz test kullanıcıları ekleyin:
       1. Kitle'yi tıklayın.
       2. Test kullanıcıları bölümünde Kullanıcı ekle'yi tıklayın.
       3. E-posta adresinizi ve yetkili diğer test kullanıcılarını girip Kaydet'i tıklayın.

Chat uygulamasını oluşturma ve dağıtma

Aşağıdaki bölümde, Chat uygulamanız için uygulama kodu (Code.gs ve appsscript.json) içeren bir Apps Komut Dosyası projesi oluşturup güncelleyeceksiniz.

İsteğe bağlı olarak, projenin tamamını GitHub'da görüntüleyebilirsiniz.

GitHub'da göster

Her dosyanın genel bir bakışını aşağıda bulabilirsiniz:

Code.gs

Kullanıcı etkileşimleri (onMessage, onAppCommand, openInitialDialog, openConfirmationDialog ve submitForm) ile mesajlardaki ve iletişim kutularındaki kartlarda gösterilen form girişi widget'ları dahil olmak üzere tüm uygulama mantığını işler.

Code.gs kodunu görüntüleme

apps-script/chat/contact-form-app/Code.gs

GitHub'da göster

/**
 * Copyright 2025 Google LLC
 *
 * 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 in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [
      { buttonList: { buttons: [{
        text: "ADD CONTACT",
        onClick: { action: {
          function: "openInitialDialog",
          interaction: "OPEN_DIALOG"
        }}
      }]}}
    ]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ 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 }
      ]
    }},
    { buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  const birthdate = event.commonEventObject.formInputs["contactBirthdate"].dateInput.msSinceEpoch;
  const type = event.commonEventObject.formInputs["contactType"].stringInputs.value[0];
  // Display the input values for confirmation
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textParagraph: { text: "Confirm contact information and submit:" }},
    { textParagraph: { text: "<b>Name:</b> " + name }},
    { textParagraph: { text: "<b>Birthday:</b> " + new Date(birthdate) }},
    { textParagraph: { text: "<b>Type:</b> " + type }},
    { buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [
          { key: "contactName", value: name },
          { key: "contactBirthdate", value: birthdate },
          { key: "contactType", value: type }
        ]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification or message.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: { action: "CLOSE_DIALOG"}}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
  }}}}};
}

appsscript.json

Chat uygulaması için Apps Komut Dosyası projesini tanımlayan ve yapılandıran Apps Komut Dosyası manifesti.

appsscript.json kodunu görüntüleme

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

GitHub'da göster

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Contact Form app",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/contact-icon.png"
    },
    "chat": {}
  }
}

Apps Komut Dosyası projesini oluşturma

Code.gs ve appsscript.json dosyalarından Apps Komut Dosyası projesi oluşturmak için:

1. Google Apps Komut Dosyası'na gidip Yeni proje'yi tıklayın.

2. Apps Komut Dosyası projenize ad verin:

   1. Başlıksız proje'yi tıklayın.

   2. Proje başlığı'na Contact Manager - Google Chat app yazın.

   3. Yeniden adlandır'ı tıklayın.

3. Code.gs dosyasının içeriğini yukarıdaki Code.gs örnek koduyla değiştirin.

4. Proje Ayarları'nı tıklayın ve "appsscript.json" manifest dosyasını düzenleyicide göster'i seçin.

5. Düzenleyici'ye dönün ve appsscript.json içeriğini yukarıdaki appsscript.json manifest koduyla değiştirip projenizi kaydedin.

Gelecekte belirli Google API'lerini kullanmak veya uygulamanızı yayınlamak isterseniz Cloud projenizi Apps Komut Dosyası projenizle ilişkilendirmeniz gerekir. Bu kılavuz için bunu yapmanız gerekmez. Daha fazla bilgi edinmek için Google Cloud projeleri kılavuzuna bakın.

Apps Komut Dosyası dağıtımı oluşturma

Tüm kodlar hazır olduğuna göre Apps Komut Dosyası projesini dağıtın. Google Cloud'da Chat uygulamasını yapılandırırken dağıtım kimliğini kullanırsınız.

1. Apps Komut Dosyası'nda Chat uygulamasının projesini açın.

   Apps Komut Dosyası'na gitme

2. Dağıt > Yeni dağıtım'ı tıklayın.

3. Eklenti henüz seçilmemişse Tür seçin'in yanındaki dağıtım türlerini tıklayın ve Eklenti'yi seçin.

4. Açıklama bölümüne bu sürümle ilgili bir açıklama girin (ör. Test of Contact Manager).

5. Dağıt'ı tıklayın. Apps Komut Dosyası, dağıtımın başarılı olduğunu bildirir ve bir dağıtım kimliği sağlar.

6. Dağıtım kimliğini kopyalamak için content_copy Kopyala'yı, ardından Bitti'yi tıklayın.

Google API Konsolu'nda Chat uygulamasını yapılandırma

Bu bölümde, Google API Konsolu'nda Google Chat API'nin nasıl yapılandırılacağı gösterilmektedir. Bu yapılandırma, Apps Komut Dosyası projenizden yeni oluşturduğunuz dağıtımın kimliği de dahil olmak üzere Chat uygulamanızla ilgili bilgileri içerir.

1. Google API Console'da Menü menu > API'ler ve Hizmetler > Etkin API'ler ve Hizmetler > Google Chat API > Yapılandırma'yı tıklayın.

   Chat API yapılandırmasına gitme

2. Uygulama adı alanına Contact Manager yazın.

3. Avatar URL'si bölümüne https://developers.google.com/chat/images/contact-icon.png yazın.

4. Açıklama bölümüne Manage your personal and business contacts yazın.

5. Etkileşimli özellikleri etkinleştir açma/kapatma düğmesini açık konumuna getirin.

6. İşlevsellik bölümünde Alanlara ve grup görüşmelerine katılma'yı seçin.

7. Bağlantı ayarları bölümünde Apps Komut Dosyası'nı seçin.

8. Deployment ID (Dağıtım Kimliği) alanına, Apps Komut Dosyası dağıtımını oluştururken önceki bölümde kopyaladığınız Apps Komut Dosyası dağıtım kimliğini yapıştırın.

9. Tetikleyiciler bölümünde, kullanıcı etkileşimlerine yanıt veren işlevleri yapılandırın:

   • Message (Mesaj) tetikleyicisi için onMessage girin.
   • Uygulama komutu tetikleyicisi için onAppCommand girin.

10. Komutlar bölümünde, eğik çizgi komutları /about ve /addContact'ü ayarlayın:

    1. İlk eğik çizgi komutunu ayarlamak için Komut ekle'yi tıklayın.
    2. Command ID (Komut kimliği) alanına 1 yazın.
    3. Açıklama bölümüne Learn how to use this Chat app to manage your contacts yazın.
    4. Komut türü bölümünde Slash command simgesini seçin.
    5. Eğik çizgi komutunun adı bölümüne /about yazın.
    6. Bitti'yi tıklayın.
    7. Başka bir eğik çizgi komutu ayarlamak için Komut ekle'yi tıklayın.
    8. Command ID (Komut kimliği) alanına 2 yazın.
    9. Açıklama bölümüne Submit information about a contact yazın.
    10. Komut türü bölümünde Slash command simgesini seçin.
    11. Eğik çizgi komutunun adı bölümüne /addContact yazın.
    12. İletişim kutusu açar'ı seçin.
    13. Bitti'yi tıklayın.

11. Görünürlük bölümünde Bu Chat uygulamasını YOUR DOMAIN'daki belirli kişiler ve gruplar için kullanılabilir hale getirin onay kutusunu işaretleyin ve e-posta adresinizi girin.

12. Günlükler bölümünde Günlük hatalarını günlüğe kaydetme'yi seçin.

13. Kaydet'i tıklayın. Yapılandırma kaydedildi mesajı gösterilir.

Chat uygulaması, Chat'te yüklenip test edilmeye hazırdır.

Chat uygulamasını test etme

Chat uygulamanızı test etmek için Chat uygulamasıyla doğrudan mesaj alanı açın ve mesaj gönderin:

1. Kendinizi güvenilir test kullanıcıları arasına eklerken sağladığınız Google Workspace hesabını kullanarak Google Chat'i açın.

   Google Chat'e gidin

2. add Yeni sohbet'i tıklayın.
3. 1 veya daha fazla kişi ekle alanına Chat uygulamanızın adını yazın.

4. Sonuçlardan Chat uygulamanızı seçin. Doğrudan mesaj açılır.

1. Chat uygulamasıyla yeni doğrudan mesajda /addContact yazıp Enter tuşuna basın.

2. Açılan iletişim kutusunda iletişim bilgilerini girin:

   1. Ad ve soyadı metin alanına bir ad girin.
   2. Doğum tarihi tarih seçicisinde bir tarih belirleyin.
   3. Kişi türü bölümünde İş veya Kişisel radyo düğmesini seçin.

3. İncele ve gönder'i tıklayın.

4. Onay iletişim kutusunda, gönderdiğiniz bilgileri inceleyin ve Gönder'i tıklayın. Chat uygulaması, ✅ CONTACT NAME has been added to your contacts. yazan bir kısa mesajla yanıt verir.

5. İsterseniz iletişim formunu aşağıdaki yöntemlerle de test edip gönderebilirsiniz:

   • /about eğik çizgi komutunu kullanın. Sohbet uygulaması, kısa mesaj ve Add a contact yazan bir aksesuar widget'ı düğmesiyle yanıt veriyor. İletişim formu içeren bir iletişim kutusu açmak için düğmeyi tıklayabilirsiniz.
   • Chat uygulamasına eğik çizgi komutu olmadan doğrudan mesaj gönderme (ör. Hello). Sohbet uygulaması, iletişim formunu içeren bir metin ve kartla yanıt verir.

Temizleme

Bu eğitimde kullanılan kaynaklar için Google Cloud hesabınızdan ücret alınmasını önlemek istiyorsanız Cloud projesini silmenizi öneririz.

1. Google API Konsolu'nda Kaynakları yönet sayfasına gidin. Şunu tıklayın: Menü menu > IAM & Admin > Kaynakları Yönetin.

   Kaynak Yöneticisi'ne gidin

2. Proje listesinde, silmek istediğiniz projeyi seçin ve Sil'i delete tıklayın.
3. İletişim kutusunda proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.

İlgili konular

• Komutlara yanıt verme
• Google Chat kullanıcılarından bilgi toplama ve bu bilgileri işleme
• Etkileşimli iletişim kutularını açma
• Diğer Google Chat uygulama örneklerini inceleyin