دمج تطبيقات Android المصغّرة مع "مساعد Google"

1. نظرة عامة

في أول درس تطبيقي حول "مهامّ في التطبيقات"، تعلّمت كيفية توسيع نطاق "مساعد Google" ليشمل تطبيقًا تجريبيًا للياقة البدنية من خلال تنفيذ الأهداف المضمّنة (BII) من فئة الأهداف المضمّنة المتعلقة بالصحة واللياقة البدنية.

تتيح "إجراءات التطبيقات" للمستخدمين تشغيل ميزات محدّدة في التطبيق مباشرةً من "مساعد Google" من خلال طلبات مثل Ok Google، ابدأ الركض في ExampleApp". بالإضافة إلى تشغيل التطبيقات، يمكن أن يعرض "مساعد Google" أداة Android تفاعلية للمستخدم لتلبية طلبات المعلومات المضمّنة في التطبيق المؤهّلة.

شاشة تعرض "مساعد Google" وهو يعرض أداة استجابةً لطلب مستخدم أدّى إلى تفعيل إحدى إمكانات GET_EXERCISE_OBSERVATION في واجهة BII للتطبيقات.

ما ستنشئه

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية عرض أدوات Android لتلبية طلبات مستخدمي "مساعد Google". ستتعرّف أيضًا على كيفية:

  • استخدِم مَعلمات BII لتخصيص التطبيقات المصغّرة.
  • توفير مقدّمات تحويل النص إلى كلام (TTS) في "مساعد Google" لعناصرك.
  • استخدِم مرجع الأهداف المضمّنة لتحديد الأهداف المضمّنة التي تتيح تنفيذ الطلبات من خلال التطبيق المصغّر.

المتطلبات الأساسية

قبل المتابعة، تأكَّد من أنّ بيئة التطوير جاهزة لتطوير مهامّ في التطبيقات. يجب أن تتضمّن ما يلي:

  • وحدة طرفية لتنفيذ أوامر shell، مع تثبيت git
  • أحدث إصدار ثابت من استوديو Android
  • جهاز Android فعلي أو افتراضي متصل بالإنترنت
  • حساب Google تم تسجيل الدخول عبره إلى استوديو Android وتطبيق Google وتطبيق "مساعد Google"

إذا كنت تستخدم جهازًا فعليًا، اربطه بجهاز التطوير المحلي.

2. التعرّف على طريقة العمل

يستخدم "مساعد Google" تقنية فهم اللغة الطبيعية (NLU) لقراءة طلب المستخدم ومطابقته مع هدف مضمّن في "مساعد Google" (BII). بعد ذلك، يربط "مساعد Google" الغرض بالإمكانية (التي تنفّذ واجهة BII)، والتي تسجّلها لهذا الغرض في تطبيقك. وأخيرًا، ينفّذ "مساعد Google" طلب المستخدم من خلال عرض أداة Android التي ينشئها تطبيقك باستخدام التفاصيل الواردة في الإمكانية.

في هذا الدرس التطبيقي حول الترميز، ستحدّد إمكانية تسجّل دعمًا لواجهة برمجة التطبيقات GET_EXERCISE_OBSERVATION المضمّنة. في هذه الإمكانية، يمكنك توجيه "مساعد Google" لإنشاء هدف Android لفئة أداة FitActions لتلبية طلبات BII هذه. يمكنك تعديل هذه الفئة لإنشاء أداة مخصّصة يعرضها "مساعد Google" للمستخدم، ومقدّمة لتحويل النص إلى كلام يعلن عنها "مساعد Google".

يوضّح المخطّط البياني التالي هذا المسار:

مخطط انسيابي يوضّح تنفيذ إحدى أدوات "مساعد Google"

تطبيق 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()

إضافة إمكانية استخدام "مساعد Google"

في هذا الدرس التطبيقي حول الترميز، ستعدّل نموذج التطبيق للتعامل مع وظيفة "مهامّ في التطبيقات". تشمل هذه التغييرات ما يلي:

  1. ضبط إمكانية GET_EXERCISE_OBSERVATION BII لعرض مثيل من العنصر StatsWidget
  2. تعديل الفئة StatsWidget لاستخدام ميزات "مهامّ في التطبيقات"، مثل:
    • استخدام مَعلمات BII للسماح للمستخدمين بالاطّلاع على إحصاءات تمارين رياضية معيّنة من خلال طرح طلبات مثل "Ok Google، اعرض إحصاءات الركض على ExampleApp"
    • توفير سلاسل مقدمة لتحويل النص إلى كلام
    • إدارة الحالات الخاصة، مثل عندما لا يتضمّن طلب بحث المستخدم مَعلمة لنوع التمرين

3- إعداد بيئة التطوير

تنزيل ملفاتك الأساسية

نفِّذ الأمر التالي لاستنساخ مستودع GitHub الخاص بالتطبيق النموذجي:

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

بعد استنساخ المستودع، اتّبِع الخطوات التالية لفتحه في استوديو Android:

  1. في مربّع الحوار "مرحبًا بك في استوديو Android"، انقر على استيراد مشروع.
  2. ابحث عن المجلد الذي نسخت المستودع فيه واختَره.

للاطّلاع على إصدار من برنامج الحماية المتقدّمة يمثّل الدرس التطبيقي حول الترميز المكتمل، استنسِخ مستودع نموذج تطبيق باستخدام العلامة --branch master.

تعديل معرّف تطبيق Android

يؤدي تعديل معرّف التطبيق إلى تحديد التطبيق بشكلٍ فريد على جهاز الاختبار وتجنُّب الخطأ "اسم حزمة مكرّر" في حال تحميل التطبيق إلى Play Console. لتعديل معرّف التطبيق، افتح app/build.gradle:

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

استبدِل "MYUNIQUENAME" في الحقل applicationId باسم فريد خاص بك.

تثبيت المكوّن الإضافي التجريبي

يتيح لك مكوّن "مساعد Google" الإضافي اختبار "مهامّ في التطبيقات" على جهاز اختباري. تعمل هذه الميزة من خلال إرسال معلومات إلى "مساعد Google" عبر تطبيق Google على جهاز Android. إذا لم يكن لديك المكوّن الإضافي، يمكنك تثبيته باتّباع الخطوات التالية:

  1. انتقِل إلى ملف (File) > الإعدادات (Settings) (استوديو Android (Android Studio) > الإعدادات المفضّلة (Preferences) على نظام التشغيل MacOS).
  2. في قسم "المكوّنات الإضافية" (Plugins)، انتقِل إلى Marketplace وابحث عن "مساعد Google". يمكنك أيضًا تنزيل أداة الاختبار وتثبيتها يدويًا.
  3. ثبِّت الأداة وأعِد تشغيل "استوديو Android".

اختبار التطبيق على جهازك

قبل إجراء المزيد من التغييرات على التطبيق، من المفيد الحصول على فكرة عمّا يمكن أن يفعله نموذج التطبيق.

تشغيل التطبيق على جهاز الاختبار:

  1. في "استوديو Android"، اختَر جهازك الفعلي أو الافتراضي، ثم انقر على تشغيل > تشغيل التطبيق أو على تشغيلتشغيل رمز التطبيق في &quot;استوديو Android&quot; في شريط الأدوات.
  2. اضغط مع الاستمرار على زرّ الشاشة الرئيسية لإعداد "مساعد Google" والتأكّد من أنّه يعمل. عليك تسجيل الدخول إلى "مساعد Google" على جهازك إذا لم يسبق لك ذلك.

لمزيد من المعلومات حول الأجهزة الافتراضية التي تعمل بنظام التشغيل Android، يُرجى الاطّلاع على إنشاء الأجهزة الافتراضية وإدارتها.

استكشِف التطبيق سريعًا لمعرفة ما يمكنه فعله. يملأ التطبيق مسبقًا 10 أنشطة رياضية ويعرض هذه المعلومات في العرض الأول.

تجربة التطبيق المصغّر الحالي

  1. انقر على زر الشاشة الرئيسية للانتقال إلى الشاشة الرئيسية لجهاز الاختبار.
  2. انقر مع الاستمرار على مساحة فارغة في الشاشة الرئيسية واختَر التطبيقات المصغّرة.
  3. انتقِل للأسفل في قائمة التطبيقات المصغّرة إلى FitActions.
  4. اضغط مع الاستمرار على رمز FitActions وضَع التطبيق المصغّر على الشاشة الرئيسية.

لقطة شاشة تعرض تطبيق FitActions المصغّر على الشاشة الرئيسية للجهاز

4. إضافة إجراء التطبيق

في هذه الخطوة، عليك إضافة إذن GET_EXERCISE_OBSERVATION BII. يمكنك إجراء ذلك من خلال إضافة عنصر capability جديد في shortcuts.xml. تحدّد هذه الإمكانية كيفية تشغيلها وكيفية استخدام مَعلمات معلومات النشاط التجاري المضمّنة (BII) وتحديد نوايا Android التي سيتم استدعاؤها لتنفيذ الطلب.

  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، وبالتالي عندما يتم تفعيل BII، يتم إنشاء التطبيق المصغّر وعرضه للمستخدم.

قبل تشغيل الأداة، يستخرج "مساعد Google" مَعلمات واجهة BII المتوافقة من طلب البحث الذي يقدّمه المستخدم. يتطلّب هذا الدرس العملي المَعلمة exerciseObservation.aboutExercise.name الخاصة بطلبات المعلومات المضمّنة، والتي تمثّل نوع التمرين الذي طلبه المستخدم. يتيح التطبيق ثلاثة أنواع من التمارين: "الجري" و"المشي" و "ركوب الدراجات". يمكنك تقديم مستودع مضمّن لإعلام "مساعد Google" بالقيم المسموح بها.

  1. حدِّد عناصر المستودع الإعلاني هذه من خلال إضافة هذا الإعداد، فوق إمكانية 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". في هذه الحالات، يطلب منك "مساعد Google" تحديد هدف احتياطي للسماح بنجاح الطلب، حتى إذا لم يتم تقديم أي مَعلمات في طلب البحث.

  1. في shortcuts.xml، أضِف غرضًا احتياطيًا إلى إمكانية 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>

في نموذج الإعداد هذا، تكون عملية التنفيذ الاحتياطية عبارة عن طلب Android بدون أي مَعلمات في بيانات Extra.

5- تفعيل التطبيق المصغّر لـ "مساعد Google"

بعد إعداد إمكانية GET_EXERCISE_OBSERVATION، عدِّل فئة التطبيق المصغّر لتتيح التفعيل الصوتي لميزة "مهامّ في التطبيقات".

إضافة مكتبة "إضافة التطبيقات المصغّرة"

تعمل مكتبة إضافة التطبيقات المصغّرة في "مهامّ في التطبيقات" على تحسين التطبيقات المصغّرة لتوفير تجارب "مساعد Google" التي تركّز على الصوت. على وجه التحديد، تتيح لك هذه السمة تقديم مقدمة مخصّصة لتحويل النص إلى كلام في تطبيقاتك المصغّرة.

  1. أضِف تبعية مكتبة "إضافة التطبيقات المصغّرة" إلى مورد تطبيق العيّنة /app/build.gradle:
    // app/build.gradle

dependencies {
  //...
  implementation "com.google.assistant.appactions:widgets:0.0.1"
}
    انقر على المزامنة الآن في مربّع التحذير الذي يظهر في "استوديو Android". تساعدك المزامنة بعد كل تغيير في 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>

أثناء طلب صوتي يؤدي إلى تفعيل أداة، يستخدم "مساعد Google" هذه الخدمة لإرسال الطلبات إلى التطبيق، وتتلقّى الخدمة الطلب مع بيانات BII. تستخدم الخدمة هذه البيانات لإنشاء عنصر واجهة مستخدم RemoteView لعرضه في "مساعد Google".

تعديل فئة التطبيق المصغّر

تم الآن إعداد تطبيقك لتوجيه طلبات إمكانية 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 للسماح للصف باستخدام بيانات خيارات التطبيق المصغّر التي تم تمريرها من "مساعد Google":
    // 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 الاستجابة لأهداف Android التي تنشئها إمكانية GET_EXERCISE_OBSERVATION:

  • ‫optionsBundle = Bundle
    • الحِزم هي عناصر يُراد استخدامها على مستوى حدود العمليات، وبين الأنشطة التي تتضمّن أغراضًا، ولتخزين الحالة المؤقتة على مستوى تغييرات الإعدادات. يستخدم &quot;مساعد Google&quot; كائنات Bundle لتمرير بيانات الإعداد إلى التطبيق المصغّر.
  • bii = actions.intent.GET_EXERCISE_OBSERVATION
    • يتوفّر اسم واجهة BII من الحزمة باستخدام AppActionsWidgetExtension.
  • hasBii = true
    • للتحقّق مما إذا كانت هناك معلومات تعريف شخصية (BII)
  • params = Bundle[{aboutExerciseName=running}]
    • يتم تضمين حزمة خاصة، يتم إنشاؤها من خلال "مهامّ في التطبيقات"، داخل خيارات التطبيق المصغّر Bundle. يحتوي على أزواج المفتاح/القيمة الخاصة بمعلومات النشاط التجاري. في هذه الحالة، تم استخراج القيمة running من طلب البحث النموذجي "Ok Google، أريد الاطّلاع على إحصاءات الركض على ExampleApp".
  • isFallbackIntent = false
    • يتحقّق من توفّر مَعلمات BII المطلوبة في الغرض Extras.
  • aboutExerciseName = running
    • تعرض هذه السمة قيمة Extras للغرض aboutExerciseName.
  • exerciseType = RUNNING
    • يستخدم aboutExerciseName للبحث عن عنصر نوع قاعدة البيانات المطابق.

بعد أن أصبح بإمكان الفئة StatsWidget معالجة بيانات intent الواردة من "مهامّ في التطبيقات" على Android، عدِّل منطق عملية إنشاء التطبيق المصغّر للتحقّق مما إذا تم تشغيل التطبيق المصغّر من خلال "مهمة في التطبيق".

  1. في 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 التي تم تمريرها من خلال هدف Android الخاص بميزة "إجراءات التطبيقات".

  1. أضِف الدالة 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()
       }
   }
}

في الرمز البرمجي السابق، استخدِم فئة مستودع حالية في التطبيق لاسترداد بيانات اللياقة البدنية من قاعدة البيانات المحلية للتطبيق. توفر هذه الفئة واجهة برمجة تطبيقات تسهّل الوصول إلى قاعدة البيانات. يعمل المستودع من خلال عرض عنصر LiveData عند تنفيذ طلبات بحث في قاعدة البيانات. في الرمز البرمجي، يمكنك مراقبة LiveData لاسترداد أحدث نشاط لياقة.

تفعيل ميزة "تحويل النص إلى كلام"

يمكنك تقديم سلسلة تحويل النص إلى كلام (TTS) ليُعلن عنها "مساعد Google" عند عرض تطبيقك المصغّر. ننصحك بتضمين هذا الوصف لتوفير سياق مسموع مع عناصر واجهة المستخدم. تتوفّر هذه الوظيفة من خلال مكتبة App Actions Widgets Extension التي تتيح لك ضبط النصوص ومقدمات تحويل النص إلى كلام (TTS) التي تصاحب تطبيقاتك المصغّرة في "مساعد Google".

يمكنك تقديم مقدمة عن ميزة "تحويل النص إلى كلام" في الدالة 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)
      }
}

يشير الرمز البرمجي السابق إلى مرجعَين لسلسلة موارد: أحدهما للكلام والآخر للنص. يمكنك الاطّلاع على جزء اقتراح أسلوب تحويل النص إلى كلام في فيديو التطبيقات المصغّرة للحصول على اقتراحات بشأن تحويل النص إلى كلام. يشير النموذج أيضًا إلى setTts، وهي دالة جديدة توفّر معلومات تحويل النص إلى كلام لمثيل الأداة.

  1. أضِف دالة 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)
}

أخيرًا، أكمل منطق تحويل النص إلى كلام من خلال ضبط معلومات تحويل النص إلى كلام عندما تُرجع قاعدة بيانات التمارين الرياضية بيانات فارغة لنوع تمرين مطلوب.

  1. عدِّل الدالة 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)
  }
}

6. اختبار إجراء التطبيق

أثناء عملية التطوير، استخدِم مكوّن "مساعد Google" الإضافي لمعاينة "مهامّ في التطبيقات" على جهاز اختباري. يمكنك تعديل مَعلمات الغرض من "إجراء التطبيق" باستخدام الأداة لاختبار كيفية تعامل الإجراء مع الطرق المختلفة التي قد يطلب بها المستخدم من "مساعد Google" تنفيذه.

إنشاء معاينة

لاختبار "إجراء التطبيق" باستخدام المكوّن الإضافي، اتّبِع الخطوات التالية:

  1. انتقِل إلى الأدوات > مساعد Google > أداة اختبار مهامّ في التطبيقات. قد يُطلب منك تسجيل الدخول إلى استوديو Android باستخدام حساب Google الخاص بك.
  2. انقر على إنشاء معاينة. راجِع سياسات وبنود خدمة "مهامّ في التطبيقات" واقبلها إذا طُلب منك ذلك.

اختبار نوع تمرين متوقّع

لعرض أداة مصغّرة تعرض معلومات عن آخر عملية تشغيل تم إكمالها في التطبيق، اتّبِع الخطوات التالية في أداة الاختبار:

  1. في الخطوة الأولى التي تطلب منك فيها الأداة اختيار معلومات بناء الهوية (BII) وإعدادها، انقر على actions.intent.GET_EXERCISE_OBSERVATION.
  2. في مربّع exerciseObservation، عدِّل اسم التمرين التلقائي من climbing إلى run.
  3. انقر على تنفيذ إجراء التطبيق.

شاشة تعرض أداة تم عرضها باستخدام مكوّن &quot;مساعد Google&quot; الإضافي

تجربة نوع تمرين غير متوقّع

لاختبار نوع تمرين غير متوقّع في أداة الاختبار، اتّبِع الخطوات التالية:

  1. في المربّع exerciseObservation، عدِّل القيمة name من Run إلى Climbing.
  2. انقر على تنفيذ إجراء التطبيق.

يجب أن يعرض "مساعد Google" أداة مصغّرة تعرض المعلومات "لم يتم العثور على أي نشاط".

شاشة تعرض أداة بدون معلومات تمارين تم عرضها باستخدام إضافة &quot;مساعد Google&quot;.

اختبار هدف احتياطي

يجب أن تعرض الطلبات التي تؤدي إلى تشغيل هدف احتياطي أداة تعرض معلومات عن آخر نشاط تم تسجيله من أي نوع من التمارين.

لاختبار الهدف الاحتياطي، اتّبِع الخطوات التالية:

  1. في مربّع exerciseObservation، احذف العنصر aboutExercise.
  2. انقر على تنفيذ إجراء التطبيق.

يجب أن يعرض "مساعد Google" أداة مصغّرة تعرض معلومات عن آخر تمرين تم إكماله.

شاشة تعرض أداة تعرض آخر نشاط تم تسجيله، باستخدام المكوّن الإضافي &quot;مساعد Google&quot;

7. الخطوات التالية

تهانينا!

يمكنك الآن تلبية طلبات المستخدمين باستخدام أداة Android مع "مساعد Google".

المواضيع التي تناولناها

في هذا الدرس العملي، تعلّمت كيفية:

  • إضافة أداة تطبيق إلى BII
  • عدِّل تطبيقًا مصغّرًا للوصول إلى المَعلمات من Android Extras.

الخطوات التالية

من هنا، يمكنك محاولة إجراء المزيد من التحسينات على تطبيق اللياقة البدنية. وللاطّلاع على المشروع المكتمل، راجِع المستودع الرئيسي على GitHub.

في ما يلي بعض الاقتراحات لمزيد من المعلومات حول توسيع نطاق هذا التطبيق باستخدام "مهام في التطبيقات":

  • انتقِل إلى مرجع الأهداف المضمّنة في "مهامّ في التطبيقات" للتعرّف على المزيد من الطرق لتوسيع نطاق تطبيقاتك ليشمل "مساعد Google".

لمواصلة رحلتك في "إجراءات Google"، يمكنك الاطّلاع على المراجع التالية:

تابِعنا على Twitter ‎@ActionsOnGoogle لتبقى على اطّلاع على آخر إعلاناتنا، وشاركنا ما أنشأته من خلال التغريد باستخدام الهاشتاغ #appactions.

استطلاع لجمع الملاحظات

أخيرًا، يُرجى ملء هذا الاستطلاع لتقديم ملاحظاتك حول تجربتك مع هذا الدرس العملي.