Uygulamanızın özelliklerini tanıtmak ve kullanımını kolaylaştırmak için kullanıcılarınıza Asistan kısayolları önerebilirsiniz. Asistan kısayolları, kullanıcıların uygulamanızın içindeki işlevleri tetiklemek için söyleyebileceği kısa ve öz ifadelerdir.
Asistan kısayolları kullanıcılarınız tarafından manuel olarak oluşturulabilse de Uygulama İçi Tanıtım SDK'sı, Asistan kısayollarını proaktif olarak önermenize ve uygulamanıza olanak tanır. Kısayollar önererek, kısayolları ayarlamak zorunda kalmadan kullanıcılarınıza uygulamanızdaki favori etkinliklerine kolayca geri dönmelerini sağlarsınız.
Örneğin, bir kullanıcı müzik uygulamanızda "heavy metal antrenman" araması yaparsa, gelecekte bu arama sonuçlarına doğrudan Asistan kısayolu önerebilirsiniz. Kısayol önerdiğinizde uygulamanızda kısayol için önerilen ifadeyi görüntüleyen ve kullanıcıya kısayolun oluşturulup oluşturulamayacağını soran bir istem görünür.
Bu örnekte, "heavy metal antrenmanımı başlat" ifadesini öneriyorsunuz. Kullanıcı öneriyi kabul eder ve ardından "Ok Google, heavy metal antrenmanımı başlat" diyerek kısayolu başlatabilir.
Uygulamanızın kitlesini büyütmenin yolları hakkında daha fazla bilgi için Uygulama işlemleriyle uygulamanızı büyütme bölümüne bakın.
Uygulama İçi Tanıtım SDK'sı aşağıdaki yöntemleri sağlar:
lookupShortcut
: Önermek istediğiniz kısayolun zaten mevcut olup olmadığını kontrol eder. Yöntem, kısayolun oluşturulmasını engelleyen sorunları da kontrol eder. Kısayol oluşturulamıyorsalookupShortcut
nedenini döndürür.createShortcutSuggestionIntent
:, kullanıcıdan önerilen kısayolu oluşturmasını istemek için kullanabileceğiniz bir niyet döndürür.createShortcutSettingsIntent
: Kullanıcıyı, uygulamanızın Asistan Kısayolu ayarlarına taşımak için kullanabileceğiniz bir niyet döndürür.
Ön koşullar ve sınırlamalar
Bu bölümde, önerilerin kullanımıyla ilgili ön koşullar ve koşulların yanı sıra karşılaşabileceğiniz sınırlamalar açıklanmaktadır.
Geliştirme ön koşulları
Önerileri kullanmak için geliştirme ortamınızın aşağıdaki ön koşulları karşılaması gerekir.
Android uygulamanızı, Uygulama İşlemleri'ni kullanacak şekilde genişletin.
Manifest'inizdeki
<queries>
etiketinecom.google.android.googlequicksearchbox
ekleyin. Örneğin:<manifest ...> <queries> <package android:name="com.google.android.googlequicksearchbox" /> </queries> ... </manifest>
Uygulamalarınızı yayınlamak için Android App Bundle'ları kullanın.
Cihaz gereksinimleri
Önerilerinizi bir cihazda test etmek için cihazınızda aşağıdaki uygulamaların yüklü olması gerekir.
Google uygulamasının en son sürümü,
Android 6.0 (API düzeyi 23) veya sonraki sürümler
Bilinen sınırlamalar
Öneriler yalnızca İngilizce dilinde desteklenmektedir. Kullanıcıların önerilerinizi görebilmesi için cihazlarındaki Asistan dilini İngilizce olarak ayarlamaları gerekir.
Önerileri uygulayın
Önerileri uygulamak için build.gradle
dosyanızı güncellemeniz, öneri istemcisini kurmanız ve ardından kullanıcılara sunmak istediğiniz önerileri tanımlamanız gerekir.
Kitaplık bağımlılığını
build.gradle
dosyanıza ekleyin.dependencies { ... implementation "com.google.assistant.appactions:suggestions:1.0.0" }
AssistantShortcutSuggestionsClient
örneğini tanımlayın.Kotlin
val shortcutsClient = AssistantShortcutSuggestionsClient.builder() .setContext(CONTEXT: Context) .setVerifyIntents(VERIFY_INTENTS: Boolean) .setCustomExecutor(CUSTOM_EXECUTOR: Object) .build()
Java
AssistantShortcutSuggestionsClient shortcutsClient = AssistantShortcutSuggestionsClient.builder() .setContext(CONTEXT: Context) .setVerifyIntents(VERIFY_INTENTS: Boolean) .setCustomExecutor(CUSTOM_EXECUTOR: Object) .build();
Bu örnekte:
CONTEXT
(zorunlu), uygulama bağlamıdır.VERIFY_INTENTS
(zorunludur), kullanıcılara kısayol önerirken oluşturulan her amacın doğrulanıp doğrulanmayacağını belirler.true
olduğundaAssistantShortcutSuggestionsClient
tarafından oluşturulan amaçlar doğrulanır. Niyet geçersizse bir istisna döndürülür.CUSTOM_EXECUTOR
(isteğe bağlı), eşzamansız görevleri çalıştırmak için kullanılan bir özel yürütücüdür. Sağlanmazsa SDK, görev için tek iş parçacıklı bir yürütücü kullanır.
Önermek istediğiniz kısayolun geçerli olup olmadığını ve isteğe bağlı olarak kısayolun zaten mevcut olup olmadığını belirlemek için
lookupShortcut
yöntemini kullanın.Bir uygulama kısayolu amacı oluşturun. Kısayol amacı, bir kullanıcıya önermek istediğiniz kısayolu temsil eder. Aşağıdaki örnekte, içecek siparişi verme kısayolu için bir amaç oluşturulmaktadır.
Kotlin
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()
Java
Map
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(); Kısayol amacını
lookupShortcut
yöntemine iletin.Kotlin
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 }
Java
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));
Kısayol amacını kullanarak öneriyi oluşturun. Öneri oluşturmak için kullanabileceğiniz iki yöntem vardır:
createShortcutSuggestionIntent
:, uygulamanız bağlamında kısayol önerisi etkinliğini başlatmak için kullandığınız bir Android amacı döndürür.Kotlin
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))
Java
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); );
Bu örnekte PHRASE, kullanıcıya kısayol olarak önermek istediğiniz ifadedir. Örneğin, kullanıcının kısayol olarak "Ok Google, inci çayı sipariş et" demesini istiyorsanız PHRASE ifadesini
"order my bubble tea"
ile değiştirin.Kotlin
val orderShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand("order my bubble tea") .build()
Java
AppShortcutSuggestion orderShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand("order my bubble tea") .build();
createShortcutSettingsIntent
: Kullanıcıyı Asistan uygulamasındaki kısayol ayarları arayüzüne taşıyan bir Android intent'i döndürür.Kotlin
val intent = shortcutsClient.createShortcutSettingsIntent().await() application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
Java
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); );
Önceki adımda döndürülen Android amacını kullanarak
startActivity
numaralı telefonu arayın.
Sorun giderme önerileri
Bu bölümde, kısayol önerirken karşılaşabileceğiniz sorunlar ve istisnalar listelenmiştir.
"GoogleUploadSupportedException: Hizmete bağlanamıyor"
Android 11 ve sonraki sürümlerde paket görünürlüğü filtreleme nedeniyle "GoogleInstallationUnsupportedException
: Hizmete bağlanamıyor" mesajı görülebilir. com.google.android.googlequicksearchbox
öğesinin manifest dosyanızdaki <queries>
etiketine dahil edildiğinden emin olun:
<manifest ...>
<queries>
<package android:name="com.google.android.googlequicksearchbox" />
</queries>
...
</manifest>
"APK imzası doğrulanamadı"
Üretim uygulamanızı uygulama paketi olarak göndermezseniz aşağıdaki hata meydana gelebilir:
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.
Uygulamanızı Android App Bundle olarak gönderdiğinizden emin olun.
"Kullanıcı kısayolları alınamadı"
Cihaza yakın zamanda bir hesap eklediyseniz ve yeni hesabın kısayol verileri henüz cihazda önbelleğe alınmamışsa "Kullanıcı kısayolları alınamadı" hata mesajıyla karşılaşabilirsiniz.
Cihazdaki kısayol verilerini senkronize etmek için Asistan uygulamasının arayüzünü kullanarak Asistan kısayolu ekleyebilir veya silebilirsiniz.
Kısayol oluşturma etkinliği, içerik gösterilmeden hemen kapanır
Uygulama İşlemleri Test Aracı'nı kullanarak bir önizleme oluşturmazsanız veya önizleme süresi dolarsa kısayol oluşturma etkinliği hiçbir içerik görüntülemeden kapanabilir. Önizlemenizi güncelleyip tekrar deneyin.