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

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

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

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

در این مثال، عبارت «تمرین هوی متال من را شروع کن» را پیشنهاد می‌دهید. کاربر پیشنهاد را می‌پذیرد و سپس می‌تواند میان‌بر را با گفتن «Ok Google، تمرین هوی متال من را شروع کن» راه‌اندازی کند.

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

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

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

  • ‫createShortcutSuggestionIntent: قصدی را برمی‌گرداند که می‌توانید از آن برای درخواست از کاربر برای ایجاد میان‌بر پیشنهادی استفاده کنید.

  • createShortcutSettingsIntent: قصدی را برمی‌گرداند که می‌توانید از آن برای انتقال کاربر به تنظیمات «میان‌بر دستیار» برای برنامه‌تان استفاده کنید.

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

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

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

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

  • برنامه Android خود را به استفاده از «کنش‌های برنامه» گسترش دهید.

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

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

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

پیش‌نیازهای دستگاه

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

  • جدیدترین نسخه برنامه Google

  • ‫Android نسخه ۶.۰ (سطح میانای برنامه‌سازی کاربردی ۲۳) یا بالاتر

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

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

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

برای پیاده‌سازی پیشنهادها، باید فایل 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 درستی‌سنجی می‌شوند. اگر هدفی نامعتبر باشد، استثنایی برگردانده می‌شود.

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

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

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

      کاتلین

      val exercise = mapOf(
    "@type" to "Exercise",
    "@context" to "http://schema.googleapis.com",
    "name" to "Running",
)

val appShortcutIntent = AppShortcutIntent.builder()
    .setIntentName("actions.intent.START_EXERCISE")
    .setPackageName("my.app.package")
    .setIntentParamName("exercise")
    .setIntentParamValue(exercise)
    .build()

      جاوا

        Map<String, Object> exercise = new HashMap<>();
  exercise.put("@type", "Exercise");
  menuItem.put("@context", "http://schema.googleapis.com");
  menuItem.put("name", "Running");

  AppShortcutIntent appShortcutIntent =
      AppShortcutIntent.builder()
          .setIntentName("actions.intent.START_EXERCISE")
          .setPackageName("my.app.package")
          .setIntentParamName("exercise")
          .setIntentParamValue(exercise)
          .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: یک هدف Android را برمی‌گرداند که شما از آن برای شروع فعالیت پیشنهاد میان‌بر در زمینه برنامه‌تان استفاده می‌کنید.

      کاتلین

      val exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand(PHRASE: String)
    .build()

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

      جاوا

        AppShortcutSuggestion exerciseShortcut =
      AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand(PHRASE: String)
          .build();

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

      در این مثال، PHRASE عبارتی است که می‌خواهید به‌عنوان میان‌بر به کاربر پیشنهاد دهید. برای مثال، اگر می‌خواهید کاربر «Ok Google، دویدن را شروع کن» را به‌عنوان میان‌بر بگوید، PHRASE را با "start a run" جایگزین کنید.

      کاتلین

      val exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand("start a run")
    .build()

      جاوا

      AppShortcutSuggestion exerciseShortcut =
    AppShortcutSuggestion.builder()
        .setAppShortcutIntent(appShortcutIntent)
        .setCommand("start a run")
        .build();

    • ‫createShortcutSettingsIntent: یک هدف Android را برمی‌گرداند که کاربر را به میان‌بر رابط تنظیمات در برنامه «دستیار» منتقل می‌کند.

      کاتلین

      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: Cannot bind to service"

به‌دلیل فیلتر کردن رؤیت‌پذیری بسته، ممکن است «GoogleInstallationUnsupportedException: Cannot bind to service» (نمی‌توان به سرویس متصل شد) در 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» ارسال می‌کنید.

«میان‌برهای کاربر دریافت نشد»

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

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

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

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