ابزارک های اندروید را با دستیار گوگل ادغام کنید

۱. مرور کلی

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

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

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

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

در این آزمایشگاه کد، یاد می‌گیرید که چگونه ویجت‌های اندروید را برای انجام درخواست‌های کاربر دستیار گوگل (Assistant) برگردانید. همچنین یاد می‌گیرید که:

• پارامترهای BII کاربر برای شخصی‌سازی ابزارک‌ها.
• برای ابزارک‌هایتان، در دستیار، مقدمه‌های متن به گفتار (TTS) ارائه دهید.
• از مرجع intent داخلی برای تعیین اینکه کدام BII ها از تکمیل ویجت پشتیبانی می‌کنند، استفاده کنید.

نکته: BII های واجد شرایط در مرجع Built-in intent شامل بخشی با عنوان "ویجت ها و برش های اندروید" هستند.

پیش‌نیازها

قبل از ادامه، مطمئن شوید که محیط توسعه شما برای توسعه App Actions آماده است. این محیط باید موارد زیر را داشته باشد:

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

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

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

دستیار گوگل از درک زبان طبیعی (NLU) برای خواندن درخواست کاربر و مطابقت آن با یک هدف (Intent) داخلی دستیار (BII) استفاده می‌کند. سپس دستیار، هدف را به قابلیتی (که BII را پیاده‌سازی می‌کند) نگاشت می‌کند، که شما برای آن هدف در برنامه خود ثبت می‌کنید. در نهایت، دستیار با نمایش ویجت اندرویدی که برنامه شما با استفاده از جزئیات موجود در قابلیت تولید می‌کند، درخواست کاربر را برآورده می‌کند.

در این آزمایشگاه کد، شما قابلیتی را تعریف می‌کنید که پشتیبانی از GET_EXERCISE_OBSERVATION BII را ثبت می‌کند. در این قابلیت، شما به دستیار دستور می‌دهید که یک اینتنت اندروید برای کلاس ویجت FitActions ایجاد کند تا درخواست‌های مربوط به این BII را انجام دهد. شما این کلاس را به‌روزرسانی می‌کنید تا یک ویجت شخصی‌سازی‌شده برای دستیار ایجاد شود تا به کاربر نمایش داده شود و یک مقدمه TTS برای دستیار ایجاد شود تا اعلام شود.

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

ویجت FitActions

برنامه نمونه FitActions شامل یک ویجت اطلاعات تمرین است که کاربران می‌توانند به صفحه اصلی خود اضافه کنند. این ویجت کاندیدای بسیار خوبی برای انجام درخواست‌های کاربر است که GET_EXERCISE_OBSERVATION BII را فعال می‌کند.

نحوه کار ویجت

وقتی کاربر یک ویجت به صفحه اصلی اضافه می‌کند، ویجت به Broadcast Receiver دستگاه پینگ می‌دهد. این سرویس اطلاعات مربوط به ویجت را از تعریف گیرنده ویجت در منبع AndroidManifest.xml برنامه بازیابی می‌کند. از این اطلاعات برای تولید یک شیء RemoteViews که نمایانگر ویجت است استفاده می‌کند.

برنامه نمونه، widgets.StatsWidgetProvider گیرنده را تعریف می‌کند که مربوط به کلاس StatsWidgetProvider است:

<!-- app/src/main/AndroidManifest.xml -->

<receiver
  android:name=".widgets.StatsWidgetProvider"
  android:exported="false">
  <intent-filter>
    <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
  </intent-filter>
  <meta-data
    android:name="android.appwidget.provider"
    android:resource="@xml/stats_widget" />
</receiver>

کلاس StatsWidgetProvider ، StatsWidgetProvider.kt ، جریان‌های ایجاد شیء StatsWidget را مدیریت می‌کند. این کلاس این مسئولیت‌ها را بر عهده دارد:

• ایجاد نمونه‌های ویجت و پر کردن آنها با داده‌های تمرین از پایگاه داده برنامه.
• قالب‌بندی داده‌های تمرین برای خوانایی بیشتر، با formatDataAndSetWidget() .
• ارائه مقادیر پیش‌فرض در صورت عدم دسترسی به داده‌های تمرین، با استفاده از setNoActivityDataWidget() .

پشتیبانی دستیار را اضافه کنید

در این آزمایشگاه کد، شما برنامه نمونه را برای مدیریت قابلیت App Actions به‌روزرسانی می‌کنید. این تغییرات شامل موارد زیر است:

1. پیکربندی قابلیت GET_EXERCISE_OBSERVATION BII برای بازگرداندن نمونه‌ای از شیء StatsWidget .
2. به‌روزرسانی کلاس StatsWidget برای استفاده از ویژگی‌های App Actions مانند:
   • با استفاده از پارامترهای BII، به کاربران اجازه می‌دهد تا با پرسیدن چیزهایی مانند «سلام گوگل، آمار دویدن من را در ExampleApp نشان بده» آمار تمرینات خاص را مشاهده کنند.
   • ارائه رشته‌های مقدماتی TTS.
   • مدیریت موارد خاص، مانند زمانی که پرس و جوی کاربر شامل پارامتر نوع تمرین نمی‌شود.

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

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

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

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

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

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

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

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

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

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

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

توجه : پس از به‌روزرسانی applicationId ، در اندروید استودیو با هشدار «فایل‌های Gradle از آخرین همگام‌سازی پروژه تغییر کرده‌اند...» مواجه خواهید شد. برای جلوگیری از بروز مشکل هنگام آپلود برنامه، روی Sync Now کلیک کنید.

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

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

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

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

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

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

1. در اندروید استودیو، دستگاه فیزیکی یا مجازی خود را انتخاب کنید و Run > Run app را انتخاب کنید یا روی Run کلیک کنید. در نوار ابزار.
2. برای تنظیم دستیار و تأیید صحت عملکرد آن، دکمه صفحه اصلی را فشار داده و نگه دارید. اگر قبلاً وارد دستیار در دستگاه خود نشده‌اید، باید وارد آن شوید.

توجه : نسخه سیستم عامل پیشنهادی اندروید ۱۰ (سطح API 30) یا بالاتر است، اگرچه App Actions روی دستگاه‌هایی با اندروید ۵ (سطح API 21) نیز کار می‌کند.

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

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

ویجت موجود را امتحان کنید

1. برای رفتن به صفحه اصلی دستگاه آزمایشی خود، روی دکمه صفحه اصلی ضربه بزنید.
2. روی یک فضای خالی از صفحه اصلی لمس طولانی کنید و گزینه Widgets را انتخاب کنید.
3. در فهرست ابزارک‌ها به پایین اسکرول کنید تا به FitActions برسید.
4. روی آیکون FitActions انگشت خود را نگه دارید و ویجت آن را روی صفحه اصلی قرار دهید.

۴. اکشن برنامه را اضافه کنید

در این مرحله، قابلیت GET_EXERCISE_OBSERVATION BII را اضافه می‌کنید. این کار را با اضافه کردن یک عنصر capability جدید در shortcuts.xml انجام می‌دهید. این قابلیت نحوه‌ی فعال شدن قابلیت، نحوه‌ی استفاده از پارامترهای BII و اینکه کدام intentهای اندروید برای انجام درخواست فراخوانی شوند را مشخص می‌کند.

1. یک عنصر capability جدید با این پیکربندی به منبع پروژه نمونه shortcuts.xml اضافه کنید:

   <!-- fitnessactions/app/src/main/res/xml/shortcuts.xml -->
   
   <capability android:name="actions.intent.GET_EXERCISE_OBSERVATION">
     <app-widget
       android:identifier="GET_EXERCISE_OBSERVATION"
       android:targetClass="com.devrel.android.fitactions.widgets.StatsWidgetProvider"
       android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE">
       <parameter
         android:name="exerciseObservation.aboutExercise.name"
         android:key="aboutExerciseName"
         android:required="true">
       </parameter>
       <extra android:name="hasTts" android:value="true"/>
     </app-widget>
     <!-- Add Fallback Intent-->
   </capability>
   

   مقدار android:targetPackage ، یعنی PUT_YOUR_APPLICATION_ID_HERE با applicationId منحصر به فرد خود جایگزین کنید.

این قابلیت، GET_EXERCISE_OBSERVATION BII را به app-widget intent نگاشت می‌کند، به طوری که وقتی BII فعال می‌شود، ویجت نمونه‌سازی شده و به کاربر نمایش داده می‌شود.

قبل از فعال‌سازی ویجت، دستیار پارامترهای پشتیبانی‌شده‌ی BII را از پرس‌وجوی کاربر استخراج می‌کند. این آزمایشگاه کد به پارامتر BII به نام exerciseObservation.aboutExercise.name نیاز دارد که نشان‌دهنده‌ی نوع تمرین درخواستی کاربر است. این برنامه از سه نوع تمرین پشتیبانی می‌کند: «دویدن»، «پیاده‌روی» و «دوچرخه‌سواری». شما یک فهرست درون‌خطی ارائه می‌دهید تا دستیار را از این مقادیر پشتیبانی‌شده مطلع کنید.

2. با اضافه کردن این پیکربندی، بالاتر از قابلیت GET_EXERCISE_OBSERVATION ، به shortcuts.xml ، این عناصر موجودی را تعریف کنید:

   <!-- shortcuts.xml -->
   
   <!-- shortcuts are bound to the GET_EXERCISE_OBSERVATION capability and
        represent the types of exercises supported by the app. -->
   
   <shortcut
     android:shortcutId="running"
     android:shortcutShortLabel="@string/activity_running">
     <capability-binding android:key="actions.intent.GET_EXERCISE_OBSERVATION">
       <parameter-binding
         android:key="exerciseObservation.aboutExercise.name"
         android:value="@array/runningSynonyms"/>
     </capability-binding>
   </shortcut>
   
   <shortcut
     android:shortcutId="walking"
     android:shortcutShortLabel="@string/activity_walking">
     <capability-binding android:key="actions.intent.GET_EXERCISE_OBSERVATION">
       <parameter-binding
         android:key="exerciseObservation.aboutExercise.name"
         android:value="@array/walkingSynonyms"/>
     </capability-binding>
   </shortcut>
   
   <shortcut
     android:shortcutId="cycling"
     android:shortcutShortLabel="@string/activity_cycling">
     <capability-binding android:key="actions.intent.GET_EXERCISE_OBSERVATION">
       <parameter-binding
         android:key="exerciseObservation.aboutExercise.name"
         android:value="@array/cyclingSynonyms"/>
     </capability-binding>
   </shortcut>
   
   <capability android:name="actions.intent.GET_EXERCISE_OBSERVATION">
     <!-- ... -->
   </capability>
   

یک هدف جایگزین اضافه کنید

فال‌بک اینتنت‌ها موقعیت‌هایی را مدیریت می‌کنند که در آن‌ها یک کوئری کاربر به دلیل فقدان پارامترهای مورد نیاز قابلیت، قابل انجام نیست. قابلیت GET_EXERCISE_OBSERVATION به پارامتر exerciseObservation.aboutExercise.name نیاز دارد که با ویژگی android:required="true" مشخص شده است. برای این موقعیت‌ها، اسیستنت از شما می‌خواهد که یک فال‌بک اینتنت تعریف کنید تا درخواست با موفقیت انجام شود، حتی اگر هیچ پارامتری در کوئری ارائه نشده باشد.

1. در shortcuts.xml ، با استفاده از این پیکربندی، یک intent پشتیبان به قابلیت GET_EXERCISE_OBSERVATION اضافه کنید:

   <!-- shortcuts.xml -->
   
   <capability android:name="actions.intent.GET_EXERCISE_OBSERVATION">
   
     <app-widget>
       <!-- ... -->
     </app-widget>
   
     <!-- Fallback intent with no parameters needed to successfully execute.-->
     <intent
       android:identifier="GET_EXERCISE_OBSERVATION_FALLBACK"
       android:action="android.intent.action.VIEW"
       android:targetClass="com.devrel.android.fitactions.widgets.StatsWidgetProvider">
     </intent>
   </capability>
   

در این پیکربندی نمونه، اجرای fallback یک intent اندروید است که هیچ پارامتری در داده‌های Extra آن وجود ندارد.

نکته : در این مثال، عنصر fallback intent بعد از تگ app-widget فهرست شده است، زیرا این عنصر، تابع catch all برای BII است که برای موفقیت به پارامتر نیاز ندارد. برای مثال، اگر کاربر بپرسد: «سلام گوگل، آمار من را در ExampleApp نشان بده» این تابع فعال می‌شود.

۵. ویجت دستیار را فعال کنید

با ایجاد قابلیت GET_EXERCISE_OBSERVATION ، کلاس ویجت را به‌روزرسانی کنید تا از فراخوانی صوتی App Actions پشتیبانی کند.

کتابخانه افزونه‌های ویجت‌ها را اضافه کنید

کتابخانه افزونه App Actions Widgets، ویجت‌های شما را برای تجربه‌های دستیار صوتی بهبود می‌بخشد. به طور خاص، این کتابخانه به شما امکان می‌دهد یک مقدمه TTS سفارشی برای ویجت‌های خود ارائه دهید.

1. وابستگی کتابخانه Widgets Extension را به منبع نمونه app /app/build.gradle اضافه کنید:

   // app/build.gradle
   
   dependencies {
     //...
     implementation "com.google.assistant.appactions:widgets:0.0.1"
   }
   

   در کادر هشداری که در اندروید استودیو ظاهر می‌شود، روی Sync Now کلیک کنید. همگام‌سازی پس از هر تغییر build.gradle به شما کمک می‌کند تا هنگام ساخت برنامه از خطاها جلوگیری کنید.

سرویس ویجت را اضافه کنید

سرویس یک جزء برنامه است که می‌تواند عملیات طولانی مدت را در پس‌زمینه انجام دهد. برنامه شما برای پردازش درخواست‌های ویجت نیاز به ارائه سرویس دارد.

1. یک سرویس با این پیکربندی به منبع AndroidManifest.xml برنامه نمونه اضافه کنید:

   <!-- AndroidManifest.xml -->
   <service
      android:name=".widgets.StatsWidgetProvider"
      android:enabled="true"
      android:exported="true">
      <intent-filter>
          <action
              android:name="com.google.assistant.appactions.widgets.PIN_APP_WIDGET" />
      </intent-filter>
   </service>
   
   

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

کلاس ویجت را به‌روزرسانی کنید

اکنون برنامه شما طوری پیکربندی شده است که درخواست‌های قابلیت GET_EXERCISE_OBSERVATION را به کلاس ویجت شما هدایت کند. در مرحله بعد، کلاس StatsWidget.kt را به‌روزرسانی کنید تا یک نمونه ویجت ایجاد شود که با استفاده از مقادیر پارامتر BII، متناسب با درخواست کاربر شخصی‌سازی شده باشد.

1. کلاس StatsWidget.kt را باز کنید و کتابخانه App Actions Widget Extension را وارد کنید:

   // StatsWidget.kt
   
   // ... Other import statements
   import com.google.assistant.appactions.widgets.AppActionsWidgetExtension
   
   

2. این متغیرهای خصوصی را که هنگام تعیین اطلاعاتی که باید ویجت را پر کنند، استفاده می‌کنید، اضافه کنید:

   // StatsWidget.kt
   
   private val hasBii: Boolean
   private val isFallbackIntent: Boolean
   private val aboutExerciseName: String
   private val exerciseType: FitActivity.Type
   

3. تابع init را اضافه کنید تا به کلاس اجازه دهید از داده‌های گزینه‌های ویجت ارسالی از Assistant استفاده کند:

   // StatsWidget.kt
   
   init {
     val optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId)
     val bii = optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII)
     hasBii = !bii.isNullOrBlank()
     val params = optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS)
   
     if (params != null) {
       isFallbackIntent = params.isEmpty
       if (isFallbackIntent) {
         aboutExerciseName = context.resources.getString(R.string.activity_unknown)
       } else {
           aboutExerciseName = params.get("aboutExerciseName") as String
         }
     } else {
         isFallbackIntent = false
         aboutExerciseName = context.resources.getString(R.string.activity_unknown)
     }
     exerciseType = FitActivity.Type.find(aboutExerciseName)
   }
   
   

بیایید بررسی کنیم که چگونه این به‌روزرسانی‌ها کلاس StatsWidget.kt را قادر می‌سازند تا به intentهای اندروید تولید شده توسط قابلیت GET_EXERCISE_OBSERVATION پاسخ دهد:

• optionsBundle = بسته نرم‌افزاری
  • بسته‌ها (Bundles) اشیایی هستند که برای استفاده در مرزهای فرآیند، بین فعالیت‌های دارای intent و ذخیره حالت گذرا در طول تغییرات پیکربندی در نظر گرفته شده‌اند. دستیار از اشیاء Bundle برای انتقال داده‌های پیکربندی به ویجت استفاده می‌کند.
• bii = actions.intent.GET_EXERCISE_OBSERVATION
  • نام BII با استفاده از AppActionsWidgetExtension از Bundle قابل دسترسی است.
• hasBii = true
  • بررسی می‌کند که آیا BII وجود دارد یا خیر.
• params = Bundle[{aboutExerciseName=running}]
  • یک Bundle ویژه که توسط App Actions تولید شده است، درون Bundle گزینه‌های ویجت قرار دارد. این Bundle شامل جفت‌های کلید/مقدار BII است. در این مورد، مقدار running از عبارت مثال "Hey Google, show my running stats on ExampleApp" استخراج شده است.
• isFallbackIntent = false
  • وجود پارامترهای مورد نیاز BII را در Intent Extras بررسی می‌کند.
• aboutExerciseName = running
  • مقدار Extras مربوط به intent را برای aboutExerciseName برمی‌گرداند.
• exerciseType = RUNNING
  • aboutExerciseName برای جستجوی شیء نوع پایگاه داده مربوطه استفاده می‌کند.

اکنون که کلاس StatsWidget می‌تواند داده‌های ورودی App Actions مربوط به اینتنت اندروید را پردازش کند، منطق جریان ایجاد ویجت را به‌روزرسانی کنید تا بررسی شود که آیا ویجت توسط یک App Action فعال شده است یا خیر.

4. در StatsWidget.kt ، تابع updateAppWidget() را با این کد جایگزین کنید:

   // StatsWidget.kt
   
   fun updateAppWidget() {
      /**
       * Checks for App Actions BII invocation and if BII parameter data is present.
       * If parameter data is missing, use data from last exercise recorded to the
       *  fitness tracking database.
       */
      if (hasBii && !isFallbackIntent) {
          observeAndUpdateRequestedExercise()
      } else observeAndUpdateLastExercise()
   }
   
   

کد قبلی به یک تابع جدید به نام observeAndUpdateRequestedExercise اشاره دارد. این تابع با استفاده از داده‌های پارامتر exerciseType که توسط App Actions Android intent ارسال می‌شود، داده‌های ویجت را تولید می‌کند.

5. تابع observeAndUpdateRequestedExercise را با این کد اضافه کنید:

   // StatsWidget.kt
   
   /**
   * Create and observe the last exerciseType activity LiveData.
   */
   private fun observeAndUpdateRequestedExercise() {
     val activityData = repository.getLastActivities(1, exerciseType)
   
      activityData.observeOnce { activitiesStat ->
          if (activitiesStat.isNotEmpty()) {
              formatDataAndSetWidget(activitiesStat[0])
              updateWidget()
          } else {
              setNoActivityDataWidget()
              updateWidget()
          }
      }
   }
   
   

در کد قبلی، از یک کلاس repository موجود در برنامه برای بازیابی داده‌های تناسب اندام از پایگاه داده محلی برنامه استفاده کنید. این کلاس یک API ارائه می‌دهد که دسترسی به پایگاه داده را ساده می‌کند. این repository با نمایش یک شیء LiveData هنگام انجام پرس و جوها در پایگاه داده کار می‌کند. در کد خود، این LiveData برای بازیابی آخرین فعالیت تناسب اندام مشاهده می‌کنید.

نکته : LiveData یک کلاس نگهدارنده داده observable است. برخلاف یک observable معمولی، LiveData از چرخه حیات آگاه است، به این معنی که به چرخه حیات سایر اجزای برنامه، مانند فعالیت‌ها، قطعات یا سرویس‌ها احترام می‌گذارد. این آگاهی تضمین می‌کند که LiveData فقط ناظرهای اجزای برنامه را که در حالت چرخه حیات فعال هستند، به‌روزرسانی می‌کند. برای این codelab ما از یک ناظر یکبار مصرف استفاده می‌کنیم.

فعال کردن TTS

شما می‌توانید یک رشته TTS برای دستیار فراهم کنید تا هنگام نمایش ویجت شما اعلام کند. توصیه می‌کنیم این را برای ارائه زمینه شنیداری به ویجت‌های خود اضافه کنید. این قابلیت توسط کتابخانه App Actions Widgets Extension ارائه می‌شود که به شما امکان می‌دهد متن و مقدمه‌های TTS را که همراه با ویجت‌های شما در دستیار هستند، تنظیم کنید.

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

1. در StatsWidget.kt ، این کد را به تابع formatDataAndSetWidget اضافه کنید:

   // StatsWidget.kt
   
   private fun formatDataAndSetWidget(
     activityStat: FitActivity,
   ) {
         // ...
   
         // Add conditional for hasBii for widget with data
         if (hasBii) {
            // Formats TTS speech and display text for Assistant
            val speechText = context.getString(
                R.string.widget_activity_speech,
                activityExerciseTypeFormatted,
                formattedDate,
                durationInMin,
                distanceInKm
            )
            val displayText = context.getString(
                R.string.widget_activity_text,
                activityExerciseTypeFormatted,
                formattedDate
            )
            setTts(speechText, displayText)
         }
   }
   
   

کد قبلی به دو منبع رشته‌ای اشاره می‌کند: یکی برای گفتار و دیگری برای متن. برای توصیه‌های TTS ، بخش توصیه به سبک متن به گفتار ویدیوی ویجت‌های ما را بررسی کنید. این نمونه همچنین به setTts ، یک تابع جدید که اطلاعات TTS را در اختیار نمونه ویجت قرار می‌دهد، اشاره دارد.

2. با استفاده از این کد، تابع setTts جدید را به StatsWidget.kt اضافه کنید:

   // StatsWidget.kt
   
   /**
    * Sets TTS to widget
    */
   private fun setTts(
     speechText: String,
     displayText: String,
   ) {
     val appActionsWidgetExtension: AppActionsWidgetExtension =
         AppActionsWidgetExtension.newBuilder(appWidgetManager)
           .setResponseSpeech(speechText)  // TTS to be played back to the user
           .setResponseText(displayText)  // Response text to be displayed in Assistant
           .build()
   
     // Update widget with TTS
     appActionsWidgetExtension.updateWidget(appWidgetId)
   }
   

در نهایت، منطق TTS را با تنظیم اطلاعات TTS هنگامی که پایگاه داده تمرین، داده‌های خالی را برای نوع تمرین درخواستی برمی‌گرداند، تکمیل کنید.

3. تابع setNoActivityDataWidget() را در StatsWidget.kt با این کد به‌روزرسانی کنید:

   // StatsWidget.kt
   
   private fun setNoActivityDataWidget() {
     // ...
     // Add conditional for hasBii for widget without data
     if (hasBii) {
       // formats speech and display text for Assistant
       // https://developers.google.com/assistant/app/widgets#library
       val speechText =
         context.getString(R.string.widget_no_activity_speech, aboutExerciseName)
       val displayText =
         context.getString(R.string.widget_no_activity_text)
   
       setTts(speechText, displayText)
     }
   }
   

۶. عملکرد برنامه را آزمایش کنید

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

ایجاد پیش‌نمایش

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

1. به ابزارها > دستیار گوگل > ابزار تست اقدامات برنامه بروید. ممکن است از شما خواسته شود با استفاده از حساب گوگل خود وارد اندروید استودیو شوید .
2. روی ایجاد پیش‌نمایش کلیک کنید. در صورت درخواست، خط‌مشی‌ها و شرایط خدمات «عملکردهای برنامه» را مرور و بپذیرید.

یک نوع ورزش مورد انتظار را آزمایش کنید

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

1. در اولین مرحله که ابزار از شما می‌خواهد یک BII را انتخاب و پیکربندی کنید، actions.intent.GET_EXERCISE_OBSERVATION را انتخاب کنید.
2. در کادر exerciseObservation ، نام پیش‌فرض Exercise را از climbing به run به‌روزرسانی کنید.
3. روی اجرای اکشن برنامه کلیک کنید.

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

یک نوع ورزش غیرمنتظره را امتحان کنید

برای آزمایش یک نوع تمرین غیرمنتظره در ابزار تست:

1. در کادر exerciseObservation ، مقدار name را از Run به Climbing به‌روزرسانی کنید.
2. روی اجرای اکشن برنامه کلیک کنید.

دستیار باید ویجتی را برگرداند که اطلاعات «هیچ فعالیتی یافت نشد» را نمایش می‌دهد.

هدف جایگزینی را آزمایش کنید

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

برای آزمایش هدف جایگزین:

1. در کادر exerciseObservation ، شیء aboutExercise را حذف کنید.
2. روی اجرای اکشن برنامه کلیک کنید.

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

۷. مراحل بعدی

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

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

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

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

• یک ویجت برنامه به BII اضافه کنید.
• یک ویجت را برای دسترسی به پارامترها از Android Extras تغییر دهید.

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

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

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

• برای کشف روش‌های بیشتر برای گسترش برنامه‌هایتان به دستیار ، به مرجع اهداف داخلی App Actions مراجعه کنید.

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

• developers.google.com/assistant/app : سایت رسمی مستندات برای اقدامات برنامه دستیار گوگل.
• فهرست نمونه App Actions : نمونه برنامه‌ها و کدها برای بررسی قابلیت‌های App Actions.
• اقدامات در مخزن گوگل گیت‌هاب : نمونه کد و کتابخانه‌ها.
• r/GoogleAssistantDev : انجمن رسمی ردیت برای توسعه‌دهندگانی که با دستیار گوگل کار می‌کنند.

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

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

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