ادغام کردن «کنش‌های برنامه» با ابزاره‌های Android

شکل ۱. درحال راه‌اندازی ابزاره‌ای برای GET_EXERCISE_OBSERVATION.

برای بسیاری از قصدها، بهترین پاسخ ارائه جواب ساده، تأیید مختصر، یا تجربه تعاملی سریع به کاربر است. می‌توانید ابزاره برنامه Android را در «دستیار Google» نمایش دهید تا این نوع هدف‌ها را برآورده کنید.

این راهنما نحوه برآورده کردن پُرسمان‌های کاربر «دستیار» بااستفاده از ابزاره‌ها و نحوه بهبود تجربه ابزاره برای «دستیار» با «کنش‌های برنامه» کتابخانه افزونه ابزاره‌ها را پوشش می‌دهد.

مزايا

ابزاره‌ها نماهای مینیاتوری برنامه هستند که می‌توانند در سطوح Android، مانند راه‌انداز یا صفحه قفل، جاسازی شوند. با «کنش‌های برنامه»، تأثیر ابزاره‌هایتان را با واجدشرایط کردن آن‌ها برای نمایش در «دستیار» افزایش می‌دهید:

  1. اکتشاف: نمایش پیش‌کنشی ابزاره‌ها در پاسخ به پُرسمان‌های زبان طبیعی کاربران.
  2. تعامل: ابزاره‌ها را در زمینه‌های دست‌آزاد نمایش دهید، مثلاً وقتی «دستیار» نتایج شخصی را در صفحه قفل و در Android Auto ارائه می‌دهد.
  3. حفظ: به کاربران اجازه دهید ابزاره‌های نمایش‌داده‌شده در «دستیار» را به راه‌اندازشان سنجاق کنند. عملکرد سنجاق کردن به کتابخانه افزونه ابزاره‌ها نیاز دارد.

نحوه نمایش ابزاره‌ها توسط «دستیار»

کاربران به دو روش می‌توانند ابزاره‌ها را در «دستیار» فراخوانی کنند:

  • به‌طور صریح ابزارکی را با نام درخواست می‌کند.
  • بیان پُرسمانی برای «دستیار» که قصد ازپیش‌تعریف‌شده (BII) یا قصد سفارشی پیکربندی‌شده برای برآورده‌سازی ابزاره را راه‌اندازی می‌کند.

فراخوانی صریح

برای فراخوانی صریح ابزاره‌ها برای هر برنامه نصب‌شده، کاربران می‌توانند از «دستیار» چنین چیزهایی را درخواست کنند:

  • «Ok Google، ابزاره ExampleApp را نشان بده.»
  • «ابزارهایی از ExampleApp.»

«دستیار» این ابزاره‌ها را با مقدمه عمومی نمایش می‌دهد: «ExampleApp می‌گوید، این یک ابزاره است.» درحالی‌که «دستیار» به‌طور پیش‌فرض ابزارهایی را که به این روش درخواست شده‌اند بدون نیاز به هیچ کاری ازسوی توسعه‌دهنده برنامه برمی‌گرداند، این روش فراخوانی مستلزم آن است که کاربر به‌طور صریح از ابزارک اطلاع داشته باشد تا بتواند آن را درخواست کند. برای ساده کردن کاوش ابزاره، از روش برآورده کردن قصد که در بخش زیر به‌طور مفصل شرح داده شده است استفاده کنید.

تحقق هدف

بااستفاده از ابزارهایتان برای برآورده کردن پرسمان‌های زبان طبیعی که کاربران در «دستیار» انجام می‌دهند، ابزارهایتان را راحت‌تر پیدا کنید. برای مثال، هروقت کاربر با پرسیدن «Ok Google، این هفته چند مایل در ExampleApp دویده‌ام؟»، GET_EXERCISE_OBSERVATION BII را در برنامه تناسب اندام شما راه‌اندازی کرد، می‌توانید ابزاره‌ای را برگردانید. علاوه‌بر ساده‌سازی کاوش، ادغام ابزاره‌ها با «کنش‌های برنامه» این مزایا را ارائه می‌دهد:

  • دسترسی به پارامتر: «دستیار» پارامترهای هدف استخراج‌شده از پُرسمان کاربر را به ابزاره شما ارائه می‌دهد و پاسخ‌های سفارشی‌شده را فعال می‌کند.
  • مقدمه‌های نوشتار به گفتار سفارشی: می‌توانید رشته نوشتار به گفتار (TTS) ارائه دهید تا «دستیار» هنگام نمایش ابزاره‌تان آن را اعلام کند.
  • سنجاق کردن ابزاره: «دستیار» دکمه افزودن این ابزاره را در نزدیکی ابزاره شما نمایش می‌دهد تا کاربران بتوانند به‌راحتی ابزاره‌های شما را به راه‌اندازشان سنجاق کنند.

پیاده‌سازی اجرای ابزاره

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

  1. با دنبال کردن مراحل شرح‌داده‌شده در ایجاد ابزاره ساده، ابزاره Android را پیاده‌سازی کنید.
  2. در فایل منبع shortcuts.xml برنامه‌تان، عنصر <app-widget> را به قابلیتتان که حاوی جزئیات برآورده‌سازی و برچسب‌های BII <parameter> است اضافه کنید. ابزارکتان را به‌روز کنید تا پارامترها را مدیریت کند.
  3. کتابخانه افزونه ابزاره‌ها موردنیاز را اضافه کنید، که به «دستیار» اجازه می‌دهد نام‌ها و پارامترهای BII را به ابزاره‌های شما ارسال کند. همچنین عملکرد مقدمه‌های سفارشی نوشتار به گفتار و سنجاق کردن ابزاره را فعال می‌کند.

بخش زیر طرح‌واره <app-widget> را برای shortcuts.xml شرح می‌دهد.

طرح‌واره ابزاره

عناصر <app-widget> به‌عنوان برآورده‌سازی در عناصر <capability> در shortcuts.xml تعریف شده‌اند. این محصولات به مشخصه‌های زیر نیاز دارند، مگراینکه به‌عنوان اختیاری علامت‌گذاری شده باشند:

برچسب `shortcuts.xml`در محدودهمشخصه‌ها
<app-widget> <capability>
  • android:identifier
  • android:targetClass
<parameter> <app-widget>
<extra> <app-widget>
  • android:name (فقط برای نوشتار به گفتار قابل‌اعمال است)
  • android:value (اختیاری)

شرح طرح‌واره ابزاره

<app-widget>

عنصر اجرای ابزاره سطح بالا.

مشخصه ها:

  • android:identifier: شناسه این برآورده‌سازی. این مقدار باید در سراسر عناصر برآورده‌سازی <app-widget> و <intent> تعریف‌شده در <capability> منحصربه‌فرد باشد.
  • ‫android:targetClass: نام کامل کلاس AppWidgetProvider برای رسیدگی به هدف.

<parameter>

پارامتر BII را به مقدار <parameter> قصد نگاشت می‌کند. می‌توانید صفر یا چند پارامتر برای هر عنصر <app-widget> تعریف کنید. درطول اجرا، «دستیار» پارامترها را با به‌روزرسانی موارد اضافی برای نمونه ابزاره به‌صورت جفت‌های کلید-مقدار با قالب زیر ارسال می‌کند:

  • کلید: android:key تعریف‌شده برای پارامتر.
  • مقدار: مقداری که «هدف داخلی» از ورودی صوتی کاربر استخراج می‌کند.

با فراخوانی getAppWidgetOptions() در شیء AppWidgetManager مرتبط، به این موارد اضافی دسترسی پیدا می‌کنید که Bundle حاوی نام BII راه‌انداز و پارامترهای آن را برمی‌گرداند. برای جزئیات، استخراج مقادیر پارامتر را ببینید.

برای اطلاعات بیشتر درباره مطابقت پارامتر «هدف درون‌برنامه»، به داده‌های پارامتر و مطابقت مراجعه کنید.

<extra>

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

  • android:name: "hasTts"
  • android:value: "true"

کدگذاری نمونه

مثال زیر از فایل shortcuts.xml پیکربندی برآورده‌سازی ابزاره را برای قابلیت BII GET_EXERCISE_OBSERVATION نشان می‌دهد:

<capability android:name="actions.intent.GET_EXERCISE_OBSERVATION">
  <app-widget
    android:identifier="GET_EXERCISE_OBSERVATION_1"
    android:targetClass="com.exampleapp.providers.exampleAppWidgetProvider"
    android:targetPackage="com.exampleapp">
    <parameter
      android:name="exerciseObservation.aboutExercise.name"
      android:key="exercisename">
    </parameter>
    <extra android:name="hasTts" android:value="true"/>
  </app-widget>
</capability>

می‌توانید چندین عنصر <app-widget> را مشخص کنید یا از ترکیبی از عناصر <app-widget> و <intent> برای هر قابلیت استفاده کنید. این رویکرد به شما امکان می‌دهد تجربه‌ای سفارشی براساس ترکیب‌های مختلف پارامترهای ارائه‌شده توسط کاربران ارائه دهید. برای مثال، اگر کاربر در پُرسمان خود مکان پیاده شدن را مشخص نکند، می‌توانید او را به فعالیتی در برنامه‌تان هدایت کنید که گزینه‌هایی برای تنظیم مکان سوار شدن و پیاده شدن نشان می‌دهد. برای اطلاعات بیشتر درباره تعریف کردن قصد بازگشت، بخش قصد بازگشت را ببینید.

استخراج مقادیر پارامتر

در کلاس نمونه AppWidgetProvider زیر، از تابع خصوصی updateAppWidget() برای استخراج نام و پارامترهای «هدف درون‌ساخت» از گزینه‌های ابزاره Bundle استفاده می‌شود:

کاتلین

package com.example.exampleapp

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

/**
 * Implementation of App Widget functionality.
 */
class MyAppWidget : AppWidgetProvider() {
    override fun onUpdate(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetIds: IntArray
    ) {
        // There might be multiple widgets active, so update all of them
        for (appWidgetId in appWidgetIds) {
            updateAppWidget(context, appWidgetManager, appWidgetId)
        }
    }

    private fun updateAppWidget(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetId: Int
    ) {
        val widgetText: CharSequence = context.getString(R.string.appwidget_text)

        // Construct the RemoteViews object
        val views = RemoteViews(context.packageName, R.layout.my_app_widget)
        views.setTextViewText(R.id.appwidget_text, widgetText)

        // Extract the name and parameters of the BII from the widget options
        val optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId)
        val bii = optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII) // "actions.intent.CREATE_TAXI_RESERVATION"
        val params = optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS)
        if (params != null && params.containsKey("dropoff")) {
            val dropoffLocation = params.getString("dropoff")
            // Build your RemoteViews with the extracted BII parameter
            // ...
        }
        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
}

جاوا

package com.example.exampleapp;

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

/**
 * Implementation of App Widget functionality.
 */
public class MyAppWidget extends AppWidgetProvider {

    @Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // There might be multiple widgets active, so update all of them
        for (int appWidgetId : appWidgetIds) {
            updateAppWidget(context, appWidgetManager, appWidgetId);
        }
    }

    private static void updateAppWidget(Context context, AppWidgetManager appWidgetManager, int appWidgetId) {

        CharSequence widgetText = context.getString(R.string.appwidget_text);

        // Construct the RemoteViews object
        RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.my_app_widget);
        views.setTextViewText(R.id.appwidget_text, widgetText);

        // Extract the name and parameters of the BII from the widget options
        Bundle optionsBundle = appWidgetManager.getAppWidgetOptions(appWidgetId);
        String bii =
                optionsBundle.getString(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_BII); // "actions.intent.CREATE_TAXI_RESERVATION"
        Bundle params =
                optionsBundle.getBundle(AppActionsWidgetExtension.EXTRA_APP_ACTIONS_PARAMS);

        if (params != null && params.containsKey(("dropoff"))){
            String dropoffLocation = params.getString("dropoff");
            // Build your RemoteViews with the extracted BII parameter
            // ...
        }

        appWidgetManager.updateAppWidget(appWidgetId, views);
    }
}

کتابخانه افزونه ابزاره‌ها

کتابخانه «افزونه ابزاره‌های کنش‌های برنامه» ابزاره‌های شما را برای تجربه‌های «دستیار» با اولویت صوتی بهبود می‌بخشد. این کتابخانه به ابزارهایتان امکان می‌دهد اطلاعات مهم برآورده‌سازی را از «هدف داخلی» راه‌انداز دریافت کنند، ازجمله نام «هدف داخلی» و هر پارامتر قصدی که از پُرسمان کاربر استخراج شده است.

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

برای شروع، کتابخانه را به بخش وابستگی‌های فایل build.gradle برای واحد برنامه‌تان اضافه کنید:

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

مقدمه‌های سفارشی

پس‌از وارد کردن کتابخانه «افزونه ابزاره‌ها»، می‌توانید مقدمه‌های سفارشی نوشتار به گفتار برای ابزاره‌هایتان ارائه دهید. برای افزودن تعریف خود به AppWidgetProvider ابزاره، کلاس را در IDE خود باز کنید و کتابخانه «افزونه ابزاره‌ها» را وارد کنید:

کاتلین

import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

جاوا

import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;
سپس، از کتابخانه برای تعریف رشته‌های مقدمه و به‌روزرسانی ابزاره استفاده کنید، همان‌طور که در این `ExampleAppWidget` نشان داده شده است:

کاتلین

package com.example.exampleapp

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension

/**
 * Implementation of App Widget functionality.
 */
object MyAppWidget : AppWidgetProvider() {
    fun updateAppWidget(
        context: Context?,
        appWidgetManager: AppWidgetManager,
        appWidgetId: Int
    ) {
        val appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager)
            .setResponseSpeech("Hello world") // TTS to be played back to the user
            .setResponseText("Hello world!") // Response text to be displayed in Assistant
            .build()

        // Update widget with TTS
        appActionsWidgetExtension.updateWidget(appWidgetId)

        // Update widget UI
        appWidgetManager.updateAppWidget(appWidgetId, views)
    }
}

جاوا

package com.example.exampleapp;

//... Other module imports
import com.google.assistant.appactions.widgets.AppActionsWidgetExtension;

/**
 * Implementation of App Widget functionality.
 */
public class MyAppWidget extends AppWidgetProvider {

  static void updateAppWidget(Context context, AppWidgetManager appWidgetManager,
    int appWidgetId) {

    AppActionsWidgetExtension appActionsWidgetExtension = AppActionsWidgetExtension.newBuilder(appWidgetManager)
      .setResponseSpeech("Hello world")  // TTS to be played back to the user
      .setResponseText("Hello world!")  // Response text to be displayed in Assistant
      .build();

      // Update widget with TTS
      appActionsWidgetExtension.updateWidget(appWidgetId);

      // Update widget UI
      appWidgetManager.updateAppWidget(appWidgetId, views);
    }

}

توصیه‌های سبک نوشتار به گفتار

از توصیه‌های سبک زیر برای بهینه‌سازی معرفی‌های ابزاره سفارشی برای «تبدیل نوشتار به گفتار» و پیام‌واره‌های نمایش‌داده‌شده استفاده کنید.

توصیه توصیه می‌شود توصیه نمی‌شود
انقباضات
از کلمات مخفف در پیام‌واره‌های نوشتار به گفتار استفاده کنید. پیام‌های بدون مخفف‌سازی، به‌جای اینکه طبیعی و محاوره‌ای باشند، رسمی و رباتیک به‌نظر می‌رسند. گفتن کلماتی مثل «نمی‌توانید» و «نکنید» می‌تواند تنبیهی و خشن به‌نظر برسد. 		ResponseSpeech (تبدیل نوشتار به گفتار)
متأسفم، رزروی پیدا نمی‌کنم.

ResponseText
متأسفم، نمی‌توانم رزروی پیدا کنم. 		ResponseSpeech (تبدیل نوشتار به گفتار)
متأسفم، رزروی پیدا نکردم.

ResponseText
متأسفم، نمی‌توانم رزروی پیدا کنم.
کاما
بااستفاده از ویرگول سریالی در فهرست‌های دارای سه مورد یا بیشتر، شفافیت را افزایش دهید. بدون ویرگول سریال، ممکن است موارد جداگانه در فهرست شما به‌اشتباه شنیده شود یا به‌عنوان گروه خوانده شود. برای مثال، در «نرگس، مروارید و آفتاب‌گردان»، «مروارید و آفتاب‌گردان» به‌نظر می‌رسد که باهم می‌آیند. در «نرگس، مروارید، و آفتابگردان»، هر سه به‌وضوح از هم جدا هستند. 		ResponseSpeech (TTS)
Our most popular ones include yellow roses, daffodils, daisies, and sunflowers.

ResponseText
محبوب‌ترین گل‌های ما شامل رز زرد، نرگس، مروارید، و آفتابگردان است. 		ResponseSpeech (TTS)
محبوب‌ترین آن‌ها شامل رز زرد، نرگس، مروارید و آفتابگردان است.

ResponseText
محبوب‌ترین گل‌های ما شامل رز زرد، نرگس، مروارید، و آفتابگردان است.
اعداد
به‌جای نوشتار از اعداد استفاده کن تا محتوای دیداری با یک نگاه قابل‌فهم‌تر شود. 		ResponseSpeech (تبدیل نوشتار به گفتار)
فشار خون شما ۱۰۰ روی ۸۰ است.

ResponseText
فشار خون شما ۱۰۰ روی ۸۰ است. 		ResponseSpeech (تبدیل نوشتار به گفتار)
فشار خون شما ۱۰۰ روی ۸۰ است.

ResponseText
فشار خون شما ۱۰۰ روی ۸۰ است.
نمادها
به‌جای نوشتار، از نمادهای تخصصی استفاده کنید تا محتوای بصری سریع‌تر قابل‌فهم باشد. 		ResponseSpeech (تبدیل نوشتار به گفتار)
آخرین خریدتان ۲۴٫۶۵ دلار بود.

ResponseText
آخرین خریدتان ۲۴٫۶۵ دلار بود. 		ResponseSpeech (تبدیل نوشتار به گفتار)
آخرین خریدتان بیست‌وچهار دلار و شصت‌وپنج سنت بود.

ResponseText
آخرین خریدتان بیست‌وچهار دلار و شصت‌وپنج سنت بود.
از تعارفات بپرهیزید
تعارفات باعث می‌شود پاسخ‌ها دور از ذهن و رسمی به‌نظر برسند. آن‌ها را کنار بگذارید و مکالمه را دوستانه و غیررسمی نگه دارید. 		ResponseSpeech (تبدیل نوشتار به گفتار)
سفارشتان تحویل داده شد.

ResponseText
سفارشتان تحویل داده شد. 		ResponseSpeech (TTS)
بله، می‌توانم به شما بگویم. سفارشتان تحویل داده شد.

ResponseText
حتماً، می‌توانم به شما بگویم. سفارشتان تحویل داده شد.
از علامت تعجب استفاده نکنید
ممکن است به‌عنوان فریاد زدن تلقی شود. 		ResponseSpeech (تبدیل نوشتار به گفتار)
امروز ۱٫۵ مایل دویدید.

ResponseText
امروز ۱٫۵ مایل دویدید. 		ResponseSpeech (تبدیل نوشتار به گفتار)
امروز ۱٫۵ مایل دویدید!

ResponseText
امروز ۱٫۵ مایل دویدید!
زمان
از عدد استفاده کنید: «5:15» به‌جای «five-fifteen» یا «quarter after five». برای ساعت ۱۲ ساعته، از «قبل‌ازظهر» یا «بعدازظهر» استفاده کنید. 		ResponseSpeech (TTS)
Your delivery should arrive by 8:15 AM.‎ (محموله شما باید تا ساعت ۸:۱۵ صبح برسد.)

ResponseText
Your delivery should arrive by 8:15 AM.‎ (محموله شما باید تا ساعت ۸:۱۵ صبح برسد.) 		ResponseSpeech (تبدیل نوشتار به گفتار)
سفارشتان باید تا ساعت ۸:۱۵ صبح امروز برسد.

ResponseText
سفارشتان باید تا ساعت ۸:۱۵ صبح امروز برسد.
تک‌گویی نکنید
اطلاعات مفیدی ارائه کن، اما پاسخ‌ها را مختصر نگه دار. بدون مزیت واضح برای کاربر، وارد جزئیات سخت‌گیرانه نشوید. 		ResponseSpeech (TTS)
ماه گذشته ۱۵۹ ساعت انرژی مصرف کردید.

ResponseText
ماه گذشته ۱۵۹ ساعت از انرژی استفاده کردید. 		ResponseSpeech (تبدیل نوشتار به گفتار)
صرفه‌جویی در مصرف انرژی برای سیاره و محیط‌زیست بسیار مهم است. ماه گذشته ۱۵۹ ساعت انرژی مصرف کردید. در این ماه، ۵۸ ساعت از انرژی استفاده کرده‌اید.

ResponseText
صرفه‌جویی در مصرف انرژی برای سیاره و محیط زیست بسیار مهم است. ماه گذشته ۱۵۹ ساعت انرژی مصرف کردید. در این ماه، ۵۸ ساعت انرژی مصرف کرده‌اید.
از کلمات کوتاه و ساده استفاده کنید
زبان ساده و روان بیشترین جذابیت را دارد و باعث می‌شود برای افراد با هر پیشینه‌ای قابل‌فهم باشد. 		ResponseSpeech (تبدیل نوشتار به گفتار)
آخرین خوانش قند خون شما ۱۲۶ بود.

ResponseText
آخرین خوانش قند خونتان ۱۲۶ میلی‌گرم بر دسی‌لیتر بود. 		ResponseSpeech (نوشتار به گفتار)
سطح قند خون یکی مانده به آخر ۱۲۶ بود.

ResponseText
سطح قند خون یکی مانده به آخر ۱۲۶ بود.

سنجاق کردن راه‌انداز

کتابخانه «افزونه ابزاره‌ها» امکان نمایش دکمه افزودن این ابزاره را با ابزاره شما در «دستیار» فراهم می‌کند. برای فعال کردن سنجاق کردن، تعریف گیرنده زیر را به AndroidManifest.xml اضافه کنید:

<application>
  <receiver android:name="com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetBroadcastReceiver"
    android:exported="false">
    <intent-filter>
      <action android:name="com.google.assistant.appactions.widgets.COMPLETE_PIN_APP_WIDGET" />
    </intent-filter>
  </receiver>
  <service
    android:name=
    "com.google.assistant.appactions.widgets.pinappwidget.PinAppWidgetService"
    android:enabled="true"
    android:exported="true">
    <intent-filter>
      <action
        android:name="com.google.assistant.appactions.widgets.PIN_APP_WIDGET" />
    </intent-filter>
  </service>
</application>

دردسترس بودن فهرست موجودی

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

موجودی درون‌خطی

کد زیر از یک فایل نمونه shortcuts.xml نشان‌دهنده یک START_EXERCISE قابلیت BII پیکربندی‌شده برای موجودی درون‌خطی و اجرای ابزاره است:

<capability
  android:name="actions.intent.START_EXERCISE">
  <app-widget
    android:identifier="START_EXERCISE_1"
    android:targetClass="com.example.exampleapp.StartExerciseAppWidgetProvider">
    <parameter
      android:name="exercise.name"
      android:key="exerciseName"
      app:shortcutMatchRequired="true">
    </parameter>
  </app-widget>
</capability>

<shortcut android:shortcutId="RunningShortcut">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetClass="com.example.exampleapp.StartExcerciseActivity" />
  <capability-binding
    android:capability="actions.intent.START_EXERCISE"
    android:parameter="exercise.name"
    android:value="running;runs" />
</shortcut>

در نمونه قبلی، وقتی کاربر این قابلیت را با گفتن «Start running with ExampleApp» به «دستیار» فعال می‌کند، بسته گزینه برای برآورده‌سازی <app-widget> حاوی جفت کلید-مقدار زیر است:

  • کلید = “exerciseName”
  • مقدار = “RunningShortcut”

موجودی وب

کد زیر از یک فایل نمونه shortcuts.xml قابلیتی را نشان می‌دهد که برای موجودی وب و برآورده‌سازی ابزاره فعال شده است:

<shortcuts>
  <capability
    android:name="actions.intent.START_EXERCISE">
    <app-widget
      android:identifier="START_EXERCISE_1"
      android:targetClass="com.example.exampleapp.CreateTaxiAppWidgetProvider">
      <parameter
        android:name="exercise.name"
        android:key="exerciseName"
        android:mimeType="text/*">
        <data android:pathPattern="https://exampleapp.com/exercise/.*" />
      </parameter>
    </app-widget>
  </capability>
</shortcuts>

آزمایش کنش‌های برنامه

برای آزمایش کردن ابزاره‌ها در دستگاه فیزیکی یا مجازی، از «ابزار آزمایش کنش‌های برنامه» استفاده کنید که یکی از ویژگی‌های افزونه «دستیار Google» برای Android Studio است. برای استفاده از ابزار آزمایش، این مراحل را دنبال کنید:

  1. دستگاه آزمایشی‌تان را درحالی‌که برنامه‌تان درحال اجرا است متصل کنید.
  2. در «استودیو Android»، به ابزارها > کنش‌های برنامه > ابزار آزمایش کنش‌های برنامه بروید.
  3. روی ساختن پیش‌نمایش کلیک کنید.
  4. بااستفاده از Android Studio، برنامه‌تان را در دستگاه آزمایشی‌تان اجرا کنید.
  5. برای آزمایش «کنش برنامه»، از برنامه «دستیار» در دستگاه آزمایشی‌تان استفاده کنید. برای مثال، می‌توانید چیزی شبیه به این بگویید: «Ok Google، این هفته چند مایل در ExampleApp دویده‌ام؟»
  6. رفتار برنامه‌تان را مشاهده کنید یا از اشکال‌زدای Android Studio استفاده کنید تا نتیجه کنش موردنظر را درستی‌سنجی کنید.

دستورالعمل‌های کیفیت

این بخش الزامات کلیدی و روال‌های مطلوب را هنگام ادغام «کنش‌های برنامه» با ابزاره‌ها برجسته می‌کند.

محتوا در ابزاره‌ها

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

رسیدگی به اصالت‌سنجی

  • (الزامی) در جایی که اصالت‌سنجی کاربر برای تکمیل جریان کاربر لازم است، ابزاره‌ای را برگردانید که توضیح می‌دهد کاربر باید در برنامه ادامه دهد. اصالت‌سنجی کاربر درون‌خطی در «دستیار Google» برای «کنش‌های برنامه» پشتیبانی نمی‌شود.
  • اگر کاربران به برنامه شما اجازه دهند داده‌ها را بااستفاده از ابزاره‌ها نشان دهد، می‌توانید ابزاره خطایی را در زمان اجرا برای کاربران غیرمجاز برگردانید.

مقصودهای جایگزین

  • (الزامی) در shortcuts.xml، همیشه علاوه‌بر اجرای ابزاره برای یک قابلیت خاص، یک جایگزین <intent> ارائه دهید. قصد جایگزین عنصر <intent> بدون مقادیر الزامی <parameter> است.

    این کار به «دستیار» امکان می‌دهد وقتی پُرسمان کاربر حاوی پارامترهای لازم برای دیگر عناصر اجرای تعریف‌شده در قابلیت نیست، کنشی را اجرا کند. استثنای این مورد زمانی است که هیچ پارامتر الزامی‌ای برای آن قابلیت وجود نداشته باشد، که در این صورت فقط اجرای ابزاره لازم است.

  • از قصد بازگشتی برای باز کردن برنامه در صفحه مربوطه استفاده کنید، نه صفحه اصلی.

کد زیر از یک نمونه فایل shortcuts.xml نشان‌دهنده یک <capability> با یک <intent> جایگزین است که از یک <app-widget> برآورده‌سازی اصلی پشتیبانی می‌کند:

<shortcuts>
  <capability
    android:name="actions.intent.CREATE_TAXI_RESERVATION">
    <!-- Widget with required parameter, specified using the "android:required" attribute. -->
    <app-widget
      android:identifier="CREATE_TAXI_RESERVATION_1"
      android:targetClass="com.example.myapplication.CreateTaxiAppWidgetProvider">
      <parameter
        android:name="taxiReservation.dropoffLocation.name"
        android:key="dropoff"
        android:required="true">
      </parameter>
    </app-widget>
    <!-- Fallback intent with no parameters required to successfully execute. -->
    <intent
      android:identifier="CREATE_TAXI_RESERVATION_3"
      android:action="myapplication.intent.CREATE_TAXI_RESERVATION_1"
      android:targetClass="com.example.myapplication.TaxiReservationActivity">
    </intent>
  </capability>
</shortcuts>

شفاف‌سازی داده‌های Google Play

این بخش داده‌های کاربر نهایی را که توسط جدیدترین نسخه کتابخانه «افزونه ابزاره‌ها» جمع‌آوری شده است فهرست می‌کند.

این کیت توسعه نرم‌افزار پاسخ‌های نوشتار به گفتار (TTS) ارائه‌شده توسط توسعه‌دهنده را ارسال می‌کند که توسط «دستیار Google» بااستفاده از فناوری گفتار «دستیار» به کاربر اعلام می‌شود. این اطلاعات توسط Google ذخیره نمی‌شود.

کنش‌های برنامه همچنین ممکن است فراداده برنامه مشتری را برای اهداف زیر جمع‌آوری کند:

  • برای نظارت بر نرخ استفاده از نسخه‌های مختلف کیت توسعه نرم‌افزار.
  • برای کمی‌سازی استفاده از ویژگی کیت توسعه نرم‌افزار در برنامه‌ها.