گسترش یک برنامه Android به Google Assistant با App Actions (سطح 2)

۱. مرور کلی

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

در اولین آزمایشگاه کدنویسی App Actions ، یاد گرفتید که چگونه با پیاده‌سازی Intentهای داخلی (BII) از دسته Health and Fitness BII، دستیار گوگل را به یک برنامه تناسب اندام نمونه گسترش دهید. BIIها در دسته‌هایی سازماندهی شده‌اند که نشان‌دهنده انواع وظایفی هستند که کاربران اغلب از دستیار می‌خواهند انجام دهد.

در این آزمایشگاه کد، یاد می‌گیرید که چگونه با استفاده از BIIها از دسته BIIهای «رایج» ، که نشان‌دهنده وظایف رایج برنامه هستند و تقریباً هر برنامه اندرویدی می‌تواند انجام دهد، اقدامات برنامه را به یک برنامه اضافه کنید.

این آزمایشگاه کد، مفاهیم سطح متوسط ​​برای توسعه با App Actions را پوشش می‌دهد. شما باید تجربه قبلی در توسعه برنامه‌های اندروید و پیاده‌سازی Android intents داشته باشید.

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

در این آزمایشگاه کد، شما دو BII مشترک را به یک برنامه نمونه لیست کارها اضافه می‌کنید و به کاربران این امکان را می‌دهید که از دستیار بخواهند:

  • با استفاده از actions.intent.OPEN_APP_FEATURE BII به ویژگی‌های درون برنامه بروید.
  • با استفاده از جستجوی درون برنامه‌ای و با استفاده از actions.intent.GET_THING BII، محتوا را جستجو کنید.

سه صفحه نمایش پیش‌رونده که در آن‌ها دستیار گوگل وظایف فعال در یک برنامه را نمایش می‌دهد.

شکل ۱. سه صفحه نمایش پیش‌رونده که در آن‌ها دستیار گوگل وظایف فعال در یک برنامه را نمایش می‌دهد.

آنچه یاد خواهید گرفت

شما یاد خواهید گرفت که چگونه از BII های دسته بندی مشترک برای گسترش Assistant به اکثر برنامه‌های اندروید استفاده کنید. همچنین یاد خواهید گرفت که چگونه BII های مشترک را با افزونه Google Assistant برای اندروید استودیو آزمایش کنید.

پیش‌نیازها

  • یک ترمینال برای اجرای دستورات shell با نصب git.
  • آخرین نسخه پایدار اندروید استودیو .
  • یک دستگاه اندروید فیزیکی یا مجازی با دسترسی به اینترنت و فروشگاه گوگل پلی برای آزمایش اقدامات شما.
  • باید با همان حساب گوگل خود وارد اندروید استودیو و هر دو برنامه گوگل و دستیار گوگل در دستگاه آزمایشی خود شوید.

در این آزمایشگاه کد، شما از یک دستگاه اندروید (فیزیکی یا مجازی) برای آزمایش اقدامات خود استفاده می‌کنید. اگر از یک دستگاه فیزیکی استفاده می‌کنید، مطمئن شوید که به دستگاه توسعه محلی شما متصل است. همچنین باید با استفاده از همان حساب گوگل، وارد برنامه گوگل در دستگاه و وارد اندروید استودیو شوید . همچنین باید برنامه دستیار گوگل روی دستگاه نصب شده باشد.

۲. نحوه‌ی کار آن را درک کنید

اقدامات برنامه، کاربران را از دستیار گوگل به برنامه اندروید شما متصل می‌کند. اما آنها چگونه کار می‌کنند؟

وقتی کاربری به دستیار می‌گوید که می‌خواهد از برنامه شما استفاده کند، دستیار به دنبال اقدامات برنامه‌ای ثبت‌شده در برنامه شما از فایل shortcuts.xml می‌گردد. این فایل شامل قابلیت‌های برنامه است که یک intent داخلی یا intent سفارشی دستیار را به یک intent اندروید یا deep link پیوند می‌دهد.

وقتی کاربری درخواستی را به دستیار می‌گوید، دستیار ورودی کاربر را تجزیه و تحلیل می‌کند و آن را با یک هدف عملیات برنامه (App Actions intent) مطابقت می‌دهد (در این آزمایشگاه کد، این هدف یک BII خواهد بود). دستیار از فایل shortcuts.xml شما در برنامه اندرویدتان می‌داند که از کدام قابلیت‌ها پشتیبانی می‌کنید. با تطابق هدف، قابلیتی که با آن BII همراه است، شامل نحوه انجام آن درخواست است. در این آزمایشگاه کد، هدف، یک هدف اندروید است که یک فعالیت (activity) را در برنامه شما راه‌اندازی می‌کند.

نمودار زیر این جریان دستیار را نشان می‌دهد:

روندی که نحوه پردازش پرس‌وجوی صوتی کاربر توسط دستیار گوگل را شرح می‌دهد. شکل ۲. جریانی که نحوه پردازش یک پرس‌وجوی صوتی توسط دستیار گوگل را شرح می‌دهد.

فایل پروژه shortcuts.xml شامل اطلاعات زیر برای هر اقدام برنامه است:

  • اکشن برنامه از چه هدف داخلی یا سفارشی استفاده می‌کند؟
  • چه فعالیت اندرویدی یا لینک عمیقی باید در اختیار کاربر قرار گیرد؟
  • چگونه پارامترهای intent داخلی به اطلاعات ارائه شده توسط کاربر به Assistant نگاشت می‌شوند؟

سپس اکتیویتی اندروید شما، نیت یا لینک عمیق اندروید ارائه شده را فیلتر و مدیریت می‌کند تا عملکرد مورد نظر کاربر را ارائه دهد. نتیجه، یک تجربه کاربری است که در آن دستیار، عملکرد برنامه شما را در پاسخ به درخواست کاربر فراخوانی می‌کند.

۳. محیط توسعه خود را آماده کنید

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

فایل‌های پایه خود را دانلود کنید

دستور زیر را برای کپی کردن مخزن گیت‌هاب برنامه نمونه اجرا کنید:

git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git

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

  1. در پنجره‌ی «به اندروید استودیو خوش آمدید» ، روی «وارد کردن پروژه» کلیک کنید.
  2. پوشه‌ای را که مخزن را در آن کلون کرده‌اید، پیدا کرده و انتخاب کنید.

برای دیدن نسخه‌ای از برنامه که نشان‌دهنده‌ی codelab تکمیل‌شده است، مخزن برنامه‌ی نمونه را با استفاده از پرچم --branch master کپی کنید.

به‌روزرسانی شناسه برنامه اندروید

به‌روزرسانی شناسه برنامه، برنامه را به‌طور منحصربه‌فرد روی دستگاه آزمایشی شما شناسایی می‌کند و در صورت آپلود برنامه در کنسول Play، از خطای "نام بسته تکراری" جلوگیری می‌کند. برای به‌روزرسانی شناسه برنامه، app/build.gradle را باز کنید:

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

عبارت "MYUNIQUENAME" را در فیلد applicationId با چیزی که مختص خودتان باشد جایگزین کنید.

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

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

  1. در اندروید استودیو، گزینه Run > Run app را انتخاب کنید یا روی Run کلیک کنید. در نوار ابزار.
  2. در پنجره‌ی «انتخاب هدف استقرار» ، دستگاهی را انتخاب کرده و روی «تأیید» کلیک کنید. نسخه‌ی سیستم عامل پیشنهادی، اندروید ۱۰ (سطح API 30) یا بالاتر است، اگرچه «اقدامات» روی دستگاه‌هایی با اندروید ۵ (سطح API 21) نیز اجرا می‌شوند.
  3. برای تنظیم دستیار و تأیید عملکرد آن، دکمه صفحه اصلی را فشار داده و نگه دارید. اگر قبلاً وارد دستیار در دستگاه خود نشده‌اید، باید وارد آن شوید.

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

انیمیشنی که نمونه برنامه لیست Todo را نشان می‌دهد

شکل ۳. انیمیشنی که برنامه نمونه فهرست کارها را نشان می‌دهد.

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

افزونه تست را نصب کنید

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

  1. به مسیر File > Settings (در MacOS ، اندروید استودیو > Preferences ) بروید.
  2. در بخش افزونه‌ها، به بازار بروید و «دستیار گوگل» را جستجو کنید. همچنین می‌توانید ابزار تست را به صورت دستی دانلود و نصب کنید.
  3. ابزار را نصب کنید و اندروید استودیو را مجدداً راه اندازی کنید.

۴. قابلیت Get Thing BII را اضافه کنید

actions.intent.GET_THING BII قابلیت جستجوی درون‌برنامه‌ای شما را به دستیار گوگل (Google Assistant) گسترش می‌دهد. در این مرحله، شما GET_THING BII را پیاده‌سازی و آزمایش خواهید کرد و به کاربران امکان می‌دهد تا وظایف خاصی را در برنامه نمونه جستجو کنند.

تعریف قابلیت Get Thing

در طول یک اقدام برنامه مرتبط با جستجو، دستیار عبارات جستجو را از پرس و جوی کاربر استخراج کرده و در پارامتر thing.name BII قرار می‌دهد، سپس آن مقدار را به برنامه اندروید منتقل می‌کند.

برای افزودن GET_THING BII به برنامه خود، shortcuts.xml که در دایرکتوری پروژه نمونه app/src/main/res/xml قرار دارد، با یک عنصر <capability> در تگ سطح بالای <shortcuts> به‌روزرسانی کنید:

میانبرها.xml 

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

پیکربندی بالا:

  1. اعلام می‌کند که برنامه به GET_THING BII پاسخ می‌دهد.
  2. نحوه ساخت یک هدف اندروید که برنامه را در پاسخ به آن BII اجرا می‌کند، مشخص می‌کند.
    • این فعالیت با استفاده از targetPackage و targetClass شناسایی می‌شود.
    • پارامتر BII thing.name در Intent Extra با نام q نگاشت شده است.

اکتیویتی نامگذاری شده باید در مانیفست برنامه موجود باشد و صادر شود.

برنامه اندروید ارائه شده حاوی فراداده است، بنابراین AndroidManifest از فایل shortcuts.xml آگاه است:

<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

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

برای آزمایش جستجوی درون‌برنامه‌ای برنامه‌تان از طریق دستیار گوگل، این مراحل را دنبال کنید:

  1. مطمئن شوید که دستگاه اندروید شما متصل است.
  2. به ابزارها > دستیار گوگل > ابزار تست عملکردهای برنامه بروید.
  3. برای پذیرش مقادیر پیش‌فرض برای نام برنامه و زبان ، روی «ایجاد پیش‌نمایش» کلیک کنید. در صورت درخواست، خط‌مشی‌ها و شرایط خدمات «عملکردهای برنامه» را مرور و بپذیرید.
  4. در اولین مرحله که ابزار از شما می‌خواهد یک BII انتخاب و پیکربندی کنید، actions.intent.GET_THING را انتخاب کنید. مقدار name را از running shoes به milk تغییر دهید.
  5. روی اجرای اکشن برنامه کلیک کنید.

در این تست، GET_THING BII از ویژگی name برای جستجوی برنامه برای وظایفی که شامل "شیر" هستند استفاده می‌کند. مانند App Action قبلی، می‌توانید عملکرد خود را با استفاده از ابزار تست آزمایش کنید، یا به سادگی بگویید "هی گوگل، در لیست وظایف، پودر کیک را جستجو کن" یا سایر عبارات جستجو را در دستگاه تست خود انجام دهید.

۵. قابلیت BII مربوط به Open app را اضافه کنید

در این مرحله، شما قابلیت Open app BII را پیاده‌سازی می‌کنید و به کاربران این امکان را می‌دهید که وظایف فعال و تکمیل‌شده خود را با استفاده از Assistant مشاهده کنند. برای انجام این کار، قابلیت موجود در shortcuts.xml را که حاوی اطلاعاتی در مورد نحوه فعال شدن این قابلیت، نحوه ارسال پارامترها و فراخوانی کدام intentهای اندروید است، تکمیل کنید. برای این codelab، از OPEN_APP_FEATURE BII استفاده خواهید کرد. پس از پیاده‌سازی این BII، اکشن را روی دستگاه خود آزمایش می‌کنید.

قابلیت ویژگی Open app را اضافه کنید

یک قابلیت دوم برای ویژگی Open app در shortcuts.xml زیر عنصر Get Thing Capability اضافه کنید:

میانبرها.xml 

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

این قابلیت، ویژگی Open app BII و Android intent را با هم نگاشت می‌کند، بنابراین وقتی ویژگی Open app فعال می‌شود، Android intent نیز فعال می‌شود.

قبل از فعال‌سازی هدف اندروید، پارامترهای پشتیبانی‌شده از ورودی کاربر دریافت می‌شوند. OPEN_APP_FEATURE BII از یک پارامتر، feature ، پشتیبانی می‌کند که نشان‌دهنده ویژگی برنامه استخراج‌شده از پرس‌وجوی کاربر است. دو نوع ویژگی وجود دارد که این برنامه پشتیبانی می‌کند: Active Task و Completed Task. این ویژگی‌ها به کاربران اجازه می‌دهند برنامه را با نمای فیلترشده‌ای از لیست وظایف خود باز کنند. برای پشتیبانی از این ویژگی‌ها باید از inline inventory استفاده کنید.

پارامترهای هدف را با استفاده از موجودی درون خطی مدیریت کنید

پارامترهای Intent عناصر استخراج شده از یک پرس و جوی کاربر را نشان می‌دهند. برای مثال، اگر کاربری چیزی شبیه به این بگوید: «سلام گوگل، از ExampleApp پیتزا سفارش بده»، Assistant کلمه «pizza» را در یک پارامتر intent از schema.org food.item می‌کند و پارامتر را برای مدیریت به اکشن شما ارسال می‌کند.

ویژگی Open app feature BII از یک پارامتر feature پشتیبانی می‌کند که نشان‌دهنده ویژگی برنامه استخراج شده از پرس‌وجوی کاربر است. برای این پارامتر، یک فهرست درون‌خطی مورد نیاز است که مجموعه‌ای از نام‌های ویژگی‌های برنامه پشتیبانی‌شده را برای تطبیق با مقدار پارامتر در اختیار Assistant قرار می‌دهد.

برای مدیریت پارامتر feature intent، یک میانبر به shortcuts.xml خود با کد زیر بالای قابلیت ویژگی Open app اضافه کنید:

میانبرها.xml 

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

در کد بالا، شما یک فهرست موجودی درون‌خطی تعریف کردید که به صورت عناصر shortcut با قابلیت‌ها و اتصال‌های پارامتر نمایش داده می‌شود. میانبرها می‌توانند به عنوان فهرست موجودی برای پارامترهای BII استفاده شوند. دستیار گوگل، کوئری کاربر را با مقادیر موجود در اتصال پارامتر Shortcuts مطابقت می‌دهد. برای یک مقدار پارامتر منطبق، shortcutId به قصد انجام اضافه می‌شود. هنگامی که کاربر OPEN_APP_FEATURE BII را با یک درخواست فعال می‌کند، دستیار مقدار پارامتر ویژگی را با ویژگی value یک میانبر مطابقت می‌دهد و مقدار را به عنوان parameter در Extra به targetClass ارسال می‌کند.

برای مثال، اگر کاربری چیزی شبیه به این بگوید: «سلام گوگل، وظایف تکمیل‌شده‌ی من را در ExampleApp نشان بده»، دستیار مقدار پارامتر هدف ویژگی، یعنی «وظایف تکمیل‌شده»، را با میانبر موجودی مربوطه مطابقت می‌دهد، که آن مقدار را به قابلیت OPEN_APP_FEATURE منتقل می‌کند. سپس دستیار، هدف اندروید را فعال می‌کند.

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

در طول توسعه و آزمایش، شما از افزونه Google Assistant برای پیش‌نمایش App Action خود با Assistant در یک دستگاه آزمایشی استفاده می‌کنید. همچنین می‌توانید از این ابزار برای تنظیم پارامترهای intent برای یک App Action استفاده کنید تا بررسی کنید که چگونه Action شما روش‌های مختلفی را که کاربر ممکن است از Assistant بخواهد آن را اجرا کند، مدیریت می‌کند.

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

  1. دستگاه تست اندروید فیزیکی خود را متصل کنید، یا شبیه‌ساز اندروید خود را اجرا کنید
  2. اگر ابزار تست قابل مشاهده نیست، با رفتن به Tools > Google Assistant > App Actions Test Tool آن را باز کنید.
  3. برای به‌روزرسانی پیش‌نمایش، روی دکمه‌ی به‌روزرسانی کلیک کنید.
  4. در اولین مرحله که ابزار از شما می‌خواهد یک BII انتخاب و پیکربندی کنید، actions.intent.OPEN_APP_FEATURE را انتخاب کنید.
  5. در کادر ویژگی ، مقدار پیش‌فرض History را با Completed tasks به‌روزرسانی کنید.
  6. روی اجرای اکشن برنامه کلیک کنید.

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

۶. مراحل بعدی

تبریک می‌گویم!

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

آنچه ما پوشش داده‌ایم

در این آزمایشگاه کد، شما یاد گرفتید:

  • چگونه به کاربران اجازه دهیم با استفاده از دستیار گوگل (Assistant) به ویژگی‌های خاص برنامه دسترسی عمیق پیدا کنند.
  • چگونه کاربران می‌توانند از طریق دستیار گوگل به جستجوی درون‌برنامه‌ای دسترسی داشته باشند.
  • نحوه آزمایش BII های رایج با استفاده از افزونه دستیار گوگل .

قدم بعدی چیست؟

از اینجا، می‌توانید اصلاحات بیشتری را در برنامه‌ی لیست کارهایتان انجام دهید. برای ارجاع به پروژه‌ی تکمیل‌شده، به شاخه‌ی repo –master در گیت‌هاب مراجعه کنید.

در اینجا چند پیشنهاد برای یادگیری بیشتر در مورد گسترش این برنامه با App Actions ارائه شده است:

برای ادامه سفر «اقدامات در گوگل» خود، این منابع را بررسی کنید:

برای اطلاع از آخرین اطلاعیه‌های ما، ما را در توییتر با شناسه @ActionsOnGoogle دنبال کنید و برای به اشتراک گذاشتن ساخته‌هایتان، به #AoGDevs توییت کنید!

نظرسنجی بازخورد

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