Perintah Canvas

Untuk menyampaikan informasi ke aplikasi web, Anda harus mengirim respons Canvas dari logika percakapan Anda. Respons Canvas dapat melakukan salah satu hal berikut:

  • Merender aplikasi web layar penuh di perangkat pengguna
  • Meneruskan data untuk mengupdate aplikasi web

Bagian berikut menjelaskan cara menampilkan respons Canvas untuk setiap skenario.

Mengaktifkan Canvas Interaktif

Anda harus mengonfigurasi Action dengan cara tertentu untuk menggunakan Canvas Interaktif. Pembuatan Action yang menggunakan Canvas Interaktif memerlukan konfigurasi tambahan di konsol Actions (dan, untuk Actions SDK, modifikasi pada file settings.yaml Anda). Untuk melihat prosedur lengkap dalam membuat dan mengonfigurasi Action Canvas Interaktif dengan Actions SDK, lihat Membuat project.

Saat menggunakan Action Builder, ikuti langkah-langkah tambahan berikut untuk mengaktifkan Canvas Interaktif:

  1. Jika Anda tidak memilih kartu Game di layar What type of Action do you want to build?, klik Deploy di navigasi atas. Di bagian Informasi Tambahan, pilih kategori Game & hiburan. Klik Simpan.
  2. Klik Develop di navigasi atas konsol Actions.
  3. Klik Interactive Canvas di navigasi kiri.
  4. Di bagian Do you want your Action to use Interactive Canvas?, pilih salah satu dari opsi berikut:
    • Mengaktifkan Canvas Interaktif dengan fulfillment webhook server. Opsi ini mengandalkan webhook untuk mengakses fitur tertentu, dan sering kali menggunakan onUpdate() untuk meneruskan data ke aplikasi web. Jika diaktifkan, kecocokan intent akan ditangani dalam scene, dan Anda dapat memilih untuk memanggil webhook sebelum bertransisi ke scene lain atau mengakhiri percakapan.
    • Aktifkan Canvas Interaktif dengan fulfillment klien. Opsi ini memungkinkan Anda memindahkan logika fulfillment webhook ke aplikasi web, dan membatasi panggilan webhook hanya ke fitur percakapan yang memerlukannya, seperti penautan akun. Jika diaktifkan, Anda dapat menggunakan expect() untuk mendaftarkan pengendali intent di sisi klien.
  5. Opsional: Masukkan URL aplikasi web ke kolom Setel URL aplikasi web default. Tindakan ini akan menambahkan respons Canvas default dengan kolom URL ke pemanggilan Utama Anda.
  6. Klik Simpan.

Saat menggunakan Actions SDK, ikuti langkah-langkah tambahan berikut untuk mengaktifkan Kanvas Interaktif:

  1. Tetapkan kolom category di file settings.yaml ke GAMES_AND_TRIVIA untuk mendeskripsikan dan membantu pengguna menemukan Action Anda dengan tepat.
  2. Tetapkan kolom usesInteractiveCanvas di file settings.yaml Anda ke true.

Memeriksa kemampuan platform

Framework Canvas Interaktif hanya berjalan di perangkat Asisten yang menyediakan antarmuka visual, sehingga Action Anda perlu memeriksa kemampuan INTERACTIVE_CANVAS di perangkat pengguna. Saat menentukan perintah di Action Builder, Anda dapat menentukan daftar kemampuan perangkat di kolom selector dari objek candidates. Pemilih perintah memilih kandidat perintah yang paling sesuai dengan kemampuan perangkat pengguna.

Untuk menampilkan respons Canvas, logika Action Anda harus melakukan hal berikut:

  1. Pastikan perangkat pengguna mendukung kemampuan INTERACTIVE_CANVAS. Jika ya, kirim respons Canvas kepada pengguna.
  2. Jika kemampuan Canvas Interaktif tidak tersedia, periksa apakah perangkat pengguna mendukung kemampuan RICH_RESPONSE. Jika ya, kirim pengguna respons kaya sebagai gantinya.
  3. Jika kemampuan respons lengkap tidak tersedia, kirim respons sederhana kepada pengguna.

Cuplikan berikut menampilkan respons yang sesuai berdasarkan kemampuan perangkat pengguna:

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.');
}
  

Render aplikasi web

Action yang menggunakan Canvas Interaktif menyertakan aplikasi web dengan visual yang disesuaikan yang Anda kirim ke pengguna sebagai respons. Setelah aplikasi web dirender, pengguna akan terus berinteraksi dengan aplikasi melalui suara, teks, atau sentuhan hingga percakapan berakhir.

Respons Canvas pertama Anda harus berisi URL aplikasi web. Jenis respons Canvas ini memberi tahu Asisten Google untuk merender aplikasi web di alamat tersebut di perangkat pengguna. Biasanya, Anda mengirim respons Canvas pertama segera setelah pengguna memanggil Action. Saat aplikasi web dimuat, library Canvas Interaktif dimuat, dan aplikasi web mendaftarkan pengendali callback dengan Interactive Canvas API.

Anda dapat menentukan URL aplikasi web di Action Builder, seperti yang ditunjukkan pada screenshot berikut:

Jika Anda membuat perintah yang menyertakan respons Canvas setelah menentukan URL aplikasi web, Action Builder akan otomatis mengisi kolom URL respons Canvas. Untuk informasi selengkapnya tentang cara menetapkan URL aplikasi web di konsol, lihat bagian Mengaktifkan Canvas Interaktif.

Cuplikan berikut menunjukkan cara membuat respons Canvas yang merender aplikasi web di Action Builder dan webhook Anda:

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"
    }
  }
}
    

Meneruskan data untuk mengupdate aplikasi web

Setelah mengirim respons Canvas awal, Anda dapat menggunakan respons Canvas tambahan untuk memberikan update ke data, yang digunakan logika kustom aplikasi web untuk membuat perubahan pada aplikasi web Anda. Saat Anda mengirim respons Canvas yang meneruskan data ke aplikasi web, langkah-langkah berikut akan terjadi:

  1. Saat dicocokkan dalam scene, intent akan memicu peristiwa, dan respons Canvas yang berisi kolom data dengan payload JSON akan dikirim kembali sebagai respons.
  2. Kolom data diteruskan ke callback onUpdate dan digunakan untuk mengupdate aplikasi web.
  3. Action Percakapan Anda dapat mengirim respons Canvas baru dan memberikan informasi di kolom data untuk mengirim update baru atau memuat status baru.

Anda dapat meneruskan data ke aplikasi web dengan dua cara:

  • Dengan Action Builder. Action Builder otomatis mengisi kolom data di respons Canvas dengan metadata yang diperlukan untuk memperbarui aplikasi web.
  • Dengan webhook. Jika memiliki webhook, Anda dapat mengonfigurasi payload data kustom untuk mengupdate aplikasi web di respons Canvas.

Bagian berikut menjelaskan cara meneruskan data melalui Action Builder dan melalui webhook.

Menggunakan Action Builder untuk meneruskan data

Dengan Action Builder, Anda tidak perlu menentukan webhook untuk mengelola metadata yang dikirim ke aplikasi web Anda. Sebagai gantinya, saat mengonfigurasi pengendali intent di UI Action Builder, Anda dapat menyertakan respons Canvas. Kolom data secara otomatis diisi dengan metadata yang diperlukan untuk mengupdate aplikasi web Anda, seperti nama intent, parameter apa pun yang diambil dari input pengguna, dan scene saat ini.

Misalnya, pengendali intent Guess berikut menunjukkan bahwa Anda ingin menyertakan respons Canvas:

YAML

candidates:
  - canvas:
      send_state_data_to_canvas_app: true
    

JSON

{
  "candidates": [
    {
      "canvas": {
        "send_state_data_to_canvas_app": true
      }
    }
  ]
}
    

Secara opsional, Anda dapat menambahkan cuplikan berikut ke pengendali intent untuk mengirim pesan TTS:

...
  - first_simple:
      variants:
        - speech: Optional message.

Action Builder secara otomatis memperluas respons Canvas dengan metadata untuk mengupdate aplikasi web, seperti ditunjukkan dalam cuplikan berikut. Dalam hal ini, pengguna menebak huruf "a" dalam game tebak kata:

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
      }
    }
  ]
}
    

Respons ini memperbarui aplikasi web Anda dengan jawaban pengguna dan bertransisi ke adegan yang sesuai.

Menggunakan webhook untuk meneruskan data

Anda dapat mengonfigurasi kolom data dari respons Canvas secara manual di webhook dengan informasi status yang diperlukan untuk mengupdate aplikasi web. Pendekatan ini direkomendasikan jika Anda perlu menyertakan payload data kustom dalam respons Canvas, bukan hanya meneruskan metadata standar yang diperlukan untuk mengupdate aplikasi web.

Cuplikan berikut menunjukkan cara meneruskan data dalam respons Canvas di webhook Anda:

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": ""
    }
  }
}
    

Panduan dan pembatasan

Perhatikan panduan dan pembatasan berikut untuk respons Canvas saat membuat Action Anda:

  • Setiap pengendali webhook dalam fulfillment Anda harus menyertakan Canvas. Jika respons webhook tidak menyertakan Canvas, aplikasi web Anda akan ditutup.
  • Anda hanya perlu menyertakan URL aplikasi web dalam respons Canvas pertama yang dikirim ke pengguna.
  • URL respons Canvas harus valid dan protokolnya harus https.
  • Respons Canvas harus berukuran 50 KB atau lebih kecil.