会話型アクションのサポートは 2023 年 6 月 13 日に終了しました。詳細については、会話型アクションの廃止をご覧ください。

このページは Cloud Translation API によって翻訳されました。

キャンバスプロンプト

ウェブアプリに情報を渡すには、Canvas レスポンスを送信する必要があります会話ロジックから抽出できますCanvas レスポンスは、次のいずれかを行うことができます。

ユーザーのデバイスで全画面ウェブアプリをレンダリングする
ウェブアプリを更新するためのデータを渡す

以降のセクションでは、各リクエストに対して Canvas のレスポンスを返す方法について説明します。説明します。

Interactive Canvas を有効にする

Interactive Canvas を使用するには、特定の方法でアクションを構成する必要があります。 Interactive Canvas を使用するアクションを作成するには、追加ので変更できます（Actions SDK の場合は、 settings.yaml ファイルを参照）。Google Cloud Storage バケットを Actions SDK を使用して Interactive Canvas アクションを構成する方法については、以下をご覧ください。プロジェクトを作成します。

Actions Builder を使用する場合、以下の追加手順に沿ってインタラクティブモードを有効にするキャンバス:

[ゲーム] カードを選択しなかった場合は、どのようなタイプのアクションビルドしますか？] 画面で、上部のナビゲーションの [デプロイ] をクリックします。 [詳細情報] で [ゲーム&カテゴリ [保存] をクリックします。
Actions Console の上部ナビゲーションで [Develop] をクリックします。
左側のナビゲーションで [Interactive Canvas] をクリックします。
[Do you want your Action to use Interactive Canvas?] で、次のいずれかを選択します。次のとおりです。 <ph type="x-smartling-placeholder">
- サーバー Webhook フルフィルメントを使用して Interactive Canvas を有効にする。このオプション Webhook を利用して特定の機能にアクセスします。 onUpdate(): データをウェブアプリに渡します。有効にすると、インテントマッチングが処理されるため、移行前に Webhook を呼び出すこともできます。会話を終了することもできます。
- クライアントフルフィルメントを使用して Interactive Canvas を有効にする。このオプションでは Webhook フルフィルメントロジックをウェブアプリに移行し、必要な会話機能のみに Webhook が呼び出します。さまざまなオプションが含まれます有効にすると、expect() を使用して次のことを行えます。クライアントサイドでインテントハンドラを登録する。
省略可: [デフォルトのウェブアプリの URL を設定する] 欄にウェブアプリの URL を入力します。表示されます。これにより、URL フィールドを含むデフォルトの Canvas レスポンスがあります。
[保存] をクリックします。

Actions SDK を使用する場合は、以下の追加手順に沿ってインタラクティブを有効にしますキャンバス:

settings.yaml ファイルの category フィールドを GAMES_AND_TRIVIA に設定します。ユーザーがアクションを見つけやすくなります。
settings.yaml ファイルの usesInteractiveCanvas フィールドを true に設定します。

サーフェスの機能を確認する

Interactive Canvas フレームワークは、以下の機能を備えたアシスタントデバイスでのみ動作します。ビジュアルインターフェースであるため、アクションでは INTERACTIVE_CANVAS を確認する必要があります。機能。Actions Builder でプロンプトを定義する際、 Google Cloud コンソールの selector フィールドでデバイス機能のリストを candidates オブジェクト。プロンプトセレクタは、最も満足度の高いプロンプト候補を使用する必要があります。

Canvas レスポンスを返すには、アクションのロジックで次のことを行う必要があります。

ユーザーのデバイスが INTERACTIVE_CANVAS 機能をサポートしていることを確認します。条件ユーザーに Canvas レスポンスを送信します。
Interactive Canvas 機能を使用できない場合は、デバイスが機能 RICH_RESPONSE をサポートしている。対応している場合は、お客様にリッチレスポンスを使用してください。
リッチレスポンス機能を使用できない場合は、ユーザーにシンプルなレスポンス。

次のスニペットは、機能に基づいて適切なレスポンスを返します。確認できます。

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

ウェブアプリをレンダリングする

Interactive Canvas を使用するアクションには、カスタマイズされたレスポンスとしてユーザーに送信します。ウェブアプリがレンダリングされるとユーザーが認識できるまで、音声、テキスト、タップで会話が終了しました。

最初の Canvas レスポンスには、ウェブアプリの URL を含める必要があります。このタイプの Canvas レスポンスは、そのアドレスでウェブアプリをレンダリングするよう Google アシスタントに指示します確認できます。通常、最初の Canvas レスポンスを送信します。ユーザーがアクションを呼び出した直後に更新する必要があります。ウェブアプリが読み込まれると、 Interactive Canvas ライブラリが読み込まれ、ウェブアプリがコールバックハンドラを登録する Interactive Canvas API を活用できます。

次の図に示すように、ウェブアプリの URL は Actions Builder で指定できます。次のスクリーンショット:

Canvas レスポンスを含むプロンプトを作成する場合、ウェブアプリ URL の場合、Actions Builder が Canvas レスポンスの URL フィールドに自動入力します。詳細コンソールでウェブアプリの URL を設定する方法については、 Interactive Canvas を有効にします。

次のスニペットは、レンダリングされる Canvas レスポンスを作成する方法を示しています。ウェブアプリケーションを Actions Builder と Webhook の両方で実行できるようにします。

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

ウェブアプリを更新するためのデータを渡す

最初の Canvas レスポンスを送信した後、追加の Canvas を使用できます。レスポンスが data の更新を提供します。これはウェブアプリのカスタムロジックで使用されます変更してください。テストに合格する Canvas レスポンスを送信すると、ウェブアプリに渡されると、次のステップが発生します。

インテントがシーン内で一致すると、イベントと Canvas レスポンスがトリガーされます。 JSON ペイロードを含む data フィールドを含むレスポンスがレスポンスとして返されます。
data フィールドは onUpdate コールバックに渡され、できます。
会話アクションは、新しい Canvas レスポンスを送信して、 data フィールドを使用して、新しいアップデートを送信するか、新しい状態を読み込みます。

注: 後続のフルフィルメントで url フィールドの値が変更された場合ウェブアプリが再読み込みされます。url に同じ値を指定した場合、または後続のレスポンスで url が除外されている場合、既存のウェブアプリデバイスに保存されます。

ウェブアプリにデータを渡すには、次の 2 つの方法があります。

Actions Builder を使用する。Actions Builder の data フィールドには、ウェブアプリを更新するために必要なメタデータを含む Canvas レスポンス。
Webhook を使用する。Webhook がある場合は、カスタムデータを使用して、Canvas レスポンスのウェブアプリを更新します。

以降のセクションでは、Actions Builder とできます。

Actions Builder を使用してデータを渡す

Actions Builder では、メタデータを管理するために Webhook を定義する必要がないウェブアプリに送信されます代わりに、Google Cloud コンソールでインテントハンドラを構成するときに、 Canvas レスポンスを含めることができます。 data フィールドには、更新に必要なメタデータが自動的に入力されます。たとえば、インテント名、ユーザーの入力から取得したパラメータ、現在のシーンが表示されます。

たとえば、次の Guess インテントハンドラは、Canvas をインクルードすることを示しています。レスポンス:

YAML

candidates:
  - canvas:
      send_state_data_to_canvas_app: true

JSON

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

必要に応じて、次のスニペットをインテントハンドラに追加して、 TTS メッセージ:

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

Actions Builder は、メタデータを含む Canvas レスポンスを自動的に拡張して、ウェブアプリを更新します。以下のスニペットをご覧ください。この場合、ユーザーは「a」の文字を推測した単語推測ゲームで、

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

このレスポンスは、ユーザーの回答でウェブアプリを更新し、選択します。

Webhook を使用してデータを渡す

Webhook の Canvas レスポンスの data フィールドは手動で構成できます必要な状態情報が渡されます。このアプローチは、 Canvas レスポンスにカスタム data ペイロードを含める必要がある場合に推奨されます。ウェブアプリの更新に必要な一般的なメタデータだけを渡すのではなく、

次のスニペットは、Canvas レスポンスでデータを渡す方法を示しています。 Webhook:

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

ガイドラインと制限事項

Canvas の回答に関する次のガイドラインと制限事項に留意してください次の点に注意してください。

フルフィルメント内の各 Webhook ハンドラに Canvas を含める必要があります。Webhook がレスポンスに Canvas が含まれていない場合、ウェブアプリは終了します。
最初の Canvas レスポンスには、ウェブアプリの URL のみを含める必要があります送信します。
Canvas レスポンス URL が有効で、プロトコルが https である必要があります。
Canvas レスポンスのサイズは 50 KB 以下にする必要があります。

キャンバス プロンプト

Interactive Canvas を有効にする

サーフェスの機能を確認する

YAML

JSON

Node.js

ウェブアプリをレンダリングする

YAML

JSON

Node.js

JSON

ウェブアプリを更新するためのデータを渡す

Actions Builder を使用してデータを渡す

YAML

JSON

YAML

JSON

Webhook を使用してデータを渡す

Node.js

JSON

ガイドラインと制限事項

キャンバスプロンプト