Web uygulamanıza bilgi aktarmak için konuşma mantığınızdan Canvas
yanıtı göndermeniz gerekir. Canvas
yanıtında aşağıdakilerden biri olabilir:
- Kullanıcının cihazında tam ekran web uygulamasını oluşturma
- Web uygulamasını güncellemek için veri iletme
Aşağıdaki bölümlerde, her bir senaryo için Canvas yanıtının nasıl döndürüleceği açıklanmaktadır.
Etkileşimli Tuvali etkinleştir
Etkileşimli Tuval'i kullanmak için İşleminizi belirli bir şekilde yapılandırmanız gerekir.
Etkileşimli Tuval kullanan bir İşlem oluşturmak için Actions konsolunda ek yapılandırma (ve Actions SDK'sı için settings.yaml
dosyanızda değişiklikler) gerekir. Actions SDK ile Etkileşimli Tuval İşlemi oluşturma ve yapılandırma prosedürünün tamamını görmek için Proje oluşturma bölümüne bakın.
Actions Builder'ı kullanırken Etkileşimli Tuval'i etkinleştirmek için aşağıdaki ek adımları uygulayın:
- Ne tür bir işlem oluşturmak istiyorsunuz? ekranında Oyun kartını seçmediyseniz üstteki gezinme menüsünden Dağıt'ı tıklayın. Ek Bilgiler'in altında Oyunlar ve eğlence kategorisini seçin. Kaydet'i tıklayın.
- Actions Console'un üst gezinme menüsünde Geliştir'i tıklayın.
- Sol gezinme menüsünde Etkileşimli Tuval'i tıklayın.
- İşleminizin Etkileşimli Tuval'i kullanmasını istiyor musunuz? bölümünün altında aşağıdakilerden birini seçin:
- Sunucu web kancası istek karşılamasıyla Etkileşimli Tuval'i etkinleştirin. Bu seçenek, belirli özelliklere erişmek için webhook'u kullanır ve web uygulamasına veri aktarmak için sıklıkla
onUpdate()
özelliğini kullanır. Etkinleştirildiğinde, amaç eşleşmeleri sahnelerde işlenir ve başka bir sahneye geçiş yapmadan veya görüşmeyi sonlandırmadan önce webhook'u çağırmayı seçebilirsiniz. - İstemci istek karşılama ile Etkileşimli Tuval'i etkinleştirin. Bu seçenek sayesinde webhook karşılama mantığınızı web uygulamasına taşıyabilirsiniz ve webhook çağrılarını yalnızca bunu gerektiren sohbet özellikleriyle (ör. hesap bağlama) sınırlandırabilirsiniz. Etkinleştirildiğinde, istemci tarafında amaç işleyicileri kaydetmek için
expect()
kullanabilirsiniz.
- Sunucu web kancası istek karşılamasıyla Etkileşimli Tuval'i etkinleştirin. Bu seçenek, belirli özelliklere erişmek için webhook'u kullanır ve web uygulamasına veri aktarmak için sıklıkla
- İsteğe bağlı: Varsayılan web uygulaması URL'nizi ayarlayın alanına web uygulaması URL'nizi girin. Bu işlem, Ana çağrınıza URL alanı olan varsayılan bir
Canvas
yanıtı ekler. - Kaydet'i tıklayın.
Actions SDK'sını kullanırken Interactive Canvas'ı etkinleştirmek için aşağıdaki ek adımları uygulayın:
- Kullanıcıların İşleminizi en iyi şekilde açıklamak ve keşfetmelerine yardımcı olmak için
settings.yaml
dosyanızdakicategory
alanınıGAMES_AND_TRIVIA
olarak ayarlayın. settings.yaml
dosyanızdakiusesInteractiveCanvas
alanınıtrue
olarak ayarlayın.
Yüzey kapasitesini kontrol edin
Etkileşimli Tuval çerçevesi yalnızca görsel arayüz sağlayan Asistan cihazlarında çalışır. Bu nedenle İşleminizin, kullanıcının cihazında INTERACTIVE_CANVAS
özelliğini kontrol etmesi gerekir. Actions Builder'da istemler tanımlarken candidates
nesnesinin selector
alanında cihaz özelliklerinin bir listesini belirtebilirsiniz. İstem seçici, kullanıcının cihaz kapasitesi için en uygun istem adayını seçer.
Canvas
yanıtı döndürmek için İşleminizin mantığı aşağıdaki işlemleri gerçekleştirmelidir:
- Kullanıcının cihazının
INTERACTIVE_CANVAS
özelliğini desteklediğinden emin olun. Bu durumda kullanıcıya birCanvas
yanıtı gönderin. - Etkileşimli Tuval özelliği kullanılamıyorsa kullanıcının cihazının
RICH_RESPONSE
özelliğini destekleyip desteklemediğini kontrol edin. Varsa kullanıcıya zengin yanıt gönderin. - Zengin yanıt özelliği kullanılamıyorsa kullanıcıya basit bir yanıt gönderin.
Aşağıdaki snippet'ler kullanıcının cihazının özelliklerine bağlı olarak uygun yanıtı döndürür:
YAML
candidates: - selector: surface_capabilities: capabilities: - INTERACTIVE_CANVAS canvas: url: 'https://example.web.app' - selector: surface_capabilities: capabilities: - RICH_RESPONSE content: card: title: Card title text: Card Content image: url: 'https://example.com/image.png' alt: Alt text button: name: Link name open: url: 'https://example.com/' - first_simple: variants: - speech: Example simple response.
JSON
{ "candidates": [ { "selector": { "surface_capabilities": { "capabilities": [ "INTERACTIVE_CANVAS" ] } }, "canvas": { "url": "https://example.web.app" } }, { "selector": { "surface_capabilities": { "capabilities": [ "RICH_RESPONSE" ] } }, "content": { "card": { "title": "Card title", "text": "Card Content", "image": { "url": "https://example.com/image.png", "alt": "Alt text" }, "button": { "name": "Link name", "open": { "url": "https://example.com/" } } } } }, { "first_simple": { "variants": [ { "speech": "Example simple response." } ] } } ] }
Node.js
const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE"); const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS"); if (supportsInteractiveCanvas) { // Respond with a Canvas response conv.add(new Canvas({ url: 'https://example.web.app', })); } else if (supportsRichResponse) { // Respond with a rich response conv.add(new Card({ title: 'Card title', image: new Image({ url: 'https://example.com/image.png', alt: 'Alt text', }), button: new Link({ name: 'Link name', open: { url: 'https://example.com/', }, }), })); } else { // Respond with a simple response conv.add('Example simple response.'); }
Web uygulamasını oluştur
Etkileşimli Tuval kullanan bir İşlem, kullanıcılara yanıt olarak gönderdiğiniz özelleştirilmiş görseller içeren bir web uygulaması içerir. Web uygulaması oluşturulduktan sonra kullanıcılar, konuşma bitene kadar ses, metin veya dokunarak web uygulaması ile etkileşimde bulunmaya devam eder.
İlk Canvas
yanıtınız web uygulamasının URL'sini içermelidir. Bu tür Canvas
yanıtı, Google Asistan'a web uygulamasını kullanıcının cihazındaki ilgili adreste oluşturmasını bildirir. Genellikle ilk Canvas
yanıtını, kullanıcı İşleminizi çağırdıktan hemen sonra gönderirsiniz. Web uygulaması yüklendiğinde Etkileşimli Tuval kitaplığı yüklenir ve web uygulaması, Interactive Canvas API ile bir geri çağırma işleyicisi kaydeder.
Web uygulamanızın URL'sini, aşağıdaki ekran görüntüsünde gösterildiği gibi Actions Builder'da belirtebilirsiniz:
Web uygulaması URL'sini belirttikten sonra Canvas
yanıtı içeren bir istem oluşturursanız Actions Builder, Canvas
yanıtının URL alanını otomatik olarak doldurur. Konsolda web uygulaması URL'sini ayarlama hakkında daha fazla bilgi için Etkileşimli Tuvali Etkinleştirme bölümüne bakın.
Aşağıdaki snippet'ler, web uygulamasını hem Actions Builder'da hem de webhook'unuzda oluşturan Canvas
yanıtlarının nasıl oluşturulacağını göstermektedir:
YAML
candidates: - first_simple: variants: - speech: >- Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later. canvas: url: 'https://your-web-app.com'
JSON
{ "candidates": [ { "first_simple": { "variants": [ { "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later." } ] }, "canvas": { "url": "https://your-web-app.com" } } ] }
Node.js
app.handle('welcome', (conv) => { conv.add('Welcome! Do you want me to change color or pause spinning? ' + 'You can also tell me to ask you later.'); conv.add(new Canvas({ url: `https://your-web-app.com`, })); });
JSON
{ "session": { "id": "session_id", "params": {} }, "prompt": { "override": false, "firstSimple": { "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later.", "text": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later." }, "canvas": { "data": [], "suppressMic": false, "url": "https://your-web-app.com" } } }
Web uygulamasını güncellemek için veri iletme
İlk Canvas
yanıtını gönderdikten sonra, web uygulamanızın özel mantığının web uygulamanızda değişiklik yapmak için kullandığı data
ile ilgili güncellemeleri sağlamak için ek Canvas
yanıtlarını kullanabilirsiniz. Verileri web uygulamasına ileten bir Canvas
yanıtı gönderdiğinizde aşağıdaki adımlar gerçekleşir:
- Amaç bir sahne içinde eşleştirildiğinde bir etkinliği tetikler ve JSON yüküne sahip bir
data
alanı içerenCanvas
yanıtı yanıt olarak geri gönderilir. data
alanı,onUpdate
geri çağırmasına iletilir ve web uygulamasını güncellemek için kullanılır.Conversational Action'ınız yeni bir
Canvas
yanıtı gönderebilir ve yeni güncellemeler göndermek veya yeni durumlar yüklemek içindata
alanına bilgi sağlayabilir.
Verileri web uygulamanıza iki şekilde aktarabilirsiniz:
- Actions Builder ile. Actions Builder, web uygulamasını güncellemek için
Canvas
yanıtındakidata
alanını gerekli meta verilerle otomatik olarak doldurur. - Webhook ile. Bir webhook'unuz varsa
Canvas
yanıtınızda web uygulamasını güncellemek için özel bir veri yükü yapılandırabilirsiniz.
Aşağıdaki bölümlerde, verilerin Actions Builder ve webhook üzerinden nasıl iletileceği açıklanmaktadır.
Veri iletmek için Actions Builder'ı kullanma
Actions Builder sayesinde, web uygulamanıza gönderilen meta verileri yönetmek için webhook tanımlamanıza gerek yoktur. Bunun yerine, Actions Builder kullanıcı arayüzünde niyet işleyicinizi yapılandırırken bir Canvas
yanıtı ekleyebilirsiniz. Web uygulamanızı güncellemek için amaç adı, kullanıcı girişinden alınan parametreler ve geçerli sahne gibi gerekli meta verilerle otomatik olarak bir data
alanı doldurulur.
Örneğin, aşağıdaki Guess
amaç işleyici, bir Canvas
yanıtı eklemek istediğinizi belirtir:
YAML
candidates: - canvas: send_state_data_to_canvas_app: true
JSON
{ "candidates": [ { "canvas": { "send_state_data_to_canvas_app": true } } ] }
İsteğe bağlı olarak, bir TTS mesajı göndermek için aşağıdaki snippet'i amaç işleyiciye ekleyebilirsiniz:
...
- first_simple:
variants:
- speech: Optional message.
Actions Builder, web uygulamasını güncellemek için aşağıdaki snippet'lerde gösterildiği gibi Canvas
yanıtını meta verilerle otomatik olarak genişletir. Bu örnekte, kullanıcı bir kelime tahmin oyununda "a" harfini tahmin etmiştir:
YAML
candidates: - canvas: data: - google: intent: params: letter: resolved: a original: a name: guess scene: Game sendStateDataToCanvasApp: true
JSON
{ "candidates": [ { "canvas": { "data": [ { "google": { "intent": { "params": { "letter": { "resolved": "a", "original": "a" } }, "name": "guess" }, "scene": "Game" } } ], "sendStateDataToCanvasApp": true } } ] }
Bu yanıt, web uygulamanızı kullanıcının yanıtıyla günceller ve uygun sahneye geçiş yapar.
Veri iletmek için webhook'unuzu kullanma
Web uygulamanızı güncellemek için gerekli durum bilgileriyle webhook'unuzdaki Canvas
yanıtlarının data
alanını manuel olarak yapılandırabilirsiniz. Bu yaklaşım, yalnızca web uygulamasını güncellemek için gereken tipik meta verileri iletmek yerine Canvas
yanıtına özel bir data
yükü eklemeniz gerektiğinde önerilir.
Aşağıdaki snippet'ler webhook'unuzdaki bir Canvas
yanıtında verilerin nasıl iletileceğini gösterir:
Node.js
app.handle('start_spin', (conv) => { conv.add(`Ok, I'm spinning. What else?`); conv.add(new Canvas({ data: { command: 'SPIN', spin: true, }, })); });
JSON
{ "session": { "id": "session_id", "params": {} }, "prompt": { "override": false, "firstSimple": { "speech": "Ok, I'm spinning. What else?", "text": "Ok, I'm spinning. What else?" }, "canvas": { "data": { "command": "SPIN", "spin": true }, "suppressMic": false, "url": "" } } }
Kurallar ve kısıtlamalar
İşleminizi oluştururken Canvas
yanıtları için aşağıdaki yönergeleri ve kısıtlamaları göz önünde bulundurun:
- Karşılamanızdaki her webhook işleyicide
Canvas
bulunmalıdır. Webhook yanıtıCanvas
içermiyorsa web uygulamanız kapatılır. - Web uygulamanızın URL'sini kullanıcıya gönderdiğiniz ilk
Canvas
yanıta eklemeniz yeterlidir. Canvas
yanıt URL'si geçerli olmalı ve protokolü https olmalıdır.Canvas
yanıtının boyutu 50 KB veya daha küçük olmalıdır.