۱. نمای کلی
پلاتفرم توسعه‌دهنده «دستیار Google» به شما امکان می‌دهد نرم‌افزاری برای گسترش عملکرد «دستیار Google»، دستیار شخصی مجازی، در بیش‌از ۱ میلیارد دستگاه، ازجمله بلندگوهای هوشمند، تلفن‌ها، خودروها، تلویزیون‌ها، هدفون‌ها، و غیره ایجاد کنید. کاربران برای انجام کارها، مثلاً خرید خواربار یا رزرو سفر، با «دستیار» مکالمه می‌کنند. به‌عنوان توسعه‌دهنده، می‌توانید از پلتفرم توسعه‌دهنده «دستیار» استفاده کنید تا به‌راحتی تجربه‌های مکالمه‌ای لذت‌بخش و مؤثری بین کاربران و سرویس اجرای شخص ثالث خودتان ایجاد و مدیریت کنید.
این codelab مفاهیم سطح مبتدی را برای توسعه با Actions SDK برای «دستیار Google» پوشش می‌دهد؛ برای تکمیل آن به هیچ تجربه قبلی با این پلاتفرم نیاز ندارید. در این codelab، یک «کنش» ساده برای «دستیار Google» می‌سازید که وقتی کاربران ماجراجویی خود را در سرزمین افسانه‌ای گریفینبرگ آغاز می‌کنند، طالع آن‌ها را می‌گوید. در codelab سطح ۲ Actions SDK، این Action را بیشتر می‌سازید تا طالع کاربر را براساس ورودی او سفارشی‌سازی کنید.
آنچه خواهید ساخت
در این codelab، یک «کنش» ساده با عملکردهای زیر می‌سازید:
- با پیام خوشامدگویی به کاربران پاسخ می‌دهد
- از کاربران سؤال می‌پرسد و به انتخاب کاربر پاسخ مناسب می‌دهد
- تراشه‌های پیشنهادی ارائه می‌دهد که کاربران می‌توانند برای ارائه ورودی روی آن‌ها کلیک کنند
- پیام خوشامدگویی به کاربر را براساس اینکه کاربر بازگشتی است یا نه تغییر می‌دهد
وقتی این آموزش را تمام کنید، «کنش» تکمیل‌شده شما جریان مکالمه زیر را خواهد داشت (نوشتار کنار میکروفون نشان‌دهنده ورودی کاربر است، درحالی‌که نوشتار کنار بلندگو نشان‌دهنده پاسخ «کنش» است):
آنچه خواهید آموخت
- نحوه ایجاد پروژه در کنسول Actions
- نحوه استفاده از ابزار gactions برای ارسال و دریافت پروژه «کنش» بین کنسول Actions و سیستم فایل محلی شما
- نحوه ارسال پیام‌واره به کاربر پس‌از فراخوانی «کنش» شما
- نحوه پردازش ورودی کاربر و برگرداندن پاسخ
- نحوه آزمایش «کنش» در شبیه‌ساز «کنش‌ها»
- نحوه پیاده‌سازی تحقق بااستفاده از ویرایشگر Cloud Functions
آنچه نیاز خواهید داشت
ابزارهای زیر باید در محیط شما باشند:
- یک IDE یا ویرایشگر نوشتار به انتخاب شما
- پایانه‌ای برای اجرای فرمان‌های پوسته برای Node.js و npm
- مرورگر وب، مثل Google Chrome
۲. تنظیم کردن
بخش‌های زیر نحوه راه‌اندازی محیط توسعه و ایجاد پروژه «کنش‌ها» را شرح می‌دهد.
تنظیمات اجازه Google را بررسی کنید
برای آزمایش «کنش» ساخته‌شده در این codelab، باید اجازه‌های لازم را فعال کنید تا شبیه‌ساز بتواند به «کنش» شما دسترسی پیدا کند.
برای فعال کردن اجازه‌ها، این مراحل را دنبال کنید:
- به کنترل‌های فعالیت بروید.
- اگر قبلاً این کار را نکرده‌اید، با «حساب Google» خود به سیستم وارد شوید.
- اجازه‌های زیر را فعال کنید:
- فعالیت‌ها در وب و برنامه
- در بخش فعالیت‌ها در وب و برنامه، چارگوش افزودن سابقه و فعالیت Chrome از سایت‌ها، برنامه‌ها، و دستگاه‌هایی که از سرویس‌های Google استفاده می‌کنند را انتخاب کنید**.**
ایجاد پروژه Actions
پروژه «کنش‌های» شما محفظه‌ای برای «کنش» شما است.
برای ایجاد پروژه Actions برای این codelab، این مراحل را دنبال کنید:
- کنسول Actions را باز کنید.
- روی پروژه جدید کلیک کنید.
- نام پروژه را وارد کنید، مثلاً
actions-codelab. (این نام برای مرجع داخلی شما است. بعداً می‌توانید نامی خارجی برای پروژه‌تان تنظیم کنید.)
- روی ایجاد پروژه کلیک کنید.
- در صفحه What kind of Action do you want to build? (چه نوع کنشی می‌خواهید بسازید؟)، کارت Custom (سفارشی) را انتخاب کنید.
- روی بعدی کلیک کنید.
- در صفحه چگونه می‌خواهید آن را بسازید؟، کارت پروژه خالی را انتخاب کنید.
- روی شروع ساخت کلیک کنید.
«شناسه پروژه» را برای «کنش» خود ذخیره کنید
«شناسه پروژه» شناسه‌ای یکتا برای «کنش» شما است. برای چندین مرحله در این codelab به شناسه پروژه خود نیاز دارید.
برای بازیابی «شناسه پروژه»، این مراحل را دنبال کنید:
- در کنسول Actions، روی سه نقطه عمودی (نماد را اینجا درج کنید) کلیک کنید.
- روی تنظیمات پروژه کلیک کنید.
- شناسه پروژه را کپی کنید**.**
مرتبط کردن حساب صورت‌حساب
اگر ازقبل حساب صورت‌حساب ندارید، باید حساب صورت‌حساب ایجاد کنید و آن را با پروژه‌تان در Google Cloud مرتبط کنید تا بعداً با Cloud Functions اجرای خود را مستقر کنید.
برای مرتبط کردن حساب صورت‌حساب با پروژه‌تان، این مراحل را دنبال کنید:
- به صفحه صورت‌حساب Google Cloud Platform بروید.
- روی افزودن حساب صورت‌حساب یا ایجاد حساب کلیک کنید.
- اطلاعات پرداختتان را وارد کنید؛
- روی شروع دوره آزمایشی رایگان یا ارسال و فعال کردن صورت‌حساب کلیک کنید.
- به صفحه صورت‌حساب Google Cloud Platform بروید.
- روی برگه پروژه‌های من کلیک کنید.
- روی سه نقطه زیر کنش‌ها در کنار پروژه «کنش‌ها» برای codelab کلیک کنید.
- روی تغییر صورت‌حساب کلیک کنید.
- در منوِ کرکره‌ای، حساب صورت‌حسابی را که پیکربندی کرده‌اید انتخاب کنید.
- روی تنظیم حساب کلیک کنید.
برای جلوگیری از کسر هزینه، مراحل بخش «پاک‌سازی پروژه» را در پایان این codelab دنبال کنید.
رابط خط فرمان gactions را نصب کنید
در این codelab، از ابزار میانای خط فرمان (CLI) gactions برای همگام‌سازی پروژه «کنش‌ها» بین کنسول «کنش‌ها» و سیستم فایل محلی‌تان استفاده می‌کنید.
برای نصب gactions CLI، دستورالعمل‌های نصب ابزار خط فرمان gactions را دنبال کنید.
بارگیری پروژه Actions
با بارگیری پروژه Actions از کنسول Actions، توسعه Action خود را شروع کنید.
برای بارگیری پروژه Actions، این مراحل را دنبال کنید:
- برای ایجاد دایرکتوری جدید و رفتن به آن دایرکتوری، فرمان‌های زیر را اجرا کنید:
mkdir myproject cd myproject
- برای کپی کردن پیکربندی پروژه Actions در سیستم فایل محلی، فرمان زیر را اجرا کنید:
gactions pull --project-id <projectID>
آشنا شدن با ساختار فایل
پروژه Actions که از کنسول Actions بارگیری می‌کنید در ساختار فایل YAML نشان داده می‌شود. تصویر زیر نمایش سطح بالایی از ساختار فایل را نشان می‌دهد:
ساختار فایل شامل موارد زیر است:
-
actions/: پروژه «کنش‌ها» شما را نشان می‌دهد. وقتی «کنش» شما فراخوانده می‌شود، سیستم باactions.yamlتماس می‌گیرد و سپس با فایلcustom/global/actions.intent.MAIN.yamlتماس می‌گیرد. custom/: دایرکتوری‌ای که در آن برای اصلاح «کنش» خود کار خواهید کرد.global/: این دایرکتوری حاوی قصدهای سیستم است که پلاتفرم به‌طور خودکار به پروژه شما اضافه می‌کند. در ادامه این codelab، درباره هدف‌های سیستم بیشتر خواهید آموخت.manifest.yaml: فایلی که حاوی اطلاعات قابل‌انتقال است یا مختص پروژه خاصی نیست و می‌توان آن را بین پروژه‌ها جابه‌جا کرد.settings/: تنظیمات پروژه Actions را نشان می‌دهد، مانند نام نمایشی، زبان پیش‌فرض، و دسته.
۳. شروع مکالمه
کاربران مکالمه با «کنش» شما را ازطریق فراخوانی شروع می‌کنند. برای مثال، اگر «کنشی» به‌نام MovieTime داشته باشید، کاربران می‌توانند با گفتن عبارتی مثل «Ok Google، با MovieTime صحبت کن» «کنش» شما را فراخوانی کنند که در آن MovieTime نام نمایشی است. اگر می‌خواهید «کنش» خود را در محیط تولید مستقر کنید، باید نام نمایشی داشته باشد؛ اما برای آزمایش «کنش» خود، نیازی به تعریف نام نمایشی ندارید. درعوض، می‌توانید از عبارت «با برنامه آزمایشی من صحبت کن» در شبیه‌ساز برای فراخوانی «کنش» خود استفاده کنید. در ادامه این بخش، درباره شبیه‌ساز بیشتر خواهید آموخت.
باید فراخوانی اصلی را ویرایش کنید تا مشخص شود پس‌از اینکه کاربر «کنش» شما را فراخوانی کرد چه اتفاقی می‌افتد.
به‌طور پیش‌فرض، «کنش» شما وقتی فراخوانی‌تان راه‌اندازی می‌شود، یک پیام‌واره عمومی ارائه می‌دهد («با تعریف فراخوانی اصلی، ساختن کنش خود را شروع کنید.»).
در بخش بعدی، پیام‌واره را برای فراخوانی اصلی‌تان در فایل custom/global/actions.intent.MAIN.yaml سفارشی‌سازی می‌کنید.
راه‌اندازی فراخوانی اصلی
می‌توانید پیام‌واره فراخوانی اصلی را در فایل actions.intent.MAIN.yaml ویرایش کنید.
برای اصلاح پیام‌واره‌ای که «کنش» شما هنگام فراخوانی «کنش» به کاربر برمی‌گرداند، این مراحل را دنبال کنید:
custom/global/actions.intent.MAIN.yamlرا در ویرایشگر نوشتار باز کنید.- نوشتار فیلد
speech(Start building your action...) را با پیام خوشامدگویی زیر جایگزین کنید:A wondrous greeting, adventurer! Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you're on your way to an epic journey.
actions.intent.MAIN.yaml
handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: A wondrous greeting, adventurer! Welcome to the mythical land of
Gryffinberg! Based on your clothes, you are not from around these lands.
It looks like you're on your way to an epic journey.
transitionToScene: actions.scene.END_CONVERSATION
- فایل را ذخیره کنید.
فراخوانی اصلی را در شبیه‌ساز آزمایش کنید
کنسول Actions ابزاری وب برای آزمایش «کنش» شما ارائه می‌دهد که شبیه‌ساز نام دارد. این میانای کاربری دستگاه‌های سخت‌افزاری و تنظیمات آن‌ها را شبیه‌سازی می‌کند تا بتوانید با «کنش» خود مکالمه کنید، گویی که در نمایشگر هوشمند، تلفن، بلندگو، یا KaiOS درحال اجرا است.
وقتی «کنش» خود را فراخوانی می‌کنید، اکنون باید با پیام‌واره سفارشی‌شده‌ای که اضافه کردید پاسخ دهد («سلامی شگفت‌انگیز، ماجراجو!...»).
می‌توانید از فرمان gactions deploy preview برای آزمایش «کنش» خود در کنسول بدون به‌روزرسانی نسخه پروژه «کنش‌های» خود استفاده کنید. وقتی این فرمان را اجرا می‌کنید، هیچ‌کدام از تغییراتی که در سیستم فایل محلی‌تان ایجاد می‌کنید به نسخه‌های مستقرشده پروژه «کنش‌های» شما منتقل نمی‌شود، اما می‌توانید آن‌ها را در نسخه پیش‌نمایش آزمایش کنید.
برای آزمایش فراخوانی اصلی «کنش» در شبیه‌ساز، این مراحل را دنبال کنید:
- برای استقرار پروژه‌تان در کنسول Actions برای آزمایش، فرمان زیر را در پایانه اجرا کنید:
gactions deploy preview
باید بروندادی شبیه به زیر دریافت کنید:
✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview
- نشانی وب ارائه‌شده را کپی کنید و در مرورگر جای‌گذاری کنید.
- برای فراخوانی «کنش» در شبیه‌ساز،
Talk to my test appرا در فیلد ورودی تایپ کنید وEnterرا فشار دهید.
وقتی فراخوانی اصلی «کنش» را راه‌اندازی می‌کنید، «دستیار» با پیام خوشامدگویی سفارشی‌شده شما پاسخ می‌دهد. در این مرحله، مکالمه پس‌از پاسخ «دستیار» با خوشامدگویی به‌پایان می‌رسد. در بخش بعدی، «کنش» خود را اصلاح می‌کنید تا مکالمه ادامه یابد.
مشاهده گزارش‌های رویداد
وقتی در برگه آزمایش در کنسول Actions هستید، پانل گزارش‌های رویداد را نشان می‌دهد که سابقه مکالمه را به‌عنوان گزارش‌های رویداد نمایش می‌دهد. هر گزارش رویداد رویدادهایی را که درطول آن نوبت مکالمه اتفاق می‌افتد نمایش می‌دهد.
«کنش» شما درحال‌حاضر یک گزارش رویداد دارد که هم ورودی کاربر («با برنامه آزمایشی من صحبت کن») و هم پاسخ «کنش» شما را نشان می‌دهد. نماگرفت زیر گزارش رویداد «کنش» شما را نشان می‌دهد:
اگر روی پیکان روبه‌پایین کنار Talk to my test app در گزارش رویداد کلیک کنید، می‌توانید رویدادهایی را که در آن نوبت مکالمه رخ داده‌اند به‌ترتیب زمانی ببینید:
userInput: با ورودی کاربر مطابقت دارد («با برنامه آزمایشی من صحبت کن»)interactionMatch: با پاسخ فراخوانی اصلی «کنش» شما مطابقت دارد که با ورودی کاربر راه‌اندازی شده است. اگر این ردیف را با کلیک کردن روی پیکان ازهم باز کنید، می‌توانید پیام‌واره‌ای را که برای فراخوانی اصلی (A wondrous greeting, adventurer!...) اضافه کرده‌اید ببینیدendConversation: با انتقال انتخاب‌شده در قصدMain invocationمطابقت دارد که درحال‌حاضر مکالمه را به‌پایان می‌رساند. در بخش بعدی این codelab، درباره انتقال‌ها بیشتر خواهید آموخت.
گزارش‌های رویداد نحوه عملکرد «کنش» شما را نشان می‌دهند و ابزارهای مفیدی برای اشکال‌زدایی «کنش» شما درصورت بروز مشکل هستند. برای دیدن جزئیات رویداد، روی پیکان کنار نام رویداد کلیک کنید، همان‌طور که در نماگرفت زیر نشان داده شده است:
۴. ایجاد مکالمه «کنش»
اکنون که تعریف کرده‌اید پس‌از اینکه کاربر «کنش» شما را فراخوانی کرد چه اتفاقی می‌افتد، می‌توانید بقیه مکالمه «کنش» خود را بسازید. قبل‌از ادامه دادن این codelab، با اصطلاحات زیر آشنا شوید تا نحوه عملکرد مکالمه «کنش» را درک کنید:
«کنش» شما می‌تواند یک یا چند صحنه داشته باشد و باید هر صحنه را قبل‌از اجرا فعال کنید. «کنشی» که در این codelab می‌سازید فقط یک صحنه با عنوان Start دارد. رایج‌ترین روش برای فعال کردن صحنه، پیکربندی «کنش» است به‌طوری‌که وقتی ورودی کاربر با قصدی در صحنه مطابقت داشته باشد، آن قصد انتقال به صحنه دیگری را راه‌اندازی و آن را فعال می‌کند.
برای مثال، یک «کنش» فرضی را تصور کنید که حقایقی درباره حیوانات به کاربر ارائه می‌دهد. وقتی کاربر این «کنش» را فراخوانی می‌کند، قصد Main invocation مطابقت داده می‌شود و انتقال به صحنه‌ای به‌نام Facts. را راه‌اندازی می‌کند. این انتقال صحنه Facts را فعال می‌کند که پیام‌واره زیر را به کاربر ارسال می‌کند: Would you like to hear a fact about cats or dogs? در صحنه Facts، قصد سفارشی‌ای به‌نام Cat وجود دارد که حاوی عبارت‌های آموزشی است که کاربر ممکن است برای شنیدن واقعیتی درباره گربه‌ها بگوید، مثلاً «می‌خواهم واقعیتی درباره گربه‌ها بشنوم» یا «گربه». وقتی کاربر می‌خواهد واقعیتی درباره گربه بشنود، قصد Cat مطابقت داده می‌شود و انتقال به صحنه‌ای به‌نام Cat fact. را راه‌اندازی می‌کند. صحنه Cat fact فعال می‌شود و پیام‌واره‌ای حاوی واقعیتی درباره گربه برای کاربر ارسال می‌کند.
شکل ۱. جریان یک نوبت مکالمه معمولی در «کنشی» که با Actions SDK ساخته شده است.
صحنه‌ها، اهداف، و انتقال‌ها باهم منطق مکالمه شما را تشکیل می‌دهند و مسیرهای مختلفی را که کاربر می‌تواند در مکالمه «کنش» شما طی کند تعریف می‌کنند. در بخش زیر، صحنه‌ای ایجاد می‌کنید و نحوه فعال شدن آن صحنه را پس‌از اینکه کاربر «کنش» شما را فراخوانی کرد تعریف می‌کنید.
انتقال از فراخوانی اصلی به صحنه
در این بخش، صحنه جدیدی به‌نام Start ایجاد می‌کنید که پیام‌واره‌ای به کاربر ارسال می‌کند و از او می‌پرسد که آیا می‌خواهد طالعش را بداند. همچنین انتقالی از فراخوانی اصلی به صحنه جدید Start اضافه می‌کنید.
برای ایجاد این صحنه و افزودن انتقال به آن، این مراحل را دنبال کنید:
custom/global/actions.intent.MAIN.yamlرا در ویرایشگر نوشتار باز کنید.- نوشتار فیلد
transitionToScene(actions.scene.END_CONVERSATION) را با نوشتار زیر جایگزین کنید:transitionToScene: Start
actions.intent.MAIN.yaml
handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: Welcome to the mythical land of Gryffinberg! Based on your clothes,
you are not from around these lands. It looks like you're on your way
to an epic journey.
transitionToScene: Start
این به «کنش» شما می‌گوید که از فراخوانی اصلی به صحنه Start منتقل شود.
- فایل را ذخیره کنید.
- در پایانه، دایرکتوری
scenesجدیدی در دایرکتوریcustomایجاد کنید:
mkdir custom/scenes
- فایل جدیدی به‌نام
Start.yamlدر فهرست راهنمایscenesایجاد کنید که نشان‌دهنده صحنهstartدر «کنش» شما است:
touch custom/scenes/Start.yaml
Start.yamlرا در ویرایشگر نوشتار باز کنید.- کد زیر را در فایل
Start.yamlجای‌گذاری کنید:
Start.yaml
onEnter:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: Before you continue on your quest, would you like your fortune
told?
در کد فایل Start.yaml، فیلدی به‌نام onEnter وجود دارد که اولین مرحله‌ای است که در چرخه حیات صحنه اجرا می‌شود.
در این مورد، وقتی کاربر برای اولین‌بار وارد صحنه Start می‌شود، پیام‌واره (Before you continue on your quest...) به صف پیام‌واره اضافه می‌شود.
افزودن تراشه‌های پیشنهاد
تراشه‌های پیشنهادی پیشنهادهای قابل‌کلیکی را برای کاربر ارائه می‌دهند که «کنش» شما آن‌ها را به‌عنوان ورودی کاربر پردازش می‌کند. در این بخش، تراشه‌های پیشنهادی Yes و No را اضافه می‌کنید که در زیر پیام‌واره‌ای که به‌تازگی پیکربندی کرده‌اید (Before you continue on your quest, would you like your fortune told?) ظاهر می‌شوند تا از کاربران در دستگاه‌های دارای صفحه‌نمایش پشتیبانی کنند.
برای افزودن تراشه‌های پیشنهادی به پیام‌واره صحنه Start، این مراحل را دنبال کنید:
- کد را در
Start.yamlبه‌روز کنید تا با تکه‌کد زیر مطابقت داشته باشد، که شامل کد پیکربندی تراشه‌های پیشنهادی است:
Start.yaml
onEnter:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: Before you continue on your quest, would you like your fortune
told?
suggestions:
- title: "Yes"
- title: "No"
- فایل را ذخیره کنید.
«کنش» خود را در شبیه‌ساز آزمایش کنید
در این مرحله، «کنش» شما باید از فراخوانی اصلی به صحنه Start منتقل شود و از کاربر بپرسد که آیا می‌خواهد طالعش را بداند. تراشه‌های پیشنهاد نیز باید در نمایشگر شبیه‌سازی‌شده نشان داده شود.
برای آزمایش «کنش» در شبیه‌ساز، این مراحل را دنبال کنید:
- در پایانه، فرمان زیر را اجرا کنید:
gactions deploy preview
باید بروندادی شبیه به زیر دریافت کنید:
✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview
- نشانی وب ارائه‌شده را کپی کنید و در مرورگر جای‌گذاری کنید.
- روی آزمایش کلیک کنید تا به شبیه‌ساز بروید.
Talk to my test appرا در فیلد ورودی تایپ کنید وEnterرا فشار دهید. «کنش» شما باید با پیام‌وارهMain invocationو پیام‌واره صحنه اضافه‌شدهStart، «قبل‌از ادامه دادن مأموریت، می‌خواهید طالعتان را بگویم؟»، و با نمایش تراشه‌های پیشنهادی پاسخ دهد.
نماگرفت زیر این تعامل را نشان می‌دهد:
- برای پاسخ دادن به پیام‌واره، روی تراشه پیشنهادی بله یا نه کلیک کنید. (همچنین می‌توانید بگویید «بله» یا «نه» یا
YesیاNoرا در فیلد ورودی وارد کنید.)
وقتی به پیام‌واره پاسخ می‌دهید، «کنش» شما با پیامی پاسخ می‌دهد که نشان می‌دهد نمی‌تواند ورودی شما را درک کند: «متأسفم، متوجه نشدم. می‌توانید دوباره امتحان کنید؟» چون هنوز «کنش» خود را برای درک و پاسخ به ورودی «بله» یا «نه» پیکربندی نکرده‌اید، «کنش» شما ورودی‌تان را با قصد NO_MATCH مطابقت می‌دهد.
به‌طور پیش‌فرض، قصد سیستم NO_MATCH پاسخ‌های عمومی ارائه می‌دهد، اما می‌توانید این پاسخ‌ها را سفارشی‌سازی کنید تا به کاربر نشان دهید که ورودی او را متوجه نشده‌اید. «دستیار» مکالمه کاربر با «کنش» شما را پس‌از اینکه سه بار نتوانست ورودی کاربر را مطابقت دهد پایان می‌دهد.
افزودن قصد yes و no
اکنون که کاربران می‌توانند به سؤالی که «کنش» شما مطرح می‌کند پاسخ دهند، می‌توانید «کنش» خود را برای درک پاسخ‌های کاربران («بله» یا «نه») پیکربندی کنید. در بخش‌های زیر، قصدهای سفارشی‌ای ایجاد می‌کنید که وقتی کاربر می‌گوید «بله» یا «نه» مطابقت داده می‌شوند و این قصدها را به صحنه Start اضافه می‌کنید.
ایجاد کردن قصد yes
برای ایجاد قصد yes، این مراحل را دنبال کنید:
- در پایانه، دایرکتوری جدیدی به‌نام
intentsدر دایرکتوریcustomایجاد کنید:
mkdir custom/intents
- فایل جدیدی به‌نام
yes.yamlدر دایرکتوریintentsبسازید:
touch custom/intents/yes.yaml
yes.yamlرا در ویرایشگر نوشتار باز کنید.- تکه‌کد زیر را که حاوی عبارت‌های آموزشی است در
yes.yamlجای‌گذاری کنید:
yes.yaml
trainingPhrases:
- of course
- let's do it
- ok
- sure
- "y"
- "yes"
- فایل را ذخیره کنید.
افزودن قصد yes به صحنه Start
اکنون، «کنش» می‌تواند تشخیص دهد که کاربر چه زمانی قصد «بله» گفتن دارد. می‌توانید قصد سفارشی yes را به صحنه Start اضافه کنید، زیرا کاربر به پیام‌واره Start پاسخ می‌دهد («قبل‌از اینکه به مأموریت خود ادامه دهید، آیا می‌خواهید طالعتان را بگویم؟»).
برای افزودن این قصد سفارشی به صحنه Start، این مراحل را دنبال کنید:
custom/scenes/Start.yamlرا در ویرایشگر نوشتار باز کنید.- گرداننده
intentEventsوyesرا به انتهای فایلStart.yamlاضافه کنید:
Start.yaml
intentEvents:
- handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: Your future depends on the item you choose to use for your quest. Choose wisely! Farewell, stranger.
intent: "yes"
transitionToScene: actions.scene.END_CONVERSATION
وقتی قصد yes مطابقت داده می‌شود، پیام‌واره «آینده شما به موردی بستگی دارد که برای مأموریتتان انتخاب می‌کنید...» به صف پیام‌واره اضافه می‌شود. سپس صحنه Start به صحنه سیستم actions.scene.END_CONVERSATION منتقل می‌شود که پیام‌واره‌ها را در صف پیام‌واره ارائه می‌دهد و مکالمه را پایان می‌دهد.
آزمایش قصد yes در شبیه‌ساز
در این مرحله، «کنش» شما متوجه می‌شود که کاربر چه زمانی می‌خواهد طالعش را بشنود و پاسخ مناسب را برمی‌گرداند.
برای آزمایش این قصد در شبیه‌ساز، این مراحل را دنبال کنید:
- در پایانه، فرمان زیر را اجرا کنید:
gactions deploy preview
باید بروندادی شبیه به زیر دریافت کنید:
✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview
- نشانی وب ارائه‌شده را کپی کنید و در مرورگر جای‌گذاری کنید.
- روی آزمایش کلیک کنید تا به شبیه‌ساز بروید.
- برای آزمایش «کنش» در شبیه‌ساز،
Talk to my test appرا در فیلد ورودی تایپ کنید وEnterرا فشار دهید. Yesرا در فیلد ورودی تایپ کنید وEnterرا فشار دهید. یا روی تراشه پیشنهادی بله کلیک کنید.
«کنش» شما به کاربر پاسخ می‌دهد و به او می‌گوید که بختش به کمکی که انتخاب می‌کند بستگی دارد. سپس «کنش» شما جلسه را به‌پایان می‌رساند چون انتقال End conversation را برای قصد yes پیکربندی کرده‌اید.
ایجاد کردن قصد no
اکنون می‌توانید هدف no را ایجاد کنید تا «کنش» شما بتواند وقتی کاربر نمی‌خواهد طالعش را بشنود، او را درک کند و به او پاسخ دهد.
برای ایجاد این هدف، این مراحل را دنبال کنید:
- در پایانه، فایل جدیدی به‌نام
no.yamlدر فهرست راهنمایintentsایجاد کنید:
touch custom/intents/no.yaml
no.yamlرا در ویرایشگر نوشتار باز کنید.- عبارت‌های آموزشی زیر را در فایل
no.yamlجای‌گذاری کنید:
no.yaml
trainingPhrases:
- nope
- I don't want
- "n"
- "no"
- nah
- no thanks
- فایل را ذخیره کنید.
افزودن قصد no به صحنه Start
اکنون، «کنش» می‌تواند متوجه شود که کاربر چه زمانی «نه» یا چیزی شبیه به «نه»، مثل «نه» را بیان می‌کند. باید قصد سفارشی no را به صحنه Start اضافه کنید زیرا کاربر به پیام‌واره Start پاسخ می‌دهد («قبل‌از اینکه به مأموریت خود ادامه دهید، آیا می‌خواهید طالعتان را بگویم؟»).
برای افزودن این هدف برای صحنه Start، این مراحل را دنبال کنید:
custom/scenes/Start.yamlرا در ویرایشگر نوشتار باز کنید.- گرداننده
noزیر را در زیر گردانندهyesدرStart.yamlاضافه کنید:
Start.yaml
- handler:
staticPrompt:
candidates:
- promptResponse:
firstSimple:
variants:
- speech: I understand, stranger. Best of luck on your quest! Farewell.
intent: "no"
transitionToScene: actions.scene.END_CONVERSATION
- فایل را ذخیره کنید.
آزمایش قصد no در شبیه‌ساز
در این مرحله، «کنش» شما متوجه می‌شود که کاربر چه زمانی نمی‌خواهد طالعش را بشنود و پاسخ مناسب را برمی‌گرداند.
برای آزمایش این قصد در شبیه‌ساز، این مراحل را دنبال کنید:
- در پایانه، فرمان زیر را اجرا کنید:
gactions deploy preview
باید بروندادی شبیه به زیر دریافت کنید:
✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview
- نشانی وب ارائه‌شده را کپی کنید و در مرورگر جای‌گذاری کنید.
- روی آزمایش کلیک کنید تا به شبیه‌ساز بروید.
Talk to my test appرا در فیلد ورودی تایپ کنید وEnterرا فشار دهید.Noرا در فیلد ورودی تایپ کنید وEnterرا فشار دهید. یا روی تراشه پیشنهادNoکلیک کنید.
به‌جای اینکه «کنش» شما طالع کاربر را به او بگوید، برای او در سفرش آرزوی موفقیت می‌کند. سپس «کنش» شما جلسه را به‌پایان می‌رساند چون انتقال End conversation را برای قصد no پیکربندی کرده‌اید.
۵. پیاده‌سازی اجرا
درحال‌حاضر، پاسخ‌های «کنش» شما ایستا است؛ وقتی صحنه‌ای حاوی پیام‌واره فعال می‌شود، «کنش» شما هربار همان پیام‌واره را ارسال می‌کند. در این بخش، اجرا را پیاده‌سازی می‌کنید که حاوی منطق ساختن پاسخ مکالمه‌ای پویا است.
تحقق شما تشخیص می‌دهد که کاربر بازگشتی است یا جدید و پیام خوشامدگویی «کنش» را برای کاربران بازگشتی تغییر می‌دهد. پیام خوشامدگویی برای کاربران قدیمی کوتاه‌تر است و بازگشت کاربر را تأیید می‌کند: «خوشامدگویی شگفت‌انگیز، ماجراجو! به سرزمین افسانه‌ای گریفینبرگ خوش برگشتید!»
برای این codelab، از ویرایشگر Cloud Functions برای ویرایش و استقرار کد تحقق استفاده می‌کنید.
«کنش» شما می‌تواند وب‌قلاب‌هایی را راه‌اندازی کند که به تحقق شما از رویدادی که درطول فراخوانی یا بخش‌های خاصی از اجرای صحنه رخ می‌دهد اطلاع می‌دهد. وقتی وب‌قلاب راه‌اندازی می‌شود، «کنش» شما درخواستی با بار JSON به تحقق شما ارسال می‌کند و نام گرداننده را برای استفاده در پردازش رویداد ارائه می‌دهد. این گرداننده منطقی را اجرا می‌کند و پاسخ JSON مربوطه را برمی‌گرداند.
ساختن تحقق
در این بخش، اجرای خود را تغییر می‌دهید تا وقتی کاربران برگشتی و کاربران جدید «کنش» شما را فراخوانی می‌کنند، پیام‌واره‌های متفاوتی برای آن‌ها تولید شود.
برای افزودن این منطق به تحقق، این مراحل را دنبال کنید:
- در پایانه، مطمئن شوید که در دایرکتوری ریشه پروژه‌تان هستید و دایرکتوری
webhooksجدیدی ایجاد کنید:
mkdir webhooks
- فایل جدیدی به‌نام
ActionsOnGoogleFulfillment.yamlدر دایرکتوریwebhooksبسازید:
touch webhooks/ActionsOnGoogleFulfillment.yaml
ActionsOnGoogleFulfillment.yamlرا در ویرایشگر نوشتار باز کنید.- گرداننده
greetingو محتوایinlineCloudFunctionرا به فایلActionsOnGoogleFulfillment.yamlاضافه کنید:
ActionsOnGoogleFulfillment.yaml
handlers:
- name: greeting
inlineCloudFunction:
executeFunction: ActionsOnGoogleFulfillment
فایل ActionsOnGoogleFulfillment.yaml گرداننده‌های وب‌قلاب شما را (مثل گرداننده greeting) تعریف می‌کند و به «کنش» شما می‌گوید که از Cloud Functions به‌عنوان نقطه پایانی وب‌قلاب استفاده کند.
- دایرکتوری
ActionsOnGoogleFulfillmentجدیدی در دایرکتوریwebhooksایجاد کنید:
mkdir webhooks/ActionsOnGoogleFulfillment
- فایل جدیدی به‌نام
index.jsدر دایرکتوریActionsOnGoogleFulfillmentبسازید:
touch webhooks/ActionsOnGoogleFulfillment/index.js
index.jsرا در ویرایشگر نوشتار باز کنید.- کد زیر را به
index.jsاضافه کنید:
index.js
const { conversation } = require('@assistant/conversation');
const functions = require('firebase-functions');
const app = conversation({debug: true});
app.handle('greeting', conv => {
let message = 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!';
if (!conv.user.lastSeenTime) {
message = 'Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you\'re on your way to an epic journey.';
}
conv.add(message);
});
exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);
این کد گرداننده greeting را تعریف می‌کند که تبریک مناسب را به
ارسال می‌کند
کاربر.
- فایل را ذخیره کنید.
- فایل جدیدی به‌نام
package.jsonدر دایرکتوریActionsOnGoogleFulfillmentبسازید:
touch webhooks/ActionsOnGoogleFulfillment/package.json
فایل package.json وابستگی‌ها و فراداده‌های دیگر را برای وب‌قلاب شما مشخص می‌کند.
package.jsonرا در ویرایشگر نوشتار باز کنید.- کد را از این مخزن GitHub کپی کنید و آن را در فایل
package.jsonجای‌گذاری کنید. - فایل را ذخیره کنید.
درک کردن کد
تحقق شما، که از کتابخانه Actions on Google Fulfillment برای Node.js استفاده می‌کند، به درخواست‌های HTTP از «دستیار Google» پاسخ می‌دهد.
در تکه‌کد قبلی، گرداننده greeting را تعریف می‌کنید که بررسی می‌کند آیا کاربر قبلاً با ویژگی lastSeenTime از «کنش» بازدید کرده است یا نه. اگر ویژگی lastSeenTime تعریف نشده باشد، کاربر جدید است و پیام خوشامدگویی مخصوص کاربران جدید را دریافت می‌کند. درغیراین‌صورت، پیام بازگشت کاربر را تأیید می‌کند و یک خوشامدگویی اصلاح‌شده تولید می‌کند.
به‌روزرسانی فراخوانی اصلی برای راه‌اندازی وب‌قلاب
اکنون که تابع greeting را تعریف کرده‌اید، می‌توانید گرداننده رویداد greeting را در هدف فراخوانی اصلی‌تان پیکربندی کنید تا «کنش» شما بداند که وقتی کاربر «کنش» شما را فراخوانی می‌کند، باید این تابع را فراخوانی کند.
برای پیکربندی «کنش» خود برای فراخوانی گرداننده greeting جدید، این مراحل را دنبال کنید:
custom/global/actions.intent.MAIN.yamlرا در ویرایشگر نوشتار باز کنید.- کد موجود در
actions.intent.MAIN.yamlرا با کد زیر جایگزین کنید:
actions.intent.MAIN.yaml
handler:
webhookHandler: greeting
transitionToScene: Start
- فایل را ذخیره کنید.
اکنون، وقتی قصد فراخوانی اصلی شما مطابقت داده می‌شود، کنترل‌کننده وب‌قلاب greeting فراخوانی می‌شود.
آزمایش فراخوانی اصلی به‌روزشده در شبیه‌ساز
برای آزمایش «کنش» در شبیه‌ساز، این مراحل را دنبال کنید:
- در پایانه، فرمان زیر را اجرا کنید:
gactions deploy preview
باید بروندادی شبیه به زیر دریافت کنید:
✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview
- نشانی وب ارائه‌شده را کپی کنید و در مرورگر جای‌گذاری کنید.
- برای آزمایش «کنش» در شبیه‌ساز،
Talk to my test appرا در فیلد ورودی تایپ کنید وEnterرا فشار دهید.
چون قبلاً در این codelab «کنش» خود را آزمایش کرده‌اید، کاربر جدید نیستید، بنابراین خوشامدگویی کوتاه زیر را دریافت می‌کنید: «خوشامدگویی شگفت‌انگیز، ماجراجو! به سرزمین افسانه‌ای گریفینبرگ خوش برگشتید!...»
۶. تجسم کردن «کنش» با Actions Builder
کیت توسعه نرم‌افزار Actions با محیط توسعه یکپارچه (IDE) مبتنی بر وب به‌نام Actions Builder که در کنسول Actions ادغام شده است، قابلیت همکاری دارد. می‌توانید سیستم فایل محلی‌تان را با فرمان gactions push به پیش‌نویس «کنش» خود در کنسول ارسال کنید. برخلاف gactions deploy preview که فقط به شما امکان می‌دهد «کنش» خود را در شبیه‌ساز آزمایش کنید، gactions push تمام محتوا را از فایل‌های محلی شما به Actions Builder منتقل می‌کند.
کنسول «کنش‌ها» نمایشی دیداری از پیکربندی «کنش» شما ارائه می‌دهد. دیدن «کنش» به‌صورت بصری می‌تواند درطول توسعه مفید باشد و بر نسخه‌ای از «کنش» که برای آزمایش ارائه می‌شود تأثیری ندارد.
برای ارسال پروژه Actions و مشاهده آن در کنسول Actions، این مراحل را دنبال کنید:
- در پایانه، فرمان زیر را اجرا کنید تا پروژه‌تان را به کنسول Actions ارسال کنید:
gactions push
باید بروندادی شبیه به زیر دریافت کنید:
✔ Done. Files were pushed to Actions Console, and you can now view your project with this URL: https://console.actions.google.com/project/{project-id}/overview. If you want to test your changes, run "gactions deploy preview", or navigate to the Test section in the Console.
- نشانی وب ارائه‌شده را کپی کنید و در مرورگر جای‌گذاری کنید.
- در کنسول Actions، روی توسعه در نوار پیمایش بالا کلیک کنید.
- روی کلید کشویی کنار صحنه‌ها کلیک کنید و روی شروع کلیک کنید. باید نمایش تصویری صحنه
Start«کنش» خود را ببینید، همان‌طور که در نماگرفت زیر نشان داده شده است:
پاک‌سازی پروژه [توصیه می‌شود]
برای جلوگیری از کسر هزینه‌های احتمالی، توصیه می‌شود پروژه‌هایی را که قصد استفاده از آن‌ها را ندارید بردارید. برای حذف پروژه‌هایی که در این codelab ایجاد کرده‌اید، این مراحل را دنبال کنید:
- برای حذف کردن «پروژه ابری» و منابع، مراحل فهرست‌شده در بخش بستن (حذف کردن) پروژه‌ها را تکمیل کنید.
- اختیاری: برای برداشتن فوری پروژه‌تان از کنسول Actions، مراحل فهرست‌شده در بخش حذف پروژه را تکمیل کنید. اگر این مرحله را تکمیل نکنید، پروژه‌تان پس‌از تقریباً ۳۰ روز به‌طور خودکار برداشته می‌شود.
۷. تبریک!
با اصول اولیه ساختن Actions for Google Assistant با Actions SDK آشنا هستید.
آنچه پوشش دادید
- نحوه راه‌اندازی پروژه Actions در کنسول Actions
- نحوه استفاده از Actions SDK برای ساختن پروژه Actions در سیستم فایل محلی
- نحوه افزودن پیام‌واره به فراخوانی اصلی تا کاربران بتوانند مکالمه‌ای را با «کنش» شما شروع کنند
- نحوه ایجاد میانای مکالمه‌ای با صحنه‌ها، هدف‌ها، انتقال‌ها، تراشه‌های پیشنهاد، و برآورده‌سازی
- نحوه آزمایش «کنش» با شبیه‌ساز «کنش‌ها»
بیشتر بدانید
برای کسب اطلاعات بیشتر درباره ساختن «کنش‌ها» برای «دستیار Google»، منابع زیر را کاوش کنید:
- سایت اسناد رسمی برای توسعه «کنش‌ها» برای «دستیار Google»
- صفحه Actions on Google GitHub برای کد نمونه و کتابخانه‌ها
- انجمن رسمی Reddit برای توسعه‌دهندگانی که با «دستیار» کار می‌کنند
برای اطلاع از جدیدترین اعلامیه‌ها، @ActionsOnGoogle را در Twitter دنبال کنید و با #AoGDevs توییت کنید تا آنچه را ساخته‌اید هم‌رسانی کنید!
نظرسنجی بازخورد
قبل‌از رفتن، لطفاً نظرسنجی کوتاهی درباره تجربه‌تان تکمیل کنید.