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

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

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

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

در این کد لبه، می‌آموزید که چگونه با استفاده از BII از دسته BII "معمول" ، که تقریباً هر برنامه اندرویدی می‌تواند انجام دهد، اقدامات برنامه را به برنامه اضافه کنید.

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

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

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

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

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

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

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

پیش نیازها

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

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

2. درک کنید که چگونه کار می کند

App Actions کاربران را از دستیار Google به برنامه Android شما متصل می کند. اما چگونه کار می کنند؟

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

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

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

جریانی که نحوه پردازش درخواست صوتی کاربر توسط «دستیار Google» را توضیح می‌دهد. شکل 2. جریانی که چگونه دستیار Google یک درخواست صوتی را پردازش می کند.

فایل پروژه shortcuts.xml حاوی اطلاعات زیر برای هر App Action است:

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

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

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

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

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

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

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

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

  1. در گفتگوی خوش آمدید به Android Studio ، روی وارد کردن پروژه کلیک کنید.
  2. پوشه ای را که مخزن را در آن کلون کرده اید، پیدا کرده و انتخاب کنید.

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

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

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

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

"MYUNIQUENAME" را در قسمت applicationId با چیزی منحصر به فرد برای خود جایگزین کنید.

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

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

  1. در Android Studio، Run > Run app را انتخاب کنید یا روی Run کلیک کنید در نوار ابزار
  2. در گفتگوی Select Deployment Target ، یک دستگاه را انتخاب کنید و روی OK کلیک کنید. نسخه سیستم عامل پیشنهادی Android 10 (سطح API 30) یا بالاتر است، اگرچه Actions در دستگاه‌هایی به Android 5 (سطح API 21) اجرا می‌شود.
  3. برای راه‌اندازی «دستیار» و تأیید عملکرد آن، دکمه «صفحه اصلی » را طولانی فشار دهید. اگر قبلاً این کار را نکرده‌اید، باید در دستگاه خود وارد «دستیار» شوید.

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

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

شکل 3. انیمیشنی که برنامه نمونه لیست کارها را نشان می دهد.

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

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

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

  1. به File > Settings ( Android Studio > Preferences در MacOS) بروید.
  2. در بخش Plugins، به Marketplace بروید و "دستیار Google" را جستجو کنید. همچنین می توانید ابزار تست را به صورت دستی دانلود و نصب کنید.
  3. ابزار را نصب کنید و اندروید استودیو را مجددا راه اندازی کنید.

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

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

قابلیت Get Thing را تعریف کنید

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

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

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. نحوه ساخت یک intent Android را مشخص می کند که برنامه را در پاسخ به آن BII راه اندازی می کند.
    • فعالیت با استفاده از targetPackage و targetClass شناسایی می شود.
    • پارامتر BII thing.name در Intent Extra با نام q نگاشت می شود.

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

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

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

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

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

  1. مطمئن شوید که دستگاه اندرویدی شما متصل است.
  2. به Tools > Google Assistant > App Actions Test Tool بروید.
  3. روی ایجاد پیش‌نمایش کلیک کنید تا مقادیر پیش‌فرض نام و منطقه برنامه را بپذیرید. در صورت درخواست، خط‌مشی‌ها و شرایط خدمات App Actions را بررسی کرده و بپذیرید.
  4. در مرحله اول که ابزار از شما می خواهد یک BII را انتخاب و پیکربندی کنید، actions.intent.GET_THING را انتخاب کنید. مقدار name از running shoes به milk تغییر دهید.
  5. روی Run App Action کلیک کنید.

در این آزمایش، GET_THING BII از ویژگی name برای جستجوی برنامه برای کارهای حاوی "شیر" استفاده می کند. مانند برنامه قبلی، می‌توانید عملکرد خود را با استفاده از ابزار تست آزمایش کنید، یا به سادگی بگویید «Hey Google, cake mix in Task List را جستجو کن» یا عبارت‌های جستجوی دیگر را در دستگاه آزمایشی خود بگویید.

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

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

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

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

shortcuts.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 فعال می شود.

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

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

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

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

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

shortcuts.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 استفاده کرد. دستیار گوگل پرس و جوی کاربر را با مقادیر موجود در اتصال پارامتر میانبرها مطابقت می دهد. برای یک مقدار پارامتر منطبق، shortcutId به هدف تحقق اضافه خواهد شد. وقتی کاربر OPEN_APP_FEATURE BII را با درخواستی فعال می کند، دستیار مقدار پارامتر ویژگی را با ویژگی مقدار یک میانبر مطابقت می دهد و مقدار را به targetClass به عنوان parameter در Extra ارسال می کند.

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

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

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

برای آزمایش App Action با ابزار تست، این مراحل را دنبال کنید:

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

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

6. مراحل بعدی

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

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

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

در این کد لبه یاد گرفتید:

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

بعدش چی

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

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

برای ادامه سفر Actions on Google، این منابع را کاوش کنید:

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

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

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