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

هنگامی که App Actions را برای برنامه Android خود پیاده‌سازی می‌کنید، ممکن است مجبور شوید درخواست‌هایی را که تغییراتی در یک موضوع هستند انجام دهید. به عنوان مثال، فرض کنید برنامه تناسب اندام شما START_EXERCISE هدف داخلی (BII) را اجرا می کند تا به کاربران اجازه دهد طیف وسیعی از تمرینات را با پرسیدن مواردی از دستیار شروع کنند، مانند «Hey Google، اجرا را در Example App شروع کن».

تحقق این هدف مستلزم منطق منطبق درخواست شما برای رسیدگی به هر نوع تمرین است، از جمله تغییراتی مانند "دویدن دویدن"، "دوی سرعت" یا "مسابقه". با افزایش تمرینات پشتیبانی شده، این منطق به سرعت دست و پا گیر می شود.

برای BII های پشتیبانی شده، مانند START_EXERCISE ، می توانید با استفاده از موجودی درون خطی از این منطق تطبیق پیچیده اجتناب کنید. موجودی درون خطی مجموعه‌ای از میانبرهای ثابت Android است که در shortcuts.xml تعریف شده‌اند و ویژگی‌ها و محتوای برنامه شما را نشان می‌دهند.

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

موجودی درون خطی به Google Assistant اجازه می‌دهد مقادیر پارامتر BII را که در طول فراخوانی‌های App Action به برنامه شما ارائه می‌شود، ساده کند.

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

شکل 1. یک نمودار جریان از یک قابلیت START_EXERCISE که از یک موجودی درون خطی برای تفسیر نام تمرینات ارائه شده توسط کاربر برای انواع تمرینات پشتیبانی شده در برنامه استفاده می کند.

توجه: موجودی درون خطی توسط پارامترهای خاصی از BII های خاص پشتیبانی می شود. برای جزئیات، به بخش "در دسترس بودن موجودی بر اساس فیلد" هر BII در مرجع BII مراجعه کنید.

محدودیت ها و جایگزین ها

میانبرهای موجودی درون خطی محدودیت های زیر را دارند:

• محدودیت میانبر: حداکثر 1000 میانبر موجودی درون خطی را می توان برای هر برنامه تعریف کرد.
• محدودیت مترادف: هر میانبر موجودی درون خطی می تواند حداکثر 20 مقدار مترادف داشته باشد.
• تعریف ثابت: میانبرهای موجودی درون خطی به صورت ایستا در shortcuts.xml اعلان می شوند و فقط با انتشار نسخه جدیدی از برنامه شما می توانند برای کاربران شما به روز شوند.

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

• موجودی وب: به «دستیار» اجازه می‌دهد هنگام تطبیق سؤالات کاربر با شناسه‌های محتوای برنامه پشتیبانی‌شده، از محتوای وب عمومی پرس و جو کند. پرس و جوهای موجودی وب به صورت بلادرنگ در طول فراخوانی اتفاق می‌افتند و به شما امکان می‌دهند کاتالوگ‌های محصول، پست‌های رسانه‌های اجتماعی و سایر محتوایی که اغلب به‌روزرسانی می‌شوند را به Assistant گسترش دهید.

• میانبرهای پویا: فهرستی از محتوای برنامه شخصی‌سازی شده را به Assistant گسترش دهید. میانبرهای پویا به کاربران این امکان را می‌دهند که به سرعت اقدامات رایج را تکرار کنند، مانند سفارش مجدد نوشیدنی مورد علاقه خود از یک برنامه سفارش غذا یا کشیدن لیست خرید در یک برنامه یادداشت برداری.

یک موجودی درون خطی ایجاد کنید

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

• Hey Google، اجرا را در Example App شروع کنید.
• هی گوگل، در Example App شروع به دویدن کنید.

در میانبر موجودی درون خطی خود، shortcutId را روی "CARDIO_RUN" تنظیم کرده اید، شناسه تمرین مورد انتظار برنامه شما. سپس "run" و "jog" را به عنوان مترادف های مرتبط با shortcutId مشخص می کنید. سپس، هنگامی که کاربر Action Action شما را با عبارت‌های جستجوی قبلی فعال می‌کند، Assistant از شناسه "CARDIO_RUN" برای پارامتر BII هنگام ایجاد یک هدف تحقق استفاده می‌کند.

قطعه زیر از نمونه فایل app/res/shortcuts.xml این مورد را پیاده سازی می کند:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
    </capability-binding>
</shortcut>

در نمونه قبلی، shortcut موجودی درون خطی، تگ <parameter-binding> را در عنصر <capability-binding> اعلام می‌کند و آن را به پارامتر BII exercise.name که در <capability> تعریف شده است، متصل می‌کند.

منبع آرایه رشته‌ای @array/run_names فهرستی از مترادف‌ها را در res/values/arrays.xml مشخص می‌کند که Assistant آنها را شناسایی کرده و به شناسه مورد "CARDIO_RUN" نگاشت:

<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
  <string-array name="run_names">
    <item>Run</item>
    <item>Jog</item>
    <item>Sprint</item>
  </string-array>
</resources>

هنگامی که یک <url-template> برای قابلیت ارائه می شود، shortcutId برای یک مقدار منطبق در URL تولید شده در مکان نگهدار مربوط به پارامتر درج می شود. کد زیر از فایل نمونه app/res/shortcuts.xml این مورد را پیاده سازی می کند:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://workout{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
</shortcut>

در نمونه قبلی، Assistant پیوند عمیق تحقق myapp://workout?exercise=CARDIO_RUN ایجاد می‌کند.

توجه: موجودی درون خطی حداکثر از یک parameter برای هر عنصر intent تحقق یک capability پشتیبانی می‌کند.

تحقق با استفاده از اهداف میانبر

به‌طور پیش‌فرض، یک میان‌بر همان‌طور که در تگ <capability-binding> میانبر اعلام شده است، کد shortcutId یک مقدار موجودی درون خطی منطبق را با intent capability میان‌بر به آن مقید است، ارائه می‌کند. می توانید به طور متناوب تعیین کنید که یک intent تعریف شده در خود میانبر با افزودن یک تگ <shortcut-fulfillment> به capability مورد استفاده قرار گیرد.

کد زیر از فایل نمونه app/res/shortcuts.xml اجرای میانبر را اجرا می کند:

<capability android:name="actions.intent.START_EXERCISE">
  <shortcut-fulfillment>
    <parameter android:name="exercise.name"/>
  </shortcut-fulfillment>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
  <intent android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</shortcut>

در نمونه قبلی، اگر پرس و جوی کاربر با مقدار موجودی درون خطی پارامتر exercise.name مطابقت داشته باشد، تگ <shortcut-fulfillment> مشخص می کند که intent میانبر محدود برای تکمیل استفاده می شود.

توجه: هر موجودی درون خطی <shortcut> که برای انجام میانبر در نظر گرفته شده است باید حاوی <intent> باشد. برای جلوگیری از خطاهای انجام، از میانبرهایی که حاوی عناصر هدف نیستند برای انجام میانبر استفاده نکنید.

موجودی درون خطی برای ویژگی برنامه باز BII

در حالی که موجودی درون خطی معمولاً یک قابلیت اختیاری برای BII هایی است که از آن پشتیبانی می کنند، برای BII های خاصی مانند OPEN_APP_FEATURE ، لازم است. این BII که معمولاً مورد استفاده قرار می‌گیرد به کاربران امکان می‌دهد با استفاده از Assistant به ویژگی‌های برنامه خاص پیوند عمیق بدهند. ویژگی برنامه باز BII به فهرستی درون خطی از نام ویژگی های برنامه نیاز دارد تا قبل از پیوند عمیق کاربر به برنامه، تأیید شود که ویژگی درخواستی کاربر وجود دارد.

کد زیر از یک فایل نمونه app/res/shortcuts.xml این BII را با یک میانبر که نشان دهنده ویژگی وضعیت سفارش برنامه است، پیاده سازی می کند:

<capability android:name="actions.intent.OPEN_APP_FEATURE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="feature"
       android:key="featureParam" />
  </intent>
  <!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="HOME_SCREEN"
       android:key="featureParam" />
  </intent>
</capability>

<!-- Inline inventory for OPEN_APP_FEATURE. -->

<shortcut android:shortcutId="ORDER_STATUS">
  <capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
    <parameter-binding
      android:key="feature"
      android:value="@array/order_status_names" />
    </capability-binding>
</shortcut>

منابع آرایه رشته‌ای در res/values/arrays.xml ، @array/order_status_names ، فهرستی از مترادف‌های این ویژگی را مشخص می‌کند:

<resources>
  <string-array name="order_status_names">
    <item>Order status</item>
    <item>Orders</item>
    <item>Order history</item>
  </string-array>
</resources>

با وجود قابلیت قبلی، Assistant می تواند عبارات مختلفی را برای همان ویژگی انجام دهد:

• "Hey Google، وضعیت سفارش من را در Example App نشان بده."
• "Hey Google، سفارشات من را در Example App نشان بده."
• "Hey Google، سابقه سفارش من را در Example App نشان بده."

موجودی درون خطی را تست کنید

موجودی خود را با بازرسی مقادیر پارامتر BII که Assistant به برنامه شما ارائه می دهد و در عین حال قابلیت های App Action مربوطه را انجام می دهد، آزمایش کنید. موجودی درون خطی با جایگزینی مقدار ارائه شده توسط کاربر یک پارامتر BII محدود به موجودی با shortcutId یک میانبر موجودی درون خطی منطبق کار می کند.

به عنوان مثال، یک قابلیت START_EXERCISE BII ممکن است از یک موجودی درون خطی برای ترجمه پارامتر BII ارائه شده توسط کاربر "run" به شناسه تمرین مربوطه خود، "CARDIO_RUN" استفاده کند.

افزونه Google Assistant به شما امکان می‌دهد تا پیش‌نمایش Inline Inventory App Actions را در Assistant در دستگاه آزمایشی مشاهده کنید. با دنبال کردن مراحل زیر، موجودی خود را با استفاده از افزونه آزمایش کنید:

1. پارامترهای محدود به موجودی قابلیت BII خود را با مقادیر مترادف مرتبط با موجودی درون خطی خود پیکربندی کنید .
2. BII را از افزونه فعال کنید و آن را در دستگاه آزمایشی خود فراخوانی کنید.
3. مقادیر پارامتر حاصل را که Assistant در حین انجام App Action به برنامه شما ارائه می‌دهد، بررسی کنید.