قصد ازپیش‌تعریف‌شده برای «کنش‌های برنامه»

قصد ازپیش‌ساخته (BII) به برنامه شما امکان می‌دهد قابلیت‌های برآورده‌سازی خود را به Google اعلام کند. با اعلام قابلیت‌ها در فایل shortcuts.xml و نگاشت پارامترهای هدف به تحقق، این امکان را برای «دستیار Google» فراهم می‌کنید که برنامه‌تان را در پاسخ به یک پُرسمان در صفحه خاصی راه‌اندازی کند تا کاربر بتواند کاری را تکمیل کند.

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

بسیاری از «قصدهای درون‌ساخت» الزامات و توصیه‌های خاصی برای پیاده‌سازی دارند. این الزامات و توصیه‌ها به برنامه شما کمک می‌کند بهترین تجربه ممکن را به کاربران ارائه دهد.

شکل ۱. START_EXERCISE BII را با پُرسمان صوتی به «دستیار» فراخوانی کنید.
شکل ۲. برنامه را در صفحه خاصی راه‌اندازی کنید تا تکلیف START_EXERCISE شروع شود.
شکل ۳. نمایش ابزاره در پاسخ به پُرسمان.

​

پیاده‌سازی «هدف‌های داخلی برنامه» و مدیریت پارامترهای هدف

برای «کنش‌های برنامه»، قابلیت‌ها را اعلام می‌کنید و پارامترهای BII را در فایل shortcuts.xml مدیریت می‌کنید. برای پیاده‌سازی «هدف درون‌ساخت» و مدیریت پارامترهای آن، این مراحل را دنبال کنید:

  1. ‫capability را با «هدف داخلی» انتخاب‌شده اعلام کنید.
  2. برای هر فیلد اطلاعات شخصی حساس که می‌خواهید اضافه کنید، عناصر parameter تودرتو اضافه کنید.
    1. اگر از targetClass یا targetPackage استفاده می‌کنید، آن‌ها را بااستفاده از نامی که انتخاب می‌کنید به هدف Android extras نگاشت کنید.
    2. اگر از نشانی وب پیوند عمیق استفاده می‌کنید، از پارامترهای نام‌گذاری‌شده در رشته پُرسمان الگوی نشانی وب استفاده کنید.

برای مدیریت پارامتر «هدف داخلی»، پارامتر «هدف داخلی» را به پارامتر متناظر هدف صریح Android در capability خود نگاشت کنید. سپس می‌توانید از مقدار آن در برنامه‌تان استفاده کنید. برنامه‌تان ملزم به مدیریت پارامترهای «هدف‌های داخلی برنامه» نیست. بااین‌حال، سعی کنید فیلدهای داده‌ای را که در مرجع قصد ازپیش‌تعریف‌شده به‌عنوان «توصیه‌شده» علامت‌گذاری شده‌اند مدیریت کنید.

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

برای مثال، قصد actions.intent.START_EXERCISE توصیه می‌کند که برنامه‌تان پارامتر BII‏ exercise.name را مدیریت کند، اما می‌توانید BII را بدون پارامتر در برنامه‌تان پیاده‌سازی کنید. اگر بخواهید پُرسمان‌های کاربر را بدون نام تمرین خاصی مدیریت کنید، ممکن است این کار را انجام دهید، مانند «از برنامه نمونه بخواهید ردیابی تمرین را شروع کند.»

قطعه زیر درصورتی‌که پارامترها در پُرسمان کاربر گنجانده نشده باشد، به اجرایی بدون پارامترهای الزامی برمی‌گردد:

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">

    <capability android:name="actions.intent.START_EXERCISE">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetClass="com.example.myapplication.Activity1"
            android:targetPackage="com.example.myapplication">
            <parameter
                android:name="exercise.name"
                android:key="exerciseType"
                android:required="true"
                />
        </intent>
        <intent
            android:action="android.intent.action.VIEW"
            android:targetClass="com.example.myapplication.Activity2">
        </intent>
    </capability>
</shortcuts>

«دستیار Google» نهایت تلاش خود را می‌کند تا هنگام برگرداندن مقادیر پارامتر به برنامه شما، مرتبط‌ترین اطلاعات را به کاربر ارائه دهد. برای مثال، پرسمان‌های کاربر برای سفارش پیتزا از برنامه تلفن همراه Example Restaurant همیشه شامل مکان نیست. برای ارائه خدمات بهتر به کاربر، «دستیار» ممکن است مقادیر طول و عرض جغرافیایی نزدیک‌ترین «رستوران نمونه» را به آن برنامه ارائه دهد.

به‌عنوان یک الزام اضافی، نباید برنامه‌تان مستقیماً کنشی را انجام دهد که وضعیت کاربر را در دنیای واقعی تغییر دهد (برای مثال، انتقال پول، ثبت سفارش، یا ارسال پیام) بدون اینکه ابتدا کنش را با کاربر تأیید کند.

ابهام‌زدایی

آرگومان‌هایی که ازطریق <url-parameter> یا موارد اضافی هدف به برنامه‌تان ارسال می‌شوند ممکن است موردی را که می‌خواهید به کاربر نشان دهید به‌طور منحصربه‌فرد شناسایی نکنند. در این مورد، از مقدار آرگومان به‌عنوان آرگومان جستجو استفاده کنید و کاربر را به صفحه جستجوی برنامه ببرید. آن‌ها می‌توانند ابهام‌زدایی کنند و مورد درست را انتخاب کنند.

برای مثال، اگر پُرسمان کاربر «سفارش از رستوران نمونه» برای BII ORDER_MENU_ITEM باشد، می‌توانید فهرستی از رستوران‌هایی را که نامشان با عبارت "Example Restaurant" مطابقت دارد به کاربر ارائه دهید.

پشتیبانی از زبان و منطقه زبانی

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