Bu sayfa, Cloud Translation API ile çevrilmiştir.

Actions Builder ile Google Asistan için Etkileşimli Tuval İşlemi oluşturma

1. Genel Bakış

Actions on Google, Google'ın sanal kişisel asistanı Google Asistan'ın işlevlerini akıllı hoparlörler, telefonlar, arabalar, TV'ler, kulaklıklar ve diğer 1 milyardan fazla cihazda geliştirmenizi sağlayan bir geliştirici platformudur. Kullanıcılar, market alışverişi veya araç rezervasyonu gibi işlemler için Google Asistan'ı kullanarak sohbet eder. Şu anda yapabileceklerinin tam listesi için İşlemler dizinine göz atın. Geliştirici olarak, kullanıcılar ile kendi üçüncü taraf hizmetiniz arasındaki keyifli ve yararlı sohbet deneyimlerini kolayca oluşturmak ve yönetmek için Actions on Google'ı kullanabilirsiniz.

Bu codelab, Google Asistan için İşlemler oluşturma konusunda belirli bir deneyime sahip okuyuculara yönelik gelişmiş bir modüldür. Daha önce Actions on Google'da uygulama geliştirme deneyiminiz yoksa tanıtım amaçlı codelab'leri ( 1. Seviye ve 2. Seviye) izleyerek platform hakkında bilgi edinin. Bu modüller, Action'ınızın işlevlerini artırmanıza ve kitlenizi büyütmenize yardımcı olabilecek bir dizi özellik konusunda size yol gösterecektir.

Bu codelab'de, Konuşma İşlemi'ne tam ekran oyun eklemek için Google Asistan'da oluşturulmuş bir çerçeve olan Etkileşimli Tuval'i kullanacaksınız. Oyun, Asistan'ın görüşme sırasında kullanıcıya yanıt olarak gönderdiği etkileşimli bir web uygulamasıdır. Kullanıcı daha sonra akıllı ekranlarda ve Android mobil cihazlarda oyunu ses veya metin girişi yoluyla oynayabilir.

Oyunun tamamını kendiniz oluşturmak yerine Kar Arkadaşı adlı ve kısmen önceden oluşturulmuş bir oyunu dağıtıp codelab'de ilerledikçe oyunun mantığını ekleyin. Snow Pal, geleneksel Hangman oyununun bir varyasyonudur; Oyunda bir kelimeyi temsil eden çok sayıda boşluk var ve bu kelimede olabileceğini düşündüğünüz harfleri tahmin ediyorsunuz. Her yanlış tahminde Kar Arkadaşı'nız biraz daha erier. Bu kelimeyi söylerseniz Kar Arkadaşınız tamamen erimeden oyunu kazanırsınız.

Şekil 1. Kısmen tamamlanmış bir Snow Pal oyunu

Neler oluşturacaksınız?

Bu codelab'de, Etkileşimli Tuval kullanan bir İşlem derleyeceksiniz. İşleminiz aşağıdaki özelliklere sahip olacak:

Kullanıcıların sesli olarak oynayabilecekleri tam ekran kelime oyunu
Kullanıcıların oyunu başlatmak için basabilecekleri bir düğme
Kullanıcıların oyunu tekrar oynamak için basabilecekleri bir düğme

Bu codelab'i tamamladığınızda tamamlanan İşleminiz aşağıdaki konuşma akışına sahip olur:

Asistan: Welcome to Snow Pal! Would you like to start playing the game?

Kullanıcı: Yes.

Asistan: Try guessing a letter in the word or guessing the word.

Kullanıcı: I guess the letter E.

Asistan: Let's see if your guess is there...E is right. Right on! Good guess.

Kullanıcı, oyun bitene kadar harfleri veya bilinmeyen kelimeyi tahmin etmeye devam eder.

Neler öğreneceksiniz?

Etkileşimli Tuval İşlemi oluşturma ve dağıtma
Kullanıcının sesine ve dokunmatik girişine göre kelime oyunu nasıl güncellenir?
Farklı yöntemler kullanarak web uygulamasına veri iletme
Etkileşimli Tuval İşleminizde hata ayıklama

Gerekenler

Bu codelab'in ön koşulları şunlardır:

Google Chrome gibi bir web tarayıcısı
Tercih ettiğiniz bir IDE veya metin düzenleyici
Makinenizde Node.js, npm ve git yüklü

Bu codelab'de kullanılan kodu anlamanıza yardımcı olması için JavaScript (ES6) hakkında bilgi sahibi olmanız önemle tavsiye edilir.

İsteğe bağlı: Örnek kodun tamamını alın

Bu codelab'de, eksik bir sürümden örneği adım adım derleyeceksiniz. Dilerseniz tamamlanmış örneği GitHub deposundan da edinebilirsiniz.

2. Etkileşimli Tuval tanıtımı

Google Asistan üzerine inşa edilmiş olan Etkileşimli Tuval, Conversational Action'ınıza tam ekran görseller ve animasyonlar eklemenize olanak tanıyan bir çerçevedir.

Etkileşimli Tuval kullanan bir işlem, normal bir konuşmaya dayalı işleme benzer şekilde çalışır. Bununla birlikte, Etkileşimli Tuval İşlemi, tam ekran web uygulaması açan cihaza yanıt gönderme özelliğine sahiptir.

Kullanıcı, görüşme sona erene kadar sesle veya dokunarak web uygulamasına giriş sağlar.

Şekil 2. Etkileşimli Tuval ile oluşturulmuş bir Action.

Bu codelab'de projeniz aşağıdaki üç ana bölümde düzenlenmiştir:

Web uygulaması: Web uygulaması dosyaları, web uygulamanızın görsel ve animasyonlarının kodunu ve kullanıcının girişine göre web uygulamasını güncelleme mantığını içerir.
Conversational Action: Conversational Action, kullanıcının girişini tanıyan, işleyen ve yanıt veren konuşma mantığınızı içerir.
Webhook: Webhook, oyunun mantığını işler. Bu codelab'de webhook'u oyun sunucunuz olarak düşünebilirsiniz.

Bu codelab'in her bölümünde web uygulamasını, Conversational Action'ı ve webhook'u değiştirerek Etkileşimli Tuval İşleminize işlev ekleyeceksiniz.

Snow Pal Action'daki Conversational Action, webhook ve web uygulaması aşağıdaki gibi çalışır:

Conversational Action, kullanıcıdan kelimedeki bir harfi veya tüm kelimeyi tahmin etmesini ister.
Kullanıcı, akıllı ekranda Snow Pal web uygulamasına "Sanırım i harfini düşünüyorum" diyor.
Kullanıcının girişi, Actions Builder ve/veya Actions SDK projenizde tanımlanan Conversational Action'a yönlendirilir.
Conversational Action, kullanıcının girişini işler ve girişin ne olduğuna bağlı olarak, web uygulamasını güncelleyen veya web uygulamasını doğrudan güncellemek için meta veri gönderen webhook mantığını tetikler.
Web uygulaması, harfin kelimede göründüğü yeri gösterecek şekilde güncellenir ve kullanıcıdan tekrar tahmin etmesi istenir.

Etkileşimli Tuval altyapısını anlama bölümünde Etkileşimli Tuval'in işleyiş şekli hakkında daha fazla bilgi edinebilirsiniz. Artık temel bilgileri edindiğinize göre, bu codelab için ortamınızı oluşturmaya başlayabilirsiniz.

3. Kur

Google izin ayarlarınızı kontrol etme

Bu codelab için oluşturduğunuz İşlemi test etmek istiyorsanız Actions konsolu simülatörünün İşleminize erişebilmesi için gerekli izinleri etkinleştirmeniz gerekir. İzinleri etkinleştirmek için şu adımları uygulayın:

Etkinlik kontrolleri'ne gidin.
Gerekirse Google Hesabınızla oturum açın.
Aşağıdaki izinleri etkinleştirin:

Web ve Uygulama Etkinliği
Web ve Uygulama Etkinliği bölümünde, Chrome geçmişini ve Google hizmetlerini kullanan site, uygulama ve cihazlardaki etkinlikleri ekle onay kutusunu işaretleyin.

gactions komut satırı arayüzünü yükleme

Bu codelab'de, Actions projenizi Actions konsolu ile yerel dosya sisteminiz arasında senkronize etmek için gactions komut satırı arayüzü (KSA) aracını kullanacaksınız.

Gactions CLI'sını yüklemek için Gactions komut satırı aracını yükleme bölümündeki talimatları uygulayın.

Firebase komut satırı arayüzünü yükleme

Firebase komut satırı arayüzü (KSA), Actions projenizi Cloud Functions'a dağıtmanıza ve web uygulamanızı barındırmanıza olanak tanır.

Bu codelab, Firebase CLI'yı yüklemek için npm'yi kullanır. Genellikle Node.js ile birlikte gelen npm'yi yüklediğinizden emin olun.

CLI'yı yüklemek veya yükseltmek için bir terminal açın ve aşağıdaki npm komutunu çalıştırın:

npm install -g firebase-tools

CLI'ın düzgün şekilde yüklendiğini doğrulamak için aşağıdaki komutu çalıştırın:

firebase --version

Firebase CLI'ın, Cloud Functions için gereken en yeni özelliklerin tümüne sahip olması için 8 veya daha yeni bir sürüm olduğundan emin olun. Yüklü değilse yeni sürüme geçmek için npm install -g firebase-tools komutunu çalıştırın.

Firebase'e giriş yapmak için aşağıdaki komutu çalıştırın:

firebase login

Firebase'e giriş yaptığınızda, Actions projenizi oluştururken kullandığınız Google Hesabı'nı kullandığınızdan emin olun.

Depoyu klonlama

Bu bölümde, bu codelab için ihtiyacınız olan dosyaları klonlayacaksınız. Bu dosyaları almak için aşağıdaki adımları izleyin:

Bir terminal penceresi açın ve genellikle kodlama projelerini depoladığınız bir dizine geçiş yapın. Google Hesabınız yoksa ana dizininize geçin.
Bu depoyu klonlamak için terminalinizde aşağıdaki komutu çalıştırın:

git clone https://github.com/actions-on-google/actions-builder-canvas-codelab-nodejs

start/ dizinini açın. Bu kod deposu, üzerinde çalışacağınız aşağıdaki önemli dizinleri içerir:

public/: Bu dizin, web uygulamanızın HTML, CSS ve JavaScript kodunu içerir.
sdk/custom/: Bu dizin, Conversational Action'ınızın mantığını (sahneler, amaçlar ve türler) içerir.
sdk/webhooks/: Bu dizin sizin webhook'unuzdur ve oyun mantığını içerir.

Şekil 3. start dizin kodunun yapısı.

4. Actions projenizi oluşturma

Bu bölümde Actions projenizi oluşturup yapılandıracaksınız, ayrıca klonlanan depodaki kodu gactions CLI ile Actions Console'a aktaracak, web uygulamanızı ve webhook'unuzu dağıtacaksınız.

Actions projesi oluşturma

Actions projeniz, İşleminiz için bir kapsayıcıdır. Bu codelab için Actions projenizi oluşturmak üzere şu adımları uygulayın:

Actions Console'u açın.
Yeni proje'yi tıklayın.
canvas-codelab gibi bir Proje adı yazın. Bu ad dahili referans içindir. Daha sonra projeniz için harici bir ad ayarlayabilirsiniz.

Create project (Proje oluştur) seçeneğini tıklayın.
Ne tür bir İşlem oluşturmak istiyorsunuz? ekranında Oyun kartını seçin.
İleri'yi tıklayın.
Boş proje kartını seçin.
Derlemeye başla'yı tıklayın.

İşleminiz için proje kimliğini kaydedin

Proje kimliği, işleminiz için benzersiz bir tanımlayıcıdır. Bu codelab'deki çeşitli adımlar için proje kimliğiniz gerekir.

Proje Kimliğinizi almak için şu adımları izleyin:

Actions konsolunda üç dikey noktayı tıklayın > Proje ayarları.

Proje kimliğini kopyalayın.

Faturalandırma hesabı ilişkilendirin

İstek karşılama işleminizi Cloud Functions'ı kullanarak daha sonra bu codelab'de dağıtmak için Google Cloud'daki projenizle bir faturalandırma hesabı ilişkilendirmeniz gerekir. Zaten bir faturalandırma hesabınız varsa aşağıdaki adımları göz ardı edebilirsiniz.

Projenizle bir faturalandırma hesabını ilişkilendirmek için şu adımları uygulayın:

Google Cloud Platform faturalandırma sayfasına gidin.
Faturalandırma hesabı ekle veya Hesap oluştur'u tıklayın.
Ödeme bilgilerinizi girin.
Ücretsiz denememi başlat veya Gönder ve faturalandırmayı etkinleştir'i tıklayın.
Google Cloud Billing sayfasına gidin.
Projelerim sekmesini tıklayın.
Üç noktayı tıklayın > Faturalandırmayı değiştirebilirsiniz.
Açılır menüde, yapılandırdığınız faturalandırma hesabını seçin.
Hesap belirle'yi tıklayın.

Ücret ödememek için Projenizi temizleme bölümündeki adımları uygulayın.

Web uygulamasını dağıtın

Bu bölümde, Firebase CLI'yı kullanarak web uygulamanızı (Snow Pal oyunu) dağıtacaksınız. Dağıtım yaptıktan sonra web uygulamasının URL'sini alabilir ve oyunun tarayıcıda nasıl göründüğünü görebilirsiniz.

Web uygulamanızı dağıtmak için şu adımları uygulayın:

Terminalde start/ dizinine gidin.
{PROJECT_ID} kısmını proje kimliğinizle değiştirerek aşağıdaki komutu çalıştırın:

firebase deploy --project {PROJECT_ID} --only hosting

Birkaç dakika sonra göreceğiniz "Deploy complete!", Snow Pal web uygulamasını Firebase'e başarıyla dağıttığınızı gösterir.

Snow Pal oyununu tarayıcıda görüntülemek için aşağıdaki adımları izleyin:

Terminalinizin çıkışında sağlanan barındırma URL'sini alın. URL şu biçimde olmalıdır: https://<PROJE_KİMLİĞİ>.web.app

URL'yi bir tarayıcıya yapıştırın. Snow Pal oyunu başlangıç ekranında Oyunu Başlat düğmesi gösterilir:

Actions projesine web uygulaması URL'si ve proje kimliği ekle

Sonra, actions.intent.MAIN.yaml dosyasına web uygulaması URL'nizi ve proje kimliğinizi ekleyin. Web uygulaması URL'sini eklemek, Conversational Action'ın hangi URL'ye veri gönderileceğini bilmesini sağlar. settings.yaml içinde proje kimliğini de eklemek, indirilen dosyaları Actions Console'da doğru projeye aktarmanıza olanak tanır.

Web uygulaması URL'nizi ve proje kimliğinizi eklemek için şu adımları uygulayın:

start/sdk/custom/global/actions.intent.MAIN.yaml dosyasını metin düzenleyicinizde açın.
URL alanında yer tutucu dizesini web uygulaması URL'nizle değiştirin.
start/sdk/settings/settings.yaml dosyasını metin düzenleyicinizde açın.
projectId alanında, yer tutucu dizesini proje kimliğinizle değiştirin.

Projeyi Actions konsoluna aktar

Actions konsolunu yerel projenizle güncellemek için Actions projenizi Actions konsoluna aktarmanız gerekir. Bunun için, aşağıdaki adımları uygulayın:

sdk dizinine geçin:

cd sdk/

Yerel dosya sisteminizin yapılandırmasını Actions konsoluna kopyalamak için aşağıdaki komutu çalıştırın:

gactions push

Webhook'u dağıt

gactions push çalıştırdığınızda, başlangıç webhook'u kodunu Actions konsoluna aktardınız. Bu codelab'in geri kalanı için webhook kodunuzu Actions Console'da düzenleyebilirsiniz. Bu noktada, webhook'u Actions konsolundan dağıtabilirsiniz.

Webhook'unuzu dağıtmak için şu adımları uygulayın:

Actions konsolunda, gezinme çubuğunda Geliştir'i tıklayın.
Gezinme çubuğunda Webhook sekmesini tıklayın.
Dağıtımı Dağıt'ı tıklayın.

Cloud Functions'ın karşılamanızı sağlaması ve dağıtması birkaç dakika sürebilir. Cloud Function dağıtımı devam ediyor... mesajını görürsünüz. Kod başarıyla dağıtıldığında mesaj, Cloud Functions dağıtımınız güncel olur olarak güncellenir.

Simülasyon aracında test etme

İşleminiz bu noktada web uygulamasına bağlanmıştır. İşleminizi çağırdığınızda web uygulamasının göründüğünden emin olmak için Actions konsolu simülatörünü kullanabilirsiniz.

İşleminizi test etmek için şu adımları uygulayın:

Actions konsolu gezinme çubuğunda Test et'i tıklayın.
Giriş alanına Talk to Snow Pal sample yazıp Enter tuşuna basın.
Giriş alanına Yes yazıp Enter tuşuna basın. Alternatif olarak Oyunu başlat'ı da tıklayabilirsiniz.

Bir harfi veya kelimeyi tahmin etmek için mantığı henüz yapılandırmadığınız için, bir kelimeyi veya harfi tahmin ederseniz "...Yanlış. Denemeye devam edin. Görünüşe göre bu özelliğin düzgün çalışması için daha fazla işlev eklememiz gerekiyor."

5. Etkileşimli Tuval altyapısını anlama

Bu projede işlevler üç ana bileşen halinde düzenlenmiştir: Conversational Action, web uygulaması ve webhook. Bunun, İşleminizi nasıl ayarlayabileceğinizi gösteren bir model olduğunu ve Etkileşimli Tuval'in temel işlevini vurgulayacak şekilde düzenlendiğini unutmayın.

Aşağıdaki bölümlerde Conversational Action, webhook ve web uygulamasının birlikte nasıl çalıştığı ve diğer önemli Etkileşimli Tuval öğeleri açıklanmaktadır.

Konuşma İşlemi

İşleminizin Konuşma İşlemi bileşeni kullanıcı girişini tanıma, işleme ve kullanıcıya bir yanıtın oluşturulduğu uygun sahneye gönderme işlemlerini yürütür. Örneğin, bir kullanıcı Snow Pal oyununda "Sanırım e harfini" söylüyorsa Sohbet İşleminiz bu harfi intent parametresi olarak alır ve uygun oyun mantığına iletir. Bu mantık, tahminin doğru olup olmadığını belirleyip web uygulamasını buna göre günceller. Bu konuşma mantığını, Actions Console'daki web tabanlı bir entegre geliştirme ortamı olan Actions Builder'da görüntüleyip değiştirebilirsiniz. Aşağıdaki ekran görüntüsünde, Actions Builder'daki Conversational Action'ın bir bölümü gösterilmektedir:

4.Şekil İşlem Oluşturucu'daki Main invocation öğesinin görselleştirmesi.

Bu ekran görüntüsünde İşleminiz için Main invocation gösteriliyor. Kullanıcılar, "Ok Google, Snow Pal örneği ile konuş" gibi bir ifade söylediklerinde eşleştiriliyor. Kullanıcı işleminizi çağırdığında Main invocation, web uygulamanızın URL'sini içeren canvas yanıtıyla bir istem gönderir.

İşleminizdeki ilk canvas yanıt, web uygulaması URL'sini içermelidir. Bu yanıt, Asistan'a, Asistan'a kullanıcının cihazındaki söz konusu adresteki web uygulamasını oluşturmasını söyler. İşlem Oluşturucu'daki ek canvas yanıtları, true olarak ayarlanmış bir send_state_data_to_canvas_app alanı içerebilir. Bu alan, intent eşleştiğinde intent adını ve parametre değerlerini web uygulamasına gönderir. Web uygulaması, kullanıcı girişinden alınan bu verilere göre güncellenir.

Webhook

Bu codelab'de webhook'unuz oyun mantığını içerir (Webhook'unuzu bir oyun sunucusu gibi düşünebilirsiniz). Oyun mantığı, kullanıcının tahmininin doğru mu yanlış mı olduğunu, kazanıp kazanmadığını veya kaybettiğini belirleme ve sonuca göre bir yanıt oluşturma gibi unsurları içerir. Webhook'unuzu Actions Builder'da değiştirebilirsiniz.

İşleminizin oyun mantığını yürütmesi gerektiğinde Actions Builder, webhook'a bir çağrı yapar. Örneğin, Game sahnesindeki guess niyeti, guess işleyiciye bir webhook çağrısı yapar ve ardından kullanıcının tahmininin doğru olup olmadığını belirlemek için mantık yürütür. Webhook, web uygulaması dosyalarıyla eşlenen ve web'i uygun şekilde güncelleyen işleyicilerin içinde Canvas yanıtları içerebilir.

Web uygulaması

5. Şekil. Etkileşimli Tuval İşlemi'nde Conversational Action, webhook ve web uygulaması arasındaki etkileşimin görsel temsili.

Web uygulaması dosyaları, web uygulamanızın görsel ve animasyonlarının kodunu ve kullanıcı girişine göre web uygulamasını güncelleme mantığını içerir. Web uygulaması dosyalarınızı metin düzenleyicinizde değiştirir ve bu değişiklikleri Firebase CLI'ı kullanarak dağıtırsınız.

Conversational Action ve web uygulaması arasında iletişim kurma

Web uygulamanızın kullanıcı girişine göre güncellenebilmesi için Conversational Action ile web uygulamanız arasında iletişimi etkinleştirmeniz gerekir. Örneğin, bir kullanıcı "Sanırım f harfini" söylüyorsa,

Web uygulamasının uygun şekilde güncellenebilmesi için Sohbet İşlemi'nin web uygulamasına f harfini sağlaması gerekir. Kullanıcının girişini Conversational Action'dan web uygulamasına aktarmak için Interactive Canvas API'yi yüklemeniz gerekir.

Bu API'nin komut dosyası, Snow Pal oyununun ana HTML dosyası olan /public/index.html içinde yer almaktadır. Bu dosya, kullanıcı arayüzünüzün çeşitli komut dosyalarında nasıl göründüğünü ve yüklendiğini tanımlar:

index.html

<!-- Load Assistant Interactive Canvas API -->
 <script type="text/javascript" src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>

Web uygulamasını kullanıcı girişine göre güncellemek için web uygulaması dosyanıza geri çağırmalar da kaydetmeniz ve yapılandırmanız gerekir. Geri çağırma işlevleri, web uygulamanızın Conversational Action'daki bilgilere veya isteklere yanıt vermesine olanak tanır.

/public/js/action.js ürününde, geri çağırmaları bildirmek ve kaydetmek için Action adında önceden yapılandırılmış bir sınıf bulunmaktadır. Action sınıfı, Interactive Canvas API'si etrafında oluşturulmuş bir sarmalayıcıdır. Web uygulaması scene.js içinde create() işleviyle oluşturulduğunda, yeni bir Action örneği oluşturulur ve aşağıdaki snippet'te gösterildiği gibi setCallbacks() çağrılır:

scene.js

// Set Assistant at game level.
this.assistant = new Action(this);
// Call setCallbacks to register Assistant Action callbacks.
this.assistant.setCallbacks();

setCallbacks() işlevi, /public/js/action.js öğesinin Action sınıfında tanımlanır. Bu işlev, geri çağırmaları tanımlar ve oyun oluşturulduktan sonra bunları Interactive Canvas API'ye kaydeder:

  setCallbacks() {
    // Declare the Interactive Canvas Action callbacks.
    const callbacks = {
      onUpdate: (data) => {
     ...
    // Called by the Interactive Canvas web app once web app has loaded to
    // register callbacks.
    this.canvas.ready(callbacks);
  }

setCallbacks() işlevi, her Canvas yanıtı gönderdiğinizde çağrılan onUpdate() geri çağırmasını tanımlar.

Sonraki bölümde, Conversational Action'dan web uygulamasına veri iletmek için bu projeye özel kodun nasıl yapılandırıldığı açıklanmaktadır.

Kullanıcı girişine göre web uygulamasını güncelleme

Bu codelab'de, kullanıcı girişine göre web uygulamasını güncellemek için bir komut eşlemesi kullanacaksınız. Örneğin, start_game amacı Welcome sahnesinde eşleştiğinde isteme dahil edilen canvas yanıtı web uygulamasına gönderilir. onUpdate(), canvas yanıtındaki meta verileri ayrıştırır ve START_GAME komutunu çağırır. Bu komut da scene.js öğesindeki start() işlevini çağırır ve web uygulamasını yeni bir oyun oturumu başlatmak üzere günceller.

scene.js içindeki start() işlevi, webhook'unuzun erişebileceği durum verilerini eklemek için setCanvasState() adlı bir yöntemi kullanan updateCanvasState() işlevini de çağırır.

updateCanvasState() yöntemi, her komutun sonunda çağrılır (bu komutları codelab boyunca ekleyeceksiniz) ve web uygulamasının durumunu günceller. updateCanvasState() her çağrıldığında displayedWord ve incorrectGuesses değerleri geçerli duruma göre güncellenir:

scene.js

...
  updateCanvasState() {
    window.interactiveCanvas.setCanvasState({
      correctWord: this.word.text,
      displayedWord: this.word.displayText.text,
      incorrectGuesses: this.incorrectGuesses,
    });

Güncellenen durum, bir sonraki konuşma sırası için kullanılabilir. Bu duruma, aşağıdaki kod snippet'inde gösterildiği gibi conv.context.canvas.state aracılığıyla webhook'tan erişebilirsiniz:

index.js

...
  let displayedWord = conv.context.canvas.state.displayedWord;
...

6. Tahmin işlevi ekleyin

Bu bölümde İşleminize guess işlevini eklersiniz. Bu işlev, kullanıcının kelime veya kelime içindeki harfleri tahmin etmesine olanak tanır.

Konuşma İşlemi

Simülatörde test etme bölümünde "Bu özelliğin düzgün çalışması için daha fazla işlev eklememiz gerekiyor" ifadesini içeren bir yanıt aldınız. Artık bu istemi Actions Console'dan silebilirsiniz. Böylece yalnızca webhook'u çağırırsınız (Game sahnesinde, guess niyeti, eşleştiğinde bir webhook çağrısı yapacak şekilde zaten yapılandırılmıştır).

guess amacı eşleştiğinde statik istemi kaldırmak için şu adımları uygulayın:

Actions konsolundaki gezinme çubuğunda Sahneler'i tıklayın.
Game sahnesine gitmek için Oyun'u tıklayın.
Kullanıcı amacı işleme bölümünde Tahmin eşleştiğinde'yi tıklayın. İstemi kaldırmak için İstemleri gönder'i temizleyin.
Kaydet'i tıklayın.

Webhook

Bu bölümde webhook'unuzu, bir kullanıcının doğru veya yanlış tahminini bir web uygulaması dosyasındaki mantığa eşleyen ve ardından web uygulamasını buna uygun şekilde güncelleyen bir mantıkla güncelleyeceksiniz. guess intent işleyicisi webhook'ta sizin için zaten yapılandırılmış. Bu nedenle, web uygulamasını güncelleyen mantığı tetiklemek için bu niyete yalnızca Canvas yanıtları eklemeniz gerekir.

Webhook'unuzu güncellemek için aşağıdaki adımları uygulayın:

Actions konsolunda, gezinme çubuğunda Webhook'u tıklayın.
guess işleyicinin altında index.js öğesine şu kodu ekleyin:

index.js (Bölüm A):

// Add Section A `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'CORRECT_ANSWER',
    displayedWord: displayedWord
  },
}));

index.js (Bölüm B):

// Add Section B `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'INCORRECT_ANSWER',
  },
}));

Sipariş Karşılamayı Kaydet'i tıklayın.
Dağıtımı Dağıt'ı tıklayın. Dağıtım tamamlandığında Cloud Function dağıtımınız güncel mesajı gösterilir.

Web uygulaması

Artık web uygulamanızı CORRECT_ANSWER ve INCORRECT_ANSWER komutlarını işleyecek şekilde yapılandırabilirsiniz.

public/js/action.js dosyasını metin düzenleyicinizde açın.
CORRECT_ANSWER ve INCORRECT_ANSWER komutlarını işlemek için web uygulamasını güncelleyin:

action.js (Bölüm C):

// Add Section C `CORRECT_ANSWER: (params) => {` content here.
      CORRECT_ANSWER: (params) => {
        this.gameScene.correctAnswer(params);
      },
      INCORRECT_ANSWER: (params) => {
        this.gameScene.incorrectAnswer();
      },

Web uygulamasını güncellemek için aşağıdaki komutu çalıştırın:

firebase deploy --project {PROJECT_ID} --only hosting

İşleminizi simülatörde test etme

Bu noktada İşleminiz bir tahminin doğru mu yanlış mı olduğunu belirleyebilir ve web uygulamasını buna göre güncelleyebilir.

İşleminizi test etmek için şu adımları uygulayın:

Gezinme çubuğunda Test et'i tıklayın.
Giriş alanına Talk to Snow Pal sample yazıp Enter tuşuna basın.
Giriş alanına Yes yazıp Enter tuşuna basın. Alternatif olarak Evet düğmesini de tıklayabilirsiniz.
Tahmin etmek istediğiniz harfi Giriş alanına yazın ve Enter tuşuna basın.

Kodu anlama

Önceki bölümde kullanıcıların oyununuzdaki harfleri tahmin edip bu tahminlerin kelimede ya da Kar Arkadaşı'nda gösterilmesini sağlayan bir kod eklemiştiniz. Yüksek bir düzeyde, guess niyeti eşleştiğinde Actions Builder'da bir webhook çağrısı yaparsınız. Bu çağrı, uygun şekilde güncellenmesi için web uygulamanıza veri iletir. Örneğin, kullanıcı Snow Pal oyununda kelimede bulunan bir harfi tahmin ederse web uygulaması güncellenerek bu harfi kelimede doğru konumda gösterir.

Etkileşimli Tuval kullanan İşlemler için verilerin webhook'tan web uygulamasına nasıl aktarıldığına ilişkin genel akış aşağıdaki gibidir:

Kullanıcının girişi, Canvas yanıtı içeren bir intent'le eşleşiyor.
Conversational Action veya webhook Canvas yanıtını gönderir. Bu da onUpdate() geri çağırmasını tetikler.
onUpdate() geri çağırması, web uygulamasını uygun şekilde güncelleyen özel mantıkla eşlenir.

Bu proje için kod şu şekilde çalışır:

Kullanıcı, guess amacıyla eşleştiğinde İşlem Oluşturucu, kullanıcının girişinden bu harfi parametre olarak çıkarır.
Actions Builder, webhook'unuzda guess işleyiciyi çağırır. Bu işleyici, kullanıcının tahmin ettiği harfin kelimede görünüp görünmediğini belirlemeye yönelik bir mantık içerir.
guess işleyicisi, biri harf doğru olduğunda, diğeri harf yanlış olduğunda yürütülen iki Canvas yanıt içerir. Her Canvas yanıtı, uygun verileri (CORRECT_ANSWER veya INCORRECT_ANSWER komutu) web uygulamasına iletir.
Canvas yanıtının data alanında bulunan veriler, action.js öğesindeki onUpdate() yöntemine iletilir. onUpdate(), scene.js uygulamasındaki komut eşlemesinde uygun komutu çağırır.
Komut eşlemesi, scene.js içindeki correctAnswer() ve incorrectAnswer() işlevleriyle eşlenir. Bu işlevler, web uygulamasını kullanıcının tahminini yansıtacak şekilde günceller ve web uygulamanızdan webhook'unuza durum verileri göndermek için setCanvasState() komutunu çağırır.

7. Kazanma/kaybetme işlevi ekleyin

Bu bölümde, İşleminize kazanan ve kaybeden işlevleri eklersiniz. Bu işlevler, kullanıcının kazanıp kaybetmediğini belirleyen mantığı ve kullanıcının sonucuna göre web uygulaması resmini güncelleme mantığını içerir.

Konuşma İşlemi

Kullanıcının oyunu kazanmasını veya kaybetmesini sağlayan işlev, guess amacı içinde yapılandırılacağından Actions Builder'da ek yapılandırma yapmanız gerekmez.

Webhook

Bu bölümde webhook'unuzu, kullanıcının oyunu kazandığında veya kaybettiğinde işleme koyan mantıkla güncelleyecek ve oyunu uygun kazanan veya kaybeden ekranla güncelleyen web uygulaması mantığıyla eşleyeceksiniz.

Webhook'unuzu güncellemek için aşağıdaki adımları uygulayın:

Actions konsolunda, gezinme çubuğunda Webhook'u tıklayın.
guess işleyicinin altında index.js öğesine şu kodu ekleyin:

index.js (Bölüm D):

// Add Section D `if (userHasWon)` content here.
    if (userHasWon) {
      conv.add(`<speak>Let's see if your guess is there...<break
        time='2500ms'/> ${guess} is right. That spells ${correctWord}!  
        ${randomArrayItem(WIN_RESPONSES)}</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'WIN_GAME',
          displayedWord: displayedWord
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (Bölüm E):

// Add Section E `}` here.
}

index.js (Bölüm F):

// Add Section F `Check if the user has exceeded the maximum` content here.
// Check if the user has exceeded the maximum amount of max guesses allowed.
    const userHasLost = conv.context.canvas.state.incorrectGuesses + 1 >= MAX_INCORRECT_GUESSES;
    if (userHasLost) {
      conv.add(`<speak>Let's see if your guess is there...<break
      time='2500ms'/> ${guess} is wrong. Sorry you lost. The word is ${correctWord}!</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'LOSE_GAME',
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (G Bölümü):

// Add Section G `}` here.
}

Sipariş Karşılamayı Kaydet'i tıklayın.
Dağıtımı Dağıt'ı tıklayın. Dağıtım tamamlandığında Cloud Function dağıtımınız güncel mesajı gösterilir.

Burada, kullanıcılar oyunu kazandığında veya kaybettiğinde yönetmek için WIN_GAME ve LOSE_GAME komutlarını içeren iki Canvas yanıtı eklediniz. Sonraki bölümde, kullanıcının kazanmasına veya kaybetmesine bağlı olarak web uygulamasını güncelleyen işlev ekleyeceksiniz.

Web uygulaması

Artık web uygulamanızı, kullanıcının kazanmasına veya kaybetmesine göre güncelleme yapacak şekilde yapılandırabilirsiniz. Web uygulamanızı güncellemek için aşağıdaki adımları uygulayın:

public/js/action.js dosyasını metin düzenleyicinizde açın.
Web uygulamanızı WIN_GAME ve LOSE_GAME komutlarını işleyecek şekilde güncelleyin:

action.js (Bölüm H):

// Add Section H `WIN_GAME: (params) => {` content here.
      WIN_GAME: (params) => {
        this.gameScene.winGame(params);
      },
      LOSE_GAME: (params) => {
        this.gameScene.loseGame();
      },

Web uygulamasını güncellemek için aşağıdaki komutu çalıştırın:

firebase deploy --project {PROJECT_ID} --only hosting

İşleminizi simülatörde test etme

İşleminiz bu noktada kullanıcı oyunu kazandığında veya kaybettiğinde başa çıkabilir ve her sonuç için uygun ekranı sunar.

İşleminizi test etmek için şu adımları uygulayın:

Actions konsolu gezinme çubuğunda Test et'i tıklayın.
Giriş alanına Talk to Snow Pal sample yazıp Enter tuşuna basın.
Giriş alanına Yes yazıp Enter tuşuna basın. Alternatif olarak Oyunu başlat düğmesini de tıklayabilirsiniz.
Kazanana veya kaybedene kadar harf ve kelime tahmin edin.

Tekrar oynamak için isterseniz, tekrar oynamak için gereken işlevin henüz eklenmediğini belirten bir mesaj alırsınız. Bu işlevi bir sonraki bölümde ekleyeceksiniz.

Kodu anlama

Kazanma ve kaybetme işlevi, tahmin işleviyle aynı şekilde çalışır. Kullanıcı guess niyetiyle eşleşir ve webhook'unuz da kullanıcının tahminini değerlendirir. Tahmini doğruysa kod, kullanıcının kazanıp kazanmadığını kontrol eder. varsa WIN_GAME komutu web uygulamasına gönderilir. Tahmini yanlışsa kod, kaybedip kaybetmediğini kontrol eder. LOSE_GAME komutu web uygulamasına gönderilir. Bu komutlar, scene.js oyunundaki winGame() ve loseGame() işlevlerini tetikler. Bu işlevler, web uygulamasını kazanan veya kaybeden ekranı gösterecek ve oyunun durumunu güncelleyecek şekilde günceller.

8. Tekrar oynatma işlevi ekleme

Bu bölümde, kullanıcının yeni bir oyuna başlamak için "Tekrar oyna" demesini veya web uygulamasındaki Tekrar Oyna düğmesini tıklamasını sağlayan işlevler eklersiniz. Actions Builder'da play_again amacını, web uygulamasını uygun şekilde güncelleyen bir canvas yanıtı gönderecek şekilde değiştirir ve kullanıcı Tekrar Oyna düğmesini tıkladığında play_again amacını tetikleyen bir mantık eklersiniz.

Konuşma İşlemi

Önceki bölümde İşleminizi test ettiğinizde, oyunu tekrar oynamayı denediğinizde şu istemi aldınız: "Bu çok iyi olurdu, ancak bu işlevi sonraki bir bölümde geliştireceğiz. Şimdilik yalnızca işlemi sıfırlayabilirsiniz." Artık bu istemi silip yerine, kullanıcı başka bir oyun istediğinde ("Tamam, işte başka bir oyun daha!") yanıt veren ve web uygulamasını yeni bir oyun başlatması için canvas yanıtı içeren istemle değiştirebilirsiniz.

Kullanıcı tekrar oynamak istediğinde istemi güncellemek için aşağıdaki adımları uygulayın:

Actions konsolunda Sahne açılır menüsünü tıklayın.
Oyun sahnesini tıklayın.
Kullanıcı amacı işleme altında play_again eşleştirildiğinde'i tıklayın.
İstemi şununla değiştirin:

candidates:
  - first_simple:
      variants:
        - speech: 'Okay, here''s another game!' 
    canvas:
      sendStateDataToCanvasApp: true

Kaydet'i tıklayın.

Webhook

Bu codelab'de webhook, oyun mantığını yönetir. Tekrar oynat işlevi herhangi bir mantık doğrulaması gerektirmediğinden webhook'u çağırmanıza da gerek yoktur. bunun yerine, gerekli verileri web uygulamasına iletmek için doğrudan Actions Builder'dan canvas yanıtı gönderebilirsiniz (bunu önceki bölümde yapılandırmıştınız).

Web uygulaması

Artık kullanıcı tekrar oynamak istediğinde web uygulaması dosyalarınızı uygun şekilde güncellenecek şekilde değiştirebilirsiniz. Bu işlevi eklemek için aşağıdaki adımları izleyin:

public/js/action.js dosyasını metin düzenleyicinizde açın.
PLAY_AGAIN komutunu işleyecek şekilde web uygulamasını güncelleyin:

action.js (Bölüm I):

// Add Section I `PLAY_AGAIN: (params) => {` content here.
      PLAY_AGAIN: (params) => {
        this.gameScene.start();
      },

public/js/scene.js dosyasını metin düzenleyicinizde açın.
Kullanıcı "Tekrar Oyna"yı tıkladığında yeni bir oyun oturumu başlatmak için web uygulamasını güncelleyin. düğme:

sahne.js (Bölüm J):

// Add Section J `sendTextQuery` content here.
     window.interactiveCanvas.sendTextQuery('Play again');

Web uygulamasını güncellemek için aşağıdaki komutu çalıştırın:

firebase deploy --project {PROJECT_ID} --only hosting

İşleminizi simülatörde test etme

İşleminiz artık kullanıcı "Tekrar oyna" dediğinde veya Tekrar Oyna düğmesini tıkladığında yeni bir oyun oturumu başlatabilir.

İşleminizi test etmek için şu adımları uygulayın:

Gezinme çubuğunda Test et'i tıklayın.
Giriş alanına Talk to Snow Pal sample yazıp Enter tuşuna basın.
Giriş alanına Yes yazıp Enter tuşuna basın. Alternatif olarak Oyunu başlat düğmesini de tıklayabilirsiniz.
Kazanana veya kaybedene kadar harf ve kelime tahmin edin.
Giriş alanına Play again yazıp Enter tuşuna basın. Alternatif olarak, Tekrar oyna düğmesini de tıklayabilirsiniz.

Kodu anlama

İşleminizi test ettiğinizde ses girişi ("Tekrar oyna") veya dokunmatik girişle (Tekrar oyna düğmesini tıklayarak) yeni bir oyun başlatabilirsiniz.

Ses girişi seçeneğinde, kullanıcı "Tekrar oyna" dediğinde veya bunun bir varyasyonunu söylediğinde play_again niyeti eşleştirilir ve istem sırasına bir istem ("Tamam, başka bir oyun daha!") ekler. İsteme dahil edilen canvas yanıtı, amaç adını ve diğer meta verileri web uygulamasına gönderir. Amaç adı onUpdate() geri çağırmasına iletilir ve bu komut da ilgili komutu (PLAY_AGAIN) action.js konumundaki komut eşlemesiyle eşler. PLAY_AGAIN komutu, scene.js içinde start() işlevini tetikler ve web uygulamasını yeni bir oyun oturumuyla günceller.

Dokunmatik giriş seçeneği olarak, düğmenin çalışması için dokunmatik giriş aracılığıyla intent tetiklemenize olanak tanıyan Interactive Canvas API'si sendTextQuery()'yi kullanıyorsunuz.

Bu codelab'de, kullanıcı Tekrar oynat düğmesini tıkladığında play_again amacını çağırmak için sendTextQuery() yöntemini kullanırsınız. Play again bağımsız değişkeni, play_again amacındaki bir eğitim ifadesiyle eşleşir ve bu amacı, kullanıcının "Tekrar oynat" demesine benzer şekilde tetikler. Ardından play_again amacı, web uygulamasını güncelleyen ve yeni bir oyun oturumu başlatan mantığı tetikler.

9. PLAY_GAME yerleşik amacını güncelleme

Bu bölümde, PLAY_GAME yerleşik intent'i güncellersiniz.

PLAY_GAME yerleşik amacı, kullanıcıların "Oyun oynamak istiyorum" gibi genel bir istekte bulunduklarında İşleminizi çağırmalarına olanak tanır.

Kaynak kodu, /sdk/custom/global/actions.intent.PLAY_GAME.yaml adresinde bulunan PLAY_GAME yerleşik amacını içeriyor. Bu durum, konsoldaki Çağrı bölümünde PLAY_GAME olarak aşağıdaki ekran görüntüsünde gösterildiği gibi yansıtılır:

Kullanıcıların işleminizi bu yerleşik intent aracılığıyla çağırmasını sağlamak için PLAY_GAME yerleşik amacına web uygulaması URL'sini içeren bir canvas yanıtı eklemeniz gerekir. Bunun için, aşağıdaki adımları uygulayın:

Actions konsolunda, gezinme çubuğunda PLAY_GAME'yi tıklayın.
İstemi, aşağıdaki snippet'te gösterildiği gibi web uygulaması URL'nizi içerecek şekilde güncelleyin:

candidates:
  - canvas:
      url: 'https://<PROJECT_ID>.web.app'

Kaydet'i tıklayın.

İşleminizi simülatörde test etme

İşleminiz artık PLAY_GAME yerleşik amacını destekliyor.

İşleminizi test etmek için şu adımları uygulayın:

Gezinme çubuğunda Test et'i tıklayın.
Yerleşik amaç işlemeyi test et'i tıklayın.
İşlemi çağır'ı tıklayın.

İşleminiz simülatörde çağrılmalıdır.

10. Ek: Etkileşimli Tuval İşlemi ile ilgili sorunları giderme

Bu bölümde, Etkileşimli Tuval İşleminiz düzgün çalışmadığında nasıl hata ayıklayacağınızı öğreneceksiniz. Snow Pal projesi, etkinleştirebileceğiniz bir hata ayıklama yer paylaşımıyla birlikte hazır olarak gelir. Yer paylaşımı, tüm console.log() ve console.error() çıkışını aşağıdaki ekran görüntüsünde gösterildiği gibi ekranın sağ alt köşesinde görüntüler:

Bu yer paylaşımını etkinleştirmek için /public/css/main.css dosyasını açın ve display: none !important; satırını aşağıdaki snippet'te gösterildiği gibi yorumlayın:

main.css

.debug {
 display: flex;
 flex-direction: column;

/* Comment below to view debug overlay */
/* display: none !important; */

 width: 500px;
 height: 150px;
 right: 0;
 bottom: 0;
 position: absolute;
}

Projenizi temizleme [önerilir]

Olası ücretlerden kaçınmak için kullanmayı düşünmediğiniz projeleri kaldırmanız önerilir. Bu codelab'de oluşturduğunuz projeleri silmek için şu adımları uygulayın:

Google Cloud projesini ve kaynaklarını silmek için Projeleri kapatma (silme) bölümünde listelenen adımları tamamlayın.

İsteğe bağlı: Projenizi Actions konsolundan hemen kaldırmak için Proje silme bölümünde listelenen adımları tamamlayın. Bu adımı tamamlamazsanız projeniz yaklaşık 30 gün sonra otomatik olarak kaldırılır.

11. Tebrikler!

Tanıtım amaçlı Etkileşimli Tuval codelab'ini tamamladınız ve artık kendi Etkileşimli Tuval İşleminizi oluşturmak için gereken becerilere sahipsiniz.

Öğrendikleriniz

Etkileşimli Tuval İşlemi oluşturma, dağıtma ve test etme
Web uygulamasını güncellemek için Canvas yanıtları nasıl kullanılır?
İşleminizi iyileştirmek için sendTextQuery() ve setCanvasState() gibi farklı yöntemleri kullanma
İşleminizde hata ayıklama

Daha fazla bilgi

Etkileşimli Tuval hakkında daha fazla bilgi edinmek için aşağıdaki kaynaklara göz atın:

Etkileşimli Tuval dokümanları: Etkileşimli Tuval için resmi Actions on Google dokümanları.
Etkileşimli Tuval örneği: Bir üçgeni döndürmenize ve renklerini değiştirmenize olanak tanıyan basit bir Etkileşimli Tuval oyununun kodu.
Oyunlar portalı: Google Asistan'da oyun geliştirmeyle ilgili yönergeler.

Geri bildirim anketi

Ayrılmadan önce lütfen deneyiminizle ilgili kısa bir anketi doldurun.