Cómo permitir que los usuarios configuren widgets de apps

Diseña tu widget para que los usuarios puedan configurar atributos específicos. Por ejemplo, un widget de reloj puede permitir que los usuarios configuren qué zona horaria mostrar.

Si deseas permitir que los usuarios configuren los parámetros de configuración de tu widget, crea una configuración del widget Activity. El host de widgets de apps inicia automáticamente esta actividad cuando se crea el widget o más adelante, según las opciones de configuración que especifiques.

Cómo declarar la actividad de configuración

Declara la actividad de configuración como una actividad normal en el archivo de manifiesto de Android. El host de widgets de apps la inicia con la ACTION_APPWIDGET_CONFIGURE acción, por lo que la actividad debe aceptar este intent. Por ejemplo:

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

Declara la actividad en el archivo AppWidgetProviderInfo.xml con el atributo android:configure. Consulta más información para declarar este archivo. A continuación, se muestra un ejemplo de cómo declarar la actividad de configuración:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

La actividad se declara con un espacio de nombres completamente calificado, ya que el selector la hace referencia desde fuera del alcance de tu paquete.

Eso es todo lo que necesitas para iniciar una actividad de configuración. A continuación, debes implementar la actividad real.

Cómo implementar la actividad de configuración

Hay dos puntos importantes que debes recordar cuando implementas la actividad:

• El host de widgets de apps llama a la actividad de configuración, y esta siempre debe mostrar un resultado. El resultado debe incluir el ID del widget de la app que pasó el intent que inició la actividad guardada en los extras del intent como EXTRA_APPWIDGET_ID.
  • El sistema no envía la ACTION_APPWIDGET_UPDATE transmisión cuando se inicia una actividad de configuración, lo que significa que no llama a las actualizaciones de tu widget inicialmente cuando se crea el widget. Es responsabilidad de la actividad de configuración solicitar una actualización desde GlanceAppWidget cuando se crea el widget por primera vez. Sin embargo, las actualizaciones se activan automáticamente para los ciclos posteriores.

Consulta los fragmentos de código de la siguiente sección para conocer un ejemplo de cómo mostrar un resultado de la configuración y actualizar el widget de Glance.

Cómo actualizar el widget desde la actividad de configuración

Cuando un widget utiliza una actividad de configuración, es responsabilidad de la actividad actualizar el widget cuando se completa la configuración. Para ello, activa una actualización manual directamente desde la instancia GlanceAppWidget.

A continuación, encontrarás un resumen del procedimiento que debes seguir para actualizar correctamente el widget y cerrar la actividad de configuración:

1. Obtén el ID del widget de la app desde el intent que inició la actividad:

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. Establece el resultado de la actividad en RESULT_CANCELED.

   De esta manera, si el usuario cancela la actividad antes del final, el sistema notifica al host de widgets de apps que se canceló la configuración y que el host no agrega el widget:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

3. Configura el widget según las preferencias del usuario, por ejemplo, escribiendo las selecciones en Datastore persistente o en una base de datos local.

4. Cuando se complete la configuración, recupera el GlanceId correspondiente al ID del widget de la plataforma:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. Actualiza el contenido del widget llamando a la función suspendida update en tu instancia GlanceAppWidget:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. Crea el intent de retorno, configúralo con el resultado de la actividad y finaliza la actividad:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

Opciones de configuración del widget

De forma predeterminada, el host de widgets de apps solo inicia la actividad de configuración una vez, inmediatamente después de que el usuario agrega el widget a su pantalla principal. Sin embargo, puedes especificar opciones que permitan al usuario reconfigurar los widgets existentes o omitir la configuración inicial del widget proporcionando una configuración predeterminada del widget.

Cómo permitir que los usuarios reconfiguren los widgets colocados

Para permitir que los usuarios reconfiguren los widgets existentes, especifica la reconfigurable marca en el widgetFeatures atributo de appwidget-provider. Por ejemplo:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

Los usuarios pueden reconfigurar su widget si lo mantienen presionado y presionan el botón Reconfigurar, que está etiquetado como 1 en la figura 1.

Cómo usar la configuración predeterminada del widget

Puedes proporcionar una experiencia de widget más fluida si permites que los usuarios omitan el paso de configuración inicial. Para ello, especifica las marcas configuration_optional y reconfigurable en el campo widgetFeatures. De esta manera, se evita iniciar la actividad de configuración después de que un usuario agrega el widget. Como se mencionó anteriormente, el usuario todavía puede reconfigurar el widget más adelante. Por ejemplo, un widget de reloj podría evitar la configuración inicial y mostrar la zona horaria del dispositivo de forma predeterminada.

A continuación, se muestra un ejemplo de cómo marcar tu actividad de configuración como reconfigurable y opcional:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>