Cómo proporcionar objetivos de Direct Share

Figura 1: Fila de Direct Share en Sharesheet, como se muestra en 1

Usa los objetivos de Direct Share para que los usuarios de otras apps puedan hacerlo de manera más fácil y rápida para compartir URLs, imágenes y otros tipos de datos con tu app. Direct Share funciona Presentando contactos de apps de mensajería y redes sociales directamente en la app de Android Sharesheet, sin que los usuarios tengan que seleccionar la app y luego buscar el contacto

ShortcutManagerCompat es una API de AndroidX que proporciona accesos directos de uso compartido, y es compatible con la API ChooserTargetService obsoleta. Esta es la opción preferida manera de publicar accesos directos de uso compartido y ChooserTargets. Para obtener instrucciones, consulta Cómo usar AndroidX para proporcionar accesos directos de uso compartido yChooserTargets en esta página.

Cómo publicar objetivos de Direct Share

La fila Sharesheet Direct Share solo muestra accesos directos dinámicos proporcionados por el API de accesos directos de uso compartido. Completa los siguientes pasos para publicar Direct Share objetivos.

  1. En el archivo de recursos XML de tu app, declara elementos share-target.

    <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
<share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity">
    <data android:mimeType="text/plain" />
    <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" />
</share-target>
</shortcuts>

  2. Cuando se inicialice tu app, usa setDynamicShortcuts. para ordenar los atajos dinámicos por importancia.

    Un índice más bajo indica más importancia. Si estás haciendo una comunicación pueden ser conversaciones principales ordenadas por fecha más reciente a medida que aparecen tu app. No publiques accesos directos que estén inactivos. una conversación sin La actividad del usuario de los últimos 30 días se considera inactiva.

    Kotlin

    ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))

    Java

    List<ShortcutInfoCompat> shortcuts = new ArrayList<>();
shortcuts.add(shortcut1);
shortcuts.add(shortcut2);
...
ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);

  3. Si estás desarrollando una aplicación de comunicación, informa el uso de accesos directos mediante pushDynamicShortcut inmediatamente cada vez que el usuario recibe o envía un mensaje a un contacto. Consulta Cómo informar sobre el uso de combinaciones de teclas para comunicaciones en esta página para obtener más información. Por ejemplo, informa el uso de mensajes que envió el usuario por especificando vinculaciones de capacidades en el acceso directo mediante ShortcutInfoCompat.Builder#addCapabilityBinding con la capability actions.intent.SEND_MESSAGE.

    Kotlin

    val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
.addCapabilityBinding("actions.intent.SEND_MESSAGE").build()
ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

    Java

    ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

  4. Si el usuario borra un contacto, usa removeLongLivedShortcut Esta es la opción preferida de quitar el atajo sin importar si el sistema lo almacena en caché de Google Cloud. En el siguiente fragmento de código, se muestra un ejemplo de cómo hacerlo.

    Kotlin

    val deleteShortcutId = "..."
ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))

    Java

    String deleteShortcutId = "...";
ShortcutManagerCompat.removeLongLivedShortcuts(
    myContext, Arrays.asList(deleteShortcutId));

Mejora las clasificaciones de tus objetivos de Direct Share

Android Sharesheet muestra una cantidad fija de objetivos de Direct Share. Estos las sugerencias se ordenan según su clasificación. Puede mejorar potencialmente la clasificación de su atajos de la siguiente manera:

  • Asegúrate de que todos los shortcutIds sean únicos y nunca se reutilicen para diferentes destinos.
  • Asegúrate de que el acceso directo sea permanente. Para ello, llama a setLongLived(true)
  • Informa el uso de combinaciones de teclas relacionadas con las conversaciones para los mensajes salientes y entrantes republicando las combinaciones de teclas correspondientes a través de ShortcutManagerCompat.pushDynamicShortcut. Consulta Cómo informar sobre el uso de accesos directos a apps de comunicación para obtener más información. para obtener más información.
  • Evita proporcionar objetivos de Direct Share irrelevantes o inactivos, por ejemplo, contactos a los que el usuario no ha enviado mensajes en los últimos 30 días.
  • En el caso de las apps de SMS, no incluyas atajos para conversaciones o códigos cortos identificados como posible spam. Es muy poco probable que los usuarios compartan contenido con esas conversaciones.
  • Llama a setCategories() para asociar el acceso directo con el apropiado mimeType atributos. Por ejemplo: para una app de SMS, si el contacto no es compatible con RCS o MMS, no asociar el atajo correspondiente con tipos MIME que no son de texto, como image/* y video/*.
  • Para una conversación dada, una vez que se envía un atajo dinámico y el uso se informa, no cambies el ID del atajo. Esto garantiza la retención de los datos de uso para clasificar los resultados.

Si el usuario presiona cualquier objetivo de Direct Share, tu app debe llevarlo a una IU en la que pueden realizar una acción directamente sobre el tema del objetivo. No presentar al usuario una IU de desambiguación y no la coloques en una IU que no esté relacionada con la objetivo presionado. Por ejemplo, en una app de mensajería, presionar Direct Share target lleva al usuario a una vista de conversación con la persona que seleccionó. El el teclado es visible y el mensaje se completa previamente con los datos compartidos.

API de accesos directos de uso compartido

A partir de Android 10 (nivel de API 29), ShortcutInfo.Builder agregó métodos y mejoras que proporcionan información adicional sobre el objetivo de uso compartido:

setCategories()
A partir de Android 10, las categorías también se usan para filtrar las combinaciones de teclas que pueden controlar intents o acciones de uso compartido. Consulta Cómo declarar un uso compartido target para obtener más información. Este campo es obligatorio para los accesos directos destinadas a usarse como objetivos de uso compartido.
setLongLived()

Especifica si un acceso directo es válido o no cuando se anula su publicación. invisibles por la app (como un acceso directo dinámico o fijo). Si un atajo es de larga duración, puede almacenarse en caché a través de varios servicios del sistema, incluso se anuló como un acceso directo dinámico.

Hacer que un acceso directo sea permanente puede mejorar su clasificación. Consulta Obtener lo mejor clasificación para obtener más detalles.

setShortLabel(), setLongLabel()

Cuando publiques un acceso directo para una persona en particular, incluye su nombre completo. nombre en setLongLabel() y cualquier nombre corto, como un sobrenombre o un nombre nombre, en setShortLabel().

Consulta un ejemplo de publicación de accesos directos de uso compartido en GitHub.

Proporciona imágenes de atajos

Para crear un acceso directo de uso compartido, tendrás que agregar una imagen mediante setIcon().

Los accesos directos de uso compartido pueden aparecer en todas las superficies del sistema y se pueden modificar. Además, algunos dispositivos con versiones de Android 7, 8 o 9 (niveles de API 25, 26, 27 y 28) podrían mostrar íconos solo de mapa de bits sin fondo, lo que reduce drásticamente el contraste. Para asegurarte de que tu acceso directo se vea como corresponde, proporcionar un mapa de bits adaptable mediante IconCompat.createWithAdaptiveBitmap()

Asegúrate de que los mapas de bits adaptables sigan las mismas pautas y dimensiones configuradas para íconos adaptables. La forma más común de lograr esto es ajustar el mapa de bits cuadrado deseado a Debe ser de 72 × 72 dp y centrarlo dentro de un lienzo transparente de 108 × 108 dp. Si el ícono incluya regiones transparentes, debes incluir un color de fondo. De lo contrario, regiones transparentes aparecen en negro.

No proporciones imágenes enmascaradas en una forma específica. Por ejemplo, antes de En Android 10 (nivel de API 29), era común proporcionar avatares de usuarios para Direct Share Elementos ChooserTarget enmascarados como un círculo. Android Sharesheet y otras del sistema en Android 10. Ahora, las imágenes de accesos directos de temas y formas El método preferido para proporcionar accesos directos de uso compartido mediante ShortcutManagerCompat: dar forma automática a los objetos ChooserTarget de Direct Share para círculos para ti.

Cómo declarar un objetivo de uso compartido

Los objetivos de uso compartido deben declararse en el archivo de recursos de la app, de manera similar a las definiciones de accesos directos estáticos. Agregar propiedad las definiciones de destino dentro del elemento raíz <shortcuts> en el archivo de recursos junto con otras definiciones de atajos estáticos. Cada elemento <share-targets> contiene información sobre el tipo de datos compartidos, las categorías coincidentes y el la clase de destino que manejará el intent de uso compartido. El código XML se ve algo así:

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity">
    <data android:mimeType="text/plain" />
    <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" />
  </share-target>
</shortcuts>

El elemento de datos en un objetivo de uso compartido es similar al de la especificación de datos en un filtro de intents. Cada objetivo de uso compartido puede tener Varias categorías, que solo se usan para que coincidan con los accesos directos publicados de una app con sus definiciones de objetivos de uso compartido. Las categorías pueden tener cualquier configuración arbitraria definida de salida.

Si el usuario selecciona un acceso directo de uso compartido en Android Sharesheet que coincide con el objetivo del ejemplo anterior, la app obtendrá el siguiente intent de uso compartido:

Action: Intent.ACTION_SEND
ComponentName: {com.example.android.sharingshortcuts /
                com.example.android.sharingshortcuts.SendMessageActivity}
Data: Uri to the shared content
EXTRA_SHORTCUT_ID: <ID of the selected shortcut>

Si el usuario abre el objetivo de uso compartido desde los accesos directos del selector, la app obtendrá el intent que se haya creado al agregar el acceso directo de uso compartido a ShortcutManagerCompat. Como se trata de un intent diferente, Intent.EXTRA_SHORTCUT_ID no estará disponible. y tendrás que pasar el ID manualmente si lo necesitas.

Cómo informar sobre el uso de accesos directos para apps de comunicación

Si estás desarrollando una aplicación de comunicación, puedes mejorar tu clasificación en el Android Sharesheet informando el uso de mensajes salientes y entrantes. Para ello, vuelve a publicar el acceso directo de la conversación que representa al contacto a través de ShortcutManagerCompat.pushDynamicShortcut

El uso de combinaciones de teclas y las vinculaciones de funciones son retrocompatibles con Android 5.0 (API 21).

Informar uso de combinaciones de teclas para mensajes salientes

El uso de informes de los mensajes enviados por el usuario es funcionalmente similar a haciendo clic en "enviar" después de crear un mensaje.

Para activar los informes de uso, especifica vinculaciones de capacidades en la combinación de teclas a ShortcutInfoCompat.Builder#addCapabilityBinding con la capability actions.intent.SEND_MESSAGE.

Kotlin

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
.addCapabilityBinding("actions.intent.SEND_MESSAGE").build()
ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

Java

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

Si el mensaje saliente es para un chat en grupo, también debes agregar el Audience valor del parámetro como recipient se asocia con la capacidad.

Kotlin

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", listOf("Audience")).build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

Java

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", Arrays.asList("Audience"))
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

Informa sobre el uso de combinaciones de teclas para los mensajes entrantes

Para activar informes de uso cuando el usuario recibe un mensaje como un SMS, haz lo siguiente: mensaje de chat, correo electrónico o notificaciones, también debes especificar en el atajo mediante ShortcutInfoCompat.Builder#addCapabilityBinding con la capability actions.intent.RECEIVE_MESSAGE.

Kotlin

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE").build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

Java

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

Si el mensaje entrante es de un chat en grupo, también debes agregar el Audience. valor del parámetro como el tipo sender está asociada con la capacidad.

Kotlin

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", listOf("Audience")).build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

Java

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", Arrays.asList("Audience"))
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

Usa AndroidX para proporcionar accesos directos de uso compartido y ChooserTargets

Para poder trabajar con la biblioteca de compatibilidad de AndroidX, el manifiesto de la app debe contener el conjunto meta-data + chooser-target-service + intent-filters. Consulta la API ChooserTargetService de Direct Share actual.

Este servicio ya está declarado en la biblioteca de compatibilidad, por lo que el usuario no es necesario declarar el servicio en el manifiesto de la app. Sin embargo, el vínculo de se debe tener en cuenta la actividad de uso compartido en el servicio como un objetivo del selector proveedor.

En el siguiente ejemplo, la implementación de ChooserTargetService es androidx.core.content.pm.ChooserTargetServiceCompat y ya está definida en AndroidX:

<activity
    android:name=".SendMessageActivity"
    android:label="@string/app_name"
    android:theme="@style/SharingShortcutsDialogTheme">
    <!-- This activity can respond to Intents of type SEND -->
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
    <!-- Only needed if you import the sharetarget AndroidX library that
         provides backwards compatibility with the old DirectShare API.
         The activity that receives the Sharing Shortcut intent needs to be
         taken into account with this chooser target provider. -->
    <meta-data
        android:name="android.service.chooser.chooser_target_service"
        android:value="androidx.sharetarget.ChooserTargetServiceCompat" />
</activity>

Preguntas frecuentes sobre accesos directos de uso compartido

¿Cómo se almacenan los datos de uso de accesos directos y salen del dispositivo?

Los atajos se almacenan por completo en el dispositivo, en el directorio de datos del sistema, en un partición de disco encriptada. La información en accesos directos, como el ícono, el intent y los nombres de personas y recursos son accesibles solo por los servicios del sistema y misma app que publica los accesos directos.

¿Cuál es el historial de Direct Share?

Presentamos Direct Share en Android 6.0 (nivel de API 23) para permitir que las apps Proporcionar objetos ChooserTarget a través de un ChooserTargetService Los resultados fueron se recuperan de manera reactiva a pedido, lo que hace que el tiempo de carga para los objetivos sea lento.

En Android 10 (nivel de API 29), reemplazamos a ChooserTargetService Direct Comparte APIs con la nueva API de accesos directos de uso compartido. En lugar de obtener resultados de forma reactiva a pedido, la API de accesos directos de uso compartido les permite a las apps publicar Direct Share tus objetivos con anticipación. Esto aceleró rápidamente el proceso de recuperación de Direct Share los objetivos cuando prepares ShareSheet. Direct Share de ChooserTargetService mecanismo seguirá funcionando, pero el sistema clasifica los objetivos que se proporcionan de esta forma más baja que cualquier objetivo que use la API de accesos directos de uso compartido.

Android 11 (nivel de API 30) dio de baja el servicio ChooserTargetService. La API de accesos directos de uso compartido es la única forma de proporcionar objetivos de Direct Share.

¿En qué se diferencian del selector los accesos directos publicados para objetivos de uso compartido? accesos directos (el típico uso de los accesos directos cuando se mantienen presionados los íconos de las apps en selector)?

Los accesos directos que se publiquen para un "objetivo de uso compartido" también serán accesos directos del selector y se mostrarán en el menú cuando se mantenga presionado el ícono de tu app. El límite máximo de accesos directos por actividad también se aplica a la cantidad total de accesos directos que publica una app (incluye objetivos de uso compartido y accesos directos de selector heredados).

¿Cuál es la guía sobre la cantidad de accesos directos de uso compartido que se debe publicar?

La cantidad de accesos directos de uso compartido está limitada al mismo límite de combinaciones de teclas accesos directos disponibles a través de getMaxShortcutCountPerActivity(android.content.Context) Se puede publicar cualquier pero ten en cuenta que los accesos directos de uso compartido pueden estar visibles En el selector de aplicaciones, mantén presionada la hoja para compartir. La mayoría de los selectores de aplicaciones están activados mantener presionado un máximo de cuatro o cinco combinaciones de teclas en modo vertical ocho en modo horizontal. Ver esto Preguntas frecuentes para obtener más detalles y orientación sobre el uso compartido de accesos directos.

Anterior
Cómo recibir datos simples de otras apps