Tuval istemleri

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:

  1. 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.
  2. Actions Console'un üst gezinme menüsünde Geliştir'i tıklayın.
  3. Sol gezinme menüsünde Etkileşimli Tuval'i tıklayın.
  4. İş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.
  5. İ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.
  6. 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:

  1. Kullanıcıların İşleminizi en iyi şekilde açıklamak ve keşfetmelerine yardımcı olmak için settings.yaml dosyanızdaki category alanını GAMES_AND_TRIVIA olarak ayarlayın.
  2. settings.yaml dosyanızdaki usesInteractiveCanvas 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:

  1. Kullanıcının cihazının INTERACTIVE_CANVAS özelliğini desteklediğinden emin olun. Bu durumda kullanıcıya bir Canvas yanıtı gönderin.
  2. 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.
  3. 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:

  1. Amaç bir sahne içinde eşleştirildiğinde bir etkinliği tetikler ve JSON yüküne sahip bir data alanı içeren Canvas yanıtı yanıt olarak geri gönderilir.
  2. data alanı, onUpdate geri çağırmasına iletilir ve web uygulamasını güncellemek için kullanılır.

  3. Conversational Action'ınız yeni bir Canvas yanıtı gönderebilir ve yeni güncellemeler göndermek veya yeni durumlar yüklemek için data 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ındaki data 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.