برای تبلیغ ویژگی‌های برنامه‌تان و آسان‌تر کردن استفاده از آن، می‌توانید میان‌برهای «دستیار» را به کاربران پیشنهاد دهید. میان‌برهای «دستیار» عبارت‌های کوتاهی هستند که کاربر می‌تواند برای راه‌اندازی عملکرد در برنامه شما بیان کند.
اگرچه میان‌برهای «دستیار» را کاربران می‌توانند به‌صورت دستی ایجاد کنند، In-App Promo SDK به شما امکان می‌دهد میان‌برهای «دستیار» را به‌طور فعال پیشنهاد و پیاده‌سازی کنید. با پیشنهاد دادن میان‌برها، مسیرهای واضح و ساده‌ای را برای بازگشت به فعالیت‌های دلخواه کاربران در برنامه‌تان به آن‌ها ارائه می‌دهید، بدون اینکه نیاز به تلاش اضافی برای راه‌اندازی میان‌برها باشد.
برای مثال، اگر کاربری در برنامه موسیقی شما «تمرین با موسیقی هوی متال» را جستجو کند، می‌توانید میان‌بر «دستیار» را مستقیماً به آن نتایج جستجو در آینده پیشنهاد دهید. وقتی میان‌بری را پیشنهاد می‌کنید، پیام‌واره‌ای در برنامه‌تان ظاهر می‌شود که عبارت پیشنهادی برای میان‌بر را نمایش می‌دهد و از کاربر می‌پرسد که آیا میان‌بر می‌تواند ایجاد شود یا نه.
در این مثال، عبارت «تمرین هوی متال من را شروع کن» را پیشنهاد می‌کنید. کاربر پیشنهاد را می‌پذیرد و سپس می‌تواند میان‌بر را با گفتن «Ok Google، تمرین هوی متال من را شروع کن» راه‌اندازی کند.
برای اطلاعات بیشتر درباره راه‌های افزایش مخاطبان برنامه‌تان، به رشد برنامه با کنش‌های برنامه مراجعه کنید.
«کیت توسعه نرم‌افزار تبلیغ درون‌برنامه» روش‌های زیر را ارائه می‌دهد:
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 خود را به‌روز کنید، کلاینت پیشنهادها را راه‌اندازی کنید، و سپس پیشنهادهایی را که می‌خواهید به کاربران ارائه دهید تعریف کنید.
وابستگی کتابخانه را به فایل
build.gradleاضافه کنید.dependencies { ... implementation "com.google.assistant.appactions:suggestions:1.0.0" }نمونه‌ای از
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(اختیاری) مجری سفارشی برای اجرای تکالیف ناهمگام است. اگر ارائه نشود، کیت توسعه نرم‌افزار از مجری تک‌رشته‌ای برای تکلیف استفاده می‌کند.
از روش
lookupShortcutاستفاده کنید تا تعیین کنید آیا میان‌بری که می‌خواهید پیشنهاد دهید معتبر است یا نه، و به‌صورت اختیاری، آیا میان‌بر ازقبل وجود دارد یا نه.ایجاد هدف میان‌بر برنامه. قصد میان‌بر نشان‌دهنده میان‌بری است که می‌خواهید به کاربر پیشنهاد دهید. مثال زیر قصدی برای میان‌بر شروع تمرین ایجاد می‌کند.
کاتلین
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();
هدف میان‌بر را به روش
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));
پیشنهاد را بااستفاده از قصد میان‌بر ایجاد کنید. دو روش برای ایجاد پیشنهاد وجود دارد:
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); );
بااستفاده از هدف Android که در مرحله قبلی برگردانده شده است،
startActivityرا فراخوانی کنید.
عیب‌یابی پیشنهادها
این بخش مشکلات و استثناهایی را که ممکن است هنگام پیشنهاد میان‌برها با آن‌ها مواجه شوید فهرست می‌کند.
"GoogleInstallationUnsupportedException: Cannot bind to service"
به‌دلیل
فیلتر کردن رؤیت‌پذیری بسته،
ممکن است «GoogleInstallationUnsupportedException: نمی‌توان به سرویس متصل شد» در
Android 11 و نسخه‌های جدیدتر اتفاق بیفتد. مطمئن شوید که com.google.android.googlequicksearchbox
در برچسب <queries> در مانیفست شما گنجانده شده باشد:
<manifest ...>
<queries>
<package android:name="com.google.android.googlequicksearchbox" />
</queries>
...
</manifest>
«امضای APK درستی‌سنجی نشد»
اگر برنامه تولیدتان را به‌صورت app bundle ارسال نکنید، ممکن است خطای زیر روی دهد:
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» ارسال می‌کنید.
«میان‌برهای کاربر دریافت نشد»
پیام خطای «دریافت میان‌برهای کاربر ناموفق بود» ممکن است زمانی اتفاق بیفتد که اخیراً حسابی به دستگاه اضافه کرده باشید و داده‌های میان‌بر حساب جدید هنوز در دستگاه ذخیره نشده باشد.
برای همگام‌سازی داده‌های میان‌بر در دستگاه، میان‌بر «دستیار» را بااستفاده از میانای برنامه «دستیار» اضافه یا حذف کنید.
فعالیت ایجاد میان‌بر بلافاصله بدون نشان دادن هیچ محتوایی بسته می‌شود
اگر پیش‌نمایشی بااستفاده از «ابزار آزمایش کنش‌های برنامه» ایجاد نکنید یا اگر پیش‌نمایش منقضی شود، فعالیت ایجاد میان‌بر می‌تواند بدون نمایش هیچ محتوایی بسته شود. پیش‌نمایش را به‌روز کنید و دوباره امتحان کنید.