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

1. Genel Bakış

Actions on Google, akıllı hoparlörler, telefonlar, arabalar, TV'ler, kulaklıklar ve daha fazlası dahil olmak üzere 1 milyardan fazla cihazda Google'ın sanal kişisel asistanı Google Asistan'ın işlevselliğini genişletmek için yazılım oluşturmanıza olanak tanıyan bir geliştirici platformudur. Kullanıcılar, Google Asistan ile konuşarak alışveriş yapma veya araç rezervasyonu yapma gibi işlemleri gerçekleştirir. Şu anda mümkün olan işlemlerin tam listesi için İşlemler dizinine bakın. Geliştirici olarak, kullanıcılar ile kendi üçüncü taraf hizmetiniz arasında keyifli ve faydalı sohbet deneyimleri oluşturup yönetmek için Actions on Google'ı kolayca kullanabilirsiniz.

Bu codelab, Google Asistan için İşlemler oluşturma konusunda deneyimli okuyuculara yönelik ileri düzey bir modüldür. Google'da Actions on Google ile ilgili daha önce geliştirme deneyiminiz yoksa giriş seviyesindeki codelab'leri ( 1. Seviye ve 2. Seviye) tamamlayarak platform hakkında bilgi edinin. Bu modüller, işleminizin işlevselliğini genişletmenize ve kitlenizi büyütmenize yardımcı olabilecek bir dizi özellik konusunda size yol gösterecektir.

Bu codelab'de, Google Asistan üzerinde oluşturulmuş bir çerçeve olan Etkileşimli Tuval'i kullanarak bir Conversational Action'a tam ekran oyun ekleyeceksiniz. Oyun, Asistan'ın sohbette 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 sesli veya metin girişiyle oynayabilir.

Tüm oyunu kendiniz oluşturmak yerine, kısmen önceden oluşturulmuş Snow Pal adlı oyunu dağıtıp codelab'de ilerledikçe oyunun mantığını ekleyeceksiniz. Snow Pal, geleneksel Adam Asmaca oyununun bir çeşididir. Oyunda, bir kelimeyi temsil eden bir dizi boşluk gösterilir ve kelimede olabileceğini düşündüğünüz harfleri tahmin edersiniz. Her yanlış tahminde Kar Arkadaşınız biraz daha erir. Kar arkadaşınız tamamen erimeden kelimeyi bulursanız oyunu kazanırsınız.

Şekil 1. Kısmen tamamlanmış bir Kar Arkadaşı oyunu

Ne oluşturacaksınız?

Bu codelab'de, Etkileşimli Tuval'i kullanan bir İşlem oluşturacaksınız. İşleminizde aşağıdaki özellikler bulunur:

Kullanıcıların sesle oynayabileceği tam ekran kelime oyunu
Kullanıcıların oyunu başlatmak için basabileceği bir düğme
Kullanıcıların oyunu tekrar oynamak için basabileceği bir düğme

Bu codelab'i tamamladığınızda, tamamlanan işleminiz aşağıdaki sohbet 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 harf tahmin etmeye veya bilinmeyen kelimeyi tahmin etmeye devam eder.

Neler öğreneceksiniz?

Etkileşimli Tuval işlemi oluşturma ve dağıtma
Kullanıcının ses ve dokunma girişine göre kelime oyununu güncelleme
Farklı yöntemler kullanarak web uygulamasına veri aktarma
Etkileşimli Tuval İşleminizde hata ayıklama

İhtiyacınız olanlar

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

Google Chrome gibi bir web tarayıcısı
Seçtiğiniz bir IDE veya metin düzenleyici
Makinenizde Node.js, npm ve git yüklü olmalıdır.

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ı: Tam örnek kodu alma

Bu codelab'de, eksik bir sürümden adım adım örnek oluşturacaksınız. İsterseniz tamamlanmış örneği GitHub deposundan da alabilirsiniz.

2. Etkileşimli Tuval'e giriş

Etkileşimli Tuval, Google Asistan'ın üzerine inşa edilmiş bir çerçevedir. Bu çerçeve, etkileşimli işleminize tam ekran görseller ve animasyonlar eklemenize olanak tanır.

Etkileşimli Tuval'i kullanan bir Action, normal bir Conversational Action'a benzer şekilde çalışır. Ancak Etkileşimli Canvas İşlemi, tam ekran web uygulaması açan cihaza yanıt gönderme gibi ek bir özelliğe sahiptir.

Kullanıcı, sohbet bitene kadar web uygulamasına ses veya dokunma yoluyla giriş yapar.

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

Bu codelab'de projeniz aşağıdaki üç ana bölümden oluşur:

Web uygulaması: Web uygulaması dosyaları, web uygulamanızın görselleri ve animasyonlarının kodunu, ayrıca web uygulamasını kullanıcının girişine göre güncelleme mantığını içerir.
Sohbet İşlemi: Sohbet İşlemi, kullanıcının girişini tanıyan, işleyen ve yanıtlayan sohbet 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, etkileşimli Canvas işleminize işlevsellik eklemek için web uygulamasını, etkileşimli işlemi ve webhook'u değiştirirsiniz.

Snow Pal işlemindeki etkileşimli işlem, webhook ve web uygulaması genel olarak şu şekilde çalışır:

Sohbet İşlemi, kullanıcıdan kelimedeki bir harfi veya kelimenin tamamını tahmin etmesini ister.
Kullanıcı, akıllı ekranda Snow Pal web uygulamasına "I guess the letter i" (I harfini tahmin ediyorum) diyor.
Kullanıcının girişi, Actions Builder ve/veya Actions SDK projenizde tanımlanan etkileşimli işleminize yönlendirilir.
Sohbet İşlemi, kullanıcının girişini işler ve girişe bağlı olarak web uygulamasını güncelleyen webhook'taki mantığı tetikler veya web uygulamasını doğrudan güncellemek için meta verileri gönderir.
Web uygulaması, harfin kelimede nerede göründüğünü gösterecek şekilde güncellenir ve kullanıcıdan tekrar tahmin etmesi istenir.

Etkileşimli Canvas'ın işleyiş şekli hakkında daha fazla bilgiyi Etkileşimli Canvas altyapısını anlama bölümünde bulabilirsiniz. Temel bilgileri edindiğinize göre artık bu codelab için ortamınızı ayarlamaya başlayabilirsiniz.

3. Kur

Google izin ayarlarınızı kontrol etme

Bu codelab için oluşturduğunuz işlemi test etmek üzere, Actions Console simülatörünün işleminize erişebilmesi için gerekli izinleri etkinleştirmeniz gerekir. İzinleri etkinleştirmek için aşağıdaki 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, İşlemler projenizi İşlemler 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'yı 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ü (CLI), Actions projenizi Cloud Functions'a dağıtmanıza ve web uygulamanızı barındırmanıza olanak tanır.

Bu codelab'de Firebase CLI'yı yüklemek için npm kullanılı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çıp aşağıdaki npm komutunu çalıştırın:

npm install -g firebase-tools

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

firebase --version

Firebase CLI sürümünün 8 veya daha yeni olduğundan emin olun. Böylece, Cloud Functions için gereken en yeni özelliklerin tümüne sahip olursunuz. Değilse yükseltmek 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ş yaparken İşlemler projenizi oluşturmak için 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ı uygulayın:

Bir terminal açın ve genellikle kodlama projelerini sakladığınız bir dizine geçin. 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 depoda, üzerinde çalışacağınız aşağıdaki önemli dizinler bulunur:

public/: Bu dizinde web uygulamanızın HTML, CSS ve JavaScript kodu bulunur.
sdk/custom/: Bu dizinde, etkileşimli işleminizin mantığı (sahneler, amaçlar ve türler) yer alır.
sdk/webhooks/: Bu dizin, webhook'unuzdur ve oyun mantığını içerir.

Şekil 3. startDizin kodunun yapısı.

4. Actions projenizi oluşturma

Bu bölümde, Actions projenizi oluşturup yapılandıracak, klonlanmış depodaki kodu gactions CLI ile Actions Console'a gönderecek ve web uygulamanızı ve webhook'unuzu dağıtacaksınız.

Actions projesi oluşturma

Actions projeniz, işleminiz için bir kapsayıcıdır. Bu codelab için Actions projenizi oluşturmak üzere aşağıdaki 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 yalnızca kendi kullanımınız içindir. Daha sonra projeniz için harici bir ad belirleyebilirsiniz.

Proje oluştur'u tıklayın.
Ne tür bir iş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.

İşleminizin proje kimliğini kaydetme

Proje kimliği, işleminizin benzersiz tanımlayıcısıdır. Bu codelab'deki çeşitli adımlar için proje kimliğinize ihtiyacınız olacak.

Proje kimliğinizi almak için şu adımları uygulayın:

İşlemler konsolunda üç dikey nokta > Proje ayarları'nı tıklayın.

Proje kimliğini kopyalayın.

Faturalandırma hesabı ilişkilendirme

Bu codelab'in ilerleyen bölümlerinde Cloud Functions'ı kullanarak karşılama işlevinizi dağıtmak için Google Cloud'da projenizle bir faturalandırma hesabı ilişkilendirmeniz gerekir. Faturalandırma hesabınız varsa aşağıdaki adımları yoksayabilirsiniz.

Faturalandırma hesabını projenizle ilişkilendirmek için aşağıdaki 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 Faturalandırmayı gönder ve etkinleştir'i tıklayın.
Google Cloud faturalandırma sayfasına gidin.
Projelerim sekmesini tıklayın.
Üç nokta simgesi > Faturalandırmayı değiştir'i tıklayın.
Açılır menüden yapılandırdığınız faturalandırma hesabını seçin.
Hesap belirle'yi tıklayın.

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

Web uygulaması dağıtma

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

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

Terminalde start/ dizinine gidin.
{PROJECT_ID} yerine proje kimliğinizi yazarak aşağıdaki komutu çalıştırın:

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

Birkaç dakika sonra, Snow Pal web uygulamasını Firebase'e başarıyla dağıttığınızı belirten "Deploy complete!" mesajını görürsünüz.

Kar Arkadaşı oyununu tarayıcıda görüntülemek için aşağıdaki adımları uygulayın:

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

URL'yi bir tarayıcıya yapıştırın. Oyunu Başlat düğmesiyle birlikte Snow Pal oyununun başlangıç ekranını görmelisiniz:

Web uygulaması URL'sini ve proje kimliğini Actions projesine ekleme

Ardından, web uygulamanızın URL'sini ve proje kimliğinizi actions.intent.MAIN.yaml dosyasına ekleyin. Web uygulaması URL'sini eklediğinizde Etkileşimli İşlem, verileri hangi URL'ye göndereceğini bilir. settings.yaml bölümüne proje kimliğini eklediğinizde ise indirilen dosyaları İşlemler Konsolu'ndaki doğru projeye gönderebilirsiniz.

Web uygulamanızın URL'sini ve proje kimliğinizi eklemek için aşağıdaki 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 uygulamanızın URL'siyle değiştirin.
start/sdk/settings/settings.yaml dosyasını metin düzenleyicinizde açın.
projectId alanında yer tutucu dizeyi proje kimliğinizle değiştirin.

Projeyi Actions Console'a aktarma

Actions Console'u yerel projenizle güncellemek için Actions projenizi Actions Console'a göndermeniz gerekir. Bunun için, aşağıdaki adımları uygulayın:

sdk dizinine geçin:

cd sdk/

Yerel dosya sisteminizin yapılandırmasını İşlemler Konsolu'na kopyalamak için aşağıdaki komutu çalıştırın:

gactions push

Webhook'u dağıtma

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

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

Actions konsolunda gezinme çubuğundaki Geliştir'i tıklayın.
Gezinme çubuğunda Webhook sekmesini tıklayın.
Deploy Fulfillment'ı (İsteği Yerine Getirme İşlemini Dağıt) tıklayın.

Cloud Functions'ın karşılama işlevinizi sağlaması ve dağıtması birkaç dakika sürebilir. Cloud Functions dağıtımı devam ediyor... mesajını görmeniz gerekir. Kod başarıyla dağıtıldığında mesaj Cloud Functions işlevi dağıtımınız güncel olarak güncellenir.

Simülatörde test etme

Bu noktada, İşleminiz web uygulamasına bağlanır. İşleminizi çağırdığınızda web uygulamasının göründüğünden emin olmak için Actions Console simülatörünü kullanabilirsiniz.

İşleminizi test etmek için aşağıdaki adımları uygulayın:

İşlemler konsolu gezinme çubuğunda Test'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'ı tıklayın.

Henüz bir harfi veya kelimeyi tahmin etme mantığını yapılandırmadığınız için bir kelime ya da harf tahmin ettiğinizde "...Yanlış. Denemeye devam edin. Bu özelliğin düzgün çalışması için daha fazla işlev eklememiz gerekiyor."

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

Bu projede işlevsellik üç ana bileşene ayrılmıştır: Sohbet İşlemi, web uygulaması ve webhook. Bu modelin, İşleminizi nasıl ayarlayabileceğinize dair bir örnek olduğunu ve Interactive Canvas'ın temel işlevini vurgulamak için bu şekilde düzenlendiğini unutmayın.

Aşağıdaki bölümlerde, etkileşimli işlem, webhook ve web uygulamasının birlikte nasıl çalıştığı ile diğer önemli Etkileşimli Tuval öğeleri hakkında daha ayrıntılı bilgi verilmektedir.

Sohbet İşlemi

İşleminizin etkileşimli işlem bileşeni, kullanıcının girişini tanıma, işleme ve uygun sahneye gönderme işlemlerini gerçekleştirir. Bu sahnede kullanıcıya yanıt oluşturulur. Örneğin, bir kullanıcı Snow Pal oyununda "E harfi olduğunu tahmin ediyorum" derse etkileşimli işleminiz harfi amaç parametresi olarak ayıklar ve tahminin doğru olup olmadığını belirleyip web uygulamasını buna göre güncelleyen uygun oyun mantığına iletir. Bu etkileşimli mantığı, Actions Console'daki web tabanlı bir IDE olan Actions Builder'da görüntüleyip değiştirebilirsiniz. Aşağıdaki ekran görüntüsünde, Actions Builder'daki etkileşimli işleminizin bir bölümü gösterilmektedir:

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

Bu ekran görüntüsünde, kullanıcıların "Ok Google, Snow Pal örneğiyle konuş" gibi bir ifade söylediğinde eşleşen İşleminizin Main invocation gösterilmektedir. Kullanıcı İşleminizi çağırdığında Main invocation, web uygulamanızın URL'sini içeren bir canvas yanıtıyla birlikte istem gönderir.

İşleminizdeki ilk canvas yanıt, web uygulaması URL'sini içermelidir. Bu yanıt, Asistan'a web uygulamasını kullanıcının cihazında bu adreste oluşturmasını söyler. Actions Builder'daki ek canvas yanıtları, true olarak ayarlanan bir send_state_data_to_canvas_app alanı içerebilir. Bu alan, amaç eşleştirildiğinde amaç adını ve tüm parametre değerlerini web uygulamasına gönderir. Web uygulaması, kullanıcının girişinden alınan bu verilere göre güncellenir.

Webhook

Bu codelab'de webhook'unuz oyun mantığını içerir (webhook'unuzu oyun sunucusu gibi düşünebilirsiniz). Oyun mantığı, kullanıcının tahmininin doğru veya yanlış olup olmadığını ya da kullanıcının kazanıp kazanmadığını belirleme ve sonuca göre 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'u çağırır. Örneğin, Game sahnesindeki guess amacı, guess işleyicisine bir webhook çağrısı yapar. Bu işleyici, kullanıcının tahmininin doğru olup olmadığını belirlemek için mantığı yürütür. Webhook, web uygulaması dosyalarıyla eşlenen işleyicilerde Canvas yanıt içerebilir ve web'i uygun şekilde güncelleyebilir.

Web uygulaması

Şekil 5. Etkileşimli Tuval işleminde, etkileşimli işlem, webhook ve web uygulaması arasındaki etkileşimin görsel temsili.

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

Etkileşimli işlem ile web uygulaması arasında iletişim kurma

Web uygulamanızın kullanıcı girişine göre güncellenebilmesi için etkileşimli işleminiz ile web uygulamanız arasındaki iletişimi etkinleştirmeniz gerekir. Örneğin, bir kullanıcı "F harfi olduğunu tahmin ediyorum" derse

Sohbet İşlemi, web uygulamasının buna göre güncelleme yapabilmesi için web uygulamasına f harfini sağlamalıdır. Kullanıcının girişini etkileşimli işlemden web uygulamasına aktarmak için Etkileşimli Tuval API'sini yüklemeniz gerekir.

Bu API'nin komut dosyası, Snow Pal oyununun ana HTML dosyası olan /public/index.html'da yer alır. Bu dosya, kullanıcı arayüzünüzün çeşitli alfabelerde nasıl görüneceğini ve yükleneceğ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ının girişine göre güncellemek için web uygulaması dosyanızda geri çağırma işlevlerini de kaydetmeniz ve yapılandırmanız gerekir. Geri çağırmalar, web uygulamanızın etkileşimli işlemden gelen bilgilere veya isteklere yanıt vermesini sağlar.

/public/js/action.js'da geri çağırmaları bildirmek ve kaydetmek için Action adlı önceden yapılandırılmış bir sınıf vardır. Action sınıfı, Etkileşimli Tuval API'sinin sarmalayıcısıdır. Web uygulaması scene.js içinde create() işleviyle oluşturulduğunda, aşağıdaki snippet'te gösterildiği gibi yeni bir Action örneği oluşturulur ve 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ı bildirir 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ı bildirir.

Sonraki bölümde, bu projeye özel kodun, verileri etkileşimli işlemden web uygulamasına aktaracak şekilde nasıl yapılandırıldığı açıklanmaktadır.

Web uygulamasını kullanıcının girişine göre güncelleme

Bu codelab'de, kullanıcının girişine göre web uygulamasını güncellemek için bir komut haritası kullanacaksınız. Örneğin, Welcome sahnesinde start_game amacı eşleştirildiğinde istemde yer alan 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'deki start() işlevini çağırır ve web uygulamasını yeni bir oyun oturumu başlatacak şekilde 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() adlı bir işlevi 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 mevcut 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 sohbet dönüşü için kullanılabilir. Bu duruma, aşağıdaki kod snippet'inde gösterildiği gibi webhook'ta conv.context.canvas.state üzerinden erişebilirsiniz:

index.js

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

6. Tahmin işlevi ekleme

Bu bölümde, kullanıcının kelime içindeki harfleri veya kelimenin kendisini tahmin etmesini sağlayan guess işlevini İşleminize eklersiniz.

Sohbet İşlemi

Simülasyon aracında test etme bölümünde, "Bunun düzgün çalışması için daha fazla işlev eklememiz gerekiyor." ifadesinin yer aldığı bir yanıt aldınız. Artık İşlemler konsolunda bu istemi silebilirsiniz. Böylece yalnızca webhook'u çağırırsınız (Game sahnesinde, guess amacı eşleştiğinde webhook çağrısı yapacak şekilde zaten yapılandırılmıştır).

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

İşlemler konsolunda, gezinme çubuğundaki Sahneler'i tıklayın.
Game sahnesine gitmek için Oyun'u tıklayın.
Kullanıcı amacını 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, kullanıcının doğru veya yanlış tahminini bir web uygulaması dosyasındaki mantığa eşleyen mantıkla webhook'unuzu güncellersiniz. Bu mantık daha sonra web uygulamasını buna göre günceller. Webhook'ta guess amaç işleyici sizin için önceden yapılandırılmıştır. Bu nedenle, web uygulamasını güncelleyen mantığı tetiklemek için bu amaca yalnızca Canvas yanıtları eklemeniz gerekir.

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

İşlemler Konsolu'nda gezinme çubuğundaki Webhook'u tıklayın.
index.js işleyicisinin altına aşağıdaki kodu ekleyin:guess

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

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

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

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

Save Fulfillment'ı (Yerine Getirme İşlemini Kaydet) tıklayın.
Deploy Fulfillment'ı (İsteği Yerine Getirme İşlemini Dağıt) tıklayın. Dağıtım tamamlandığında Cloud Functions 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.
Web uygulamasını CORRECT_ANSWER ve INCORRECT_ANSWER komutlarını işleyecek şekilde güncelleyin:

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

// 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 tahminin doğru mu yoksa yanlış mı olduğunu anlayabilir ve web uygulamasını buna göre güncelleyebilir.

İşleminizi test etmek için aşağıdaki adımları uygulayın:

Gezinme çubuğunda Test'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 tıklayın.
Tahmin etmek istediğiniz harfi Giriş alanına yazıp Enter tuşuna basın.

Kodu anlama

Önceki bölümde, kullanıcıların oyununuzda harfleri tahmin etmesine ve bu tahminlerin kelimeye veya Kar Arkadaşı'na yansıtılmasına olanak tanıyan bir kod eklediniz. Özet olarak, guess amacı eşleştiğinde İşlemler Oluşturucu'da bir webhook çağrısı yaparsınız. Bu çağrı, web uygulamanızı buna göre güncellemek için verileri web uygulamanıza iletir. Örneğin, kullanıcı Snow Pal oyununda kelimede bulunan bir harfi tahmin ederse web uygulaması, harfi kelimede doğru konumda gösterecek şekilde güncellenir.

Interactive Canvas'ı kullanan işlemler için verilerin webhook'tan web uygulamasına aktarılmasıyla ilgili genel akış aşağıdaki gibidir:

Kullanıcının girişi, Canvas yanıtı içeren bir amaçla eşleşiyor.
Görüşme işlemi veya webhook, Canvas yanıtını gönderir. Bu yanıt, onUpdate() geri çağırmasını tetikler.
onUpdate() geri çağırma, web uygulamasını buna göre güncelleyen özel mantıkla eşlenir.

Bu projede kod şu şekilde çalışır:

Kullanıcı guess niyetiyle eşleştiğinde Actions Builder, kullanıcının girişindeki harfi parametre olarak ayıklar.
Actions Builder, webhook'unuzdaki guess işleyicisini çağırır. Bu işleyici, kullanıcının tahmin ettiği harfin kelimede olup olmadığını belirleyecek mantığı içerir.
guess işleyicisi iki Canvas yanıtı içerir: biri harf doğru olduğunda, diğeri ise harf yanlış olduğunda yürütülür. 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 içindeki onUpdate() yöntemine iletilir. onUpdate(), scene.js içindeki komut eşlemesinde uygun komutu çağırır.
Komut haritası, scene.js içindeki correctAnswer() ve incorrectAnswer() işlevleriyle eşlenir. Bu işlevler, kullanıcının tahminini yansıtacak şekilde web uygulamasını uygun şekilde günceller ve web uygulamanızdaki durum verilerini webhook'unuza göndermek için setCanvasState() işlevini çağırır.

7. Kazanma/kaybetme işlevi ekleme

Bu bölümde, kullanıcının kazanıp kazanmadığını belirleyen mantık ve kullanıcının sonucuna göre web uygulaması resmini güncelleyen mantık da dahil olmak üzere, kazanma ve kaybetme işlevini İşleminize eklersiniz.

Sohbet İşlemi

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

Webhook

Bu bölümde, kullanıcının oyunu kazandığı veya kaybettiği durumları işleyen mantıkla webhook'unuzu günceller ve oyunu uygun kazanma veya kaybetme ekranıyla güncelleyen web uygulaması mantığıyla eşlersiniz.

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

İşlemler Konsolu'nda gezinme çubuğundaki Webhook'u tıklayın.
index.js işleyicisinin altına aşağıdaki kodu ekleyin:guess

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

// 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 (E Bölümü):

// Add Section E `}` here.
}

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

// 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.
}

Save Fulfillment'ı (Yerine Getirme İşlemini Kaydet) tıklayın.
Deploy Fulfillment'ı (İsteği Yerine Getirme İşlemini Dağıt) tıklayın. Dağıtım tamamlandığında Cloud Functions dağıtımınız güncel mesajı gösterilir.

Burada, kullanıcılar oyunu kazandığında veya kaybettiğinde yapılacak işlemleri belirlemek için WIN_GAME ve LOSE_GAME komutlarıyla iki Canvas yanıtı eklediniz. Sonraki bölümde, kullanıcının kazanıp kazanmadığına göre web uygulamasını güncelleyen işlevler ekleyeceksiniz.

Web uygulaması

Artık web uygulamanızı, kullanıcının kazanıp kazanmadığına göre güncellenecek ş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 (H Bölümü):

// 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

Bu noktada İşleminiz, kullanıcının oyunu kazanması veya kaybetmesi durumunu yönetebilir ve her sonuç için uygun ekranı gösterebilir.

İşleminizi test etmek için aşağıdaki adımları uygulayın:

İşlemler konsolu gezinme çubuğunda Test'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 tıklayın.
Kazanana veya kaybedene kadar harf ve kelime tahmin edin.

Tekrar oynamak istediğinizde, tekrar oynamak için gerekli 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 amacına uygun bir tahmin yapar ve webhook'unuz kullanıcının tahminini değerlendirir. Tahmin doğruysa kod, kullanıcının kazanıp kazanmadığını kontrol eder. Kullanıcı kazandıysa WIN_GAME komutu web uygulamasına gönderilir. Tahmin yanlışsa kod, kullanıcının kaybedip kaybetmediğini kontrol eder. Kullanıcı kaybettiyse LOSE_GAME komutu web uygulamasına gönderilir. Bu komutlar, scene.js içindeki winGame() ve loseGame() işlevlerini tetikleyerek web uygulamasını kazanma veya kaybetme ekranını gösterecek şekilde günceller ve oyunun durumunu 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" demesine veya web uygulamasında Tekrar Oyna düğmesini tıklamasına olanak tanıyan işlevler ekleyebilirsiniz. Web uygulamasını uygun şekilde güncelleyen bir canvas yanıtı göndermek için Actions Builder'da play_again niyetini değiştirir ve kullanıcı Tekrar Oyna düğmesini tıkladığında play_again niyetini tetikleyen bir mantık eklersiniz.

Sohbet İşlemi

Önceki bölümde İşleminizi test ettiğinizde oyunu tekrar oynamaya çalıştığınızda şu istemi aldınız: "Bu harika olurdu ancak bu işlevi daha sonraki bir bölümde oluşturacağız. Şimdilik sadece İşlemi sıfırlayın." Artık bu istemi silebilir ve kullanıcının başka bir oyun isteğinde bulunması durumunda yanıt veren ("Tamam, işte başka bir oyun!") ve web uygulamasının yeni bir oyun başlatmasını tetikleyecek bir canvas yanıtı içeren bir 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ı niyeti işleme bölümünde play_again eşleştiğinde'yi tıklayın.
İstemi aşağıdakiyle 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 oynatma işlevi herhangi bir mantık doğrulaması gerektirmediğinden webhook'u çağırmanız gerekmez. Bunun yerine, gerekli verileri web uygulamasına (bunu önceki bölümde yapılandırdınız) iletmek için doğrudan Actions Builder'dan bir canvas yanıtı gönderebilirsiniz.

Web uygulaması

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

public/js/action.js dosyasını metin düzenleyicinizde açın.
Web uygulamasını PLAY_AGAIN komutunu işleyecek şekilde 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" düğmesini tıkladığında yeni bir oyun oturumu başlatmak için web uygulamasını güncelleyin:

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

// 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 aşağıdaki adımları uygulayın:

Gezinme çubuğunda Test'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 tıklayın.
Kazanana veya kaybedene kadar harf ve kelime tahmin edin.
Giriş alanına Play again yazıp Enter tuşuna basın. Alternatif olarak, Tekrar oynat düğmesini tıklayın.

Kodu anlama

İşleminizi test ederken sesli giriş ("Tekrar oyna") veya dokunma girişi (Tekrar oyna düğmesini tıklama) ile yeni bir oyun başlatabiliyordunuz.

Sesli giriş seçeneğinde, kullanıcı "Tekrar oynat" dediğinde veya bunun bir varyasyonunu söylediğinde play_again amacı eşleştirilir ve istem kuyruğuna bir istem ("Tamam, işte bir oyun daha!") eklenir. İstemde yer alan canvas yanıtı, amaç adını ve diğer meta verileri web uygulamasına gönderir. Amaç adı, ilgili komutu (PLAY_AGAIN) action.js içindeki komut haritasına eşleyen onUpdate() geri çağırma işlevine iletilir. 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ğinde, düğmeyi çalıştırmak için dokunmatik girişle bir amaç tetiklemenize olanak tanıyan bir Interactive Canvas API'si olan sendTextQuery()'yı kullanırsınız.

Bu codelab'de, kullanıcı Tekrar oyna düğmesini tıkladığında play_again amacını çağırmak için sendTextQuery() kullanacaksı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" demesiyle aynı şekilde tetikler. play_again niyeti, 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 amacı güncelleyeceksiniz.

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

Kaynak kod, PLAY_GAME yerleşik amacını içerir. Bu amaç, /sdk/custom/global/actions.intent.PLAY_GAME.yaml konumunda bulunur. Bu durum, aşağıdaki ekran görüntüsünde gösterildiği gibi konsoldaki Invocation (Çağırma) bölümünde PLAY_GAME olarak yansıtılır:

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

İşlemler konsolunda, gezinme çubuğundaki PLAY_GAME'i tıklayın.
Aşağıdaki snippet'te gösterildiği gibi istemi web uygulamanızın URL'sini içerecek şekilde güncelleyin:

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

Kaydet'i tıklayın.

İşleminizi simülatörde test etme

Action'ınız artık PLAY_GAME yerleşik amacını destekliyor.

İşleminizi test etmek için aşağıdaki adımları uygulayın:

Gezinme çubuğunda Test'i tıklayın.
Test built-in intent handling'i (Yerleşik amaç işleme özelliğini test et) tıklayın.
Invoke Action'ı (İşlemi Çağır) tıklayın.

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

10. Ek: Etkileşimli Tuval İşlemiyle İlgili Sorunları Giderme

Bu bölümde, etkileşimli Canvas İş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 yerleşimiyle birlikte gelir. Yer paylaşımı, aşağıdaki ekran görüntüsünde gösterildiği gibi tüm console.log() ve console.error() çıkışını ekranın sağ alt kısmında gösterir:

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

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 aşağıdaki 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 hemen Actions Console'dan kaldırmak için Proje silme bölümünde listelenen adımları uygulayın. Bu adımı tamamlamazsanız projeniz yaklaşık 30 gün sonra otomatik olarak kaldırılır.

11. Tebrikler!

Etkileşimli Canvas'a giriş niteliğindeki codelab'i tamamladınız ve artık kendi Etkileşimli Canvas İş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ını kullanma
İşleminizi geliştirmek için sendTextQuery() ve setCanvasState() gibi farklı yöntemleri kullanma
İşleminizde hata ayıklama

Daha fazla bilgi

Etkileşimli Canvas hakkında daha fazla bilgi edinmek için aşağıdaki kaynakları inceleyin:

Etkileşimli Tuval dokümanları: Etkileşimli Tuval ile ilgili resmi Actions on Google dokümanları.
Etkileşimli Tuval örneği: Üçgeni döndürmenize ve renklerini değiştirmenize olanak tanıyan basit bir Etkileşimli Tuval oyununun kodu.
Oyun portalı: Google Asistan'da oyun geliştirme kuralları.

Geri bildirim anketi

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