생성된 위젯 미리보기를 사용하면 사용자의 홈 화면에 표시되는 방식을 정확하게 반영하는 위젯의 동적 맞춤형 미리보기를 만들 수 있습니다. 이러한 미리보기는 푸시 API를 통해 제공됩니다. 즉, 앱은 위젯 호스트로부터 명시적 요청을 받지 않고도 수명 주기 중 언제든지 미리보기를 제공합니다.
이 가이드에서는 Glance 기반 위젯의 미리보기를 제공하는 방법을 설명합니다. 위젯이 RemoteViews로 구현된 경우 위젯 선택 도구에 미리보기 추가를 참고하세요.
Glance 위젯의 앱 위젯 선택 도구 환경을 개선하려면 Android 15 이상 기기에서
를 사용하여 생성된 위젯 미리보기를 제공하고 이전 버전의 경우 previewImage
를 지정하며 생성된 미리보기를 사용할 수 없는 경우 Android 15+에서 대체로 지정합니다.GlanceAppWidget.providePreview
자세한 내용은 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를 재정의하고 DpSize 값 집합을 제공하여 SizeMode.Responsive로 설정합니다. 이렇게 하면 Android에 미리보기를 렌더링하는 데 필요한 모든 레이아웃 크기가 표시되므로 모든 요소가 올바르게 표시됩니다.
특정 폼 팩터에 맞게 최적화합니다. 최소 크기에서 시작하여 위젯의 중단점을 따르는 크기를 하나 또는 두 개 제공합니다. 이전 버전과의 호환성을 위해
previewImage 를 하나 이상 지정합니다. 위젯 디자인 가이드에서 다양한 그리드 크기에 적합한 최소 DP 값을 확인할 수 있습니다.
SizeMode
위젯 미리보기와의 이전 버전과의 호환성
Android 15보다 낮은 버전을 실행하는 기기의 위젯 선택 도구에서 위젯 미리보기를 표시하거나 Android 15+에서 생성된 미리보기의 대체로 표시하려면
previewImage 속성을 지정합니다.
위젯의 모양을 변경하는 경우 미리보기 이미지를 업데이트합니다.