1. Genel Bakış
Actions on Google, Google'ın sanal kişisel asistanı Google Asistan'ın işlevselliğini akıllı hoparlörler, telefonlar, arabalar, TV'ler ve kulaklıklar dahil olmak üzere 1 milyardan fazla cihazda genişletmenizi sağlayan bir geliştirici platformudur. Kullanıcılar, alışveriş yapma veya araç rezervasyonu yapma gibi işlemleri gerçekleştirmek için Asistan ile etkileşime girer. (Yapılabilecek işlemlerin tam listesi için İşlemler dizinine bakın.) Geliştirici olarak, kullanıcılar ile üçüncü taraf hizmetiniz arasında keyifli ve etkili sohbet deneyimleri oluşturup yönetmek için Google'daki İşlemler'i kolayca kullanabilirsiniz.
Bu, Google Asistan için İşlemler oluşturma konusunda deneyimli okuyuculara yönelik ileri düzey bir codelab modülüdür. Google'da İşlemler ile ilgili daha önce geliştirme deneyiminiz yoksa giriş seviyesi codelab'lerimizi ( 1. Seviye, 2. Seviye ve 3. Seviye) inceleyerek platform hakkında bilgi edinmenizi önemle tavsiye ederiz. Bu gelişmiş modüller, işleminizin işlevselliğini genişletmenize ve kitlenizi büyütmenize yardımcı olabilecek bir dizi özellik konusunda size yol gösterecek.
Bir İşlemin başarısını ölçmenin önemli bir yolu, kullanıcı etkileşimi veya İşlemin ilk etkileşimden sonra kullanıcıları geri getirme konusunda ne kadar etkili olduğudur. Bu süreci kolaylaştırmak için İşleminizde, kullanıcılara görüşmenize geri dönme yolları sunan çeşitli özellikler uygulayabilirsiniz.
Bu codelab'de, Google'daki İşlemler için kullanıcı etkileşimi özellikleri ve en iyi uygulamalar ele alınmaktadır.

Ne oluşturacaksınız?
Zaten oluşturulmuş bir özelliği etkinleştirerek aşağıdaki işlemleri yapabilirsiniz:
- Kullanıcılara, İşleminizle konuşmak için dokunabilecekleri günlük bir güncelleme gönderme
- Kullanıcılara İşleminize geri bağlantı veren push bildirimleri gönderme
- Kullanıcıları mobil web tarayıcısından İşleminize yönlendiren bir bağlantı oluşturma
Neler öğreneceksiniz?
- Kullanıcı etkileşimi nedir ve bir İşlemin başarısı için neden önemlidir?
- Kullanıcı etkileşimini artırmak için bir işlemi değiştirme
- Farklı türlerdeki işlemlerde hangi kullanıcı etkileşimi özelliklerinin kullanılacağı
- Asistan üzerinden bildirim göndermek için İşlemler API'sini kullanma
İhtiyacınız olanlar
Aşağıdaki araçlara sahip olmanız gerekir:
- WebStorm, Atom veya Sublime gibi istediğiniz bir IDE/metin düzenleyici
- Node.js, npm ve git'in yüklü olduğu kabuk komutlarını çalıştırmak için bir terminal
- Google Chrome gibi bir web tarayıcısı
- Firebase komut satırı arayüzünün bulunduğu yerel bir geliştirme ortamı
- Asistan'ın yüklü olduğu bir mobil cihaz (Android veya iOS) (Bu projeyi oluşturmak için kullanacağınız Google Hesabı ile Asistan'da oturum açmış olmanız gerekir.)
Webhook kodunu anlamak için JavaScript (ES6) hakkında bilgi sahibi olmanız zorunlu olmasa da şiddetle tavsiye edilir.
2. Projenizi oluşturma
Bu bölümde, daha önce oluşturulmuş ve tamamlanmış bir işleme kullanıcı etkileşimi özelliklerinin nasıl ekleneceği gösterilmektedir.
Örneği anlama
Bu codelab'deki örnek, "Action Gym" adlı kurgusal bir spor salonu için basit bir Action'dır. İşlem, her gün değişen derslerin listesi de dahil olmak üzere spor salonu hakkında bilgi sağlar. Dönen sınıf listesi her gün farklı faydalı bilgiler verdiğinden, bu gibi bilgilendirici bir işlem tüm kullanıcı etkileşimi özellikleri için iyi bir adaydır.
Aşağıdaki şemada, Action Gym örneğinin sohbet akışı gösterilmektedir:

Eklediğiniz etkileşim özelliklerine daha iyi uyum sağlamak için iletişim kutusunda küçük değişiklikler yaparsınız. Ancak görüşmenin genel tasarımı çok değişmeyecek.
Temel dosyalarınızı indirme
Codelab için GitHub deposunu klonlamak üzere aşağıdaki komutu çalıştırın:
git clone https://github.com/actions-on-google/user-engagement-codelab-nodejs
Projenizi ve aracınızı oluşturma
Actions projenizi ve Dialogflow temsilcinizi ayarlamak için aşağıdaki adımları tamamlayın:
- Actions Console'u açın.
- Yeni proje'yi tıklayın.
- Proje adı (ör.
engagement-codelab) yazın. - Proje Oluştur'u tıklayın.
- Bir kategori seçmek yerine Diğer seçenekler bölümüne gidin ve Sohbet kartını tıklayın.
- Seçenekleri genişletmek için İşleminizi Derleme'yi tıklayın ve İşlem Ekle'yi seçin.
- İlk İşleminizi Ekleyin'i tıklayın.
- İşlem Oluştur iletişim kutusunda Özel Amaç'ı seçin ve ardından Dialogflow konsolunu başlatmak için Oluştur'u tıklayın.
- Dialogflow konsolunun aracı oluşturma sayfasında Oluştur'u tıklayın.
- Sol gezinme menüsünde
(dişli simgesi) seçeneğini tıklayın. - Dışa Aktar ve İçe Aktar'ı, ardından Zip'ten Geri Yükle'yi tıklayın.
- Daha önce indirdiğiniz
/user-engagement-codelab-nodejs/start/dizinindenagent.zipdosyasını yükleyin. RESTOREyazın ve Geri yükle'yi tıklayın.- Bitti'yi tıklayın.
İstek karşılama işleminizi dağıtma
Actions projeniz ve Dialogflow aracınız hazır olduğuna göre Firebase Functions CLI'yı kullanarak yerel index.js dosyanızı dağıtın.
Temel dosyalarınızın /user-engagement-codelab-nodejs/start/functions/ dizininde aşağıdaki komutları çalıştırın:
firebase use <PROJECT_ID>
npm install
firebase deploy
Birkaç dakika sonra "Deploy complete!" (Dağıtım tamamlandı) mesajını görürsünüz. Bu mesaj, webhook'unuzu Firebase'e başarıyla dağıttığınızı gösterir.
Dağıtım URL'sini alma
Dialogflow'a Cloud Functions URL'sini sağlamanız gerekir. Bu URL'yi almak için aşağıdaki adımları uygulayın:
- Firebase Console'u açın.
- Seçenekler listesinden Actions projenizi seçin.
- Sol gezinme çubuğunda Geliştir > İşlevler'e gidin. "Veri paylaşımı ayarlarını seçin " istemiyle karşılaşırsanız Bunu daha sonra yap'ı tıklayarak bu seçeneği yoksayabilirsiniz.
- Kontrol paneli sekmesinde, Tetikleyici bölümünde URL'si olan bir "karşılama" girişi görmeniz gerekir. Bu URL'yi kaydedin. Bir sonraki bölümde Dialogflow'a kopyalamanız gerekecek.

Dialogflow'da webhook URL'sini ayarlama
Şimdi, karşılamada webhook'unuzu kullanmak için Dialogflow temsilcinizi güncellemeniz gerekiyor. Bunu yapmak için şu adımları uygulayın:
- Dialogflow konsolunu açın (isterseniz Firebase konsolunu kapatabilirsiniz).
- Soldaki gezinme panelinde Karşılama'yı tıklayın.
- Webhook'u etkinleştirin.
- Henüz görünmüyorsa Firebase kontrol panelinden kopyaladığınız URL'yi yapıştırın.
- Kaydet'i tıklayın.
Projenizin doğru şekilde ayarlandığını doğrulayın
Kullanıcılar, Action Gym hakkında bilgi almak için İşleminizi çağırabilmelidir. Bu bilgiler arasında çalışma saatlerini içeren sabit kodlu bir metin yanıtı ve haftanın her günü için ders programını listeleyen bir metin yanıtı yer alır.
İşleminizi Actions simülatöründe test etmek için:
- Dialogflow konsolunun sol gezinme bölmesinde Entegrasyonlar > Google Asistan'ı tıklayın.
- Değişiklikleri otomatik olarak önizle'nin etkinleştirildiğinden emin olun ve İşlemler projenizi güncellemek için Test et'i tıklayın.
- Actions simülatörü, Actions projenizi yükler. İşleminizi test etmek için Giriş alanına
Talk to my test appyazıp Enter tuşuna basın. - Action Gym'e hoş geldiniz diyen bir yanıt görmeniz gerekir. İsteğinizi yerine getirirken sohbete devam etmek için istemleri uygulamayı deneyin.

3. Günlük güncelleme abonelikleri ekleme
Kullanıcılarla etkileşim kurmanın yaygın bir yolu, onlara en faydalı olduğu zamanlarda bilgi sunmaktır. Bu, kullanıcılara bir amaç için günlük güncellemelere abone olma seçeneği sunularak gerçekleştirilir. Bu sayede kullanıcılara, doğrudan söz konusu amacın yerine getirilmesine bağlanan bir Asistan bildirimi gönderilir.
Bu adımda, günlük güncelleme abonelikleri hakkında bilgi edinecek ve bunları işleminizin Sınıf Listesi amacına ekleyeceksiniz. Bu talimatları uyguladıktan sonra işleminizin görüşmesi aşağıdaki şemada gösterildiği gibi görünür:

Bu özellik kullanıcıların ilgisini nasıl çekecek?
Akıllı telefon kullanıcıları, uygulamaya özel bilgiler ve güncellemeler sağlayan push bildirimlerine muhtemelen aşinadır. Günlük güncelleme abonelikleri, güncellemeleri gönderdiğiniz amacın kullanıcıya günlük olarak değer sağlamaya devam etmesi koşuluyla, Asistan dışında mobil cihazlardaki kullanıcılara ulaşmanın basit bir yoludur.
Günlük güncellemeler, etkileşim için yararlı bir araç olabilir ancak her işlemde kullanılması gerekmez. Bir işleme günlük güncelleme abonelikleri ekleyip eklemeyeceğinize karar verirken aşağıdaki ipuçlarını göz önünde bulundurun:
- Günlük güncellemeler sayesinde kullanıcının her gün farklı ve faydalı bilgiler göreceğinden emin olun. Günlük güncellemeye dokunulduğunda her seferinde aynı istem gösteriliyorsa kullanıcı birkaç gün sonra muhtemelen e-posta listesinden çıkar.
- Kullanıcınız doğrudan günlük güncellemenizin amacına giderse diyalogunuzun anlamlı olduğundan emin olun. Kullanıcınız görüşmeye en baştan başlamayabilir. Bu nedenle, kullanıcının çok fazla bağlam bilgisine sahip olması beklenmemelidir.
- Kullanıcınıza, günlük güncellemelere abone olmasını istemeden önce İşleminizin avantajını gösterin. Kullanıcınız, abone olma seçeneği sunulduğunda "Bu içeriği her gün görmek istiyorum" diye düşünmelidir.
- Kullanıcıyı, kanala abone olma önerilerini tekrarlayarak bunaltmayın. Kullanıcıya neye abone olacağını gösterdikten hemen sonra günlük güncelleme aboneliği teklif edin ve başka bir yerde bu konuda kullanıcıyı rahatsız etmeyin.
- Güncelleme amacı tetiklendikten sonra sohbeti kısa tutun. Günlük güncellemelerin çoğu yalnızca tek bir yanıttan oluşmalı ve kullanıcı girişi gerektirmeden kapatılmalıdır.
Günlük güncellemeleri etkinleştirme
Günlük güncelleme abonelikleri, kullanıcıyı görüşmenizin başlangıcına yerleştiren karşılama amacına veya kullanıcıyı görüşme içinde bir yere derin bağlamak için daha spesifik bir amaca eklenebilir. Bu codelab'de, diyalog her gün değişeceği ve kullanıcılara hangi sınıfların mevcut olduğunu hatırlatmanın faydalı olabileceği için en mantıklı seçenek Class List (Sınıf Listesi) amacıdır.
Class List (Sınıf Listesi) amacı için günlük güncellemeleri etkinleştirmek üzere aşağıdaki adımları uygulayın:
- Actions Console'da Geliştir sekmesini tıklayın ve soldaki gezinme çubuğunda İşlemler'i seçin.
- İşlemler listesinde Sınıf Listesi'ni tıklayın.
- Kullanıcı etkileşimi bölümünde, Kullanıcılara günlük güncellemeler sunmak ister misiniz? seçeneğini etkinleştirin veya devre dışı bırakın.
- Günlük güncellemeyi açıklayan bir İçerik başlığı belirleyin. Bağlam "Günlük " güncellemelerini saat kaçta göndermemi istersin?" şeklinde olacağından başlığınızın hem açıklayıcı hem de yüksek sesle okunduğunda doğru olduğundan emin olun. Bu örnekte, İçerik başlığı değerini
list of upcoming Action Gym classesolarak ayarlayın. - Sayfanın üst kısmındaki Kaydet'i tıklayın.

Dialogflow kurulumu
Günlük güncelleme aboneliği akışı için niyet oluşturmak üzere Dialogflow konsolunda aşağıdaki adımları uygulayın:
Kullanıcıdan abone olmasını isteme
- Kullanıcının günlük güncellemelere abone olma isteğini işlemek için yeni bir amaç oluşturun. Yeni bir amaç oluşturmak için Dialogflow konsolunda sol gezinme bölümündeki Amaçlar'ın yanındaki + düğmesini tıklayın.
- Bu yeni amaca
Setup Updatesadını verin. - Eğitim ifadeleri bölümünde aşağıdaki kullanıcı ifadelerini ekleyin:
Send daily remindersReminderRemind meUpdatesUpcoming classes
- İstek karşılama bölümünde Bu niyet için webhook çağrısını etkinleştir seçeneğini açın.
- Sayfanın üst kısmındaki Kaydet'i tıklayın.

Kullanıcının kararını işleme
- Kullanıcının günlük güncellemeler aboneliği istemine verdiği yanıtı işlemek için yeni bir amaç oluşturun. Yeni bir amaç oluşturmak için sol gezinme bölümünde Amaçlar'ın yanındaki + düğmesini tıklayın.
- Bu yeni amaca
Confirm Updatesadını verin. - Etkinlikler bölümüne
actions_intent_REGISTER_UPDATEekleyin. Bu Dialogflow etkinliği, kullanıcının günlük güncelleme aboneliği akışını tamamlamasıyla tetiklenir. Kullanıcının abone olup olmaması bu durumu etkilemez. - İstek karşılama bölümünde Bu niyet için webhook çağrısını etkinleştir seçeneğini açın.
- Sayfanın üst kısmındaki Kaydet'i tıklayın.

Sipariş karşılama işlemini gerçekleştirme
Webhook'unuzda karşılama işlemini uygulamak için aşağıdaki adımları tamamlayın:
Bağımlılıkları yükleme
index.js dosyasında, actions-on-google paketinden RegisterUpdate paketini eklemek için require() işlevini güncelleyin. Böylece içe aktarmalarınız aşağıdaki gibi görünür:
index.js
const {
dialogflow,
Suggestions,
RegisterUpdate,
} = require('actions-on-google');
Öneri çipini güncelleme
index.js dosyasında, öneri çipi başlıkları listesine bir DAILY girişi ekleyin. Böylece Suggestion tanımınız aşağıdaki gibi görünür:
index.js
// Suggestion chip titles
const Suggestion = {
HOURS: 'Ask about hours',
CLASSES: 'Learn about classes',
DAILY: 'Send daily reminders',
};
Yeni amaçlar için karşılama ekleme
Kullanıcı abone olmak istediğini söylediğinde, güncellemenin hedef amacı (Class List) ve türü (DAILY) ile RegisterUpdate yardımcı işlevini çağırarak günlük güncellemeler abonelik akışını başlatın. Abonelik akışı tamamlandıktan sonra Asistan, aboneliğin başarılı olup olmadığını açıklayan bir status bağımsız değişkeniyle actions_intent_REGISTER_UPDATE etkinliğini tetikler. Kullanıcıya, abonelik durumuna göre değişen takip istemleri sunma.
index.js dosyasına aşağıdaki kodu ekleyin:
index.js
// Start opt-in flow for daily updates
app.intent('Setup Updates', (conv) => {
conv.ask(new RegisterUpdate({
intent: 'Class List',
frequency: 'DAILY',
}));
});
// Confirm outcome of opt-in for daily updates
app.intent('Confirm Updates', (conv, params, registered) => {
if (registered && registered.status === 'OK') {
conv.ask(`Gotcha, I'll send you an update everyday with the ` +
'list of classes. Can I help you with anything else?');
} else {
conv.ask(` I won't send you daily reminders. Can I help you with anything else?`);
}
if (conv.screen) {
conv.ask(new Suggestions([Suggestion.HOURS, Suggestion.CLASSES]));
}
});
Kullanıcıya alternatif istemler sunma
Sınıf Listesi yanıtınızın sonunda günlük güncelleme aboneliği teklif edilir ancak bu bir sorun teşkil eder. Kullanıcı günlük güncelleme bildirimine dokunduğunda da aynı yanıt tetikleneceğinden, günlük güncelleme bildiriminden gelmiş olsa bile günlük güncellemelere abone olması istenir. Kullanıcının yeniden abone olması gerektiğini düşünmesini nasıl önleyebilirsiniz?
Neyse ki conv nesnenizin bağımsız değişkenleri, kullanıcının görüşmeyi başlattığı yerle ilgili bilgileri içeriyor. Kullanıcının sohbete günlük güncelleme bildiriminden başlayıp başlamadığını gösteren bir UPDATES bölümü içerip içermediğini görmek için conv bağımsız değişkenlerini kontrol edebilir ve yanıtı buna göre değiştirebilirsiniz. Ayrıca, günlük güncellemeyi kısa tutma konusundaki en iyi uygulamamıza uygun olarak, sınıf listesini sağladıktan hemen sonra iletişim kutusunu kapatmak için bu görüşme dalını da kullanabilirsiniz.
index.js dosyasında aşağıdaki kodu değiştirin:
index.js
// Class list intent handler
app.intent('Class List', (conv, {day}) => {
if (!day) {
day = DAYS[new Date().getDay()];
}
const classes =
[...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
.join(', ');
const classesMessage =
`On ${day} we offer the following classes: ${classes}. ` +
`Can I help you with anything else?`;
conv.ask(classesMessage);
if (conv.screen) {
conv.ask(new Suggestions([Suggestion.HOURS]));
}
});
ile değiştirin:
index.js
// Class list intent handler
app.intent('Class List', (conv, {day}) => {
if (!day) {
day = DAYS[new Date().getDay()];
}
const classes =
[...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
.join(', ');
let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
// If the user started the conversation from the context of a daily update,
// the conv's arguments will contain an 'UPDATES' section.
let engagement = conv.arguments.get('UPDATES');
// Check the conv arguments to tailor the conversation based on the context.
if (engagement) {
classesMessage += `Hope to see you soon at Action Gym!`;
conv.close(classesMessage);
} else {
classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
conv.ask(classesMessage);
if (conv.screen) {
conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
};
};
});
Günlük güncellemelerinizi test etme
Terminalde, güncellenen webhook kodunuzu Firebase'e dağıtmak için aşağıdaki komutu çalıştırın:
firebase deploy
İşlemler simülasyonunda özel yeniden isteminizi test etmek için aşağıdaki adımları uygulayın:
- Actions Console'da Test'e gidin.
- Giriş alanına
Talk to my test appyazıp Enter tuşuna basın. Learn about classesyazıp Enter tuşuna basın. İşleminizin yanıtında artık günlük hatırlatma gönderme seçeneği sunulmalıdır.Send daily remindersyazıp Enter tuşuna basın.- Güncellemeyi görmek istediğiniz zamanı yazıp Enter tuşuna basın. Test amacıyla, geçerli saatten 3-5 dakika sonra yanıt vermeyi deneyin.

Mobil cihazınızda, güncellemeler için belirttiğiniz saatlerde Asistan'dan bildirim alırsınız. Bu bildirimin görünmesi birkaç dakika sürebilir. Bildirime dokunduğunuzda doğrudan Asistan'daki Sınıf Listesi amacına derin bağlantı oluşturulur ve yaklaşan sınıfların listesi gösterilir:

4. Push bildirimleri ekleme
İşleminizin dışındaki kullanıcılarla etkileşim kurmak için bir başka seçenek olarak, kullanıcılara push bildirimleri göndermek üzere Actions API'yi çağırabilirsiniz. Günlük güncellemelerin aksine bu bildirimler Asistan tarafından otomatik olarak planlanmaz. Bu nedenle, istediğiniz zaman gönderebilirsiniz.
Bu adımda, yeni bir Class Canceled (Sınıf İptal Edildi) amacı ekleyerek ve kullanıcılara sınıf iptali hakkında bildirim göndererek İşleminize push bildirimlerini nasıl uygulayacağınızı öğreneceksiniz. Ayrıca bildirim göndermek için gereken aşağıdaki üç bileşeni de ayarlarsınız:
- Actions API hesabı: API'ye
POSTisteği göndererek kullanıcıya bildirim gönderirsiniz. Bu nedenle, bu API ile arayüz oluşturmak için bir hizmet hesabı ve kimlik bilgileri ayarlamanız gerekir. - İzin yardımcısı: Kullanıcıya push bildirimi göndermek için gereken kullanıcı kimliğine erişmek üzere kullanıcının izni gerekir. Bu örnekte, izin yardımcısını çağırmak ve bu kimliği istemek için bir istemci kitaplığı işlevi kullanacaksınız.
- Depolama: Bir kullanıcının görüşme dışındayken push bildirimi gönderebilmek için kullanıcı kimliklerini istediğiniz zaman geri çağırabileceğiniz bir yerde saklamanız gerekir. Bu örnekte, her kullanıcının bilgilerini depolamak için bir Firestore veritabanı oluşturacaksınız.
Bu talimatları uyguladıktan sonra aşağıdaki iletişim kutusunu İşleminizin görüşmesine eklersiniz:

Bu özellik kullanıcıların ilgisini nasıl çekecek?
Akıllı telefon kullanıcıları, uygulamaya özel bilgiler ve güncellemeler sağlayan push bildirimlerine muhtemelen aşinadır. Push bildirimleri, kullanıcıların etkinleştirmesi için iyi bir neden sunulduğu takdirde, Asistan dışında mobil cihazlardaki kullanıcılara ulaşmanın esnek bir yoludur. Günlük güncellemelerle kullanıcılar, her gün bildirim alacaklarını zaten biliyor. Ancak push bildirimlerinde kullanıcılar, nadir bildirimler almayı mı kabul ettiklerini yoksa günde birden fazla bildirimle rahatsız mı edileceklerini bilmiyor.
Push bildirimleri, etkileşimi artırmak için faydalı bir araç olabilir ancak her işlemde kullanılması zorunlu değildir. Bir işleme anlık bildirim ekleyip eklemeyeceğinize karar verirken aşağıdaki ipuçlarını göz önünde bulundurun:
- Push bildirimleriniz için bazı örnek programlar planlayın. Günde yalnızca bir push bildirimi göndermeyi planlıyorsanız bunun yerine günlük güncellemeleri kullanmayı düşünebilirsiniz.
- Push bildirimlerinizin her alındığında faydalı bilgiler sağladığından emin olun. Bildirimleriniz, İşleminizin intent'lerinden birine de derin bağlantı verebilir. Bu nedenle, intent'in faydalı ve alakalı olduğundan emin olun.
- Kullanıcıdan push bildirimlerine abone olmasını isterken açık bir dil kullanın. Her push bildiriminde ne bekleyeceklerini ve bildirimlerin ne sıklıkta gönderildiğini bilmelidirler.
Actions API'yi etkinleştirme
- Google Cloud Console'u açın ve açılır listeden Actions projenizin adını seçin.

- Gezinme menüsünde (☰) API'ler ve Hizmetler > Kitaplık'a gidin.
- Actions API'yi arayın ve Etkinleştir'i tıklayın.

Hizmet hesabı oluşturma
Actions API kimlik doğrulama gerektirdiğinden istek göndermek için bir hizmet hesabı oluşturmanız gerekir. Actions API için hizmet hesabı anahtarı oluşturmak ve yüklemek üzere aşağıdaki adımları uygulayın:
- Google Cloud Console'un gezinme menüsünde (☰) API'ler ve Hizmetler > Kimlik Bilgileri'ne gidin.
- Kimlik bilgisi oluştur > Hizmet hesabı anahtarı'nı tıklayın.
- Hizmet hesabı açılır menüsünde Yeni Hizmet Hesabı'nı seçin.
- Aşağıdaki bilgileri girin:
- Hizmet hesabı adı:
service-account - Rol: Proje > Sahip
- Hizmet hesabı kimliği:
service-account(her zaman @<project_id>.iam.gserviceaccount.com ile birlikte kullanılır) - Anahtar türü: JSON
- Oluştur'u tıklayın.
- İndirilen JSON dosyasını projenizin /user-engagement-codelab/start/functions/ dizinine taşıyın.
- JSON dosyasının adını
service-account.jsonolarak değiştirin.

Firestore'u etkinleştirme
Konuşma dışına bildirim göndermek için bildirim kodunuzdan referans verilebilecek kullanıcı kimliklerini depolamanın bir yolunu bulmanız gerekir. Bu örnekte, abone olan kullanıcıların kimliklerini depolamak için Firestore veritabanı kullanıyoruz.
İşleminiz için Firestore veritabanı oluşturmak üzere aşağıdaki adımları uygulayın:
- Firebase konsolunda Actions projenizin adını seçin.
- Soldaki gezinme bölmesinde Geliştir > Veritabanı'na gidin ve Veritabanı oluştur'u tıklayın.
- Test modunda başlat'ı seçin.
- Etkinleştir'i tıklayın.

Dialogflow kurulumu
Anlık bildirimlere kaydolma akışı oluşturmak için Dialogflow konsolunda aşağıdaki adımları uygulayın:
Kullanıcıdan abone olmasını isteme
- Kullanıcının iptal edilen derslerle ilgili push bildirimlerine abone olma isteğini işlemek için yeni bir amaç oluşturun. Yeni bir amaç oluşturmak için Dialogflow konsolunda sol gezinme bölümündeki Amaçlar'ın yanındaki + düğmesini tıklayın.
- Bu yeni amaca
Setup Push Notificationsadını verin. - Eğitim ifadeleri bölümünde aşağıdaki kullanıcı ifadelerini ekleyin:
Subscribe to notificationsSend notificationNotify meSend class notificationsCancelled notifications
- İstek karşılama bölümünde Bu niyet için webhook çağrısını etkinleştir seçeneğini açın.
- Sayfanın üst kısmındaki Kaydet'i tıklayın.

Kullanıcının kararını işleme
- Kullanıcının push bildirimleri aboneliği istemine verdiği yanıtı işlemek için yeni bir amaç oluşturun. Yeni bir amaç oluşturmak için sol gezinme bölümünde Amaçlar'ın yanındaki + düğmesini tıklayın.
- Bu yeni amaca
Confirm Push Notificationsadını verin. - Etkinlikler bölümüne
actions_intent_PERMISSIONekleyin. Bu Dialogflow etkinliği, kullanıcının push bildirimi aboneliği akışını tamamlamasıyla tetiklenir. Kullanıcının abone olup olmaması bu durumu etkilemez. - İstek karşılama bölümünde Bu niyet için webhook çağrısını etkinleştir seçeneğini açın.
- Sayfanın üst kısmındaki Kaydet'i tıklayın.

Push bildirimini işleme
Push bildirimlerinizi belirli bir amaca bağlayabilirsiniz. Böylece, push bildirimine dokunan kullanıcılar doğrudan İşleminizdeki bu amaca derin bağlantıyla yönlendirilir. Bu örnekte, iptal edilen derslerle ilgili ayrıntılar sağlayan push bildirimleri için yeni bir amaç ekleyin.
Kullanıcının anlık bildirime dokunmasıyla tetiklenecek bir amaç eklemek için aşağıdaki adımları uygulayın:
- Yeni bir amaç oluşturmak için Dialogflow konsolunda sol gezinme bölümündeki Amaçlar'ın yanındaki + düğmesini tıklayın.
- Bu yeni amaca
Class Canceledadını verin. - Eğitim ifadeleri bölümünde
Cancelationsifadesini kullanıcı ifadesi olarak ekleyin. - İstek karşılama bölümünde Bu niyet için webhook çağrısını etkinleştir seçeneğini açın.
- Sayfanın üst kısmındaki Kaydet'i tıklayın.

Konuşma sırasında test bildirimleri gönderme
Üretimde, push bildirimleri gönderen, işlem karşılama kodunuzdan ayrı bir komut dosyanız olmalıdır. Bu örnek için, İşleminizle konuşurken push bildirimi göndermek üzere çağırabileceğiniz bir amaç oluşturun. Bu amaç yalnızca hata ayıklama amaçlıdır. Uygulamada, push bildirimleri karşılama tarafından işlenmemeli veya İşleminizin görüşmesi kapsamında başka bir şekilde tetiklenmemelidir.
Push bildirimlerini test etmek için niyet oluşturmak üzere aşağıdaki adımları uygulayın:
- Test ve hata ayıklama amacıyla, abone olan kullanıcılara push bildirimi göndermenize olanak tanıyan yeni bir amaç oluşturun. Yeni bir amaç oluşturmak için Dialogflow konsolunda sol gezinme bölümündeki Amaçlar'ın yanındaki + düğmesini tıklayın.
- Bu yeni amaca
Test Notificationadını verin. - Eğitim ifadeleri bölümünde
Test notificationifadesini kullanıcı ifadesi olarak ekleyin. - İstek karşılama bölümünde Bu niyet için webhook çağrısını etkinleştir seçeneğini açın.
- Sayfanın üst kısmındaki Kaydet'i tıklayın.

Push bildirimlerini etkinleştir
Sınıf İptal Edildi amacında anlık bildirimleri etkinleştirmek için şu adımları uygulayın:
- Dialogflow konsolunda gezinme çubuğundaki Entegrasyonlar'a gidin.
- Google Asistan kartında Entegrasyon Ayarları'nı tıklayın.
- Class Canceled'ı Implicit invocation (Örtülü çağırma) intent'i olarak ekleyin. Bu adım, Dialogflow'un kullanıcıların Class Canceled (Sınıf İptal Edildi) niyetiyle (push bildirimine dokunarak) görüşmenizi başlatabileceğini tanıması için gereklidir.
- Kapat'ı tıklayın.

- Actions Console'da Geliştir sekmesini tıklayın ve soldaki gezinme çubuğunda İşlemler'i seçin.
- İşlemler listesinde Sınıf İptal Edildi'yi tıklayın.
- Kullanıcı etkileşimi bölümünde Push bildirimi göndermek ister misiniz? seçeneğini açın veya kapatın.
- Push bildirimini açıklayan bir İçerik başlığı belirleyin. Bağlam "Is it ok if I send push notifications for ?" ( için push bildirimleri gönderebilir miyim?) olacak. Bu nedenle başlığınızın hem açıklayıcı hem de yüksek sesle okunduğunda doğru olduğundan emin olun. Bu örnekte, İçerik başlığı değerini
class cancelationsolarak ayarlayın. - Sayfanın üst kısmındaki Kaydet'i tıklayın.

Sipariş karşılama işlemini gerçekleştirme
Webhook'unuzda karşılama işlemini uygulamak için aşağıdaki adımları tamamlayın:
Bağımlılıkları yükleme
index.js dosyasında, actions-on-google paketinden UpdatePermission paketini eklemek için require() işlevini güncelleyin. Böylece içe aktarmalarınız aşağıdaki gibi görünür:
index.js
const {
dialogflow,
Suggestions,
RegisterUpdate,
UpdatePermission,
} = require('actions-on-google');
Öneri çipini güncelleme
index.js dosyasında, öneri çipi başlıkları listesine bir NOTIFICATIONS girişi ekleyin. Böylece Suggestion tanımınız aşağıdaki gibi görünür:
index.js
// Suggestion chip titles
const Suggestion = {
HOURS: 'Ask about hours',
CLASSES: 'Learn about classes',
DAILY: 'Send daily reminders',
NOTIFICATIONS: 'Get notifications',
};
Yeni içe aktarma işlemleri oluşturma
Firestore veritabanınıza bağlanmak için firebase-admin paketini ekleyin ve veritabanında depolanan alanlar için sabitler ekleyin. Ayrıca, kimlik doğrulama ve İşlemler API'sine yönelik istekleri işlemek için google-auth-library ve request paketlerini içe aktarın.
index.js dosyasında, içe aktarmalarınıza aşağıdaki kodu ekleyin:
index.js
// Firebase admin import
const admin = require('firebase-admin');
// Initialize Firestore
admin.initializeApp();
const db = admin.firestore();
// Firestore constants
const FirestoreNames = {
INTENT: 'intent',
USER_ID: 'userId',
USERS: 'users',
};
// Actions API authentication imports
const {auth} = require('google-auth-library');
const request = require('request');
Sınıf iptali bildirimlerini ayarlama teklifi
index.js dosyasında aşağıdaki kodu değiştirin:
index.js
// Class list intent handler
app.intent('Class List', (conv, {day}) => {
if (!day) {
day = DAYS[new Date().getDay()];
}
const classes =
[...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
.join(', ');
let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
// If the user started the conversation from the context of a daily update,
// the conv's arguments will contain an 'UPDATES' section.
let engagement = conv.arguments.get('UPDATES');
// Check the conv arguments to tailor the conversation based on the context.
if (engagement) {
classesMessage += `Hope to see you soon at Action Gym!`;
conv.close(classesMessage);
} else {
classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
conv.ask(classesMessage);
if (conv.screen) {
conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
};
};
});
ile değiştirin:
index.js
// Class list intent handler
app.intent('Class List', (conv, {day}) => {
if (!day) {
day = DAYS[new Date().getDay()];
}
const classes =
[...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
.join(', ');
let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
// If the user started the conversation from the context of a daily update,
// the conv's arguments will contain an 'UPDATES' section.
let engagement = conv.arguments.get('UPDATES');
// Check the conv arguments to tailor the conversation based on the context.
if (engagement) {
classesMessage += `Hope to see you soon at Action Gym!`;
conv.close(classesMessage);
} else {
classesMessage += `Would you like to receive daily reminders of upcoming classes, subscribe to notifications about cancelations, or can I help you with anything else?`;
conv.ask(classesMessage);
if (conv.screen) {
conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.NOTIFICATIONS,
Suggestion.HOURS]));
};
};
});
Yeni amaçlar için karşılama ekleme
Kullanıcı, anlık bildirimlere abone olmak istediğini söylediğinde kullanıcıdan izin istemek için UpdatePermission yardımcısını çağırın. Bu işlem başarılı olursa PERMISSION bağımsız değişkeni, conv nesnesinin bağımsız değişkenlerine eklenir. Bu bağımsız değişkeni, görüşmeyi yönlendirmek için kontrol edebilirsiniz.
Kullanıcının iznini aldıktan sonra conv nesnesinin bağımsız değişkenlerinden kullanıcı kimliğini alın ve veritabanınıza kaydedin. Daha sonra bu kullanıcı kimliğini Actions API'ye gönderirsiniz. Asistan, bildirimi kimin alacağını bu şekilde belirler.
Son olarak, push bildirimine dokunarak tetiklenen Class Canceled amacına yönelik karşılama ekleyin. Bu örnekte yanıtınız yer tutucu bir dizedir. Ancak bu işlemin üretime hazır bir sürümünde bildirim komut dosyanız, hangi sınıfın iptal edildiği hakkında daha dinamik bilgiler sağlar.
index.js dosyasına aşağıdaki kodu ekleyin:
index.js
// Call the User Information helper for permission to send push notifications
app.intent('Setup Push Notifications', (conv) => {
conv.ask('Update permission for setting up push notifications');
conv.ask(new UpdatePermission({intent: 'Class Canceled'}));
});
// Handle opt-in or rejection of push notifications
app.intent('Confirm Push Notifications', (conv) => {
if (conv.arguments.get('PERMISSION')) {
let userId = conv.arguments.get('UPDATES_USER_ID');
if (!userId) {
userId = conv.request.conversation.conversationId;
}
// Add the current conversation ID and the notification's
// target intent to the Firestore database.
return db.collection(FirestoreNames.USERS)
.add({
[FirestoreNames.INTENT]: 'Class Canceled',
[FirestoreNames.USER_ID]: userId,
})
.then(() => {
conv.ask(`Great, I'll notify you whenever there's a class cancelation. ` +
'Can I help you with anything else?');
});
} else {
conv.ask(`Okay, I won't send you notifications about class cancelations. ` +
'Can I help you with anything else?');
}
if (conv.screen) {
conv.ask(new Suggestions([Suggestion.CLASSES, Suggestion.HOURS]));
}
});
// Intent triggered by tapping the push notification
app.intent('Class Canceled', (conv) => {
conv.ask('Classname at classtime has been canceled.');
});
Test bildirimleri ekleme
Kullanıcıya push bildirimi göndermek için kullanıcı kimliği, bildirimin başlığı ve hedef amaç ile Actions API'ye bir POST isteği gönderin. Bu örnekte, Test Notification amacının tetiklenmesiyle Firestore veritabanınızda yineleme yapılır ve bildirimlere abone olan her kullanıcıya push bildirimi gönderilir.
Bu örnekte, push bildirimi gönderen kodu webhook karşılama yanıtınıza eklediğinizi ve konuşmanızda bir test amacı çağırarak bu kodu tetiklediğinizi unutmayın. Yayınlamayı planladığınız işlemlerde, push bildirimi kodunuz karşılamanızdan ayrı bir komut dosyasında bulunmalıdır.
index.js dosyasına aşağıdaki kodu ekleyin:
index.js
// Debug intent to trigger a test push notification
app.intent('Test Notification', (conv) => {
// Use the Actions API to send a Google Assistant push notification.
let client = auth.fromJSON(require('./service-account.json'));
client.scopes = ['https://www.googleapis.com/auth/actions.fulfillment.conversation'];
let notification = {
userNotification: {
title: 'Test Notification from Action Gym',
},
target: {},
};
client.authorize((err, tokens) => {
if (err) {
throw new Error(`Auth error: ${err}`);
}
// Iterate through Firestore and send push notifications to every user
// who's currently opted in to canceled class notifications.
db.collection(FirestoreNames.USERS)
.where(FirestoreNames.INTENT, '==', 'Class Canceled')
.get()
.then((querySnapshot) => {
querySnapshot.forEach((user) => {
notification.target = {
userId: user.get(FirestoreNames.USER_ID),
intent: user.get(FirestoreNames.INTENT),
};
request.post('https://actions.googleapis.com/v2/conversations:send', {
'auth': {
'bearer': tokens.access_token,
},
'json': true,
'body': {'customPushMessage': notification, 'isInSandbox': true},
}, (err, httpResponse, body) => {
if (err) {
throw new Error(`API request error: ${err}`);
}
console.log(`${httpResponse.statusCode}: ` +
`${httpResponse.statusMessage}`);
console.log(JSON.stringify(body));
});
});
})
.catch((error) => {
throw new Error(`Firestore query error: ${error}`);
});
});
conv.ask('A notification has been sent to all subscribed users.');
});
Push bildirimlerinizi test etme
Terminalde, güncellenen webhook kodunuzu Firebase'e dağıtmak için aşağıdaki komutu çalıştırın:
firebase deploy
İşlemler simülatöründe bildirimleri test etmek için aşağıdaki adımları uygulayın:
- Actions Console'da Test sekmesine gidin.
- Giriş alanına
Talk to my test appyazıp Enter tuşuna basın. Learn about classesyazıp Enter tuşuna basın.Get notificationsyazıp Enter tuşuna basın.- İşleminize henüz size anlık bildirim gönderme izni vermediyseniz
yesyazıp Enter tuşuna basın. yesyazıp Enter tuşuna basın. Google Hesabınız artık bu işlem için anlık bildirimlere abone olmalıdır.

noyazıp Enter tuşuna basarak çıkın.- Yeni bir görüşme başlatmak için
Talk to my test appyazıp Enter tuşuna basın. Test notificationyazıp Enter tuşuna basın.

Birkaç dakika içinde mobil cihazınızda "Action Gym'den Test Bildirimi" başlıklı bir Asistan push bildirimi alırsınız. Bu bildirime dokunduğunuzda, İşleminizin Class Canceled (Sınıf İptal Edildi) amacına derin bağlantı oluşturulur.

5. Asistan bağlantısı oluşturma
Şimdiye kadar, kullanıcıların İşleminize geri dönmesini sağlamak için uygulayabileceğiniz etkileşim özelliklerini ele aldık. Ancak bu özellikler, İşleminizi keşfeden ve kullanan kullanıcıların varlığına bağlıdır.
Mobil cihazlardaki kullanıcıları doğrudan Asistan'daki İşleminize bağlayacak bir Asistan bağlantısı oluşturabilirsiniz. Asistan bağlantısı standart bir köprü olduğundan, web sitesine veya blog ya da sosyal medya yayını gibi web pazarlama materyallerine ekleyebilirsiniz.
Bu adımda, Asistan bağlantısının ne olduğunu, İşleminizin karşılama amacına yönelik nasıl bağlantı oluşturacağınızı ve bunu test için basit bir web sitesine nasıl ekleyeceğinizi öğreneceksiniz.
Bu özellik kullanıcıların ilgisini nasıl çekecek?
Kullanıcıları ilk kez Action'ınıza çekmek zor olabilir. Özellikle de kullanıcıların Asistan'da Action'ınızı açıkça çağırması gerektiğinde bu zorluk daha da artar. Asistan bağlantısı, kullanıcılara İşleminize doğrudan bağlantı vererek bu sürtünmeyi azaltır. Kullanıcı, Asistan özellikli bir cihazda Asistan bağlantınızı tıkladığında doğrudan İşleminize yönlendirilir. Kullanıcılar, bağlantınızı mobil olmayan bir cihazda veya Asistan'ı desteklemeyen başka bir cihazda açtığında yine İşlemler dizini girişinize (yayınlandıysa) yönlendirilir. Böylece bağlantı, İşleminizi bu kullanıcılara tanıtmaya devam edebilir.
Asistan bağlantıları, etkileşimi artırmak için kullanışlı bir araç olabilir. Bu nedenle, İşleminizin reklamını web siteniz veya sosyal medya üzerinden yapmayı planlıyorsanız bir Asistan bağlantısı oluşturmanız gerekir. Asistan bağlantısı oluşturup dağıtmadan önce aşağıdaki ipuçlarını göz önünde bulundurun:
- Asistan bağlantıları yalnızca İşleminiz yayınlandıktan sonra çalışır. Projeniz taslak durumundayken bağlantı yalnızca kendi cihazlarınızda çalışır. Diğer kullanıcılar, İşlemler dizinindeki bir 404 sayfasına yönlendirilir.
- İşleminizi alfa veya beta ortamında yayınlayarak kullanıcıların yayınlamadan önce bir Asistan bağlantısını test etmesine izin verebilirsiniz. Yalnızca alfa veya beta testinize katılan kullanıcıların Asistan bağlantınızı test edebileceğini unutmayın.
- Asistan bağlantınızın hedef amacı, yeni kullanıcılar üzerinde iyi bir ilk izlenim bırakmalıdır. Karşılama amacı, İşleminizi tanıtma konusunda iyi bir iş çıkaracağı için Asistan bağlantısının varsayılan hedefidir.
Asistan bağlantılarını etkinleştirme
Karşılama amacı için Asistan bağlantısı oluşturmak üzere aşağıdaki adımları uygulayın:
- Actions Console'da Geliştir sekmesini tıklayın ve soldaki gezinme çubuğunda İşlemler'i seçin.
- İşlemler listesinde actions.intent.MAIN'i tıklayın.
- Bağlantılar bölümünde, Bu işlem için URL'yi etkinleştirmek ister misiniz? seçeneğini etkinleştirin.
- İşleminizi açıklayan bir bağlantı başlığı belirleyin. Başlığınızı, kullanıcının işleminizle neler yapabileceğini açıklayan basit bir fiil-isim çifti olarak oluşturun. Bu örnekte, Bağlantı başlığı değerini
learn about Action Gymolarak ayarlayın. - Bu sayfanın en altındaki HTML snippet'ini kopyalayın ve daha sonra kullanmak üzere kaydedin.
- Sayfanın üst kısmındaki Kaydet'i tıklayın.

Test web sitesi dağıtma
Asistan bağlantınızı test etmek için Firebase araçlarını kullanarak karşılamanızla birlikte bir test web sitesi dağıtabilirsiniz. Bu örnek için basit bir test web sitesi oluşturduk. Yalnızca Asistan bağlantınızı eklemeniz yeterlidir.
Yerine getirme işleminizin /user-engagement-codelab-nodejs/start/public/ dizinine gidin ve index.html dosyasını bir metin düzenleyicide açın.
index.html dosyasında, Asistan bağlantınızın HTML snippet'ini gövde öğesine yapıştırın. Dosya aşağıdaki snippet'e benzer şekilde görünmelidir:
index.html
<body>
<p>
<a href="https://assistant.google.com/services/invoke/uid/000000efb5f2fd97">🅖 Ask my test app to learn about Action Gym
</a>
</p>
</body>
Asistan bağlantınızı test etme
Terminalde, test web sitenizi Firebase'e dağıtmak için aşağıdaki komutu çalıştırın:
firebase deploy
Dağıtım komutu çalışmayı tamamladığında çıkıştaki Hosting URL'sini not edin.

Mobil cihazınızın web tarayıcısında bu URL'ye gidin. Test web sitenizde Asistan bağlantısını görmeniz gerekir. Mobil cihazınızda bu bağlantıyı tıkladığınızda Asistan'daki İşleminizin karşılama amacına yönlendirilmeniz gerekir.

Ayrıca, masaüstü tarayıcıda Hosting URL'sine gitmeyi de deneyebilirsiniz. Bu URL, İşleminiz yayınlanmadığı için sizi Yardımcı dizinindeki 404 sayfasına yönlendirmelidir.
6. Sonraki adımlar
Tebrikler!
Artık bir İşlem geliştirirken kullanıcı etkileşiminin önemi, platformda hangi kullanıcı etkileşimi özelliklerinin bulunduğu ve her bir özelliği İşleme nasıl ekleyeceğiniz hakkında bilgi sahibisiniz.
Ek öğrenme kaynakları
İşleminizdeki kullanıcı etkileşimi hakkında daha fazla bilgi edinmek için aşağıdaki kaynakları inceleyin:
- Kullanıcı etkileşimi ve Asistan, dokümanları bağlar: Bu codelab'de ele alınan özellikler ve genel olarak kullanıcı etkileşimi hakkında resmi Actions on Google dokümanları.
- Kullanıcı elde tutma analizi: İşlemler Konsolu'ndaki, yayınlanmış İşleminiz için kullanıcı elde tutma oranını gösteren analiz özelliğiyle ilgili dokümanlar.
- Sohbete dayalı tasarım yönergeleri: Kullanıcı etkileşimi özelliklerinin nasıl tasarlanacağına dair en iyi uygulamalar ve yönergeler.
- Actions on Google GitHub deposu: Örnek kod ve kitaplıklar.
- r/GoogleAssistantDev: Asistan ile çalışan geliştiriciler için resmi Reddit topluluğu.
En son duyurularımızdan haberdar olmak için Twitter'da @ActionsOnGoogle hesabımızı takip edin ve geliştirdiklerinizi paylaşmak için #AoGDevs etiketini kullanarak tweet atın.
Geri bildirim anketi
Gitmeden önce bu formu doldurarak performansımız hakkındaki görüşlerinizi bizimle paylaşın.