با استفاده از In-App Promo SDK میانبرهایی را پیشنهاد دهید

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

اگرچه میانبرهای Assistant را می توان به صورت دستی توسط کاربران ایجاد کرد، اما In-App Promo SDK به شما این امکان را می دهد که به طور فعال میانبرهای Assistant را پیشنهاد و پیاده سازی کنید. با پیشنهاد میانبرها، مسیرهای ساده و واضحی را به کاربران خود می‌دهید تا به فعالیت‌های مورد علاقه‌شان در برنامه‌تان بازگردند، بدون اینکه تلاش بیشتری برای راه‌اندازی میان‌برها انجام دهید.

به عنوان مثال، اگر کاربری در برنامه موسیقی شما جستجوی "هی متال تمرین" را انجام دهد، ممکن است در آینده یک میانبر دستیار را مستقیماً به آن نتایج جستجو پیشنهاد دهید. هنگامی که یک میانبر را پیشنهاد می کنید، یک پیام در برنامه شما ظاهر می شود که عبارت پیشنهادی برای میانبر را نمایش می دهد و از کاربر می پرسد که آیا می توان میانبر را ایجاد کرد یا خیر.

در این مثال شما عبارت "شروع تمرین هوی متال من" را پیشنهاد می کنید. کاربر پیشنهاد را می پذیرد و سپس می تواند میانبر را با گفتن «Hey Google, start my heavy metal workout» راه اندازی کند.

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

In-App Promo SDK روش های زیر را ارائه می دهد:

• lookupShortcut : بررسی می کند که آیا میانبری که می خواهید پیشنهاد دهید از قبل وجود داشته باشد یا خیر. این روش همچنین مشکلاتی را که از ایجاد میانبر جلوگیری می کند، بررسی می کند. اگر میانبر نمی تواند ایجاد شود، lookupShortcut دلایل آن را برمی گرداند.

• createShortcutSuggestionIntent : یک intent را برمی گرداند که می توانید از آن برای ایجاد میانبر پیشنهادی از کاربر استفاده کنید.

• createShortcutSettingsIntent : هدفی را برمی گرداند که می توانید از آن برای انتقال کاربر به تنظیمات میانبر Assistant برای برنامه خود استفاده کنید.

پیش نیازها و محدودیت ها

این بخش پیش نیازها و الزامات استفاده از پیشنهادات و همچنین محدودیت هایی را که ممکن است با آن مواجه شوید، توضیح می دهد.

پیش نیازهای توسعه

برای استفاده از پیشنهادات، محیط توسعه شما باید پیش نیازهای زیر را داشته باشد.

• برنامه Android خود را برای استفاده از App Actions گسترش دهید.

• com.google.android.googlequicksearchbox در تگ <queries> در مانیفست خود قرار دهید. به عنوان مثال:

  <manifest ...>
    <queries>
      <package android:name="com.google.android.googlequicksearchbox" />
    </queries>
    ...
  </manifest>
  

• از Android App Bundles برای انتشار برنامه های خود استفاده کنید.

الزامات دستگاه

برای آزمایش پیشنهادات خود در دستگاه، دستگاه شما باید موارد زیر را نصب کرده باشد.

• آخرین نسخه برنامه Google

• Android 6.0 (سطح API 23) یا بالاتر

محدودیت های شناخته شده

پیشنهادات فقط به زبان انگلیسی پشتیبانی می شوند. برای اینکه کاربران بتوانند پیشنهادات شما را ببینند، باید زبان دستیار در دستگاه خود را روی انگلیسی تنظیم کنند.

پیشنهادات را اجرا کنید

برای پیاده سازی پیشنهادات، باید فایل build.gradle خود را به روز کنید، سرویس گیرنده پیشنهادات را راه اندازی کنید، و سپس پیشنهاداتی را که می خواهید به کاربران بدهید تعریف کنید.

1. وابستگی کتابخانه را به فایل build.gradle خود اضافه کنید.

   dependencies {
     ...
     implementation "com.google.assistant.appactions:suggestions:1.0.0"
   }
   

2. یک نمونه از AssistantShortcutSuggestionsClient را تعریف کنید.

   کاتلین

   val shortcutsClient =
     AssistantShortcutSuggestionsClient.builder()
       .setContext(CONTEXT: Context)
       .setVerifyIntents(VERIFY_INTENTS: Boolean)
       .setCustomExecutor(CUSTOM_EXECUTOR: Object)
       .build()
   

   جاوا

   AssistantShortcutSuggestionsClient shortcutsClient =
     AssistantShortcutSuggestionsClient.builder()
       .setContext(CONTEXT: Context)
       .setVerifyIntents(VERIFY_INTENTS: Boolean)
       .setCustomExecutor(CUSTOM_EXECUTOR: Object)
       .build();
   

   در این مثال:

   • CONTEXT (الزامی) زمینه برنامه است.

   • VERIFY_INTENTS (الزامی) تعیین می کند که آیا هنگام پیشنهاد میانبرها به کاربران، هر هدف ایجاد شده تأیید شود. وقتی true ، مقاصد ایجاد شده توسط AssistantShortcutSuggestionsClient تأیید می شوند. اگر یک intent نامعتبر باشد، یک استثنا برگردانده می شود.

   • CUSTOM_EXECUTOR (اختیاری) یک مجری سفارشی برای اجرای کارهای ناهمزمان است. اگر ارائه نشود، SDK از یک مجری تک رشته ای برای کار استفاده می کند.

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

   1. یک هدف میانبر برنامه ایجاد کنید. قصد میانبر نشان دهنده میانبری است که می خواهید به کاربر پیشنهاد دهید. مثال زیر قصدی برای میانبر برای سفارش نوشیدنی ایجاد می کند.

      کاتلین

      val menuItem = mapOf(
          "@type" to "MenuItem",
          "@context" to "http://schema.googleapis.com",
          "name" to "Fresh Lemon Honey Jasmine Green Tea",
      )
      
      val appShortcutIntent = AppShortcutIntent.builder()
          .setIntentName("actions.intent.ORDER_MENU_ITEM")
          .setPackageName("my.app.package")
          .setIntentParamName("menuItem")
          .setIntentParamValue(menuItem)
          .build()
       

      جاوا

        Map<String, Object> menuItem = new HashMap<>();
        menuItem.put("@type", "MenuItem");
        menuItem.put("@context", "http://schema.googleapis.com");
        menuItem.put("name", "Fresh Lemon Honey Jasmine Green Tea");
      
        AppShortcutIntent appShortcutIntent =
            AppShortcutIntent.builder()
                .setIntentName("actions.intent.ORDER_MENU_ITEM")
                .setPackageName("my.app.package")
                .setIntentParamName("menuItem")
                .setIntentParamValue(menuItem)
                .build();
       

   2. هدف میانبر را به متد lookupShortcut ارسال کنید.

      کاتلین

      val result = shortcutsClient.lookupShortcut(appShortcutIntent).await()
      if (!result.isShortcutPresent) {
          // App can suggest creating a shortcut
      } else {
          // App can remind the user that they have a shortcut for this app action
      }
      

      جاوا

      shortcutsClient.lookupShortcut(appShortcutIntent)
        .addOnSuccessListener(shortcutLookupResult -> {
          if (!shortcutLookupResult.isShortcutPresent()) {
            // App can suggest creating a shortcut
          } else {
            // App can remind the user that they have a shortcut for this app action
          }
        })
        .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));
      

4. پیشنهاد را با استفاده از قصد میانبر ایجاد کنید. برای ایجاد یک پیشنهاد می توانید از دو روش استفاده کنید:

   • createShortcutSuggestionIntent : یک intent Android را برمی‌گرداند که از آن برای شروع فعالیت پیشنهاد میانبر در زمینه برنامه خود استفاده می‌کنید.

     کاتلین

     val orderShortcut = AppShortcutSuggestion.builder()
         .setAppShortcutIntent(appShortcutIntent)
         .setCommand(PHRASE: String)
         .build()
     
     val intent = shortcutsClient.createShortcutSuggestionIntent(orderShortcut).await()
     application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
     

     جاوا

       AppShortcutSuggestion orderShortcut =
           AppShortcutSuggestion.builder()
               .setAppShortcutIntent(appShortcutIntent)
               .setCommand(PHRASE: String)
               .build();
     
       shortcutsClient.createShortcutSuggestionIntent(orderShortcut)
           .addOnSuccessListener(intent ->
               getApplication().startActivity(
                   intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
           )
           .addOnFailureListener(e ->
               Log.e(TAG, "Failed to get shortcut suggestion intent", e);
           );
     

     در این مثال، PHRASE عبارتی است که می خواهید به عنوان میانبر به کاربر پیشنهاد دهید. برای مثال، اگر می‌خواهید کاربر به‌عنوان میان‌بر بگوید «Hey Google, order my bubble tea» را با "order my bubble tea" جایگزین PHRASE کنید.

     کاتلین

     val orderShortcut = AppShortcutSuggestion.builder()
         .setAppShortcutIntent(appShortcutIntent)
         .setCommand("order my bubble tea")
         .build()
     

     جاوا

     AppShortcutSuggestion orderShortcut =
         AppShortcutSuggestion.builder()
             .setAppShortcutIntent(appShortcutIntent)
             .setCommand("order my bubble tea")
             .build();
     

   • createShortcutSettingsIntent : یک intent Android را برمی گرداند که کاربر را به رابط تنظیمات میانبر در برنامه Assistant منتقل می کند.

     کاتلین

     val intent = shortcutsClient.createShortcutSettingsIntent().await()
     application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
     

     جاوا

       shortcutsClient.createShortcutSettingsIntent()
         .addOnSuccessListener(intent ->
             getApplication().startActivity(
                 intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
         )
         .addOnFailureListener(e ->
             Log.e(TAG, "Failed to get shortcut settings intent", e);
         );
     

5. با استفاده از هدف Android که در مرحله قبل برگردانده شده است، با startActivity تماس بگیرید.

عیب یابی پیشنهادات

این بخش مشکلات و استثناهایی را که ممکن است هنگام پیشنهاد میانبرها با آنها مواجه شوید فهرست می کند.

"GoogleInstallationUnsupportedException: نمی توان به سرویس متصل شد"

به دلیل فیلتر قابلیت مشاهده بسته ، « GoogleInstallationUnsupportedException : نمی‌توان به سرویس متصل شد» ممکن است در Android 11 به بعد اتفاق بیفتد. مطمئن شوید که com.google.android.googlequicksearchbox در تگ <queries> در مانیفست شما گنجانده شده است:

<manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

"تأیید امضای APK انجام نشد"

اگر برنامه تولید خود را به عنوان یک بسته برنامه ارسال نکنید، ممکن است خطای زیر رخ دهد:

Failed to verify the APK signature. If this is a development build, please
make sure to update the preview of your app in App Actions Test Tool.

مطمئن شوید که برنامه خود را به عنوان یک بسته نرم افزاری Android ارسال می کنید .

"دریافت میانبرهای کاربر ناموفق بود"

اگر اخیراً حسابی به دستگاه اضافه کرده باشید و اطلاعات میانبر حساب جدید هنوز در دستگاه ذخیره نشده باشد، پیام خطای «دریافت میانبرهای کاربر ناموفق بود» ممکن است رخ دهد.

برای همگام‌سازی داده‌های میانبر روی دستگاه، میانبر دستیار را با استفاده از رابط برنامه دستیار اضافه یا حذف کنید.

فعالیت ایجاد میانبر بلافاصله بدون نمایش محتوای بسته می شود

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