Cómo permitir que los usuarios configuren widgets de apps

Los widgets de la app se pueden configurar. Por ejemplo, un widget de reloj puede permitir que los usuarios configuren qué zona horaria mostrar.

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

Declara 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 la app lo inicia con la acción ACTION_APPWIDGET_CONFIGURE, 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. Obtén 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 totalmente calificado, ya que el selector hace referencia a ella 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.

Implementa la actividad de configuración

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

  • El host del widget de la app 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, que se guardó en los extras del intent como EXTRA_APPWIDGET_ID.
  • El sistema no envía la emisión ACTION_APPWIDGET_UPDATE cuando se inicia una actividad de configuración, lo que significa que no llama al método onUpdate() cuando se crea el widget. Es responsabilidad de la actividad de configuración solicitar una actualización de AppWidgetManager cuando se crea el widget por primera vez. Sin embargo, se llama a onUpdate() para actualizaciones posteriores (solo se omitirá la primera vez).

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.

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

Cuando un widget usa una actividad de configuración, es responsabilidad de la actividad actualizar el widget cuando se completa la configuración. Puedes hacerlo solicitando una actualización directamente desde AppWidgetManager.

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:

    Kotlin

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

    Java

    Intent intent = getIntent();
Bundle extras = intent.getExtras();
int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
if (extras != null) {
    appWidgetId = extras.getInt(
            AppWidgetManager.EXTRA_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 de llegar al final, el sistema notifica al host del widget de la app que se canceló la configuración y que el host no agrega el widget:

    Kotlin

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

    Java

    int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
setResult(Activity.RESULT_CANCELED, resultValue);

  3. Configura el widget según las preferencias del usuario.

  4. Cuando se complete la configuración, obtén una instancia de AppWidgetManager llamando a getInstance(Context):

    Kotlin

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. Para actualizar el widget con un diseño RemoteViews, llama a updateAppWidget(int,RemoteViews):

    Kotlin

    val views = RemoteViews(context.packageName, R.layout.example_appwidget)
appWidgetManager.updateAppWidget(appWidgetId, views)

    Java

    RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
appWidgetManager.updateAppWidget(appWidgetId, views);

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

    Kotlin

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

    Java

    Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
setResult(RESULT_OK, resultValue);
finish();

Consulta la clase de muestra ListWidgetConfigureActivity.kt en GitHub para ver un ejemplo.

Opciones de configuración del widget

De forma predeterminada, el host de widgets de la app 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 te permitan permitir que los usuarios reconfiguren los widgets existentes o omitan la configuración inicial del widget proporcionando una configuración predeterminada.

Cómo permitir que los usuarios reconfiguren los widgets colocados

Para permitir que los usuarios reconfiguren los widgets existentes, especifica la marca reconfigurable en el atributo widgetFeatures de appwidget-provider. Consulta la guía para declarar el archivo AppWidgetProviderInfo.xml y obtener más información. Por ejemplo:

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

Para reconfigurar el widget, los usuarios deben mantenerlo presionado y presionar el botón Reconfigurar, que se etiqueta como 1 en la Figura 1.

El botón aparece en la esquina inferior derecha.
Figura 1: Botón Reconfigurar del widget.

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 puede omitir la configuración inicial y mostrar la zona horaria del dispositivo de forma predeterminada.

Este es 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>