생성된 위젯 미리보기를 사용하면 위젯이 사용자의 홈 화면에 어떻게 표시되는지 정확하게 반영하는 동적 맞춤 미리보기를 만들 수 있습니다. 푸시 API를 통해 제공됩니다. 즉, 앱은 위젯 호스트로부터 명시적인 요청을 받지 않고도 수명 주기 중 언제든지 미리보기를 제공합니다.
이 가이드에서는 Glance 기반 위젯의 미리보기를 제공하는 방법을 설명합니다. 위젯이 RemoteViews로 구현된 경우 위젯 선택 도구에 미리보기 추가를 참고하세요.
Glance 위젯의 앱 위젯 선택 도구 환경을 개선하려면 Android 15 이상 기기에서 GlanceAppWidget.providePreview를 사용하여 생성된 위젯 미리보기를 제공하고, 이전 버전의 경우 previewImage를 지정하고, 생성된 미리보기를 사용할 수 없는 경우 Android 15 이상에서 대체로 지정합니다.
자세한 내용은 YouTube의 실시간 소식 및 위젯으로 앱 보강을 참고하세요.
생성된 위젯 미리보기를 위한 앱 설정
Android 15 이상 기기에서 생성된 위젯 미리보기를 표시하려면 먼저 모듈 build.gradle 파일에서 compileSdk 값을 35 이상으로 설정하여 위젯 선택 도구에서 생성된 미리보기를 사용 설정합니다.
그러면 앱은 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를 하나 이상 지정하여 이전 Android 버전을 지원합니다. 위젯 디자인 가이드에서 다양한 그리드 크기에 적합한 최소 DP 값을 확인할 수 있습니다.
이전 Android 버전 지원
Android 14 이하를 실행하는 기기에서 위젯 미리보기를 표시하거나 Android 15 이상에서 생성된 미리보기를 사용할 수 없는 경우 previewImage 속성을 지정합니다.
위젯의 모양을 변경하는 경우 미리보기 이미지를 업데이트합니다.