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ının uygulamanızdaki işlevleri tetiklemek için söyleyebileceği kısa ifadelerdir.

Asistan kısayolları kullanıcılarınız tarafından manuel olarak oluşturulabilir ancak Uygulama İçi Promosyon SDK'sı, Asistan kısayollarını proaktif olarak önermenize ve uygulamanıza olanak tanır. Kısayol önererek kullanıcılarınıza, kısayol oluşturma zahmetine girmeden uygulamanızdaki favori etkinliklerine geri dönmeleri için net ve basit yollar sunarsınız.

Örneğin, bir kullanıcı müzik uygulamanızda "heavy metal antrenman" araması yaparsa gelecekte doğrudan bu arama sonuçlarına yönlendiren bir Asistan kısayolu önerebilirsiniz. Bir kısayol önerdiğinizde uygulamanızda kısayol için önerilen ifadeyi gösteren 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 İşlemleri ile uygulamanızı büyütme başlıklı makaleyi inceleyin.

Uygulama İçi Promosyon 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 bunun nedenlerini döndürür.

  • createShortcutSuggestionIntent:, kullanıcıdan önerilen kısayolu oluşturmasını istemek için kullanabileceğiniz bir intent döndürür.

  • createShortcutSettingsIntent: Kullanıcıyı uygulamanızın Asistan kısayolu ayarlarına yönlendirmek için kullanabileceğiniz bir intent döndürür.

Ön koşullar ve sınırlamalar

Bu bölümde, önerileri kullanmayla ilgili ön koşullar ve şartları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 dosyanızdaki <queries> etiketine com.google.android.googlequicksearchbox öğesini 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ğıdakilerin yüklü olması gerekir.

Bilinen sınırlamalar

Öneriler yalnızca İngilizce olarak desteklenir. Kullanıcıların önerilerinizi görebilmesi için cihazlarındaki Asistan dilini İngilizce olarak ayarlamaları gerekir.

Önerileri uygulama

Önerileri uygulamak için build.gradle dosyanızı güncellemeniz, öneri istemcisini ayarlamanız ve ardından kullanıcılara vermek 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ği 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 (zorunlu), kullanıcılara kısayol önerilirken oluşturulan her intent'in doğrulanıp doğrulanmayacağını belirler. true olduğunda AssistantShortcutSuggestionsClient tarafından oluşturulan niyetler doğrulanır. Amaç 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 özel bir 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. Uygulama kısayolu intent'i oluşturun. Kısayol intent'i, kullanıcıya önermek istediğiniz kısayolu temsil eder. Aşağıdaki örnekte, egzersiz başlatmak için kısayol amacı oluşturulmaktadır.

      Kotlin

      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()

      Java

        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. Kısayol intent'ini 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 intent'ini kullanarak öneriyi oluşturun. Öneri oluşturmak için iki yöntem kullanabilirsiniz:

    • createShortcutSuggestionIntent: Uygulamanız bağlamında kısayol önerisi etkinliğini başlatmak için kullandığınız bir Android intent'i döndürür.

      Kotlin

      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))

      Java

        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);
      );

      Bu örnekte PHRASE, kullanıcıya kısayol olarak önermek istediğiniz ifadedir. Örneğin, kullanıcının kısayol olarak "Ok Google, koşu başlat" demesini istiyorsanız PHRASE ifadesini "start a run" ile değiştirin.

      Kotlin

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

      Java

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

    • createShortcutSettingsIntent: Kullanıcıyı Asistan uygulamasındaki kısayol ayarları arayüzüne yönlendiren 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 intent'ini kullanarak startActivity yöntemini çağırın.

Önerilerle ilgili sorunları giderme

Bu bölümde, kısayol önerirken karşılaşabileceğiniz sorunlar ve istisnalar listelenmiştir.

"GoogleInstallationUnsupportedException: Hizmete bağlanılamıyor"

Paket görünürlüğü filtrelemesi nedeniyle Android 11 ve sonraki sürümlerde "GoogleInstallationUnsupportedException: Hizmete bağlanılamıyor" hatası oluşabilir. Manifest dosyanızdaki <queries> etiketine com.google.android.googlequicksearchbox öğesinin eklendiğ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 oluşabilir:

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ı"

"Kullanıcı kısayolları alınamadı" hata mesajı, cihaza yakın zamanda bir hesap eklediyseniz ve yeni hesabın kısayol verileri henüz cihazda önbelleğe alınmadıysa gösterilebilir.

Cihazdaki kısayol verilerini senkronize etmek için Asistan uygulamasının arayüzünü kullanarak bir Asistan kısayolu ekleyin veya silin.

Kısayol oluşturma etkinliği, herhangi bir içerik gösterilmeden hemen kapanıyor

Uygulama İşlemleri Test Aracı'nı kullanarak önizleme oluşturmazsanız veya önizlemenin süresi dolarsa kısayol oluşturma etkinliği herhangi bir içerik gösterilmeden kapanabilir. Önizlemenizi güncelleyip tekrar deneyin.