Cómo sugerir atajos con el SDK de promoción en la app

Para promocionar funciones de tu app y facilitar su uso, puedes sugerir atajos de Asistente a los usuarios. Los atajos del Asistente son frases concisas que un usuario puede pronunciar para activar funciones de la app.

Si bien los usuarios pueden crear atajos del Asistente de forma manual, el SDK de promoción en la app te permite sugerir e implementar esos atajos de forma proactiva. Al sugerir atajos, les brindas a los usuarios rutas claras y simples a sus actividades favoritas en tu app sin el esfuerzo adicional de configurar los atajos.

Por ejemplo, si un usuario busca "entrenamiento con heavy metal" en tu app de música, podrías sugerir un atajo del Asistente directamente a esos resultados de la búsqueda en el futuro. Cuando sugieres un atajo, aparece un mensaje en la app que muestra la frase propuesta para el atajo y le pregunta al usuario si se debe crear el atajo.

En este ejemplo, sugieres la frase "comienza mi entrenamiento de heavy metal". El usuario acepta la sugerencia y, luego, podrá iniciar el atajo con "Hey Google, comienza mi entrenamiento de heavy metal".

Si deseas obtener más información para aumentar el público de tu app, consulta Cómo ampliar el alcance de tu app con Acciones en apps.

El SDK de promoción en la app brinda los siguientes métodos:

  • lookupShortcut: verifica si el atajo que deseas sugerir ya existe. El método también comprueba si hay problemas que impidan la creación del atajo. Si no se puede crear el atajo, lookupShortcut muestra los motivos.

  • createShortcutSuggestionIntent: muestra un intent que puedes usar para solicitarle al usuario que cree el atajo sugerido.

  • createShortcutSettingsIntent: Muestra un intent que puedes usar para mover al usuario a la configuración de atajos del Asistente de tu app.

Requisitos previos y limitaciones

En esta sección, se describen los requisitos para usar las sugerencias, así como las limitaciones que puedes encontrar.

Requisitos previos del desarrollo

Para usar sugerencias, el entorno de desarrollo debe cumplir con los siguientes requisitos previos:

  • Extiende tu app para Android para poder usar Acciones en apps.

  • Incluye com.google.android.googlequicksearchbox en la etiqueta <queries> de tu manifiesto. Por ejemplo:

    <manifest ...>
      <queries>
        <package android:name="com.google.android.googlequicksearchbox" />
      </queries>
      ...
    </manifest>
    
  • Usa los Android App Bundles para publicar tus apps.

Requisitos del dispositivo

Para probar las sugerencias en un dispositivo, debe tener instalado lo siguiente:

  • La versión más reciente de la app de Google

  • Android 6.0 (nivel de API 23) o una versión posterior

Limitaciones conocidas

Las sugerencias solo se admiten en inglés. Para que los usuarios vean tus sugerencias, deben configurar el idioma de Asistente en su dispositivo en inglés.

Cómo implementar sugerencias

Para implementar sugerencias, debes actualizar tu archivo build.gradle, configurar el cliente de sugerencias y, luego, definir las sugerencias que deseas brindar a los usuarios.

  1. Agrega la dependencia de biblioteca a tu archivo build.gradle.

    dependencies {
      ...
      implementation "com.google.assistant.appactions:suggestions:1.0.0"
    }
    
  2. Define una instancia de AssistantShortcutSuggestionsClient.

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

    En este ejemplo:

    • CONTEXT (obligatorio) es el contexto de la aplicación.

    • VERIFY_INTENTS (obligatorio) determina si se debe verificar cada intent creado cuando se sugieren atajos a los usuarios. Cuando es true, se verifican los intents creados por AssistantShortcutSuggestionsClient. Si un intent no es válido, se muestra una excepción.

    • CUSTOM_EXECUTOR (opcional) es un ejecutor personalizado para realizar tareas asíncronas. Si no se proporciona, el SDK usa un ejecutor de un solo subproceso para la tarea.

  3. Usa el método lookupShortcut para determinar si el atajo que deseas sugerir es válido y si ya existe.

    1. Crea un intent de atajos de la app. El intent de atajo representa el que deseas sugerirle a un usuario. En el siguiente ejemplo, se crea un intent para un atajo utilizado para pedir una bebida.

      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. Pasa el intent de atajo al método lookupShortcut.

      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. Crea la sugerencia con el intent de atajo. Existen dos métodos que puedes usar para crear una sugerencia:

    • createShortcutSuggestionIntent: Muestra un intent de Android que puedes usar para iniciar la actividad de sugerencias de atajos en el contexto de tu app.

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

      En este ejemplo, PHRASE es la frase que deseas sugerir al usuario como atajo. Por ejemplo, si quieres que el usuario diga "Hey Google, pide mi té de burbujas" como atajo, reemplaza PHRASE por "order my bubble tea".

      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: Muestra un intent de Android que lleva al usuario a la interfaz de configuración de atajos en la app de Asistente.

      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. Llama a startActivity con el intent de Android que se mostró durante el paso anterior.

Sugerencias para solucionar problemas

En esta sección, se enumeran los problemas y las excepciones que puedes encontrar cuando sugieres atajos.

"GoogleInstallationUnsupportedException: No se puede vincular al servicio"

Debido al filtrado de visibilidad de paquetes, el error "GoogleInstallationUnsupportedException: No se puede vincular al servicio" podría ocurrir en Android 11 y versiones posteriores. Asegúrate de que com.google.android.googlequicksearchbox esté incluido en la etiqueta <queries> de tu manifiesto:

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

"No se pudo verificar la firma del APK"

El siguiente error puede ocurrir si no envías tu app en producción como un paquete de aplicación:

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.

Asegúrate de enviar la app como un Android App Bundle.

"No se pudieron obtener los atajos del usuario"

El mensaje de error "Failed to get user shortcuts" puede ocurrir si recientemente agregaste una cuenta al dispositivo y si los datos de atajos de la cuenta nueva aún no se almacenaron en caché en el dispositivo.

Para sincronizar los datos de atajos en el dispositivo, agrega o borra un atajo del Asistente mediante la interfaz de la app de Asistente.

La actividad de creación de atajos se cierra de inmediato sin mostrar ningún contenido

La actividad de creación de atajos puede cerrarse sin mostrar ningún contenido si no creaste una vista previa con la herramienta de pruebas de Acciones en apps, o bien si esa vista previa caducó. Actualiza la vista previa y vuelve a intentarlo.