Se usó la API de Cloud Translation para traducir esta página.

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.

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

dependencies {
  ...
  implementation "com.google.assistant.appactions:suggestions:1.0.0"
}

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.

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

Crea un intent de atajos de la app. El intent de atajo representa el que deseas sugerirle a un usuario. El siguiente ejemplo Crea un intent para un acceso directo que permite iniciar un ejercicio.

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

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

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

En este ejemplo, PHRASE es la frase que deseas sugerir al usuario como atajo. Por ejemplo, si quieres que el usuario diga "Hey Google, inicia una actividad de correr" como atajo, reemplaza PHRASE por "start a run".

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

Llama a startActivity con el intent de Android que se mostró durante el paso anterior.

Nota: Si el atajo que sugieres está en conflicto con uno existente, el usuario permanecerá en el contexto de tu app y se le pedirá que establezca un enunciado nuevo para el atajo.

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.