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

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Para promocionar funciones de tu app y facilitar su uso, puedes sugerir atajos del 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, te aseguras de que los usuarios tengan rutas de acceso claras y simples a sus actividades favoritas en la 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 el artículo para ampliar el alcance de tus apps 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

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

  • Asegúrate de que tu app para Android se extienda de modo que use Acciones en apps.

  • Incluye com.google.android.googlequicksearchbox en las etiquetas <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, este debe cumplir con los siguientes requisitos:

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

  • Contar con la versión M de Android (nivel de API 23) o una posterior

Limitaciones conocidas

En esta sección, se describen las limitaciones en relación con las sugerencias.

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

Cuando implementas sugerencias, debes actualizar tu archivo build.gradle, configurar el cliente de sugerencias y, luego, definir las sugerencias que deseas ofrecer a los usuarios.

A fin de implementar sugerencias en tu app, haz lo siguiente:

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

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

    Dónde:

    • 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 a fin de determinar si el atajo que deseas sugerir es válido y si ya existe. Te recomendamos que implementes lookupShortcut para verificar que los intents creados por tus sugerencias sean válidos, incluso si no planeas verificar los atajos de usuarios existentes.

    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 describe un atajo para pedir una bebida al usuario.

      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 to create a shortcut
      } else {
          // app can remind that the user has a shortcut for this app action
      }
      

      Java

      shortcutsClient.lookupShortcut(appShortcutIntent)
        .addOnSuccessListener(shortcutLookupResult -> {
          if (!shortcutLookupResult.isShortcutPresent()) {
            // app can suggest to create a shortcut
          } else {
            // app can remind that the user has 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 a fin de 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);
            );
      

      PHRASE es la declaración 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.

Solución de problemas para sugerencias

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, GoogleInstallationUnsupportedException: Cannot bind to service puede 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.