Uygulama İçi Tanıtım SDK'sını kullanarak kısayollar önerme

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ıyorsa lookupShortcut 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> etiketine com.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.

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.

  1. Kitaplık bağımlılığını build.gradle dosyanıza ekleyin.

    dependencies {
      ...
      implementation "com.google.assistant.appactions:suggestions:1.0.0"
    }
    
  2. 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ğunda AssistantShortcutSuggestionsClient 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.

  3. Ö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.

    1. 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();
       
    2. 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));
      
  4. 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);
          );
      
  5. Ö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.