1. بررسی اجمالی
با App Actions، میتوانید از Google Assistant برای پرش مستقیم به ویژگیهای برنامه و تکمیل وظایف با استفاده از صدای خود استفاده کنید. بهعنوان یک توسعهدهنده اندروید، عناصر قابلیت را برای افزودن App Actions پیادهسازی میکنید. قابلیتها به دستیار اجازه میدهند بدانند کدام ویژگیهای برنامه از درخواستهای صوتی کاربر پشتیبانی میکنند و چگونه میخواهید این درخواستها برآورده شوند.
این کد لبه مفاهیم سطح مبتدی را برای توسعه با App Actions پوشش می دهد. برای پیروی از این کد لبه، باید تجربه قبلی با توسعه برنامه های اندروید و اهداف اندروید داشته باشید. اگر در اندروید تازه کار هستید، ممکن است بخواهید با یکی از نرم افزارهای کد برای اصول برنامه نویس اندروید شروع کنید.
چیزی که خواهی ساخت
در این کد لبه، شما دو برنامه App Actions داخلی (BIIs) را به یک نمونه برنامه اندرویدی تناسب اندام اضافه میکنید که به کاربران امکان میدهد تایمر تمرین را با استفاده از صدای خود شروع و متوقف کنند.
چیزی که یاد خواهید گرفت
نحوه استفاده از BII از دسته Health and Fitness برای گسترش Assistant به یک برنامه Android را خواهید آموخت. همچنین یاد خواهید گرفت که از افزونه Google Assistant برای اندروید استودیو برای آزمایش BII خود استفاده کنید.
پیش نیازها
قبل از ادامه، مطمئن شوید که ابزارهای زیر را در محیط خود دارید:
- ترمینالی برای اجرای دستورات پوسته با نصب git .
- آخرین نسخه اندروید استودیو .
- یک حساب Google با دسترسی به [کنسول Google Play][].
- یک دستگاه اندروید فیزیکی یا مجازی با دسترسی اینترنت به فروشگاه Play.
قبل از ادامه، مطمئن شوید که همان حساب Google به سیستم Android Studio و برنامه Google در دستگاه آزمایشی شما وارد شده است.
2. درک کنید که چگونه کار می کند
App Actions کاربران را از دستیار Google به برنامه Android شما متصل می کند. چگونه کار می کنند؟
وقتی کاربری از دستیار میخواهد با استفاده از برنامه شما کاری را انجام دهد، دستیار درخواست او را با capability
App Actions تعریف شده در shortcuts.xml
XML برنامه شما مطابقت میدهد.
شکل 1. نمودار جریانی که نشان می دهد چگونه Assistant یک درخواست صوتی App Actions را پردازش می کند.
هر عنصر قابلیت تعریف می کند:
- یک هدف : هدف صوتی برنامه Actions که باید این قابلیت را فعال کند.
- یک یا چند اجرا : اهداف یا پیوندهای عمیق Android که دستیار برای راهاندازی برنامه و انجام درخواست صوتی کاربر ایجاد میکند. تعاریف تحقق مشخص می کند که کدام پارامترها از پرس و جو کاربر انتظار می رود و چگونه آن پارامترها باید در دستورالعمل های راه اندازی کدگذاری شوند.
مقاصد
در درک زبان طبیعی (NLU)، intent گروهی از عبارات کاربر است که دارای معانی مشابهی هستند. گوگل دهها هدف داخلی (BIIs) را که طیف گستردهای از انواع درخواستها را پوشش میدهند با App Actions در دسترس قرار داده است. برای مثال، «دستیار» آموزش دیده است تا عبارات «سفارش پیتزا» یا «منوی دسر را به من نشان بده» با ORDER_MENU_ITEM
BII مرتبط کند. با App Actions، می توانید از این BII ها برای گسترش سریع درخواست های صوتی رایج به عملکرد برنامه استفاده کنید.
تحقق ها
هنگامی که یک درخواست کاربر یک Action APP را در shortcuts.xml
راهاندازی میکند، فعالیت Android شما باید هدف یا پیوند عمیق Android ورودی را شناسایی کرده و مدیریت کند و عملکرد مورد نظر خود را در اختیار کاربر قرار دهد. نتیجه یک تجربه کاربری مبتنی بر صدا است که در آن Assistant برنامه شما را در پاسخ به درخواست کاربر فراخوانی میکند.
3. محیط توسعه خود را آماده کنید
این کد لبه از برنامه نمونه تناسب اندام برای اندروید استفاده می کند. این برنامه به کاربران اجازه می دهد تایمر ورزش را شروع و متوقف کنند و آمار مربوط به تمرینات خود را مشاهده کنند.
فایل های پایه خود را دانلود کنید
برای دریافت فایل های پایه این کد لبه، دستور زیر را برای کلون کردن مخزن GitHub اجرا کنید:
git clone --branch codelab-start https://github.com/actions-on-google/appactions-fitness-kotlin.git
هنگامی که مخزن را شبیه سازی کردید، آن را در Android Studio باز کنید:
- در گفتگوی خوش آمدید به Android Studio ، روی وارد کردن پروژه کلیک کنید.
- پوشه ای را که مخزن را در آن کلون کرده اید، پیدا کرده و انتخاب کنید.
شناسه برنامه اندروید را به روز کنید
بهروزرسانی شناسه برنامه برنامه بهطور منحصربهفرد برنامه را در دستگاه آزمایشی شما شناسایی میکند و در صورتی که برنامه در کنسول Play آپلود شود، از خطای «نام بسته تکراری» جلوگیری میکند. برای بهروزرسانی شناسه برنامه، app/build.gradle
را باز کنید:
android {
...
defaultConfig {
applicationId "com.MYUNIQUENAME.android.fitactions"
...
}
}
"MYUNIQUENAME" را در قسمت applicationId
با چیزی منحصر به فرد برای خود جایگزین کنید.
برنامه را در دستگاه خود امتحان کنید
قبل از ایجاد تغییرات بیشتر در کد برنامه، ایدهای در مورد کارهایی که برنامه نمونه میتواند انجام دهد، مفید است. آزمایش برنامه در محیط توسعه دهنده شامل این مراحل است:
- باز کردن دستگاه آزمایشی اندروید مجازی یا فیزیکی.
- تأیید اینکه برنامه دستیار کار می کند.
- با استفاده از Android Studio برای استقرار و اجرای نمونه برنامه در دستگاه خود.
این مراحل را برای آزمایش برنامه خود دنبال کنید:
- در Android Studio، Run > Run app را انتخاب کنید یا روی Run کلیک کنید در نوار ابزار
- اگر از یک دستگاه مجازی استفاده می کنید، در گفتگوی Select Deployment Target ، یک دستگاه مجازی را انتخاب کنید و روی OK کلیک کنید. نسخه سیستم عامل پیشنهادی اندروید 8 (سطح API 26) یا بالاتر است، اگرچه Actions در دستگاههای اندروید 5 (سطح API 21) اجرا میشود.
- پس از باز کردن برنامه، دکمه Home را به مدت طولانی فشار دهید تا Assistant راهاندازی شود و مطمئن شوید که کار میکند. اگر قبلاً وارد «دستیار» نشدهاید، وارد شوید.
- برنامه را دوباره باز کنید.
شکل 2. برنامه نمونه Fit Actions که آمار تمرین را نمایش می دهد.
به طور خلاصه برنامه را بررسی کنید تا ببینید چه کاری می تواند انجام دهد. با ضربه زدن روی نماد Run یک تایمر تمرینی شروع می شود و ضربه زدن روی نماد X سپس تایمر را متوقف می کند. اینها کارهایی هستند که برای کنترل صوتی با App Actions فعال خواهید کرد.
افزونه Google Assistant را نصب کنید
افزونه Google Assistant به شما این امکان را می دهد تا App Actions خود را در یک دستگاه آزمایشی آزمایش کنید. برای افزودن آن به اندروید استودیو مراحل زیر را دنبال کنید:
- به File > Settings ( Android Studio > Preferences در MacOS) بروید.
- در بخش Plugins، به Marketplace بروید و «دستیار Google» را جستجو کنید.
- ابزار را نصب کرده و اندروید استودیو را ریستارت کنید.
4. قابلیت Start Exercise BII را اضافه کنید
actions.intent.START_EXERCISE
BII به کاربران امکان میدهد برنامهای را باز کنند و با استفاده از صدای خود تمرینی را شروع کنند. در این مرحله، قابلیتی را برای این BII پیادهسازی میکنید که به کاربران اجازه میدهد از Assistant بخواهند اجرا را در برنامه Fitness شروع کنند.
قابلیت را تعریف کنید
دستیار از عناصر capability
تعریف شده در shortcuts.xml
برای پردازش صدای دستورات صوتی با مراحل زیر استفاده می کند:
- دستیار پرس و جوی صوتی کاربر را با BII تعریف شده در قابلیت های برنامه شما مطابقت می دهد.
- دستیار مقادیر را از پرس و جو به پارامترهای BII استخراج می کند. هر پارامتر به یک
Bundle
متصل به یکIntent
تولید شده اضافه می شود. - Assistant از
Intent
برای راهاندازی برنامه استفاده میکند و به برنامه امکان دسترسی به پارامترهای همراه را میدهد.
START_EXERCISE
BII از پارامتر exercise.name
BII پشتیبانی می کند. شما از این پارامتر استفاده می کنید تا به کاربران اجازه دهید نوع تمرینی را برای ردیابی در برنامه مشخص کنند.
START_EXERCISE
BII را با افزودن این capability
به shortcuts.xml
که در دایرکتوری نمونه پروژه app/src/main/res/xml
قرار دارد به برنامه خود اضافه کنید:
<!-- shortcuts.xml -->
<capability android:name="actions.intent.START_EXERCISE">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
android:targetClass="com.devrel.android.fitactions.FitMainActivity">
<parameter
android:name="exercise.name"
android:key="exerciseType"/>
</intent>
</capability>
PUT_YOUR_APPLICATION_ID_HERE
را با applicationId
منحصربفردی که در مرحله قبل تعریف کردید جایگزین کنید.
نمونه XML قبلی:
- قابلیتی را برای
START_EXERCISE
BII اعلام می کند. -
intent
اندرویدی را که دستیار برای راهاندازی برنامه ایجاد میکند، مشخص میکند:- ویژگی های
targetPackage
وtargetClass
فعالیت دریافت کننده را مشخص می کنند. - ویژگی
parameter
، پارامترexercise.name
BII را در قسمت های اضافیBundle
دریافت شده توسط فعالیت بهexerciseType
نگاشت می کند.
- ویژگی های
کنترل پارامترهای BII با موجودی درون خطی
پارامترهای BII عناصر استخراج شده از یک جستجوی کاربر Assistant را نشان می دهند. به عنوان مثال، هنگامی که کاربر می گوید: "Hey Google، اجرا را در ExampleApp شروع کن"، Assistant "run" را در پارامتر BII exercise.name
schema.org استخراج می کند. برای برخی از BII ها، می توانید به Assistant دستور دهید تا پارامترهای BII را با مجموعه ای از شناسه های مورد انتظار برنامه شما مطابقت دهد.
شما این کار را با اتصال عناصر موجودی درون خطی به پارامتر BII انجام می دهید. موجودی درون خطی مجموعه ای از مقادیر پارامتر BII پشتیبانی شده، مانند "run"، "hike" و "jog" و شناسه میانبر مربوطه آنها، مانند EXERCISE_RUN
است. این موجودی صحافی به دستیار امکان میدهد شناسه میانبر برای پارامترهای منطبق را به جای مقدار جستجوی خام، به فعالیت تکمیلی شما ارسال کند.
برخی از پارامترهای BII، مانند exercise.name
، برای عملکرد به موجودی درون خطی نیاز دارند. برای مدیریت این پارامتر، عناصر shortcut
موجودی زیر را به shortcuts.xml
اضافه کنید:
<!-- shortcuts.xml -->
<shortcuts>
<shortcut
android:shortcutId="running"
android:shortcutShortLabel="@string/activity_running">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/runningSynonyms"/>
</capability-binding>
</shortcut>
<shortcut
android:shortcutId="walking"
android:shortcutShortLabel="@string/activity_walking">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/walkingSynonyms"/>
</capability-binding>
</shortcut>
<shortcut
android:shortcutId="cycling"
android:shortcutShortLabel="@string/activity_cycling">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/cyclingSynonyms"/>
</capability-binding>
</shortcut>
<capability> ... </capability>
</shortcuts>
در کد قبلی، سه میانبر تعریف کردهاید که نشاندهنده موجودی درون خطی برای انواع تمرینات پشتیبانیشده برنامه است: دویدن، پیادهروی و دوچرخهسواری. هر میانبر به روش های زیر به قابلیت متصل می شود:
- ویژگی
android:key
هر عنصرcapability-binding
به همانSTART_EXCERCISE
BII تعریف شده برای قابلیت اشاره دارد. - عنصر
parameter-binding
هر کلید میانبر به پارامتر BIIexercise.name
.
مترادف موجودی درون خطی را اضافه کنید
ویژگیهای android:value
عنصر parameter-binding
در میانبرهای موجودی قبلی به منبع آرایهای از مترادفها برای هر عنصر موجودی اشاره دارد. مترادف ها تغییرات یک نوع عنصر مانند "run"، "jog" و "sprint" را برای اشاره به یک shortcutId
فعال می کنند. ورودی های مترادف زیر را به منبع array.xml
پروژه اضافه کنید:
<!-- array.xml -->
<array name="runningSynonyms">
<item>Run</item>
<item>Jog</item>
<item>Jogging</item>
<item>Sprint</item>
</array>
<array name="walkingSynonyms">
<item>Walk</item>
<item>Hike</item>
<item>Hiking</item>
</array>
<array name="cyclingSynonyms">
<item>Biking</item>
<item>Riding</item>
<item>Pedaling</item>
</array>
اهداف اندروید ورودی را برآورده کنید
مقاصد Android اشیایی پیامرسانی هستند که Android از آن برای درخواست اقدام از یک برنامه دیگر استفاده میکند. دستیار با ایجاد یک هدف از جزئیات پیکربندی در قابلیت راه اندازی شده، پرس و جوهای صوتی کاربران را برآورده می کند. به منظور تحقق اهداف برای قابلیت START_EXERCISE
، کلاس هدف FitMainActivity
را بهروزرسانی کنید تا پارامترهای intent و BII ورودی را مدیریت کند.
ابتدا تابع Intent.handleIntent
را با کد زیر جایگزین کنید:
//FitMainActivity.kt
private fun Intent.handleIntent() {
when (action) {
// When the BII is matched, Intent.Action_VIEW will be used
Intent.ACTION_VIEW -> handleIntent(data)
// Otherwise start the app as you would normally do.
else -> showDefaultView()
}
}
سپس یک تابع handleIntent
جدید با کد زیر به کلاس اضافه کنید:
//FitMainActivity.kt
/**
* Use extras provided by the intent to handle the different BIIs
*/
private fun handleIntent(data: Uri?) {
// path is normally used to indicate which view should be displayed
// i.e https://fit-actions.firebaseapp.com/start?exerciseType="Running" -> path = "start"
var actionHandled = true
val startExercise = intent?.extras?.getString(START_EXERCISE)
// Add stopExercise variable here
if (startExercise != null){
val type = FitActivity.Type.find(startExercise)
val arguments = Bundle().apply {
putSerializable(FitTrackingFragment.PARAM_TYPE, type)
}
updateView(FitTrackingFragment::class.java, arguments)
} // Add conditional for stopExercise
else{
// path is not supported or invalid, start normal flow.
showDefaultView()
// Unknown or invalid action
actionHandled = false
}
notifyActionSuccess(actionHandled)
}
در تابع Intent.handleIntent
قبلی، وقتی ACTION_VIEW
فعال میشود، دادههای هدف App Action به تابع handleIntent
ارسال میشود. پارامترهای BII دستهبندی شده در intent START_EXERCISE
از طریق intent?.extras?.getString(START_EXERCISE)
قابل دسترسی هستند. بقیه تابع FitTrackingFragment
برای نمایش نوع تناسب اندام انتخاب شده startExercise
به روز می کند.
اکشن برنامه خود را آزمایش کنید
در طول توسعه App Actions، از افزونه Google Assistant برای پیشنمایش اقدامات خود در یک دستگاه آزمایشی استفاده میکنید. همچنین میتوانید از این افزونه برای تنظیم مقادیر پارامتر هدف یک Action استفاده کنید تا نحوه عملکرد برنامهتان با روشهای مختلفی که کاربر ممکن است درخواست دستیار را برای برنامه شما بیان کند، بررسی کند.
برای آزمایش App Action خود با افزونه، مراحل زیر را دنبال کنید:
- با انتخاب Run > Run App یا با کلیک کردن روی نماد Run در نوار ابزار بالا، برنامه خود را در Android Studio اجرا کنید.
- به Tools > App Actions > Google Assistant > App Actions Test Tool بروید.
- روی ایجاد پیش نمایش کلیک کنید. در صورت درخواست، خطمشیها و شرایط خدمات App Actions را بررسی کرده و بپذیرید.
-
actions.intent.START_EXERCISE
intent داخلی را انتخاب کنید. - در کادر تمرین ، مقدار اجرای پیش فرض را بگذارید.
- روی Run App Action کلیک کنید. بررسی کنید که Assistant به تایمر تمرین برنامه پیوند عمیق دارد و اینکه تایمر یک تمرین از نوع دویدن را آغاز کرده باشد.
شما اولین App Actions خود را با START_EXERCISE
BII اجرا کرده اید. تبریک میگم در مرحله بعد، کاربران را قادر میسازیم تا تمرین دویدن را در برنامه شما متوقف کنند.
5. قابلیت Stop Exercise BII را اضافه کنید
actions.intent.STOP_EXERCISE
BII به کاربران این امکان را میدهد که با پرسیدن مواردی مانند «Hey Google، اجرای من را در ExampleApp متوقف کن»، یک جلسه تمرینی را متوقف کنند. با افزودن capability
دوم به shortcuts.xml
، این BII را در برنامه Fitness پیاده سازی کنید:
<!-- shortcuts.xml -->
<capability android:name="actions.intent.STOP_EXERCISE">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
android:targetClass="com.devrel.android.fitactions.FitMainActivity">
<!-- Eg. name = "Running" -->
<parameter
android:name="exercise.name"
android:key="stopExercise"/>
</intent>
</capability>
PUT_YOUR_APPLICATION_ID_HERE
با applicationId
منحصر به فرد خود جایگزین کنید.
کنترل پارامترهای BII با موجودی درون خطی
این BII از همان پارامتر exercise.name
مانند START_EXERCISE
BII پشتیبانی میکند و به کاربران امکان میدهد مشخص کنند که کدام تمرین فعال را میخواهند به پایان برسانند. برای فعال کردن این، مجموعه دومی از عناصر میانبر موجودی را به shortcuts.xml
اضافه کنید:
<!-- shortcuts.xml -->
<shortcut
android:shortcutId="running"
android:shortcutShortLabel="@string/activity_running">
<capability-binding android:key="actions.intent.STOP_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/runningSynonyms"/>
</capability-binding>
</shortcut>
<shortcut
android:shortcutId="walking"
android:shortcutShortLabel="@string/activity_walking">
<capability-binding android:key="actions.intent.STOP_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/walkingSynonyms"/>
</capability-binding>
</shortcut>
<shortcut
android:shortcutId="cycling"
android:shortcutShortLabel="@string/activity_cycling">
<capability-binding android:key="actions.intent.STOP_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/cyclingSynonyms"/>
</capability-binding>
</shortcut>
اهداف اندروید ورودی را برآورده کنید
با بهروزرسانی کلاس FitMainActivity
برنامه را فعال کنید تا اهداف ورودی STOP_EXERCISE
Android را مدیریت کند. ابتدا یک متغیر به تابع handleIntent
اضافه کنید تا داده های هدف STOP_EXERCISE
را نگه دارد:
// FitMainActivity.kt
private fun handleIntent(data: Uri?) {
val stopExercise = intent?.extras?.getString(STOP_EXERCISE)
//...
}
سپس، منطق شرطی تابع handleIntent
را برای مدیریت مقاصد STOP_EXERCISE
به روز کنید:
// FitMainActivity.kt
private fun handleIntent(data: Uri?) {
//...
if (startExercise != null){
val type = FitActivity.Type.find(startExercise)
val arguments = Bundle().apply {
putSerializable(FitTrackingFragment.PARAM_TYPE, type)
}
updateView(FitTrackingFragment::class.java, arguments)
} // Add conditional for stopExercise
<strong>
} else if(stopExercise != null){
// Stop the tracking service if any and return to home screen.
stopService(Intent(this, FitTrackingService::class.java))
updateView(FitStatsFragment::class.java)
}
</strong>
//...
}
در کد قبلی، تابع handleIntent
را برای بررسی STOP_EXERCISE
BII در intent اندروید ورودی به روز کردید. در صورت پیدا شدن، عملکرد تایمر فعال را متوقف می کند و کاربر را به صفحه اصلی باز می گرداند.
اکشن برنامه خود را آزمایش کنید
با دنبال کردن این مراحل با استفاده از افزونه Google Assistant Action App خود را آزمایش کنید:
- با انتخاب Run > Run App یا با کلیک کردن روی نماد Run در نوار ابزار بالا، برنامه خود را در Android Studio اجرا کنید.
- در برنامه، یک تمرین جدید "دویدن" را شروع کنید.
- افزونه را در Android Studio باز کنید: به Tools > App Actions > Google Assistant > App Actions Test Tool بروید.
- روی ایجاد پیش نمایش کلیک کنید.
- قصد داخلی
actions.intent.STOP_EXERCISE
را انتخاب کنید. - در کادر تمرین ، مقدار اجرای پیش فرض را بگذارید.
- روی Run App Action کلیک کنید. بررسی کنید که دستیار تمرین را متوقف می کند و شما را به صفحه اصلی باز می گرداند.
6. مراحل بعدی
تبریک می گویم!
اکنون میدانید که چگونه میتوانید یک برنامه Android را با استفاده از اهداف داخلی Assistant فعال کنید. در این کد لبه یاد گرفتید:
- چگونه به کاربران اجازه دهیم تا با استفاده از Assistant به ویژگیهای برنامه خاص بپردازند.
- نحوه استفاده از موجودی درون خطی
- نحوه تست BII با استفاده از افزونه Google Assistant .
بعدش چی
از اینجا، میتوانید اصلاحات بیشتری را در برنامه تناسب اندام خود انجام دهید. برای ارجاع به پروژه تمام شده، به شعبه اصلی در GitHub مراجعه کنید.
در اینجا چند پیشنهاد برای یادگیری بیشتر در مورد گسترش این برنامه با App Actions وجود دارد:
- سایر کدهای App Actions ما را بررسی کنید.
- برای کشف BII های بیشتر برای گسترش برنامه های خود به دستیار ، از مرجع اهداف داخلی App Actions دیدن کنید.
برای ادامه سفر Actions on Google، این منابع را کاوش کنید:
- developers.google.com/assistant : سایت اسناد رسمی برای Actions on Google.
- نمایه نمونه اقدامات برنامه : نمونه برنامه ها و کد برای کاوش قابلیت های App Actions.
- اقدامات در مخزن Google GitHub : نمونه کد و کتابخانه ها.
- r/GoogleAssistantDev : انجمن رسمی Reddit برای توسعه دهندگانی که با Google Assistant کار می کنند.
ما را در Twitter @ActionsOnGoogle دنبال کنید تا با آخرین اعلانهای ما همراه باشید و برای #appactions توییت کنید تا آنچه ساختهاید به اشتراک بگذارید!
نظرسنجی بازخورد
در نهایت، لطفاً این نظرسنجی را پر کنید تا در مورد تجربه خود در مورد این کد لبه نظر بدهید.