عمومی
س: کجا و به چه زبانی باید زیرساخت‌های اجرایی Actions on Google را اجرا کنیم؟
پاسخ: تا زمانی که از SSL مدرن (TLS) و OAuth 2.0 پشتیبانی می کند، می توانید زیرساخت خود را بر روی هر پلتفرم و به هر زبانی که انتخاب می کنید پیاده سازی کنید. برای بهبود قابلیت اطمینان و کاهش تأخیر اجرا در دستگاه های کاربر واقعی، توصیه می کنیم تا حد امکان نزدیک به بقیه زیرساخت های خود مستقر شوید.
س: آیا شناسه های دستگاه باید منحصر به فرد باشد؟
A: شناسه ها باید منحصر به فرد باشند. اگر شناسه‌های منحصربه‌فرد در سراسر سرویس خود ندارید، باید حداقل در سطح هر کاربر منحصربه‌فرد باشند. کاربری را با چندین خانه تصور کنید، جایی که هر دو خانه با یک کاربر ادغام می شوند. درخواست روشن کردن چراغ در یک خانه نباید چراغی را با همان شناسه در خانه دیگر روشن کند.
س: آیا نام دستگاه باید منحصر به فرد باشد؟
پاسخ: لازم نیست نام‌ها منحصر به فرد باشند، اگرچه با گذشت زمان ممکن است افراد را تشویق کنیم که نامگذاری بد را پس از راه‌اندازی برای تجربه کاربری بهتر بهبود بخشند.
در اینجا یک راهنمای نامگذاری سریع آمده است:
- نام ها باید چیزهایی باشند که مردم واقعاً می توانند بگویند.
- ما زیرمجموعه‌های رشته‌ها را تشخیص می‌دهیم، بنابراین اگر «نور رنگ acme» دارید، به «نور acme» نیز پاسخ خواهیم داد.
- ما هم یک نام توصیفی برای محصول و هم یک یا چند نام تعریف شده توسط کاربر را توصیه می کنیم.
- کاربران نیازی به نام اتاق چراغ ها ندارند، زیرا ما اتاق هایی برای آن داریم. آنها باید اسامی منحصر به فرد در هر اتاق داشته باشند، اما همیشه می توانند از جمع برای فرمان دادن به همه چیز استفاده کنند (به عنوان مثال، دو لامپ در دیوارکوب های اداری "نور شمال" و "نور شرقی" هستند، اما می توان آنها را فقط به عنوان "چراغ" فرمان داد).
س: وضعیت دستگاه هر چند وقت یکبار به روز می شود؟
A: حالت زودگذر بر روی QUERY یا EXECUTE بازیابی می شود که اقداماتی هستند که توسط کاربر آغاز شده است. اگر کاربر بپرسد "آیا چراغ روشن است؟"، یا بخواهد نوری را روشن کند، باید یک پرس و جو انجام دهیم تا وضعیت فعلی را بفهمیم.
س: آیا می توان Home Graph را با وضعیت فعلی دستگاه به طور مستقیم به روز کرد؟
پاسخ: بله، از تماس API Report State استفاده کنید.
پیوند حساب و OAuth
س: آیا باید پیوند حساب را انجام دهیم؟
پاسخ: بله، برای اتصال دستگاه های کاربر به خدمات ابری ارائه دهنده، پیوند حساب لازم است.
س: برای OAuth، ما توکن های دسترسی را هر 15.213 ساعت منقضی می کنیم، آیا مشکلی ندارد؟
پاسخ: بله، اما لطفاً با یک زمان انقضا نسبتاً کوتاه، مثلاً 10-20 دقیقه، تست کنید. مشتری OAuth ما باید در صورت نیاز توکن‌ها را تازه‌سازی کند، و آزمایش با زمان انقضای کوتاه ثابت می‌کند که این کار درست است.
مقاصد
س: چه زمانی SYNC اتفاق می افتد؟
پاسخ: همگام‌سازی بلافاصله پس از تکمیل OAuth و پس از برقراری تماس درخواست همگام‌سازی انجام می‌شود.
س: چرا SYNC کار نمی کند؟
پاسخ: چندین دلیل متداول وجود دارد که چرا این ممکن است شکست بخورد.
شما در حال ارسال انواع دستگاه اشتباه هستید.
- برای مثال، ما انتظار
action.devices.types.LIGHTداریم، اما شماaction.devices.types.Lightارسال می کنید.
- برای مثال، ما انتظار
شما در حال ارسال انواع دستگاه پشتیبانی نشده هستید.
- برای مثال، شما
action.devices.types.FLASHLIGHTارسال می کنید - این چیزی نیست که ما پشتیبانی کنیم.
- برای مثال، شما
شما در حال ارسال فیلدهای نامعتبر/ پشتیبانی نشده هستید.
- به عنوان مثال، شما یک فیلد نسخه یا فیلد دیگری دارید که در مشخصات ما نیست.
مشکل قالب‌بندی دیگری در پاسخ SYNC شما وجود دارد.
- براکت های خود را بررسی کنید!
شما با مشکل پیوند حساب مواجه هستید.
- لطفاً بررسی کنید که یک نشانه دسترسی معتبر در سرصفحه Auth درخواست SYNC دریافت می‌کنید.
پاسخ دادن به درخواست SYNC خیلی طول می کشد.
- لطفاً بررسی کنید که در عرض 5 ثانیه به درخواست SYNC پاسخ می دهید.
س: آیا پاسخ «در انتظار» خوب است؟
پاسخ: اگر دستگاه‌های شما در زمان واقعی در دسترس باشند، ما به‌شدت پاسخ موفقیت‌آمیز/شکست را ترجیح می‌دهیم، به جای پاسخ‌های معلق. لطفاً اگر احساس می‌کنید که به یک پاسخ «در انتظار» نیاز دارید، تماس بگیرید -- ما می‌دانیم که برخی از دستگاه‌های کم مصرف و غیر همزمان ممکن است به یک پاسخ معلق و مدل اجرای ناهمزمان نیاز داشته باشند.
تست و ارسال
س: آیا می توانیم یک env صحنه سازی راه اندازی کنیم؟
پاسخ: بله، لطفاً یک پروژه جداگانه ایجاد کنید و راه‌اندازی آن پروژه را اجرا کنید. شما می توانید هر تعداد پروژه را که برای نقشه برداری از فرآیندها و زیرساخت های توسعه خود نیاز دارید، ایجاد کنید.
س: هر چند وقت یک بار باید پروژه پیش نویس خود را به روز کنم؟
A: یک پروژه پیش نویس باید هر 3 روز یکبار تجدید شود. پس از 3 روز، عامل تست از تنظیمات Mobile-HomeControl ناپدید می شود. اگر با این مشکل مواجه شدید، روی دکمه TEST DRAFT برای پروژه خود در Actions on Google Console کلیک کنید.
س: آیا می توانم همزمان روی بیش از یک دستگاه تست کنم؟
A: Actions on Google تنها از یک AP "تست روی دستگاه" در یک زمان پشتیبانی می کند. اگر برای اولین بار از TEST DRAFT در "ap1" استفاده می کنید و دستگاه های همگام سازی می کنید، سپس (بدون قطع پیوند ap1) مستقیماً TEST DRAFT "ap2" را اجرا کنید، "ap1" از تنظیمات mobile-HomeControl ناپدید می شود. برای تصحیح این موضوع، دوباره TEST DRAFT را روی "ap1" اجرا کنید و می توانید پیوند "ap1" را در تنظیمات لغو کنید.
توجه داشته باشید که این بسته اقدام برای همه دستگاه‌های Google Assistant شما برای کاربر در دسترس خواهد بود -- به عنوان مثال، می‌توانید ادغام سخت‌افزار جدید خود را هم در بلندگوهای فعال‌شده صوتی و هم Android آزمایش کنید.
س: ارسال پروژه Actions من به دلیل نام یا تلفظ رد شد، چه چیزی را باید تغییر دهم؟
پاسخ: ما تلفظ نام را بررسی می کنیم تا مطمئن شویم که نام تلفظ توسط یک اقدام دیگر در آینده انجام نمی شود و با نام نمایشی مطابقت دارد (برای جلوگیری از عدم تطابق که بر ثبت نام های آینده تأثیر می گذارد).
برای ادامه استفاده از همین نام، لطفاً با پشتیبانی تماس بگیرید تا نام نمایشی توسط تیم گفتار به Assistant اضافه شود.
س: My Action در بخش Home Control برنامه Google Home قابل مشاهده نیست، چه خبر است؟
پاسخ: مشکل می تواند یکی از موارد زیر باشد:
- شما روی دکمه TEST DRAFT برای پروژه خود در Actions Console کلیک نکردید.
- شما می‌توانید به‌طور همزمان فقط یک Action را در Test-on-Device داشته باشید.
- در Actions Console ، از تب Simulator برای پروژه Actions خود دیدن کنید و کلید Active/Inactive را به غیر فعال و سپس دوباره فعال کنید.
- اگر این اقدامی است که با شما به اشتراک گذاشته شده است، لطفاً مطمئن شوید که تمام دستورالعمل‌های اشتراک‌گذاری رعایت شده است.
- تست روی دستگاه پس از سه روز منقضی می‌شود. روی دکمه TEST DRAFT برای پروژه خود در Actions Console کلیک کنید.
س: چرا هنگام تایپ "talk to <my agent name> " در شبیه ساز به من خطا می دهد؟
A: اقدامات خانه هوشمند از نام های فراخوانی استفاده نمی کند. برای آزمایش در شبیه ساز، باید از طریق پیوند حساب در تلفن Android یا iOS با Google Home app (GHA) نصب شده اجرا کنید. قبل از اجرای پیوند حساب، باید دستگاه‌هایی را نیز با حساب خود مرتبط کنید.
س: چرا وقتی سعی می کنم از شبیه ساز استفاده کنم با خطا مواجه می شوم؟
پاسخ: شما نمی توانید از شبیه ساز برای آزمایش اقدامات smart home مستقر شده استفاده کنید. اگر می خواهید از شبیه ساز برای یک پروژه اتوماسیون خانگی که در حال تولید است استفاده کنید، باید یک پروژه جدید برای اهداف آزمایشی ایجاد کنید.
گزارش وضعیت
س: آیا پیش نیازهایی برای اجرای گزارش State وجود دارد؟
پاسخ: پروژه باید از Smart Home API استفاده کند، از OAuth2 پشتیبانی کند و باید ویژگی هایی داشته باشد که حالت(های) گزارش شود.
س: هر چند وقت یکبار نیاز به گزارش وضعیت در دستگاه داریم؟
پاسخ: گوگل به حالت انتقال و ترمینال علاقه مند است، با این حال، اگر در مدت زمان کوتاهی تغییرات زیادی در وضعیت ایجاد شود (به عنوان مثال، کاربر یخچال را سه بار در یک دقیقه باز و بسته می کند یا یک دیمر را می کشد) ما فقط نیاز به وضعیت نهایی گزارش شده است.
س: آیا هنگام برقراری تماس‌های وضعیت گزارش وضعیت باید ارسال شود؟
پاسخ: به‌روزرسانی‌های حالت جزئی پشتیبانی نمی‌شوند، بنابراین تماس‌های Report State همیشه باید شامل همه داده‌های یک ویژگی خاص باشد که به‌روزرسانی شده است. اگر دو صفت ناهماهنگی ایجاد کنند، باید با هم گزارش شوند.
س: آیا Google می تواند دستگاه من را برای دریافت وضعیت (یعنی نظرسنجی از دستگاه) پرس و جو کند؟
A: این یک مکانیسم بازگشتی است که ما توصیه نمی کنیم. اگر لازم باشد به نظرسنجی مکرر از یک دستگاه برای آن کاربران بازگردیم، نمی‌توانیم تضمین کنیم که بار اضافی چقدر خواهد بود. نیاز از سطوح بصری جدید ناشی می شود. علاوه بر مشکل بارگذاری ناشناخته، یک تجربه کاربری ضعیف خواهد بود. ما احساس می کنیم که Report State برای پلتفرم بسیار مهم است.
س: در حال حاضر چه ویژگی هایی از وضعیت گزارش پشتیبانی می کنند؟
A: تمام ویژگی های عمومی که دارای حالت های مرتبط هستند پشتیبانی می شوند. هر گونه تغییر در وضعیت آنلاین دستگاه نیز باید گزارش شود.
توجه داشته باشید که صحنه ها حالت ندارند. با این حال، ممکن است منجر به تغییر حالت(های) دستگاه(ها) شود. اگر هر دستگاهی در Google Home Graph دارای وضعیت تغییر است، باید دوباره گزارش شود.
س: آیا وضعیت گزارش نیاز به ارسال مهر زمانی دارد؟
پاسخ: ما به مهر زمانی نیاز نداریم. آخرین وضعیت ارسال شده، تماس های قبلی را لغو می کند.
س: اگر در حال ارسال وضعیت در Query و/یا Execute هستم، آیا باید وضعیت را جداگانه گزارش کنم؟
A: Home Graph فقط وضعیتی را ذخیره می کند که از طریق Report State ارسال می شود. حالتی که به عنوان پاسخ به مقاصد EXECUTE و QUERY برگردانده می شود فقط برای پاسخ های گفتاری به کاربر استفاده می شود و ذخیره نمی شود. در نتیجه، Report State باید فراخوانی شود، حتی اگر وضعیت جدید دستگاه قبلاً به عنوان پاسخ به یک هدف EXECUTE یا QUERY برگردانده شده باشد.
س: عدم اجرای کامل گزارش State در مهلت مقرر چه پیامدهایی دارد؟
A: این منجر به یک تجربه کاربری ضعیف می شود، به عنوان مثال در GHA و سطوح بصری. به این معنی است که بسیاری از مقاصد QUERY به نظرسنجی برای وضعیت ارسال می‌شوند و ما نمی‌توانیم تضمین کنیم که چه چیزی با بار اضافی در ابر شریک مطابقت دارد.
س: چگونه می توانم اجرای گزارش وضعیت خود را آزمایش کنم؟
A: از Home Graph Viewer استفاده کنید - یک ابزار تست سلف سرویس که وضعیت فعلی دستگاه ذخیره شده در Home Graph را به شما نشان می دهد.
س: آیا می توانیم از یک requestId تصادفی برای گزارش وضعیت استفاده کنیم؟
پاسخ: ما به شرکا توصیه می کنیم از همان requestId استفاده کنند که از درخواست EXECUTE دریافت کرده اند اگر Report State توسط درخواست EXECUTE راه اندازی شود، در غیر این صورت می توانید فقط از یک requestId تصادفی استفاده کنید.
س: اگر یک کاربر چندین دستگاه داشته باشد و یکی از آنها تغییر وضعیت دهد، آیا باید آخرین وضعیت همه دستگاه ها را گزارش کنیم؟
پاسخ: خیر. فقط باید وضعیت آن دستگاه خاص را گزارش دهید.
بهترین شیوه ها
س: چه نوع تاخیری قابل قبول است؟
پاسخ: کمتر از 200 میلی ثانیه ایده آل است، بین 2 تا 5 ثانیه خوب است. اگر تاخیر شما حدود 5 ثانیه است، با ما تماس بگیرید.
س: چگونه بلندگوی فعال شده با صدای خود را در حالت آفلاین به درستی پاسخ دهم؟
A: وضعیت آفلاین را برای دستگاه های آفلاین برگردانید. ما "در حال حاضر در دسترس نیست" را به عنوان TTS برای این خطا برگردانیم. برای اطلاعات بیشتر، خطاها و استثناها را ببینید.