생성된 위젯 미리보기를 사용하면 위젯이 사용자의 홈 화면에 표시되는 방식을 정확하게 반영하는 동적이고 개인화된 위젯 미리보기를 만들 수 있습니다. 이러한 미리보기는 푸시 API를 통해 제공됩니다. 즉, 앱은 위젯 호스트로부터 명시적 요청을 받지 않고도 수명 주기 중 언제든지 미리보기를 제공합니다.
이 가이드에서는 Glance 기반 위젯의 미리보기를 제공하는 방법을 설명합니다. 위젯이 RemoteViews로 구현된 경우 위젯 선택기에 미리보기 추가를 참고하세요.
Glance 위젯의 앱 위젯 선택 도구 환경을 개선하려면 Android 15 이상 기기에서 GlanceAppWidget.providePreview를 사용하여 생성된 위젯 미리보기를 제공하고 이전 버전의 경우 previewImage를 지정하세요. 생성된 미리보기를 사용할 수 없는 경우 Android 15 이상에서 대체로 사용됩니다.
자세한 내용은 YouTube의 실시간 업데이트 및 위젯으로 앱 풍부하게 만들기를 참고하세요.
생성된 위젯 미리보기를 위한 앱 설정
Android 15 이상 기기에서 생성된 위젯 미리보기를 표시하려면 먼저 모듈 build.gradle 파일에서 compileSdk 값을 35 이상으로 설정하여 위젯 선택 도구에 RemoteViews를 제공할 수 있도록 합니다.
그러면 앱이 GlanceAppWidgetManager에서 setWidgetPreview을 사용할 수 있습니다. 악용을 방지하고 시스템 상태 문제를 완화하기 위해 setWidgetPreview는 비율 제한 API입니다. 기본 한도는 시간당 약 2회 호출입니다.
Jetpack Glance로 업데이트된 미리보기 생성
Jetpack Glance로 빌드된 위젯의 경우 다음을 실행합니다.
GlanceAppWidget.providePreview함수를 재정의하여 미리보기에 사용할 컴포저블 콘텐츠를 제공합니다.provideGlance에서와 마찬가지로 앱의 데이터를 로드하고 위젯의 콘텐츠 컴포저블에 전달하여 미리보기에 정확한 데이터가 표시되도록 합니다.provideGlance와 달리 재구성이나 효과가 없는 단일 컴포지션입니다.GlanceAppWidgetManager.setWidgetPreviews를 호출하여 미리보기를 생성하고 게시합니다.
미리보기를 제공하는 시스템의 콜백이 없으므로 앱에서 setWidgetPreviews를 호출할 시기를 결정해야 합니다. 업데이트 전략은 위젯의 사용 사례에 따라 다릅니다.
- 위젯에 정적 정보가 있거나 빠른 작업인 경우 앱이 처음 실행될 때 미리보기를 설정합니다.
- 앱에 데이터가 있는 경우(예: 사용자가 로그인하거나 초기 설정한 후) 미리보기를 설정할 수 있습니다.
- 선택한 빈도로 미리보기를 업데이트하는 주기적 작업을 설정할 수 있습니다.
생성된 미리보기 문제 해결
일반적인 문제는 미리보기를 생성한 후 위젯의 드롭 크기에 비해 이미지, 아이콘 또는 기타 컴포저블이 미리보기 이미지에서 누락될 수 있다는 것입니다. 이 드롭 크기는 targetCellWidth 및 targetCellHeight(지정된 경우) 또는 앱 위젯 제공자 정보 파일의 minWidth 및 minHeight에 의해 정의됩니다.
이는 Android가 기본적으로 위젯의 최소 크기에서 보이는 컴포저블만 렌더링하기 때문에 발생합니다. 즉, Android는 기본적으로 previewSizeMode을 SizeMode.Single로 설정합니다. 앱 위젯 제공자 정보 XML에서 android:minHeight 및 android:minWidth을 사용하여 그릴 컴포저블을 결정합니다.
이 문제를 해결하려면 GlanceAppWidget에서 previewSizeMode를 재정의하고 SizeMode.Responsive로 설정하여 DpSize 값 집합을 제공하세요. 이렇게 하면 Android에 미리보기를 렌더링하는 데 필요한 모든 레이아웃 크기가 표시되어 모든 요소가 올바르게 표시됩니다.
특정 폼 팩터에 맞게 최적화합니다. 최소 크기부터 시작하여 위젯의 중단점을 따르는 크기를 하나 또는 두 개 제공합니다. 이전 버전과의 호환성을 위해 previewImage을 하나 이상 지정합니다. 다양한 그리드 크기에 적합한 최소 DP 값은 위젯 디자인 안내에서 확인할 수 있습니다.
위젯 미리보기와의 하위 호환성
Android 15 미만 버전을 실행하는 기기의 위젯 선택 도구에서 위젯 미리보기를 표시하거나 Android 15 이상에서 생성된 미리보기의 대체로 사용하려면 previewImage 속성을 지정합니다.
위젯의 모양을 변경하면 미리보기 이미지를 업데이트합니다.