با Actions Builder یک اکشن Canvas Interactive برای Google Assistant بسازید

1. بررسی اجمالی

هشدار: کنش‌های مکالمه در 13 ژوئن 2023 منسوخ شد. برای اطلاعات بیشتر، غروب کنش‌های مکالمه را ببینید .

Actions on Google یک پلت فرم توسعه دهنده است که به شما امکان می دهد نرم افزاری ایجاد کنید تا عملکرد Google Assistant ، دستیار شخصی مجازی Google را در بیش از 1 میلیارد دستگاه، از جمله بلندگوهای هوشمند، تلفن ها، اتومبیل ها، تلویزیون ها، هدفون ها و موارد دیگر گسترش دهید. کاربران برای انجام کارهایی مانند خرید مواد غذایی یا رزرو یک سواری، دستیار Google را در گفتگو درگیر می‌کنند. برای فهرست کاملی از آنچه اکنون امکان پذیر است، دایرکتوری Actions را ببینید. به عنوان یک برنامه‌نویس، می‌توانید از Actions on Google برای ایجاد و مدیریت تجربیات گفتگوی لذت‌بخش و مفید بین کاربران و سرویس شخص ثالث خود به‌راحتی استفاده کنید.

این کد لبه یک ماژول پیشرفته است که برای خوانندگانی در نظر گرفته شده است که قبلاً تجربه ساخت اکشن‌ها برای دستیار Google را دارند. اگر تجربه توسعه قبلی با Actions on Google ندارید، با دنبال کردن کدهای مقدماتی ( سطح 1 و سطح 2 ) با این پلتفرم آشنا شوید. این ماژول‌ها شما را از طریق مجموعه‌ای از ویژگی‌ها راهنمایی می‌کنند که می‌توانند به شما در گسترش عملکرد Action و افزایش مخاطبانتان کمک کنند.

در این کد لبه، شما از Interactive Canvas ، یک چارچوب ساخته شده بر روی دستیار Google، برای افزودن یک بازی تمام صفحه به یک کنش مکالمه استفاده می‌کنید. این بازی یک برنامه وب تعاملی است که Assistant به عنوان پاسخی برای کاربر در مکالمه ارسال می کند. سپس کاربر می تواند بازی را از طریق ورودی صوتی یا متنی روی نمایشگرهای هوشمند و دستگاه های تلفن همراه اندرویدی انجام دهد.

به جای اینکه خودتان یک بازی کامل بسازید، یک بازی نیمه از پیش ساخته شده به نام Snow Pal را اجرا می کنید و با پیشروی در لابلای کد، منطق بازی را اضافه می کنید. Snow Pal نوعی از بازی سنتی Hangman است. بازی تعدادی فضای خالی به شما نشان می دهد که یک کلمه را نشان می دهد و حروفی را که فکر می کنید ممکن است در کلمه باشد حدس می زنید. با هر حدس نادرست، Snow Pal شما کمی بیشتر آب می شود. اگر بتوانید کلمه را قبل از ذوب شدن کامل Snow Pal خود بفهمید، بازی را برنده خواهید شد.

شکل 1. بازی Snow Pal نیمه کامل شده

چیزی که خواهی ساخت

در این کد لبه، شما یک Action می سازید که از Canvas تعاملی استفاده می کند. Action شما دارای ویژگی های زیر خواهد بود:

• یک بازی کلمه تمام صفحه که کاربران می توانند از طریق صدا بازی کنند
• دکمه ای که کاربران می توانند برای شروع بازی فشار دهند
• دکمه ای را که کاربران می توانند برای بازی دوباره فشار دهند

وقتی این کد لبه را تمام کردید، Action تکمیل شده شما جریان مکالمه زیر را خواهد داشت:

دستیار: Welcome to Snow Pal! Would you like to start playing the game?

کاربر: Yes.

دستیار: Try guessing a letter in the word or guessing the word.

کاربر: I guess the letter E باشد .

دستیار: Let's see if your guess is there...E is right. Right on! Good guess.

کاربر به حدس زدن حروف یا حدس زدن خود کلمه ناشناخته تا پایان بازی ادامه می دهد.

چیزی که یاد خواهید گرفت

• چگونه یک اکشن Canvas Interactive بسازیم و اجرا کنیم
• نحوه به روز رسانی بازی کلمات بر اساس صدای کاربر و ورودی لمسی
• نحوه انتقال داده ها به برنامه وب با استفاده از روش های مختلف
• چگونه اکشن Interactive Canvas خود را اشکال زدایی کنیم

آنچه شما نیاز دارید

پیش نیازهای این کد لبه شامل موارد زیر است:

• یک مرورگر وب، مانند گوگل کروم
• یک IDE یا ویرایشگر متن به انتخاب شما
• Node.js ، npm و git روی دستگاه شما نصب شده است

آشنایی با جاوا اسکریپت (ES6) اکیداً توصیه می شود تا به شما در درک کدهای استفاده شده در این کد لبه کمک کند.

اختیاری: کد نمونه کامل را دریافت کنید

در این کد لبه، شما نمونه را گام به گام از روی یک نسخه ناقص می سازید. در صورت تمایل، می توانید نمونه کامل شده را از مخزن GitHub نیز دریافت کنید.

2. معرفی بوم تعاملی

بوم تعاملی چارچوبی است که بر روی Google Assistant ساخته شده است که به شما امکان می دهد تصاویر و انیمیشن های تمام صفحه را به کنش مکالمه خود اضافه کنید.

اصطلاح کلیدی:

• کنش مکالمه: اقدامی که از یک رابط مکالمه برای انجام درخواست های کاربر استفاده می کند.

اکشنی که از Canvas تعاملی استفاده می‌کند مانند یک کنش مکالمه معمولی عمل می‌کند. با این حال، یک کنش بوم تعاملی دارای قابلیت اضافی برای ارسال پاسخ به دستگاهی است که یک برنامه وب تمام صفحه را باز می کند.

اصطلاح کلیدی:

• برنامه وب: برنامه ای که از فناوری های مبتنی بر وب مانند HTML، CSS و جاوا اسکریپت برای ایجاد یک تجربه تعاملی و بصری مانند یک بازی استفاده می کند. در این کد، اپلیکیشن وب، تصاویر و انیمیشن های بازی Snow Pal است.

کاربر تا زمانی که مکالمه به پایان برسد، ورودی را از طریق صدا یا لمس به برنامه وب ارائه می دهد.

شکل 2. یک اقدام ساخته شده با بوم تعاملی.

در این نرم افزار کد، پروژه شما در سه بخش اصلی زیر سازماندهی شده است:

• برنامه وب: فایل های برنامه وب حاوی کد تصاویر و انیمیشن های برنامه وب شما و همچنین منطق به روز رسانی برنامه وب بر اساس ورودی کاربر است.
• کنش مکالمه: کنش مکالمه حاوی منطق مکالمه شما است که ورودی کاربر را شناسایی، پردازش کرده و به آن پاسخ می دهد.
• Webhook: وب هوک منطق بازی را کنترل می کند. برای این نرم افزار کد، می توانید وب هوک را به عنوان سرور بازی خود در نظر بگیرید.

اصطلاح کلیدی:

• Webhook: یک تماس پاسخ HTTP که درخواستی از یک صحنه یا هدف را مدیریت می کند، که معمولاً برای ایجاد پویا یک پاسخ مکالمه (اغلب با برقراری تماس های API) استفاده می شود.

برای هر بخش از این کد لبه، برنامه وب، کنش مکالمه و وب هوک را تغییر می‌دهید تا عملکردی به کنش بوم تعاملی خود اضافه کنید.

در سطح بالایی، Conversational Action، webhook، و برنامه وب در Snow Pal Action به روش زیر کار می کنند:

1. کنش مکالمه از کاربر می خواهد حرفی را در کلمه حدس بزند یا کل کلمه را حدس بزند.
2. کاربر می گوید "حدس می زنم حرف i" را به برنامه وب Snow Pal در یک نمایشگر هوشمند می گوید.
3. ورودی کاربر به کنش مکالمه شما هدایت می شود، که در پروژه Actions Builder و/یا Actions SDK تعریف شده است.
4. کنش مکالمه ورودی کاربر را پردازش می‌کند و بسته به اینکه ورودی چیست، منطقی را در وب هوکی که برنامه وب را به‌روزرسانی می‌کند فعال می‌کند یا متادیتا را برای به‌روزرسانی مستقیم برنامه وب ارسال می‌کند.
5. برنامه وب برای نشان دادن جایی که حرف در کلمه ظاهر می شود به روز می شود و از کاربر خواسته می شود دوباره حدس بزند.

در بخش درک زیرساخت بوم تعاملی، در مورد نحوه عملکرد بوم تعاملی بیشتر خواهید آموخت. اکنون که اصول اولیه را می دانید، می توانید شروع به تنظیم محیط خود برای این نرم افزار کد کنید.

3. راه اندازی کنید

تنظیمات مجوز Google خود را بررسی کنید

برای آزمایش اکشنی که برای این کد لبه می‌سازید، باید مجوزهای لازم را فعال کنید تا شبیه‌ساز کنسول Actions بتواند به Action شما دسترسی داشته باشد. برای فعال کردن مجوزها، مراحل زیر را دنبال کنید:

1. به Activity Controls بروید.
2. در صورت لزوم، با حساب Google خود وارد شوید.
3. مجوزهای زیر را فعال کنید:

• فعالیت وب و برنامه
• در بخش «فعالیت وب و برنامه» ، کادر تأیید «شامل سابقه Chrome و فعالیت از سایت‌ها، برنامه‌ها و دستگاه‌هایی که از خدمات Google استفاده می‌کنند» را انتخاب کنید.

رابط خط فرمان gactions را نصب کنید

در این کد لبه، شما از ابزار رابط خط فرمان gactions (CLI) برای همگام سازی پروژه Actions خود بین کنسول Actions و سیستم فایل محلی خود استفاده می کنید.

اصطلاحات کلیدی:

• gactions CLI: ابزاری که به شما امکان می‌دهد فایل‌های پروژه Action را مقداردهی اولیه کنید، به‌روزرسانی‌ها را به کنسول Actions فشار دهید، پروژه‌های Actions را مستقر کنید و موارد دیگر.

برای نصب gactions CLI، دستورالعمل های بخش Install the gactions command-line tool را دنبال کنید.

رابط خط فرمان Firebase را نصب کنید

رابط خط فرمان Firebase (CLI) به شما امکان می دهد پروژه Actions خود را در Cloud Functions مستقر کنید و برنامه وب خود را میزبانی کنید.

اگر قبلاً Firebase CLI را نصب کرده‌اید، می‌توانید این مراحل را رد کرده و به بخش بعدی بروید.

این کد لبه از npm برای نصب Firebase CLI استفاده می کند. مطمئن شوید که npm را نصب کنید، که معمولاً با Node.js ارائه می شود.

1. برای نصب یا ارتقاء CLI، یک ترمینال را باز کنید و دستور npm زیر را اجرا کنید:

npm install -g firebase-tools

کار نمی کند؟ ممکن است لازم باشد مجوزهای npm را تغییر دهید .

2. برای اطمینان از اینکه CLI به درستی نصب شده است، دستور زیر را اجرا کنید:

firebase --version

مطمئن شوید که نسخه Firebase CLI 8 یا بالاتر باشد تا آخرین ویژگی‌های مورد نیاز برای Cloud Function را داشته باشد. اگر اینطور نیست، npm install -g firebase-tools برای ارتقا اجرا کنید.

3. برای ورود به Firebase دستور زیر را اجرا کنید:

firebase login

وقتی وارد Firebase می‌شوید، مطمئن شوید که از همان حساب Google استفاده می‌کنید که برای ایجاد پروژه Actions خود استفاده کرده‌اید.

مخزن را شبیه سازی کنید

در این قسمت فایل های مورد نیاز این کد لبه را کلون می کنید. برای دریافت این فایل ها مراحل زیر را دنبال کنید:

1. یک ترمینال را باز کنید و به دایرکتوری تغییر دهید که معمولاً پروژه های کدنویسی را در آن ذخیره می کنید. اگر یکی ندارید، به فهرست اصلی خود تغییر دهید.
2. برای کلون کردن این مخزن، دستور زیر را در ترمینال خود اجرا کنید:

git clone https://github.com/actions-on-google/actions-builder-canvas-codelab-nodejs

دایرکتوری start/ باز کنید. این مخزن شامل دایرکتوری های مهم زیر است که شما با آنها کار خواهید کرد:

• public/ : این فهرست شامل کدهای HTML، CSS و جاوا اسکریپت برای برنامه وب شما است.
• sdk/custom/ : این فهرست حاوی منطق کنش مکالمه شما (صحنه ها، مقاصد و انواع) است.
• sdk/webhooks/ : این دایرکتوری وب هوک شماست و حاوی منطق بازی است.

شکل 3. ساختار کد دایرکتوری start .

توجه: فایل های دارای کد تکمیل شده در پوشه complete/ موجود هستند.

4. پروژه Actions خود را راه اندازی کنید

در این بخش، پروژه Actions خود را ایجاد و پیکربندی می‌کنید، کد را از مخزن کلون شده به کنسول Actions با gactions CLI فشار می‌دهید و برنامه وب و وب هوک خود را مستقر می‌کنید.

یک پروژه Actions ایجاد کنید

پروژه Actions شما محفظه ای برای Action شماست. برای ایجاد پروژه Actions خود برای این کد لبه، مراحل زیر را دنبال کنید:

1. کنسول Actions را باز کنید.
2. پروژه جدید را کلیک کنید.
3. نام پروژه مانند canvas-codelab را تایپ کنید. این نام برای مرجع داخلی شما است. بعداً می توانید یک نام خارجی برای پروژه خود تعیین کنید.

4. روی ایجاد پروژه کلیک کنید.
5. در چه نوع اکشنی می خواهید بسازید؟ صفحه، کارت بازی را انتخاب کنید.
6. روی Next کلیک کنید.
7. کارت پروژه خالی را انتخاب کنید.
8. روی Start building کلیک کنید.

شناسه پروژه را برای اکشن خود ذخیره کنید

شناسه پروژه یک شناسه منحصر به فرد برای Action شما است. برای چندین مرحله در این کد لبه به شناسه پروژه خود نیاز دارید.

برای بازیابی ID پروژه خود، این مراحل را دنبال کنید:

1. در کنسول Actions، روی سه نقطه عمودی > تنظیمات پروژه کلیک کنید.

2. شناسه پروژه را کپی کنید.

یک حساب صورتحساب را مرتبط کنید

برای استقرار اجرای خود در این آزمایشگاه کد با استفاده از توابع Cloud، باید یک حساب صورت‌حساب را با پروژه خود در Google Cloud مرتبط کنید. اگر قبلاً یک حساب صورت‌حساب دارید، می‌توانید مراحل زیر را نادیده بگیرید.

برای مرتبط کردن یک حساب صورتحساب با پروژه خود، این مراحل را دنبال کنید:

1. به صفحه صورتحساب Google Cloud Platform بروید.
2. روی افزودن حساب صورت‌حساب یا ایجاد حساب کلیک کنید.
3. اطلاعات پرداخت خود را پر کنید
4. روی شروع نسخه آزمایشی رایگان یا ارسال و فعال کردن صورتحساب کلیک کنید.
5. به صفحه صورتحساب Google Cloud بروید.
6. روی تب My Projects کلیک کنید.
7. روی سه نقطه > تغییر صورتحساب کلیک کنید.
8. در منوی کشویی، حساب صورت‌حساب را که پیکربندی کرده‌اید انتخاب کنید.
9. روی تنظیم حساب کلیک کنید.

برای جلوگیری از تحمیل هزینه، مراحل موجود در بخش Clean up your project را دنبال کنید.

استقرار برنامه وب

در این بخش، برنامه وب خود (بازی Snow Pal ) را با استفاده از Firebase CLI اجرا می کنید. پس از استقرار، می توانید URL برنامه وب را بازیابی کنید و ببینید که بازی در مرورگر چگونه به نظر می رسد.

می‌توانید به‌طور اختیاری Action خود را تعریف کنید تا امکان استقرار فایل‌های تکمیل و فایل‌های برنامه وب با فرمان Firebase firebase deploy شود. در این کد لبه، شما برنامه وب و اجرای خود را به طور جداگانه اجرا می کنید.

برای استقرار برنامه وب خود، این مراحل را دنبال کنید:

1. در ترمینال، به دایرکتوری start/ بروید.
2. دستور زیر را اجرا کنید و {PROJECT_ID} با ID پروژه خود جایگزین کنید:

firebase deploy --project {PROJECT_ID} --only hosting

پس از چند دقیقه، " Deploy complete! " را مشاهده می کنید که نشان می دهد برنامه وب Snow Pal را با موفقیت در Firebase مستقر کرده اید.

برای مشاهده بازی Snow Pal در مرورگر مراحل زیر را دنبال کنید:

1. URL میزبان ارائه شده در خروجی ترمینال خود را بازیابی کنید. URL باید به شکل زیر باشد: https://<PROJECT_ID>.web.app

اگر URL در خروجی ترمینال شما ظاهر نمی شود، می توانید URL برنامه وب را با مراحل زیر بازیابی کنید:

1. کنسول Firebase را باز کنید.
2. پروژه Actions خود را از لیست گزینه ها انتخاب کنید.
3. روی Develop > Hosting در نوار پیمایش کلیک کنید.
4. در زیر تب داشبورد ، باید لیستی از دامنه های پروژه خود را مشاهده کنید. URL را کپی کنید. باید به شکل زیر باشد: https://<PROJECT_ID>.web.app

2. URL را در مرورگر جایگذاری کنید. شما باید صفحه شروع بازی Snow Pal را با دکمه شروع بازی ببینید:

URL برنامه وب و شناسه پروژه را به پروژه Actions اضافه کنید

سپس، URL برنامه وب و شناسه پروژه خود را به فایل actions.intent.MAIN.yaml اضافه کنید. افزودن URL برنامه وب به Conversational Action اجازه می‌دهد تا بداند به کدام URL اطلاعات را ارسال کند، در حالی که افزودن شناسه پروژه در settings.yaml به شما امکان می‌دهد فایل‌های دانلود شده را به پروژه صحیح در کنسول Actions فشار دهید.

برای افزودن URL برنامه وب و شناسه پروژه، این مراحل را دنبال کنید:

1. فایل start/sdk/custom/global/actions.intent.MAIN.yaml را در ویرایشگر متن خود باز کنید.
2. در فیلد URL ، رشته نگهدارنده مکان را با URL برنامه وب خود جایگزین کنید.
3. فایل start/sdk/settings/settings.yaml را در ویرایشگر متن خود باز کنید.
4. در قسمت projectId ، رشته محل نگهدارنده را با ID پروژه خود جایگزین کنید.

پروژه را به کنسول Actions فشار دهید

برای به‌روزرسانی کنسول Actions با پروژه محلی خود، باید پروژه Actions خود را به کنسول Actions فشار دهید. برای انجام این کار، این مراحل را دنبال کنید:

1. تغییر به دایرکتوری sdk :

cd sdk/

2. برای کپی کردن پیکربندی فایل سیستم محلی خود در کنسول Actions، دستور زیر را اجرا کنید:

gactions push 

وب هوک را مستقر کنید

وقتی gactions push اجرا کردید، کد شروع وب هوک را به کنسول Actions وارد کردید. برای بقیه این نرم افزار کد، می توانید کد وب هوک خود را در کنسول Actions ویرایش کنید. در این مرحله، می توانید وب هوک را از کنسول Actions مستقر کنید.

برای استقرار وب هوک خود، این مراحل را دنبال کنید:

1. در کنسول Actions، روی Develop در نوار پیمایش کلیک کنید.
2. روی تب Webhook در نوار ناوبری کلیک کنید.
3. روی Deploy Fulfillment کلیک کنید.

احتیاط: پس از کلیک بر روی Deploy Fulfillment، پیام مورد نیاز حساب صورت‌حساب ظاهر می‌شود. برای استقرار وب هوک خود، باید یک حساب صورتحساب را با پروژه خود در Google Cloud مرتبط کنید. برای راه‌اندازی حساب صورت‌حساب، روی Open Cloud console کلیک کنید و مراحل پیوند دادن یک حساب صورت‌حساب را دنبال کنید. برای جلوگیری از تحمیل هزینه، می توانید این پروژه را در انتهای این کد لبه حذف کنید. برای اطلاعات بیشتر به بخش پاکسازی مراجعه کنید.

ممکن است چند دقیقه طول بکشد تا Cloud Functions اجرای شما را ارائه و اجرا کند. شما باید یک پیام Cloud Function در حال توسعه را ببینید. هنگامی که کد با موفقیت اجرا شد، پیام به‌روزرسانی‌شده برای استقرار عملکرد Cloud شما به‌روز است .

در شبیه ساز تست کنید

در این مرحله، Action شما به برنامه وب مرتبط می شود. می‌توانید از شبیه‌ساز کنسول Actions استفاده کنید تا مطمئن شوید که برنامه وب هنگام فراخوانی Action ظاهر می‌شود.

برای آزمایش Action خود، این مراحل را دنبال کنید:

1. در نوار پیمایش کنسول Actions، روی Test کلیک کنید.
2. Talk to Snow Pal sample را در قسمت Input تایپ کنید و Enter فشار دهید.
3. Yes را در قسمت Input تایپ کرده و Enter فشار دهید. یا روی شروع بازی کلیک کنید.

شما هنوز منطق حدس زدن یک حرف یا حدس کلمه را پیکربندی نکرده‌اید، بنابراین اگر کلمه یا حرفی را حدس بزنید، این پاسخ را دریافت می‌کنید، "...نادرست است. به تلاش خود ادامه دهید! به نظر می‌رسد که باید عملکرد بیشتری به آن اضافه کنیم. این کار را به درستی انجام دهید."

5. زیرساخت های Interactive Canvas را درک کنید

برای این پروژه، عملکرد به سه جزء اصلی سازماندهی شده است: کنش مکالمه، برنامه وب و هوک. توجه داشته باشید که این یکی از مدل‌هایی است که چگونه می‌توانید Action خود را راه‌اندازی کنید و به این ترتیب سازماندهی شده است تا عملکرد اصلی Canvas تعاملی را برجسته کند.

بخش‌های زیر به جزئیات بیشتری در مورد نحوه کارکرد Conversational Action، webhook و web app و همچنین سایر عناصر مهم Interactive Canvas می‌پردازد.

کنش مکالمه

مولفه Conversational Action Action شما به شناسایی ورودی کاربر، پردازش آن و ارسال آن به صحنه مناسب، جایی که پاسخی برای کاربر ساخته می‌شود، می‌پردازد. به عنوان مثال، اگر کاربر در بازی Snow Pal بگوید "حدس می‌زنم حرف e" ، کنش مکالمه شما حرف را به عنوان پارامتر هدف استخراج می‌کند و آن را به منطق بازی مناسب منتقل می‌کند، که تعیین می‌کند آیا حدس درست است و وب را به‌روزرسانی می‌کند. بر این اساس برنامه می‌توانید این منطق مکالمه را در Actions Builder، یک IDE مبتنی بر وب در کنسول Actions، مشاهده و اصلاح کنید. تصویر زیر بخشی از کنش مکالمه شما را در Actions Builder نشان می دهد:

شکل 4. تجسم Main invocation در Actions Builder.

این اسکرین شات Main invocation برای Action شما را نشان می‌دهد که کاربران وقتی عبارتی مانند «Hey Google, talk to Snow Pal sample» را می‌گویند با آن مطابقت دارند. هنگامی که کاربر اقدام شما را فراخوانی می کند، Main invocation یک درخواست با یک پاسخ canvas ارسال می کند که حاوی URL برنامه وب شما است.

اصطلاحات کلیدی:

• Canvas : پاسخی که حاوی URL برنامه وب و/یا داده هایی برای ارسال آن است. می‌توانید پاسخ‌های Canvas در webhook یا Actions Builder پیکربندی کنید. برای اطلاعات بیشتر، به درخواست‌های Canvas مراجعه کنید.

اولین پاسخ canvas در Action شما باید شامل URL برنامه وب باشد. این پاسخ به دستیار می‌گوید برنامه وب را در آن آدرس در دستگاه کاربر ارائه کند. پاسخ‌های canvas اضافی در Actions Builder می‌تواند شامل فیلدی باشد، send_state_data_to_canvas_app ، که روی true تنظیم شده است. این فیلد نام intent و هر مقدار پارامتر را به برنامه وب ارسال می‌کند که intent مطابقت دارد، و برنامه وب براساس این داده‌ها از ورودی کاربر به‌روزرسانی می‌شود.

وب هوک

برای این نرم افزار کد، وب هوک شما حاوی منطق بازی است (شما می توانید وب هوک خود را مانند یک سرور بازی در نظر بگیرید). منطق بازی شامل عناصری مانند تعیین درست یا نادرست بودن حدس کاربر، برنده یا باخت کاربر، و ساختن پاسخ بر اساس نتیجه است. می توانید وب هوک خود را در Actions Builder تغییر دهید.

زمانی که Action شما نیاز به اجرای منطق بازی دارد، Actions Builder با وب هوک تماس می گیرد. به عنوان مثال، هدف guess در صحنه Game یک فراخوانی وب هوک به کنترل کننده guess می‌زند، که سپس منطق را برای تعیین اینکه حدس کاربر درست است یا خیر، اجرا می‌کند. وب هوک می‌تواند شامل پاسخ‌های Canvas در کنترل‌کننده‌هایی باشد که به فایل‌های برنامه وب نقشه می‌دهند و وب را به‌طور مناسب به‌روزرسانی می‌کنند.

برنامه وب

شکل 5. یک نمایش بصری از تعامل بین کنش مکالمه، وب هوک و برنامه وب در یک کنش بوم تعاملی.

فایل های برنامه وب حاوی کد تصاویر و انیمیشن های برنامه وب شما و همچنین منطق به روز رسانی برنامه وب بر اساس ورودی کاربر است. شما فایل های برنامه وب خود را در ویرایشگر متن خود تغییر می دهید و این تغییرات را با استفاده از Firebase CLI اعمال می کنید.

برقراری ارتباط بین اکشن مکالمه و برنامه وب

باید ارتباط بین Conversational Action و برنامه وب خود را فعال کنید تا برنامه وب شما بتواند بر اساس ورودی کاربر به روز شود. به عنوان مثال، اگر کاربر بگوید "حدس می زنم حرف f" ،

کنش مکالمه باید به برنامه وب با حرف f ارائه شود تا برنامه وب بتواند مطابق با آن به روز شود. برای ارسال ورودی کاربر از Conversational Action به برنامه وب، باید در Interactive Canvas API بارگیری کنید.

اصطلاح کلیدی:

• Interactive Canvas API: یک API جاوا اسکریپت که در برنامه وب قرار می دهید تا ارتباط بین برنامه وب و کنش مکالمه شما را فعال کند.

اسکریپت این API در /public/index.html موجود است که فایل HTML اصلی بازی Snow Pal است. این فایل نحوه ظاهر و بارگیری رابط کاربری شما را در چندین اسکریپت مشخص می کند:

index.html

<!-- Load Assistant Interactive Canvas API -->
 <script type="text/javascript" src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>

برای به روز رسانی برنامه وب بر اساس ورودی کاربر، باید تماس های برگشتی را نیز در فایل برنامه وب خود ثبت و پیکربندی کنید. پاسخ به تماس به برنامه وب شما اجازه می‌دهد به اطلاعات یا درخواست‌های کنش مکالمه پاسخ دهد.

در /public/js/action.js یک کلاس از پیش پیکربندی شده به نام Action برای اعلام و ثبت تماس ها وجود دارد. کلاس Action یک پوشش در اطراف Interactive Canvas API است. هنگامی که برنامه وب با تابع create() در scene.js ایجاد می شود، یک نمونه Action جدید ایجاد می شود و setCallbacks() فراخوانی می شود، همانطور که در قطعه زیر نشان داده شده است:

صحنه.js

// Set Assistant at game level.
this.assistant = new Action(this);
// Call setCallbacks to register Assistant Action callbacks.
this.assistant.setCallbacks();

تابع setCallbacks() در کلاس Action از /public/js/action.js تعریف شده است. این تابع پس از ایجاد بازی، تماس‌های برگشتی را اعلام می‌کند و آنها را با Interactive Canvas API ثبت می‌کند:

  setCallbacks() {
    // Declare the Interactive Canvas Action callbacks.
    const callbacks = {
      onUpdate: (data) => {
     ...
    // Called by the Interactive Canvas web app once web app has loaded to
    // register callbacks.
    this.canvas.ready(callbacks);
  }

تابع setCallbacks() فراخوانی onUpdate() را اعلام می کند که هر بار که یک پاسخ Canvas ارسال می کنید، فراخوانی می شود.

اصطلاح کلیدی:

• onUpdate() : یک تماس برگشتی که هر بار که یک پاسخ Canvas ارسال می کنید اجرا می شود. onUpdate() می تواند به منطق سفارشی که برنامه وب را به روز می کند، نقشه برداری کند.

بخش بعدی نحوه پیکربندی کد خاص این پروژه را برای انتقال داده ها از Conversational Action به برنامه وب توضیح می دهد.

به روز رسانی برنامه وب بر اساس ورودی کاربر

در این کد لبه، شما از نقشه فرمان برای به روز رسانی برنامه وب بر اساس ورودی کاربر استفاده می کنید. به عنوان مثال، هنگامی که هدف start_game در صحنه Welcome مطابقت داده می‌شود، پاسخ canvas موجود در اعلان به برنامه وب ارسال می‌شود. onUpdate() فراداده را از پاسخ canvas تجزیه می کند و دستور START_GAME را فراخوانی می کند که به نوبه خود تابع start() را در scene.js فراخوانی می کند و برنامه وب را برای شروع یک جلسه بازی جدید به روز می کند.

تابع start() در scene.js تابعی به نام updateCanvasState() را نیز فراخوانی می کند که از روشی به نام setCanvasState() برای اضافه کردن داده های حالتی که وب هوک شما می تواند به آن دسترسی داشته باشد استفاده می کند.

اصطلاح کلیدی:

• setCanvasState() : روشی که به شما امکان می دهد داده های وضعیت را از برنامه وب Interactive Canvas خود به وب هوک خود ارسال کنید. برنامه وب حالت به روز شده خود را به عنوان یک شی JSON ارسال می کند.

متد updateCanvasState() در پایان هر دستور فراخوانی می شود (شما این دستورات را در سرتاسر Codelab اضافه می کنید) و وضعیت برنامه وب را به روز می کند. هر بار که updateCanvasState() فراخوانی می شود، مقادیر displayedWord و incorrectGuesses بر اساس وضعیت فعلی به روز می شوند:

صحنه.js

...
  updateCanvasState() {
    window.interactiveCanvas.setCanvasState({
      correctWord: this.word.text,
      displayedWord: this.word.displayText.text,
      incorrectGuesses: this.incorrectGuesses,
    });

سپس حالت به روز شده برای نوبت مکالمه بعدی در دسترس است. همانطور که در قطعه کد زیر نشان داده شده است، می توانید از طریق conv.context.canvas.state به این وضعیت در webhook دسترسی پیدا کنید:

index.js

...
  let displayedWord = conv.context.canvas.state.displayedWord;
...

6. قابلیت حدس زدن را اضافه کنید

در این بخش، قابلیت guess را به Action خود اضافه می‌کنید که به کاربر امکان می‌دهد حروف درون کلمه یا خود کلمه را حدس بزند.

کنش مکالمه

در بخش تست در بخش شبیه ساز ، پاسخی دریافت کردید که شامل این بود: "به نظر می رسد ما باید عملکرد بیشتری اضافه کنیم تا این کار به درستی انجام شود." اکنون، می‌توانید آن فرمان را در کنسول Actions حذف کنید تا فقط وب‌هوک را فراخوانی کنید (در صحنه Game ، هدف guess از قبل برای برقراری تماس وب‌هوک زمانی که مطابقت دارد، پیکربندی شده است).

برای حذف اعلان ایستا زمانی که هدف guess مطابقت دارد، این مراحل را دنبال کنید:

1. در کنسول Actions، روی Scenes در نوار پیمایش کلیک کنید.
2. برای رفتن به صحنه Game روی Game کلیک کنید.
3. وقتی حدس منطبق است در زیر مدیریت قصد کاربر کلیک کنید. برای حذف درخواست ، دستورهای ارسال را پاک کنید.
4. روی ذخیره کلیک کنید.

وب هوک

در این بخش، وب هوک خود را با منطقی به روز می کنید که حدس صحیح یا نادرست کاربر را به منطق در فایل برنامه وب ترسیم می کند، که سپس برنامه وب را بر این اساس به روز می کند. کنترل کننده هدف guess از قبل برای شما در webhook پیکربندی شده است، بنابراین فقط باید پاسخ های Canvas به این هدف اضافه کنید تا منطقی را که برنامه وب را به روز می کند، راه اندازی کنید.

برای به روز رسانی وب هوک خود، این مراحل را دنبال کنید:

1. در کنسول Actions، روی Webhook در نوار ناوبری کلیک کنید.
2. کد زیر را به index.js تحت کنترلر guess اضافه کنید:

توجه: در این لبه کد، کدهایی که اضافه می کنید به بخش های حروف الفبا تقسیم می شوند. فایل‌هایی که تغییر می‌دهید شامل نظراتی هستند که مشخص می‌کنند کجا باید هر قطعه را اضافه کنید (به عنوان مثال، // Add section F } را here اضافه کنید). قطعه مربوطه را بعد از خط نظر اضافه کنید.

index.js (بخش A):

// Add Section A `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'CORRECT_ANSWER',
    displayedWord: displayedWord
  },
}));

index.js (بخش B):

// Add Section B `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'INCORRECT_ANSWER',
  },
}));

3. روی Save Fulfillment کلیک کنید.
4. روی Deploy Fulfillment کلیک کنید. وقتی استقرار کامل شد، پیامی به این مضمون می‌خواند که استقرار عملکرد ابری شما به‌روز است .

برنامه وب

اکنون می توانید برنامه وب خود را طوری پیکربندی کنید که دستورات CORRECT_ANSWER و INCORRECT_ANSWER را انجام دهد.

1. public/js/action.js را در ویرایشگر متن خود باز کنید.
2. برنامه وب را برای کنترل دستورات CORRECT_ANSWER و INCORRECT_ANSWER به روز کنید:

action.js (بخش C):

// Add Section C `CORRECT_ANSWER: (params) => {` content here.
      CORRECT_ANSWER: (params) => {
        this.gameScene.correctAnswer(params);
      },
      INCORRECT_ANSWER: (params) => {
        this.gameScene.incorrectAnswer();
      },

3. دستور زیر را برای به روز رسانی برنامه وب اجرا کنید:

firebase deploy --project {PROJECT_ID} --only hosting

اکشن خود را در شبیه ساز تست کنید

در این مرحله، Action شما می‌تواند درست یا نادرست بودن حدس را تشخیص دهد و برنامه وب را متناسب با آن به‌روزرسانی کند.

برای آزمایش Action خود، این مراحل را دنبال کنید:

1. در نوار پیمایش، روی تست کلیک کنید.
2. Talk to Snow Pal sample را در قسمت Input تایپ کنید و Enter فشار دهید.
3. Yes را در قسمت Input تایپ کرده و Enter فشار دهید. یا روی دکمه Yes کلیک کنید.
4. حرفی را که می خواهید حدس بزنید در قسمت Input تایپ کنید و Enter فشار دهید.

کد را درک کنید

در بخش قبل، کدی را اضافه کردید که به کاربران اجازه می‌دهد حروف بازی شما را حدس بزنند و آن حدس‌ها را در کلمه یا Snow Pal منعکس کنند. در سطح بالایی، هنگامی که هدف guess مطابقت دارد، در Actions Builder یک تماس با هوک برقرار می‌کنید، که داده‌ها را به برنامه وب شما ارسال می‌کند تا آن را مطابق با آن به‌روزرسانی کند. به عنوان مثال، اگر کاربر حرفی را در بازی Snow Pal حدس بزند که در کلمه وجود دارد، برنامه وب به روز می شود تا حرف را در موقعیت صحیح کلمه نشان دهد.

برای کنش‌هایی که از بوم تعاملی استفاده می‌کنند، جریان کلی نحوه انتقال داده‌ها از webhook به برنامه وب به شرح زیر است:

1. ورودی کاربر با هدفی که شامل پاسخ Canvas است مطابقت دارد.
2. کنش مکالمه یا webhook پاسخ Canvas را می فرستد، که پاسخ تماس onUpdate() فعال می کند.
3. onUpdate() به منطق سفارشی نگاشت می شود که برنامه وب را بر این اساس به روز می کند.

اصطلاح کلیدی:

• onUpdate() : یک فراخوانی که هر بار که انجام شما یک پاسخ Canvas ارسال می کند، اجرا می شود . onUpdate() می تواند به منطق سفارشی که برنامه وب را به روز می کند، نقشه برداری کند.

برای این پروژه خاص، کد به روش زیر عمل می کند:

1. هنگامی که کاربر با هدف guess مطابقت دارد، Actions Builder حرف را از ورودی کاربر به عنوان یک پارامتر استخراج می کند.
2. Actions Builder کنترل کننده guess را در وب هوک شما فراخوانی می کند، که حاوی منطق برای تعیین اینکه آیا حرفی که کاربر حدس زده است در کلمه ظاهر می شود یا خیر.
3. کنترل کننده guess شامل دو پاسخ Canvas است - یکی که وقتی حرف درست باشد و دیگری وقتی حرف نادرست باشد اجرا می شود. هر پاسخ Canvas داده های مناسب (دستور CORRECT_ANSWER یا INCORRECT_ANSWER ) را به برنامه وب ارسال می کند.
4. داده های موجود در فیلد data پاسخ Canvas به متد onUpdate() در action.js ارسال می شود. onUpdate() دستور مناسب را در دستور map در scene.js فراخوانی می کند.
5. دستور نقشه به correctAnswer() و incorrectAnswer() در scene.js نگاشت. این توابع برنامه وب را به‌طور مناسب به‌روزرسانی می‌کنند تا حدس کاربر را منعکس کند و setCanvasState() را فراخوانی کند تا داده‌های وضعیت را از برنامه وب شما به webhook شما ارسال کند.

7. قابلیت برد/باخت را اضافه کنید

در این بخش، عملکرد برد و باخت را به Action خود اضافه می‌کنید، که شامل منطقی است که تعیین می‌کند کاربر برنده یا باخته است و منطق به‌روزرسانی تصویر برنامه وب بر اساس نتیجه کاربر.

کنش مکالمه

عملکردی که برنده یا باخت کاربر در بازی را کنترل می کند، با هدف guess پیکربندی می شود، بنابراین نیازی به انجام هیچ گونه پیکربندی اضافی در Actions Builder ندارید.

وب هوک

در این بخش، وب هوک خود را با منطقی به روز می کنید که زمانی که کاربر بازی را برد یا باخت انجام می دهد، و نقشه ها را به منطق برنامه وب که بازی را با صفحه برد یا باخت مناسب به روز می کند، به روز می کنید.

برای به روز رسانی وب هوک خود، این مراحل را دنبال کنید:

1. در کنسول Actions، روی Webhook در نوار ناوبری کلیک کنید.
2. کد زیر را به index.js تحت کنترلر guess اضافه کنید:

index.js (بخش D):

// Add Section D `if (userHasWon)` content here.
    if (userHasWon) {
      conv.add(`<speak>Let's see if your guess is there...<break
        time='2500ms'/> ${guess} is right. That spells ${correctWord}!  
        ${randomArrayItem(WIN_RESPONSES)}</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'WIN_GAME',
          displayedWord: displayedWord
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (بخش E):

توجه: در این قسمت یک براکت بسته برای بستن بلوک کد اضافه می کنید.

// Add Section E `}` here.
}

index.js (بخش F):

// Add Section F `Check if the user has exceeded the maximum` content here.
// Check if the user has exceeded the maximum amount of max guesses allowed.
    const userHasLost = conv.context.canvas.state.incorrectGuesses + 1 >= MAX_INCORRECT_GUESSES;
    if (userHasLost) {
      conv.add(`<speak>Let's see if your guess is there...<break
      time='2500ms'/> ${guess} is wrong. Sorry you lost. The word is ${correctWord}!</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'LOSE_GAME',
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (بخش G):

توجه: در این قسمت یک براکت بسته برای بستن بلوک کد اضافه می کنید.

// Add Section G `}` here.
}

3. روی Save Fulfillment کلیک کنید.
4. روی Deploy Fulfillment کلیک کنید. وقتی استقرار کامل شد، پیامی به این مضمون می‌خواند که استقرار عملکرد ابری شما به‌روز است .

در اینجا، شما دو پاسخ Canvas را با دستورات WIN_GAME و LOSE_GAME اضافه کرده‌اید تا زمانی که کاربران در بازی برنده یا می‌بازند، کنترل شود. در بخش بعدی، عملکردی را اضافه می کنید که برنامه وب را بر اساس برنده شدن یا باختن کاربر به روز می کند.

برنامه وب

اکنون می توانید برنامه وب خود را برای به روز رسانی بر اساس برنده شدن یا باختن کاربر پیکربندی کنید. برای به روز رسانی برنامه وب خود، این مراحل را دنبال کنید:

1. public/js/action.js را در ویرایشگر متن خود باز کنید.
2. برنامه وب خود را برای کنترل دستورات WIN_GAME و LOSE_GAME به روز کنید:

action.js (بخش H):

// Add Section H `WIN_GAME: (params) => {` content here.
      WIN_GAME: (params) => {
        this.gameScene.winGame(params);
      },
      LOSE_GAME: (params) => {
        this.gameScene.loseGame();
      },

3. دستور زیر را برای به روز رسانی برنامه وب اجرا کنید:

firebase deploy --project {PROJECT_ID} --only hosting

اکشن خود را در شبیه ساز تست کنید

در این مرحله، Action شما می‌تواند زمانی را که کاربر برنده یا می‌بازد، کنترل کند و صفحه مناسب را برای هر نتیجه ارائه دهد.

برای آزمایش Action خود، این مراحل را دنبال کنید:

1. در نوار پیمایش کنسول Actions، روی Test کلیک کنید.
2. Talk to Snow Pal sample را در قسمت Input تایپ کنید و Enter فشار دهید.
3. Yes را در قسمت Input تایپ کرده و Enter فشار دهید. یا روی دکمه شروع بازی کلیک کنید.
4. حروف و کلمات را حدس بزنید تا زمانی که برنده شوید یا ببازید.

اگر بخواهید دوباره بازی کنید، پیامی دریافت می کنید که نشان می دهد هنوز عملکرد لازم برای بازی مجدد اضافه نشده است. شما این قابلیت را در بخش بعدی اضافه می کنید.

کد را درک کنید

عملکرد برد و باخت به همان شیوه عملکرد حدس زدن کار می کند - کاربر با هدف guess مطابقت دارد و وب هوک شما حدس کاربر را ارزیابی می کند. اگر حدس آنها درست باشد، کد بررسی می کند که آیا کاربر برنده شده است یا خیر. اگر داشته باشند، دستور WIN_GAME به برنامه وب ارسال می شود. اگر حدس آنها اشتباه باشد، کد بررسی می کند که آیا آنها گم شده اند یا خیر. در صورت وجود، دستور LOSE_GAME به برنامه وب ارسال می شود. این دستورات توابع winGame() و loseGame() را در scene.js فعال می کنند، که برنامه وب را برای نمایش صفحه برنده یا بازنده به روز می کند و وضعیت بازی را به روز می کند.

8. قابلیت پخش مجدد را اضافه کنید

در این بخش، عملکردی را اضافه می‌کنید که به کاربر اجازه می‌دهد برای شروع یک بازی جدید، بگوید «بازی دوباره» یا روی دکمه «بازی دوباره» در برنامه وب کلیک کند. شما قصد play_again را در Actions Builder تغییر می‌دهید تا یک پاسخ canvas ارسال شود که برنامه وب را به‌طور مناسب به‌روزرسانی می‌کند، و منطقی را اضافه می‌کنید که وقتی کاربر روی دکمه Play Again کلیک می‌کند، قصد play_again را فعال می‌کند.

کنش مکالمه

هنگامی که Action خود را در بخش قبلی آزمایش کردید، اگر سعی کنید بازی را دوباره انجام دهید، پیام زیر را دریافت کردید: "این عالی خواهد بود، اما ما این قابلیت را در بخش بعدی ایجاد خواهیم کرد. در حال حاضر، فقط Action را بازنشانی کنید." اکنون می‌توانید این درخواست را حذف کنید و آن را با درخواستی جایگزین کنید که وقتی کاربر بازی دیگری را درخواست می‌کند به او پاسخ می‌دهد ( "بسیار خوب، بازی دیگری است!" ) و شامل یک پاسخ canvas برای فعال کردن برنامه وب برای شروع یک بازی جدید است.

برای به روز رسانی درخواست زمانی که کاربر می خواهد دوباره بازی کند، این مراحل را دنبال کنید:

1. در کنسول Actions، روی منوی کشویی Scene کلیک کنید.
2. روی صحنه بازی کلیک کنید.
3. وقتی play_again مطابقت دارد در زیر مدیریت قصد کاربر کلیک کنید.
4. دستور زیر را جایگزین کنید:

candidates:
  - first_simple:
      variants:
        - speech: 'Okay, here''s another game!' 
    canvas:
      sendStateDataToCanvasApp: true

5. روی ذخیره کلیک کنید.

وب هوک

در این کد لبه، webhook منطق بازی را مدیریت می کند. از آنجایی که عملکرد play-ain به هیچ نوع اعتبار منطقی نیاز ندارد، نیازی به فراخوانی webhook ندارید. در عوض، می‌توانید یک پاسخ canvas مستقیماً از Actions Builder ارسال کنید تا داده‌های لازم را به برنامه وب ارسال کنید (این را در بخش قبلی پیکربندی کرده‌اید).

برنامه وب

اکنون می‌توانید فایل‌های برنامه وب خود را تغییر دهید تا زمانی که کاربر درخواست می‌کند دوباره پخش شود، به‌طور مناسب به‌روزرسانی شوند. برای افزودن این قابلیت، مراحل زیر را دنبال کنید:

1. public/js/action.js را در ویرایشگر متن خود باز کنید.
2. برنامه وب را برای کنترل فرمان PLAY_AGAIN به روز کنید:

action.js (بخش I):

// Add Section I `PLAY_AGAIN: (params) => {` content here.
      PLAY_AGAIN: (params) => {
        this.gameScene.start();
      },

3. public/js/scene.js را در ویرایشگر متن خود باز کنید.
4. برنامه وب را به روز کنید تا وقتی کاربر روی دکمه " بازی دوباره " کلیک کرد ، یک جلسه بازی جدید را شروع کنید:

Scene.js (بخش J):

// Add Section J `sendTextQuery` content here.
     window.interactiveCanvas.sendTextQuery('Play again');

5. دستور زیر را برای به روزرسانی برنامه وب اجرا کنید:

firebase deploy --project {PROJECT_ID} --only hosting

عمل خود را در شبیه ساز تست کنید

وقتی کاربر می گوید "دوباره بازی کنید" یا دکمه بازی را دوباره کلیک می کند ، اکنون می توانید یک جلسه بازی جدید را شروع کنید.

برای آزمایش عملکرد خود ، این مراحل را دنبال کنید:

1. در نوار ناوبری ، روی تست کلیک کنید.
2. Talk to Snow Pal sample در قسمت ورودی را تایپ کنید و Enter فشار دهید.
3. Yes در قسمت ورودی تایپ کرده و Enter فشار دهید. از طرف دیگر ، روی دکمه شروع بازی کلیک کنید.
4. حروف و کلمات را حدس بزنید تا اینکه برنده شوید یا از دست ندهید.
5. Play again در قسمت ورودی تایپ کرده و Enter فشار دهید. از طرف دیگر ، روی دکمه بازی دوباره کلیک کنید.

کد را درک کنید

هنگامی که عملکرد خود را آزمایش کردید ، می توانید یک بازی جدید را از طریق ورودی صوتی ( "بازی دوباره" ) شروع کنید یا ورودی را لمس کنید (روی دکمه Play دوباره کلیک کنید).

برای گزینه ورودی صدا ، هنگامی که کاربر می گوید "دوباره بازی کنید" یا برخی از تغییرات آن ، قصد play_again با هم مطابقت دارد و سریع ( "خوب ، اینجا بازی دیگری است!" ) را به صف سریع اضافه می کند. پاسخ canvas موجود در The Prompt نام هدف و سایر ابرداده ها را به برنامه وب ارسال می کند. نام هدف به پاسخ به تماس onUpdate() منتقل می شود ، که دستور مربوطه ، PLAY_AGAIN به نقشه فرمان در action.js نقشه می کند. دستور PLAY_AGAIN عملکرد start() را در scene.js ایجاد می کند و برنامه وب را با یک جلسه بازی جدید به روز می کند.

برای گزینه Touch Input ، شما از sendTextQuery() ، یک API بوم تعاملی استفاده می کنید که به شما امکان می دهد از طریق ورودی لمسی قصد ایجاد کنید تا دکمه کار کند.

اصطلاح کلیدی:

• sendTextQuery() : روشی که یک پرس و جو متنی را به اقدام مکالمه ارسال می کند تا برنامه ای از یک هدف استفاده کند.

در این CodeLab ، وقتی کاربر دوباره روی دکمه Play کلیک play_again کند ، از sendTextQuery() استفاده می کنید. استدلال Play again با یک عبارت تمرینی در قصد play_again مطابقت دارد و این هدف را به همان روشی که کاربر می گوید "دوباره بازی می کند" را برانگیخته است. قصد play_again سپس منطق را به روز می کند که برنامه وب را به روز می کند و یک جلسه بازی جدید را آغاز می کند.

9. به روز رسانی Play_game داخلی

در این بخش ، هدف داخلی PLAY_GAME را به روز می کنید.

اصطلاح کلیدی:

• هدف داخلی: یک شناسه منحصر به فرد که می توانید مشخص کنید که به دستیار بگویید که عمل شما می تواند یک دسته خاص از درخواست های کاربر را انجام دهد.

PLAY_GAME Intent Intent به کاربران این امکان را می دهد تا هنگام درخواست کلی ، مانند "من می خواهم یک بازی انجام دهم" از عملکرد شما استفاده کنند.

کد منبع شامل PLAY_GAME Intent Intent است که در /sdk/custom/global/actions.intent.PLAY_GAME.yaml قرار دارد. این در کنسول در بخش دعوت به عنوان PLAY_GAME منعکس شده است ، همانطور که در تصویر زیر نشان داده شده است:

برای اینکه کاربران بتوانند از طریق این هدف داخلی ، اقدامات خود را فراخوانی کنند ، باید یک پاسخ canvas را با URL برنامه وب به PLAY_GAME داخلی اضافه کنید. برای انجام این کار، این مراحل را دنبال کنید:

1. در کنسول Actions ، روی play_game در نوار ناوبری کلیک کنید.
2. همانطور که در قطعه زیر نشان داده شده است ، سریعاً URL برنامه وب خود را وارد کنید:

candidates:
  - canvas:
      url: 'https://<PROJECT_ID>.web.app'

3. روی ذخیره کلیک کنید.

عمل خود را در شبیه ساز تست کنید

عمل شما اکنون PLAY_GAME داخلی پشتیبانی می کند.

برای آزمایش عملکرد خود ، این مراحل را دنبال کنید:

1. در نوار ناوبری ، روی تست کلیک کنید.
2. روی تست داخلی با هدف قرار دادن کلیک کنید.
3. روی Invoke Action کلیک کنید.

عمل شما باید در شبیه ساز فراخوانی شود.

10. پیوست: عیب یابی عمل بوم تعاملی

در این بخش ، یاد می گیرید که چگونه به درستی کار نکند ، عملکرد بوم تعاملی خود را اشکال زدایی کنید. پروژه Snow Pal با یک روکش اشکال زدایی که می توانید فعال کنید از قبل بسته بندی شده است. Overlay تمام خروجی console.log() و console.error() را به سمت راست پایین صفحه نمایش نشان می دهد ، همانطور که در تصویر زیر نشان داده شده است:

برای فعال کردن این پوشش ، پرونده /public/css/main.css را باز کنید و display: none !important; ، همانطور که در قطعه زیر نشان داده شده است:

main.css

.debug {
 display: flex;
 flex-direction: column;

/* Comment below to view debug overlay */
/* display: none !important; */

 width: 500px;
 height: 150px;
 right: 0;
 bottom: 0;
 position: absolute;
}

پروژه خود را پاک کنید [توصیه شده]

برای جلوگیری از تحمل هزینه های احتمالی ، توصیه می شود پروژه هایی را که قصد استفاده از آنها را ندارید حذف کنید. برای حذف پروژه هایی که در این CodeLab ایجاد کرده اید ، این مراحل را دنبال کنید:

1. برای حذف پروژه و منابع Google Cloud ، مراحل ذکر شده در بخش پروژه های خاموش (حذف) را انجام دهید.

احتیاط : اطمینان حاصل کنید که پروژه صحیح حذف را در صفحه تنظیمات پلت فرم Google Cloud انتخاب کرده اید.

2. اختیاری: برای حذف بلافاصله پروژه خود از کنسول اقدامات ، مراحل ذکر شده در بخش حذف یک پروژه را تکمیل کنید. اگر این مرحله را کامل نکنید ، پروژه شما پس از حدود 30 روز به طور خودکار حذف می شود.

11. تبریک!

شما CodeLab بوم تعاملی مقدماتی را به اتمام رسانده اید و اکنون مهارت های لازم برای ساخت عملکرد بوم تعاملی خود را دارید.

آنچه آموخته اید

• نحوه ساخت ، استقرار و آزمایش یک عمل بوم تعاملی
• نحوه استفاده از پاسخهای Canvas برای به روزرسانی برنامه وب
• نحوه استفاده از روشهای مختلف برای تقویت عملکرد خود ، مانند sendTextQuery() و setCanvasState()
• چگونه عمل خود را اشکال زدایی کنید

بیشتر بدانید

برای کسب اطلاعات بیشتر در مورد بوم تعاملی ، منابع زیر را بررسی کنید:

• مستندات بوم تعاملی : اقدامات رسمی در اسناد گوگل برای بوم تعاملی.
• نمونه بوم تعاملی : کد برای یک بازی بوم تعاملی ساده که به شما امکان می دهد مثلث را بچرخانید و رنگ های آن را تغییر دهید.
• پورتال بازی ها : دستورالعمل ساخت بازی ها در Google Assistant.

بررسی بازخورد

قبل از رفتن ، لطفاً یک نظرسنجی کوتاه در مورد تجربه خود را پر کنید.