사용자가 앱 위젯을 구성하도록 사용 설정

사용자가 특정 특성을 구성할 수 있도록 위젯을 디자인합니다. 예를 들어 시계 위젯을 사용하면 사용자가 표시할 시간대를 구성할 수 있습니다.

사용자가 위젯의 설정을 구성하도록 하려면 위젯 구성 Activity를 만듭니다. 이 활동은 위젯이 생성될 때 또는 나중에 지정한 구성 옵션에 따라 앱 위젯 호스트에 의해 자동으로 실행됩니다.

구성 활동 선언

구성 활동을 Android 매니페스트 파일에서 일반 활동으로 선언합니다. 앱 위젯 호스트는 ACTION_APPWIDGET_CONFIGURE 작업을 사용하여 실행하므로 활동에서 이 인텐트를 수락해야 합니다. 예를 들면 다음과 같습니다.

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

AppWidgetProviderInfo.xml 파일에서 android:configure 속성을 사용하여 활동을 선언합니다. 이 파일 선언에 관한 자세한 내용은 여기를 참고하세요. 다음은 구성 활동을 선언하는 방법을 보여주는 예입니다.

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

활동은 정규화된 네임스페이스로 선언됩니다. 런처가 패키지 범위 외부에서 참조하기 때문입니다.

이것으로 구성 활동을 시작하기만 하면 됩니다. 다음으로 실제 활동을 구현해야 합니다.

구성 활동 구현

활동을 구현할 때 기억해야 할 두 가지 중요한 사항이 있습니다.

• 앱 위젯 호스트는 구성 활동을 호출하며 구성 활동은 항상 결과를 반환해야 합니다. 결과에는 활동을 실행한 인텐트에 의해 전달된(추가 인텐트에 저장된) 앱 위젯 ID가 포함되어야 합니다EXTRA_APPWIDGET_ID.
  • 구성 활동이 실행될 때 시스템에서 ACTION_APPWIDGET_UPDATE 브로드캐스트 를 보내지 않습니다. 즉, 위젯이 생성될 때 위젯 업데이트를 처음에는 호출하지 않습니다. 위젯을 처음 만들 때 GlanceAppWidget에 업데이트를 요청하는 것은 구성 활동의 책임입니다. 하지만 후속 주기의 경우 업데이트가 자동으로 트리거됩니다.

구성에서 결과를 반환하고 Glance 위젯을 업데이트하는 방법의 예는 다음 섹션의 코드 스니펫을 참고하세요.

구성 활동에서 위젯 업데이트

위젯이 구성 활동을 사용하는 경우 구성이 완료된 후 위젯을 업데이트하는 것은 활동의 책임입니다. GlanceAppWidget 인스턴스에서 직접 수동 업데이트를 트리거하여 이 작업을 실행할 수 있습니다.

다음은 위젯을 제대로 업데이트하고 구성 활동을 닫는 절차를 요약한 것입니다.

1. 활동을 실행한 인텐트에서 앱 위젯 ID를 가져옵니다.

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

2. 활동 결과를 RESULT_CANCELED로 설정합니다.

   이러한 방식으로 사용자가 끝에 도달하기 전에 활동을 취소하면 시스템에서 구성이 취소되었음을 앱 위젯 호스트에 알리고 호스트는 위젯을 추가하지 않습니다.

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

3. 사용자의 환경설정에 따라 위젯을 구성합니다. 예를 들어 선택사항을 영구 Datastore 또는 로컬 데이터베이스에 작성합니다.

4. 구성이 완료되면 플랫폼 위젯 ID에 해당하는 GlanceId를 검색합니다.

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

5. GlanceAppWidget 인스턴스에서 update 정지 함수를 호출하여 위젯 콘텐츠를 업데이트합니다.

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

6. 반환 인텐트를 만들고 활동 결과를 사용하여 설정한 다음 활동을 완료합니다.

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

위젯 구성 옵션

기본적으로 앱 위젯 호스트는 사용자가 위젯을 홈 화면에 추가한 직후 구성 활동을 한 번만 실행합니다. 하지만 기본 위젯 구성을 제공하여 사용자가 기존 위젯을 재구성하거나 초기 위젯 구성을 건너뛸 수 있는 옵션을 지정할 수 있습니다.

사용자가 배치된 위젯을 재구성할 수 있도록 함

사용자가 기존 위젯을 재구성하도록 하려면 appwidget-provider의 widgetFeatures 속성에서 reconfigurable 플래그를 지정합니다. 예를 들면 다음과 같습니다.

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

사용자는 위젯을 길게 터치하고 그림 1에서 1로 표시된 재구성 버튼을 탭하여 위젯을 재구성할 수 있습니다.

위젯의 기본 구성 사용

사용자가 초기 구성 단계를 건너뛸 수 있도록 하여 더 원활한 위젯 환경을 제공할 수 있습니다. 이렇게 하려면 widgetFeatures 필드에서 configuration_optional 및 reconfigurable 플래그를 모두 지정합니다. 이를 통해 사용자가 위젯을 추가한 후 구성 활동 실행을 우회할 수 있습니다. 앞서 언급했듯이 사용자는 나중에 위젯을 재구성 할 수 있습니다. 예를 들어 시계 위젯은 초기 구성을 우회하고 기본적으로 기기 시간대를 표시할 수 있습니다.

다음은 구성 활동을 재구성 가능 및 선택사항으로 표시하는 방법을 보여주는 예입니다.

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