Interactive Canvas는 개발자가 대화 작업에 시각적 몰입형 환경을 추가할 수 있도록 Google 어시스턴트를 기반으로 빌드된 프레임워크입니다. 이 시각적 환경은 대화에서 어시스턴트가 사용자에게 응답으로 전송하는 대화형 웹 앱입니다. 어시스턴트 대화에서 인라인으로 존재하는 리치 응답과 달리 Interactive Canvas 웹 앱은 전체 화면 웹 뷰로 렌더링됩니다.
웹 앱: 대화 중에 사용자에게 응답으로 응답으로 전송하는 맞춤설정된 시각 요소가 있는 프런트엔드 웹 앱입니다. HTML, 자바스크립트, CSS와 같은 웹 기술을 사용하여 웹 앱을 빌드합니다.
Interactive Canvas 작업과 상호작용하는 사용자는 목표를 달성하기 위해 Google 어시스턴트와 연락을 주고받습니다. 그러나 Interactive Canvas의 경우 이 대화의 대부분은 웹 앱 컨텍스트 내에서 발생합니다. 대화형 작업을 웹 앱에 연결할 때 웹 앱 코드에 Interactive Canvas API를 포함해야 합니다.
대화형 캔버스 라이브러리: API를 사용하여 웹 앱과 대화 작업 간의 통신을 사용 설정하기 위해 웹 앱에 포함하는 자바스크립트 라이브러리입니다. 자세한 내용은 Interactive Canvas API 문서를 참고하세요.
Interactive Canvas 라이브러리를 포함하는 것 외에도 대화에서 Canvas 응답 유형을 반환하여 사용자 기기에서 웹 앱을 열어야 합니다. Canvas 응답을 사용하여 사용자 입력을 기반으로 웹 앱을 업데이트할 수도 있습니다.
Canvas: 웹 앱의 URL과 이를 전달할 데이터가 포함된 응답입니다. Actions Builder는 일치하는 인텐트와 현재 장면 데이터로 Canvas 응답을 자동으로 채워 웹 앱을 업데이트할 수 있습니다. 또는 Node.js 처리 라이브러리를 사용하여 웹훅에서 Canvas 응답을 전송할 수 있습니다. 자세한 내용은 캔버스 메시지를 참고하세요.
Interactive Canvas의 작동 방식을 보여주기 위해 기기 화면 색상을 사용자가 지정하는 색상으로 변경하는 Cool Colors라는 가상의 작업이 있다고 가정해 보겠습니다. 사용자가 작업을 호출하면 다음 흐름이 발생합니다.
사용자가 어시스턴트 기기에 "화면을 파란색으로 켜 줘"라고 말합니다.
Actions on Google 플랫폼은 사용자의 요청을 대화 로직으로 라우팅하여 인텐트를 일치시킵니다.
플랫폼은 인텐트를 이벤트와 일치시켜 이벤트를 트리거하고, 기기에 Canvas 응답을 전송합니다. 기기는 응답에 제공된 URL을 사용하여 웹 앱을 로드합니다 (아직 로드되지 않은 경우).
웹 앱이 로드되면 Interactive Canvas API에 콜백을 등록합니다.
캔버스 응답에 data 필드가 포함된 경우 data 필드의 객체 값이 웹 앱의 등록된 onUpdate 콜백에 전달됩니다. 이 예에서 대화형 로직은 값이 blue인 변수를 포함하는 데이터 필드와 함께 Canvas 응답을 전송합니다.
Canvas 응답의 data 값을 수신하면 onUpdate 콜백이 웹 앱의 맞춤 로직을 실행하고 정의된 변경사항을 적용할 수 있습니다. 이 예에서 onUpdate 콜백은 data에서 색상을 읽고 화면을 파란색으로 바꿉니다.
클라이언트 측 및 서버 측 처리
Interactive Canvas 작업을 빌드할 때 서버 처리 또는 클라이언트 처리 중에서 선택할 수 있습니다. 서버 처리에서는 주로 웹훅이 필요한 API를 사용합니다. 클라이언트 처리를 사용하면 클라이언트 측 API와 필요한 경우 캔버스가 아닌 기능 (예: 계정 연결)에 웹훅이 필요한 API를 사용할 수 있습니다.
프로젝트 생성 단계에서 서버 웹훅 처리를 사용하여 빌드하려는 경우 대화형 로직과 클라이언트 측 자바스크립트를 처리하는 웹훅을 배포하여 웹 앱을 업데이트하고 둘 사이의 통신을 관리해야 합니다.
클라이언트 처리(현재 개발자 프리뷰에서 사용 가능)로 빌드하려는 경우 새로운 클라이언트 측 API를 사용하여 웹 앱에만 있는 작업 로직을 빌드할 수 있습니다. 이를 통해 개발 환경이 간소화되고 대화 차례 간의 지연 시간이 줄어들며 기기 내 기능을 사용할 수 있게 됩니다. 필요한 경우 클라이언트에서 서버 측 로직으로 전환할 수도 있습니다.
[null,null,["최종 업데이트: 2023-05-16(UTC)"],[[["\u003cp\u003eInteractive Canvas is a framework by Google Assistant to build interactive, full-screen web apps for visual experiences within Conversational Actions.\u003c/p\u003e\n"],["\u003cp\u003eIt is currently supported on smart displays and Android mobile devices and is primarily used for gaming, storytelling, and educational experiences.\u003c/p\u003e\n"],["\u003cp\u003eInteractive Canvas Actions utilize a conversational interface paired with a web app, communicating using the Interactive Canvas API for dynamic updates.\u003c/p\u003e\n"],["\u003cp\u003eYou can implement your Action's logic using either server fulfillment (webhooks) or client fulfillment (client-side APIs).\u003c/p\u003e\n"],["\u003cp\u003eFor detailed guidance and a sample project, refer to the web apps documentation and the GitHub sample.\u003c/p\u003e\n"]]],[],null,["# Interactive Canvas\n\n**Figure 1.** An interactive game built using Interactive Canvas.\n\nInteractive Canvas is a framework built on Google Assistant that allows\ndevelopers to add visual, immersive experiences to Conversational Actions. This visual\nexperience is an interactive web app that Assistant sends as a response to the\nuser in conversation. Unlike [rich responses](/assistant/conversational/prompts-rich) that exist in-line in an\nAssistant conversation, the Interactive Canvas web app renders as a full-screen\nweb view.\n\nUse Interactive Canvas if you want to do any of the following in your Action:\n\n- Create full-screen visuals\n- Create custom animations and transitions\n- Do data visualization\n- Create custom layouts and GUIs\n\n| **Note:** At this time, Google is only approving Actions that use Interactive Canvas for gaming, storytelling, and educational experiences. Actions that use Interactive Canvas also take slightly longer for Google's review team to test and approve. Allow extra time in your release process to account for this.\n\nSupported devices\n-----------------\n\nInteractive Canvas is currently available on the following devices:\n\n- Smart displays\n- Android mobile devices\n\n| **Note:** For Canvas to work on Android mobile devices, your Android Google Search App (AGSA) must be version 9.86 or later.\n\nHow it works\n------------\n\nAn Action that uses Interactive Canvas consists of two main components:\n\n- **Conversational Action:** An Action that uses a conversational interface to fulfill user requests. You can use either [Actions Builder](/assistant/conversational/build#actions_builder) or the [Actions SDK](/assistant/conversational/build#actions_sdk) to build your conversation.\n- **Web app:** A front-end web app with customized visuals that your Action sends as a response to users during a conversation. You build the web app with web technologies like HTML, JavaScript, and CSS.\n\nUsers interacting with an Interactive Canvas Action have a back-and-forth\nconversation with Google Assistant to fulfill their goal. However, for\nInteractive Canvas, the bulk of this conversation occurs within the context of\nyour web app. When connecting your Conversational Action to your web app, you must include\nthe **Interactive Canvas API** in your web app code.\n\n- **Interactive Canvas library:** A JavaScript library that you include in the web app to enable communication between the web app and your Conversational Action using an API. For more information, see the [Interactive Canvas API documentation](/assistant/interactivecanvas/reference).\n\nIn addition to including the Interactive Canvas library, you must return the\n[`Canvas`](/assistant/conversational/reference/rest/v1/TopLevel/fulfill#canvas) response type in your conversation to open your web app on the\nuser's device. You can also use a `Canvas` response to update your web app based\non the user's input.\n\n- **`Canvas`:** A response that contains a URL of the web app and data to pass it. Actions Builder can automatically populate the `Canvas` response with the matched intent and current scene data to update the web app. Alternatively, you can send a `Canvas` response from a webhook using the [Node.js fulfillment library](https://actions-on-google.github.io/assistant-conversation-nodejs/3.0.0/classes/_conversation_prompt_canvas_.canvas.html). For more information, see [Canvas prompts](/assistant/interactivecanvas/prompts).\n\nTo illustrate how Interactive Canvas works, imagine a hypothetical Action\ncalled *Cool Colors* that changes the device screen color to a color the user\nspecifies. After the user invokes the Action, the following flow happens:\n\n1. The user says, *\"Turn the screen blue.\"* to the Assistant device.\n2. The Actions on Google platform routes the user's request to your conversational logic to match an intent.\n3. The platform matches the intent with the Action's scene, which triggers an event and sends a `Canvas` response to the device. The device loads a web app using a URL provided in the response (if it has not yet been loaded).\n4. When the web app loads, it registers callbacks with the Interactive Canvas API. If the Canvas response contains a `data` field, the object value of the `data` field is passed into the registered `onUpdate` callback of the web app. In this example, the conversational logic sends a `Canvas` response with a data field that includes a variable with the value of `blue`.\n5. Upon receiving the `data` value of the `Canvas` response, the `onUpdate` callback can execute custom logic for your web app and make the defined changes. In this example, the `onUpdate` callback reads the color from `data` and turns the screen blue.\n\nClient-side and server-side fulfillment\n---------------------------------------\n\n| **Warning:** Some client-side APIs listed in this documentation are in Developer Preview. You can test these APIs in the simulator, but do not deploy an Action that uses this feature to alpha, beta, or production channels. Actions deployed using these features will not function on end-user devices.\n\nWhen building an Interactive Canvas Action, you can choose between two fulfillment\nimplementation paths: server fulfillment or client fulfillment. With server\nfulfillment, you primarily use APIs that require a webhook. With client fulfillment,\nyou can use client-side APIs and, if needed, APIs that require a webhook for\nnon-Canvas features (such as account linking).\n\nIf you choose to build with [**server webhook fulfillment**](/assistant/interactivecanvas/prompts#enable_interactive_canvas) in\nthe project creation stage, you must deploy a webhook to handle the conversational\nlogic and client-side JavaScript to update the web app and manage communication\nbetween the two.\n\nIf you choose to build with [**client fulfillment**](/assistant/interactivecanvas/prompts#enable_interactive_canvas)\n(currently available in Developer Preview), you can use new client-side APIs to\nbuild your Action's logic exclusively in the web app, which simplifies the\ndevelopment experience, reduces latency between conversational turns, and\nenables you to use on-device capabilities. If needed, you can also switch to\nserver-side logic from the client.\n\nFor more information about client-side capabilities, see\n[Build with client-side fulfillment](/assistant/interactivecanvas/fulfillment#build_with_client-side_fulfillment).\n\nNext steps\n----------\n\nTo learn how to build a web app for Interactive Canvas, see [Web apps](/assistant/interactivecanvas/web-apps).\n\nTo see the code for a complete Interactive Canvas Action, see the\n[sample on GitHub](https://github.com/actions-on-google/actions-builder-canvas-nodejs)."]]
