Kullanıcının İşleminize devam etmek için çeşitli seçeneklerden birini seçmesini istiyorsanız bir görsel seçim yanıtı kullanın. Bir istem kapsamında aşağıdaki görsel seçim yanıtı türlerini kullanabilirsiniz:
- Liste
- Koleksiyon
- Koleksiyona göz at
Görsel seçim yanıtı tanımlarken RICH_RESPONSE
yüzey özelliğine sahip bir aday kullanın. Böylece Google Asistan, yanıtı yalnızca desteklenen cihazlarda döndürür. Bir istemde content
nesnesi başına yalnızca bir zengin yanıt kullanabilirsiniz.
Görsel seçim yanıtı ekleme
Görsel seçim yanıtları, hem kullanıcının belirleyebileceği hem de seçilen bir öğeyi işleyebilecek seçenekleri sunmak için bir sahnede slot doldurmayı kullanır. Kullanıcılar bir öğe seçtiğinde Asistan, seçilen öğe değerini webhook'unuza bağımsız değişken olarak iletir. Ardından, seçilen öğenin anahtarını bağımsız değişken değerinde alırsınız.
Görsel bir seçim yanıtı kullanabilmek için önce kullanıcının daha sonra seçtiği yanıtı temsil eden bir tür tanımlamanız gerekir. Webhook'unuzda, bu türü, seçim için görüntülenmesini istediğiniz içerikle geçersiz kılarsınız.
Actions Builder'daki bir sahneye görsel seçim yanıtı eklemek için şu adımları uygulayın:
- Sahnede Yuva doldurma bölümüne bir aralık ekleyin.
- Görsel seçim yanıtınız için önceden tanımlanmış bir tür seçin ve ona bir ad verin. Webhook'unuz, daha sonra türe referans vermek için bu alan adını kullanır.
- Webhook'unuzu çağırın kutusunu işaretleyin ve webhook'unuzda görsel seçim yanıtı için kullanmak istediğiniz etkinlik işleyicinin adını girin.
- İstem gönder kutusunu işaretleyin.
- İstemde, döndürmek istediğiniz görsel seçim yanıtına göre uygun JSON veya YAML içeriğini sağlayın.
- Webhook'unuzda, Seçili öğeleri işleme bölümündeki adımları uygulayın.
Kullanılabilir istem özellikleri ve geçersiz kılma türleri örnekleri için aşağıdaki liste, koleksiyon ve koleksiyona göz atma bölümlerine bakın.
Seçili öğeler işleniyor
Görsel seçim yanıtları, webhook kodunuzda bir kullanıcının seçimini işlemenizi gerektirir. Kullanıcı, görsel seçim yanıtından bir şey seçtiğinde Google Asistan, alanı bu değerle doldurur.
Aşağıdaki örnekte, webhook kodu, belirlenen seçeneği bir değişkende alıp depolar:
Node.js
app.handle('Option', conv => { // Note: 'prompt_option' is the name of the slot. const selectedOption = conv.session.params.prompt_option; conv.add(`You selected ${selectedOption}.`); });
JSON
{ "responseJson": { "session": { "id": "session_id", "params": { "prompt_option": "ITEM_1" } }, "prompt": { "override": false, "firstSimple": { "speech": "You selected ITEM_1.", "text": "You selected ITEM_1." } } } }
Liste
![Mobil cihazda liste seçimi yanıtı örneği](https://developers-dot-devsite-v2-prod.appspot.com/static/assistant/conversational/images/list.png?authuser=6&hl=tr)
Bir liste, kullanıcılara birden çok öğeden oluşan dikey bir liste sunar ve kullanıcıların dokunarak veya ses girişiyle bir öğe seçmelerine olanak tanır. Bir kullanıcı listeden öğe seçtiğinde Asistan, liste öğesinin başlığını içeren bir kullanıcı sorgusu (sohbet balonu) oluşturur.
Listeler, seçeneklerin netleştirilmesinin önemli olduğu veya kullanıcının tümüyle taranması gereken seçenekler arasında seçim yapması gerektiği durumlarda yararlıdır. Örneğin, Peter Jons ile mi yoksa Peter Hans'la mı konuşmanız gerekiyor?
Listeler en az 2, en fazla 30 liste öğesi içermelidir. Başlangıçta görüntülenen öğe sayısı kullanıcının cihazına bağlıdır ve yaygın başlangıç numarası 10 öğedir.
Liste oluşturma
Liste oluştururken, isteminiz yalnızca kullanıcının seçebileceği her öğe için anahtarlar içerir. Webhook'unuzda, bu anahtarlara karşılık gelen öğeleri Entry
türüne göre tanımlarsınız.
Entry
nesneleri olarak tanımlanan liste öğeleri, aşağıdaki görüntüleme özelliklerine sahiptir:
- Başlık
- Sabit yazı tipi ve yazı tipi boyutu
- Maks. uzunluk: 1 satır (üç noktayla kısaltılır...)
- Benzersiz olması gerekir (ses seçimini desteklemek için)
- Açıklama (isteğe bağlı)
- Sabit yazı tipi ve yazı tipi boyutu
- Maksimum uzunluk: 2 satır (üç noktayla kısaltılır...)
- Resim (isteğe bağlı)
- Boyut: 48x48 piksel
Görsel seçim yanıtları, TYPE_REPLACE
modunda çalışma zamanı türü kullanarak türü alan adıyla geçersiz kılmanızı gerektirir. Webhook etkinlik işleyicinizde, name
özelliğindeki alan adına göre (Seçim yanıtları ekleme bölümünde tanımlanır) geçersiz kılmak için türe başvurun.
Bir türün üzerine yazıldıktan sonra sonuçta ortaya çıkan tür, kullanıcınızın Asistan'ın gösterdiği arasından seçebileceği öğe listesini temsil eder.
Özellikler
Liste yanıt türü aşağıdaki özelliklere sahiptir:
Özellik | Tür | Koşul | Açıklama |
---|---|---|---|
items |
ListItem dizisi |
Gerekli | Listede kullanıcıların seçebileceği bir öğeyi temsil eder. Her ListItem , liste öğesi için başvurulan bir türle eşlenen bir anahtar içerir. |
title |
dize | İsteğe bağlı | Listenin tek bir satırla sınırlandırılmış düz metin başlığı. Başlık belirtilmezse kart yüksekliği daraltılır. |
subtitle |
dize | İsteğe bağlı | Listenin düz metin alt başlığı. |
Örnek kod
Aşağıdaki örnekler, webhook kodunda veya JSON webhookResponse'ta istem içeriğini tanımlar. Ancak bunun yerine istem içeriğini Actions Builder'da (YAML veya JSON olarak) tanımlayabilirsiniz.
Node.js
const ASSISTANT_LOGO_IMAGE = new Image({ url: 'https://developers.google.com/assistant/assistant_96.png', alt: 'Google Assistant logo' }); app.handle('List', conv => { conv.add('This is a list.'); // Override type based on slot 'prompt_option' conv.session.typeOverrides = [{ name: 'prompt_option', mode: 'TYPE_REPLACE', synonym: { entries: [ { name: 'ITEM_1', synonyms: ['Item 1', 'First item'], display: { title: 'Item #1', description: 'Description of Item #1', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_2', synonyms: ['Item 2', 'Second item'], display: { title: 'Item #2', description: 'Description of Item #2', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_3', synonyms: ['Item 3', 'Third item'], display: { title: 'Item #3', description: 'Description of Item #3', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_4', synonyms: ['Item 4', 'Fourth item'], display: { title: 'Item #4', description: 'Description of Item #4', image: ASSISTANT_LOGO_IMAGE, } }, ] } }]; // Define prompt content using keys conv.add(new List({ title: 'List title', subtitle: 'List subtitle', items: [ { key: 'ITEM_1' }, { key: 'ITEM_2' }, { key: 'ITEM_3' }, { key: 'ITEM_4' } ], })); });
JSON
{ "responseJson": { "session": { "id": "session_id", "params": {}, "typeOverrides": [ { "name": "prompt_option", "synonym": { "entries": [ { "name": "ITEM_1", "synonyms": [ "Item 1", "First item" ], "display": { "title": "Item #1", "description": "Description of Item #1", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_2", "synonyms": [ "Item 2", "Second item" ], "display": { "title": "Item #2", "description": "Description of Item #2", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_3", "synonyms": [ "Item 3", "Third item" ], "display": { "title": "Item #3", "description": "Description of Item #3", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_4", "synonyms": [ "Item 4", "Fourth item" ], "display": { "title": "Item #4", "description": "Description of Item #4", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } } ] }, "typeOverrideMode": "TYPE_REPLACE" } ] }, "prompt": { "override": false, "content": { "list": { "items": [ { "key": "ITEM_1" }, { "key": "ITEM_2" }, { "key": "ITEM_3" }, { "key": "ITEM_4" } ], "subtitle": "List subtitle", "title": "List title" } }, "firstSimple": { "speech": "This is a list.", "text": "This is a list." } } } }
Koleksiyon
Koleksiyon yatay olarak kaydırılır ve kullanıcıların dokunarak veya ses girişiyle bir öğe seçmesine olanak tanır. Listelere kıyasla koleksiyonlar büyük karolara sahiptir ve daha zengin içeriğe olanak tanır. Koleksiyonu oluşturan karolar, resimli temel karta benzer. Kullanıcılar bir koleksiyondan öğe seçtiğinde Asistan, öğenin başlığını içeren bir kullanıcı sorgusu (sohbet balonu) oluşturur.
Koleksiyonlar, kullanıcıya çeşitli seçenekler sunulduğunda kullanışlıdır, ancak bunlar arasında doğrudan karşılaştırma yapmak gerekmez (listelere kıyasla). Genel olarak, listelerin görsel olarak taranması ve sesle etkileşim kurulması daha kolay olduğundan, koleksiyon yerine listeleri tercih edin.
Koleksiyonlar en az 2, en fazla 10 karo içermelidir. Görüntüleme özellikli cihazlarda, kullanıcılar bir öğeyi seçmeden önce koleksiyondaki kartlar arasında gezinmek için ekranı sola veya sağa kaydırabilirler.
![Akıllı ekranda koleksiyon seçimi yanıtı örneği](https://developers-dot-devsite-v2-prod.appspot.com/static/assistant/conversational/images/smart-display/carousel.png?authuser=6&hl=tr)
Koleksiyon oluşturma
Koleksiyon oluştururken, isteminiz yalnızca kullanıcının seçebileceği her öğe için anahtar içerir. Webhook'unuzda, bu anahtarlara karşılık gelen öğeleri Entry
türüne göre tanımlarsınız.
Entry
nesneleri olarak tanımlanan koleksiyon öğeleri, aşağıdaki görüntüleme özelliklerine sahiptir:
- Resim (isteğe bağlı)
- Resmin genişliği 128 dp yüksekliği x 232 dp olması zorunlu kılınır
- Resmin en boy oranı resim sınırlayıcı kutuyla eşleşmiyorsa resim her iki tarafta çubuklarla ortalanır.
- Resim bağlantısı bozuksa bunun yerine yer tutucu resim kullanılır
- Başlık (zorunlu)
- Düz metin, Markdown desteklenmez. Temel kart zengin yanıt ile aynı biçimlendirme seçenekleri
- Başlık belirtilmezse kart yüksekliği daraltılır.
- Benzersiz olması gerekir (ses seçimini desteklemek için)
- Açıklama (isteğe bağlı)
- Düz metin, Markdown desteklenmez. Temel kart zengin yanıt ile aynı biçimlendirme seçenekleri
Görsel seçim yanıtları, TYPE_REPLACE
modunda çalışma zamanı türü kullanarak türü alan adıyla geçersiz kılmanızı gerektirir. Webhook etkinlik işleyicinizde, name
özelliğindeki alan adına göre (Seçim yanıtları ekleme bölümünde tanımlanır) geçersiz kılmak için türe başvurun.
Bir türün üzerine yazıldıktan sonra elde edilen tür, kullanıcınızın Asistan'ın görüntülediği öğeler arasından seçim yapabileceği öğe koleksiyonunu temsil eder.
Özellikler
Koleksiyon yanıt türü aşağıdaki özelliklere sahiptir:
Özellik | Tür | Koşul | Açıklama |
---|---|---|---|
items |
CollectionItem dizisi |
Gerekli | Koleksiyonda kullanıcıların seçebileceği bir öğeyi temsil eder. Her CollectionItem , koleksiyon öğesi için başvurulan bir türle eşlenen bir anahtar içerir. |
title |
dize | İsteğe bağlı | Koleksiyonun düz metin başlığı. Ses seçimini desteklemek için koleksiyonda başlıklar benzersiz olmalıdır. |
subtitle |
dize | İsteğe bağlı | Koleksiyonun düz metin alt başlığı. |
image_fill |
ImageFill |
İsteğe bağlı | Resmin en boy oranı, resim kapsayıcısının en boy oranıyla eşleşmediğinde kullanılacak kart ile resim kapsayıcısı arasındaki kenarlık. |
Örnek kod
Aşağıdaki örnekler, webhook kodunda veya JSON webhook yanıtında bulunan istem içeriğini tanımlar. Ancak bunun yerine istem içeriğini Actions Builder'da (YAML veya JSON olarak) tanımlayabilirsiniz.
Node.js
const ASSISTANT_LOGO_IMAGE = new Image({ url: 'https://developers.google.com/assistant/assistant_96.png', alt: 'Google Assistant logo' }); app.handle('Collection', conv => { conv.add("This is a collection."); // Override type based on slot 'prompt_option' conv.session.typeOverrides = [{ name: 'prompt_option', mode: 'TYPE_REPLACE', synonym: { entries: [ { name: 'ITEM_1', synonyms: ['Item 1', 'First item'], display: { title: 'Item #1', description: 'Description of Item #1', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_2', synonyms: ['Item 2', 'Second item'], display: { title: 'Item #2', description: 'Description of Item #2', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_3', synonyms: ['Item 3', 'Third item'], display: { title: 'Item #3', description: 'Description of Item #3', image: ASSISTANT_LOGO_IMAGE, } }, { name: 'ITEM_4', synonyms: ['Item 4', 'Fourth item'], display: { title: 'Item #4', description: 'Description of Item #4', image: ASSISTANT_LOGO_IMAGE, } }, ] } }]; // Define prompt content using keys conv.add(new Collection({ title: 'Collection Title', subtitle: 'Collection subtitle', items: [ { key: 'ITEM_1' }, { key: 'ITEM_2' }, { key: 'ITEM_3' }, { key: 'ITEM_4' } ], })); });
JSON
{ "responseJson": { "session": { "id": "ABwppHHz--uQEEy3CCOANyB0J58oF2Yw5JEX0oXwit3uxDlRwzbEIK3Bcz7hXteE6hWovrLX9Ahpqu8t-jYnQRFGpAUqSuYjZ70", "params": {}, "typeOverrides": [ { "name": "prompt_option", "synonym": { "entries": [ { "name": "ITEM_1", "synonyms": [ "Item 1", "First item" ], "display": { "title": "Item #1", "description": "Description of Item #1", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_2", "synonyms": [ "Item 2", "Second item" ], "display": { "title": "Item #2", "description": "Description of Item #2", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_3", "synonyms": [ "Item 3", "Third item" ], "display": { "title": "Item #3", "description": "Description of Item #3", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } }, { "name": "ITEM_4", "synonyms": [ "Item 4", "Fourth item" ], "display": { "title": "Item #4", "description": "Description of Item #4", "image": { "alt": "Google Assistant logo", "height": 0, "url": "https://developers.google.com/assistant/assistant_96.png", "width": 0 } } } ] }, "typeOverrideMode": "TYPE_REPLACE" } ] }, "prompt": { "override": false, "content": { "collection": { "imageFill": "UNSPECIFIED", "items": [ { "key": "ITEM_1" }, { "key": "ITEM_2" }, { "key": "ITEM_3" }, { "key": "ITEM_4" } ], "subtitle": "Collection subtitle", "title": "Collection Title" } }, "firstSimple": { "speech": "This is a collection.", "text": "This is a collection." } } } }
Koleksiyona göz at
Bir koleksiyona benzer şekilde, koleksiyona göz atma kullanıcıların seçenek kartlarında gezinmesine olanak tanıyan zengin bir yanıttır. Koleksiyona göz atma, web içeriği için özel olarak tasarlanmıştır ve seçilen kartı bir web tarayıcısında (veya tüm karolar AMP özellikliyse bir AMP tarayıcısında) açar.
Koleksiyona göz atma yanıtları en az 2, en fazla 10 karo içerir. Görüntüleme özellikli cihazlarda, kullanıcılar bir öğeyi seçmeden önce yukarı veya aşağı kaydırarak kartlar arasında gezinebilirler.
Koleksiyona göz atma oluşturma
Koleksiyona göz atma oluştururken kullanıcıların bu istemle nasıl etkileşimde bulunacağını düşünün. Her koleksiyona göz atma item
, tanımlı URL'sini açar. Bu nedenle, kullanıcıya faydalı bilgiler sağlayın.
Koleksiyona göz atma öğeleri aşağıdaki görünüm özelliklerine sahiptir:
- Resim (isteğe bağlı)
- Resim 128 dp yükseklik x 232 dp genişlikte olmaya zorlanır.
- Resmin en boy oranı resim sınırlayıcı kutuyla eşleşmiyorsa görüntü yanlarda veya üstte ve altta çubuklarla ortalanır. Çubukların rengi, koleksiyona göz atma
ImageFill
özelliği tarafından belirlenir. - Resim bağlantısı bozuksa onun yerine bir yer tutucu resim kullanılır.
- Başlık (zorunlu)
- Düz metin, Markdown desteklenmez. Temel kart zengin yanıtı ile aynı biçimlendirme kullanılır.
- Başlık tanımlanmamışsa kart yüksekliği daraltılır.
- Açıklama (isteğe bağlı)
- Düz metin, Markdown desteklenmez. Temel kart zengin yanıtı ile aynı biçimlendirme kullanılır.
- Altbilgi (isteğe bağlı)
- Düz metin; Markdown desteklenmez.
Özellikler
Koleksiyona göz atma yanıt türü aşağıdaki özelliklere sahiptir:
Özellik | Tür | Koşul | Açıklama |
---|---|---|---|
item |
nesne | Gerekli | Koleksiyonda kullanıcıların seçebileceği bir öğeyi temsil eder. |
image_fill |
ImageFill |
İsteğe bağlı | Resmin en boy oranı, resim kapsayıcısının en boy oranıyla eşleşmediğinde kullanılacak kart ile resim kapsayıcısı arasındaki kenarlık. |
Koleksiyona göz atma item
aşağıdaki özelliklere sahiptir:
Özellik | Tür | Koşul | Açıklama |
---|---|---|---|
title |
dize | Gerekli | Koleksiyon öğesinin düz metin başlığı. |
description |
dize | İsteğe bağlı | Koleksiyon öğesinin açıklaması. |
footer |
dize | İsteğe bağlı | Koleksiyon öğesinin açıklamanın altında görüntülenen altbilgi metni. |
image |
Image |
İsteğe bağlı | Koleksiyon öğesi için gösterilen resim. |
openUriAction |
OpenUrl |
Gerekli | Koleksiyon öğesi seçildiğinde açılacak URI. |
Örnek kod
Aşağıdaki örnekler, webhook kodunda veya JSON webhook yanıtında bulunan istem içeriğini tanımlar. Ancak bunun yerine istem içeriğini Actions Builder'da (YAML veya JSON olarak) tanımlayabilirsiniz.
YAML
candidates: - first_simple: variants: - speech: This is a collection browse. content: collection_browse: items: - title: Item #1 description: Description of Item #1 footer: Footer of Item #1 image: url: 'https://developers.google.com/assistant/assistant_96.png' open_uri_action: url: 'https://www.example.com' - title: Item #2 description: Description of Item #2 footer: Footer of Item #2 image: url: 'https://developers.google.com/assistant/assistant_96.png' open_uri_action: url: 'https://www.example.com' image_fill: WHITE
JSON
{ "candidates": [ { "firstSimple": { "speech": "This is a collection browse.", "text": "This is a collection browse." }, "content": { "collectionBrowse": { "items": [ { "title": "Item #1", "description": "Description of Item #1", "footer": "Footer of Item #1", "image": { "url": "https://developers.google.com/assistant/assistant_96.png" }, "openUriAction": { "url": "https://www.example.com" } }, { "title": "Item #2", "description": "Description of Item #2", "footer": "Footer of Item #2", "image": { "url": "https://developers.google.com/assistant/assistant_96.png" }, "openUriAction": { "url": "https://www.example.com" } } ], "imageFill": "WHITE" } } } ] }
Node.js
// Collection Browse app.handle('collectionBrowse', (conv) => { conv.add('This is a collection browse.'); conv.add(new CollectionBrowse({ 'imageFill': 'WHITE', 'items': [ { 'title': 'Item #1', 'description': 'Description of Item #1', 'footer': 'Footer of Item #1', 'image': { 'url': 'https://developers.google.com/assistant/assistant_96.png' }, 'openUriAction': { 'url': 'https://www.example.com' } }, { 'title': 'Item #2', 'description': 'Description of Item #2', 'footer': 'Footer of Item #2', 'image': { 'url': 'https://developers.google.com/assistant/assistant_96.png' }, 'openUriAction': { 'url': 'https://www.example.com' } } ] })); });
JSON
{ "responseJson": { "session": { "id": "session_id", "params": {}, "languageCode": "" }, "prompt": { "override": false, "content": { "collectionBrowse": { "imageFill": "WHITE", "items": [ { "title": "Item #1", "description": "Description of Item #1", "footer": "Footer of Item #1", "image": { "url": "https://developers.google.com/assistant/assistant_96.png" }, "openUriAction": { "url": "https://www.example.com" } }, { "title": "Item #2", "description": "Description of Item #2", "footer": "Footer of Item #2", "image": { "url": "https://developers.google.com/assistant/assistant_96.png" }, "openUriAction": { "url": "https://www.example.com" } } ] } }, "firstSimple": { "speech": "This is a collection browse.", "text": "This is a collection browse." } } } }