The Watch Face Format is required for watch faces to be installed on devices with Wear OS 5 or later pre-installed and for all new watch faces published on Google Play.
Starting in January 2026, the Watch Face Format will be required for watch faces to be installed on all Wear OS devices.
Learn more about the user-facing changes in this Help Center article.
시계 모드 서비스 빌드
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
시계 화면은 Wear OS 앱에 패키징된 서비스입니다. 사용자가 사용 가능한 시계 화면을 선택하면 선택한 시계 화면이 표시되고 서비스 콜백 메서드가 호출됩니다.
사용자가 시계 화면이 있는 Wear 앱을 설치하면 시계에서 시계 화면 선택기를 통해 시계 화면을 사용할 수 있습니다.
또는 사용자가 페어링된 스마트폰의 호환 앱에서 시계 화면을 선택할 수 있습니다.
이 페이지에서는 시계 화면을 포함하도록 Wear OS 프로젝트를 구성하는 방법 및 시계 화면 서비스를 구현하는 방법에 관해 설명합니다.
시계 화면 프로젝트 만들기
참고: Wear OS 개발에는 프로젝트 설정, 라이브러리 포함, 패키징 편의성을 제공하는 Android 스튜디오를 사용하는 것이 좋습니다.
Android 스튜디오에서 시계 화면을 위한 프로젝트를 생성하려면 다음 단계를 완료하세요.
- File > New > New project를 클릭합니다.
- Select a project template 창에서 Wear 탭을 선택하고 옵션 목록에서 Watch Face를 선택한 후 Next를 클릭합니다.
- Configure your project 창에서 기본값을 수락하고 Finish를 클릭합니다.
Android 스튜디오는 시계 화면 서비스용 app
모듈로 프로젝트를 만듭니다.
종속 항목
Android 스튜디오는 build.gradle
파일에 필요한 종속 항목을 자동으로 추가합니다. 종속 항목에는 AndroidX 시계 화면 라이브러리가 포함되어 있습니다. 이 라이브러리에 관한 자세한 내용은 GitHub의
코드 샘플을 참고하세요.
웨어러블 지원 라이브러리 API 참조
참조 문서는 시계 화면을 구현하는 데 사용하는 클래스에 관한 자세한 정보를 제공합니다. 웨어러블 지원 라이브러리용 API 참조 문서를 찾아보세요.
권한 선언
시계 화면에는 WAKE_LOCK
권한이 필요합니다.
manifest
요소 아래에서 Wear OS 앱과 함께 휴대전화 앱의 매니페스트 파일에 다음 권한을 추가합니다.
<manifest ...>
<uses-permission
android:name="android.permission.WAKE_LOCK" />
<!-- Required for complications to receive complication data and open the provider chooser. -->
<uses-permission
android:name="com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA"/>
...
</manifest>
직접 부팅 지원
직접 부팅 안내에 따라 사용자 잠금 해제 전에 시계 화면을 사용할 수 있도록 해야 합니다.
- 매니페스트에서 서비스의
android:directBootAware
속성을 true
로 설정합니다.
- 시계 화면은 기기 암호화 저장소에 정보를 저장해야 합니다.
서비스 및 콜백 메서드 구현
Wear OS의 시계 화면은 WatchFaceService
로 구현됩니다.
WatchFaceService
를 구현하려면 UserStyleSchema
, ComplicationSlotsManager
, WatchFace
라는 세 가지 객체를 만들어야 합니다.
이 세 객체는 다음 예와 같이 WatchFaceService
의 추상 메서드 세 개를 재정의하여 지정합니다.
Kotlin
class CustomWatchFaceService : WatchFaceService() {
/**
* The specification of settings the watch face supports.
* This is similar to a database schema.
*/
override fun createUserStyleSchema(): UserStyleSchema = // ...
/**
* The complication slot configuration for the watchface.
*/
override fun createComplicationSlotsManager(
currentUserStyleRepository: CurrentUserStyleRepository
): ComplicationSlotsManager = // ...
/**
* The watch face itself, which includes the renderer for drawing.
*/
override suspend fun createWatchFace(
surfaceHolder: SurfaceHolder,
watchState: WatchState,
complicationSlotsManager: ComplicationSlotsManager,
currentUserStyleRepository: CurrentUserStyleRepository
): WatchFace = // ...
}
시계 화면 서비스 등록
시계 화면 서비스를 구현한 후 웨어러블 앱의 매니페스트 파일에 구현을 등록합니다. 사용자가 이 앱을 설치하면 시스템이 서비스에 관한 정보를 사용하여 Wear OS 호환 앱 및 웨어러블 기기의 시계 화면 선택 도구에서 시계 화면을 사용할 수 있도록 설정합니다.
다음 샘플은 <application>
요소 아래에서 시계 화면 구현을 등록하는 방법을 보여줍니다.
<service
android:name=".AnalogWatchFaceService"
android:label="@string/analog_name"
android:permission="android.permission.BIND_WALLPAPER" >
<meta-data
android:name="android.service.wallpaper"
android:resource="@xml/watch_face" />
<meta-data
android:name="com.google.android.wearable.watchface.preview_circular"
android:resource="@drawable/preview_analog_circular" />
<intent-filter>
<action android:name="android.service.wallpaper.WallpaperService" />
<category
android:name=
"com.google.android.wearable.watchface.category.WATCH_FACE" />
</intent-filter>
</service>
웨어러블 기기의 Wear OS by Google 호환 앱과 시계 화면 선택 도구는 기기에 설치된 모든 시계 화면을 사용자에게 표시할 때 com.google.android.wearable.watchface.preview_circular
메타데이터 항목에 의해 정의된 미리보기 이미지를 사용합니다. 드로어블을 가져오려면 Wear OS 기기 또는 에뮬레이터 인스턴스에서 시계 화면을 실행하고 스크린샷을 찍습니다. hdpi 화면이 있는 Wear 기기에서는 미리보기 이미지의 크기가 일반적으로 320x320픽셀입니다.
android.service.wallpaper
메타데이터 항목은 다음 샘플과 같이 wallpaper
요소가 포함된 watch_face.xml
리소스 파일을 지정합니다.
<?xml version="1.0" encoding="UTF-8"?>
<wallpaper xmlns:android="http://schemas.android.com/apk/res/android" />
웨어러블 앱에는 둘 이상의 시계 화면을 포함할 수 있습니다. 각각의 시계 화면 구현에서 웨어러블 앱의 매니페스트 파일에 서비스 항목을 추가해야 합니다.
다음 관련 리소스를 참고하세요.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-07-26(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-26(UTC)"],[],[],null,["# Build a watch face service\n\nA watch face is a [service](/guide/components/services)\npackaged in a [Wear OS app](/training/wearables/apps).\nWhen a user selects an available watch face, the watch face displays and the\nservice callback methods are invoked.\n\nWhen a user installs a Wear app that has watch faces, the watch\nfaces are available on the watch using the watch face selector.\nAlternatively, the user can select a watch face from a companion app on the paired phone.\n\nThis page describes how to configure a Wear OS project to include watch faces and how\nto implement a watch face service.\n\nCreate a watch face project\n---------------------------\n\n**Note:** We recommend that you use [Android Studio](/studio) for Wear OS development, as\nit provides project setup, library inclusion, and packaging conveniences.\n\nComplete the following steps to\n[create a project](/studio/projects/create-project#StartAProject)\nin Android Studio for your watch face:\n\n1. Click **File** \\\u003e **New** \\\u003e **New project**.\n2. In the **Select a project template** window, select the **Wear** tab, then select **Watch Face** from the list of options and click **Next**.\n3. In the **Configure your project** window, accept the default values and click **Finish**.\n\nAndroid Studio creates a project with an `app` module for your watch face service.\n\n### Dependencies\n\nAndroid Studio automatically adds the required dependencies in your `build.gradle`\nfiles. Included in the dependencies is the\n[AndroidX\nwatch face library](/reference/kotlin/androidx/wear/watchface/package-summary); see the\n[code sample](https://github.com/android/wear-os-samples/tree/main/WatchFaceKotlin) on GitHub for details about this library.\n\n### Wearable support library API reference\n\nThe reference documentation provides detailed information about the classes you use to\nimplement watch faces. Browse the\n[API reference\ndocumentation](/reference/android/support/wearable/watchface/package-summary) for the Wearable support library.\n\n### Declare permissions\n\nA watch face requires the `WAKE_LOCK` permission.\nAdd the following permission to the manifest files of both the Wear OS app\nand the mobile phone app under the `manifest` element: \n\n```xml\n\u003cmanifest ...\u003e\n \u003cuses-permission\n android:name=\"android.permission.WAKE_LOCK\" /\u003e\n\n \u003c!-- Required for complications to receive complication data and open the provider chooser. --\u003e\n \u003cuses-permission\n android:name=\"com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA\"/\u003e\n ...\n\u003c/manifest\u003e\n```\n\n### Support direct-boot\n\nYou must make your watchface available before user-unlock by following\n[Direct Boot](https://developer.android.com/training/articles/direct-boot) guidance:\n\n1. Set `android:directBootAware` attribute to `true` for your service in your manifest.\n2. Your watch face should store information in [device encrypted storage](https://developer.android.com/training/articles/direct-boot#access).\n\n\u003cbr /\u003e\n\nImplement the service and callback methods\n------------------------------------------\n\nWatch faces in Wear OS are implemented as a\n[`WatchFaceService`](/reference/kotlin/androidx/wear/watchface/WatchFaceService).\nImplementing a `WatchFaceService` requires creating three objects: a\n`UserStyleSchema`, a `ComplicationSlotsManager`, and a\n`WatchFace`.\n\nThese three objects are specified by overriding three abstract methods from\n`WatchFaceService`, shown in the following example: \n\n### Kotlin\n\n```kotlin\nclass CustomWatchFaceService : WatchFaceService() {\n\n /**\n * The specification of settings the watch face supports.\n * This is similar to a database schema.\n */\n override fun createUserStyleSchema(): UserStyleSchema = // ...\n\n /**\n * The complication slot configuration for the watchface.\n */\n override fun createComplicationSlotsManager(\n currentUserStyleRepository: CurrentUserStyleRepository\n ): ComplicationSlotsManager = // ...\n\n /**\n * The watch face itself, which includes the renderer for drawing.\n */\n override suspend fun createWatchFace(\n surfaceHolder: SurfaceHolder,\n watchState: WatchState,\n complicationSlotsManager: ComplicationSlotsManager,\n currentUserStyleRepository: CurrentUserStyleRepository\n ): WatchFace = // ...\n\n}\n```\n\nRegister the watch face service\n-------------------------------\n\nAfter you implement the watch face service, register the implementation in the manifest\nfile of the wearable app. When users install this app, the system uses the information about\nthe service to make the watch face available in the [Wear OS companion app](https://play.google.com/store/apps/details?id=com.google.android.wearable.app&hl=en) and in the watch face picker on the wearable device.\n\nThe following sample shows how to register a watch face implementation\nunder the [`\u003capplication\u003e`](/guide/topics/manifest/application-element) element: \n\n```xml\n\u003cservice\n android:name=\".AnalogWatchFaceService\"\n android:label=\"@string/analog_name\"\n android:permission=\"android.permission.BIND_WALLPAPER\" \u003e\n \u003cmeta-data\n android:name=\"android.service.wallpaper\"\n android:resource=\"@xml/watch_face\" /\u003e\n \u003cmeta-data\n android:name=\"com.google.android.wearable.watchface.preview_circular\"\n android:resource=\"@drawable/preview_analog_circular\" /\u003e\n \u003cintent-filter\u003e\n \u003caction android:name=\"android.service.wallpaper.WallpaperService\" /\u003e\n \u003ccategory\n android:name=\n \"com.google.android.wearable.watchface.category.WATCH_FACE\" /\u003e\n \u003c/intent-filter\u003e\n\u003c/service\u003e\n```\n\nThe Wear OS by Google companion app and the watch face picker on the wearable device use the preview\nimage defined by the `com.google.android.wearable.watchface.preview_circular` metadata entry when\npresenting users with all the watch faces installed on the device. To obtain this drawable,\nrun the watch face on your Wear OS device or in an emulator instance and\n[take a screenshot](/studio/debug/am-screenshot). On Wear\ndevices with hdpi screens, the preview image is typically 320x320 pixels in size.\n\nThe `android.service.wallpaper` metadata entry specifies the\n`watch_face.xml` resource file, which contains a `wallpaper`\nelement, as shown in the following sample: \n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cwallpaper xmlns:android=\"http://schemas.android.com/apk/res/android\" /\u003e\n```\n\nYour wearable app can contain more than one watch face. You must add a service entry to the\nmanifest file of the wearable app for each of your watch face implementations.\n\nRelated resources\n-----------------\n\n\nRefer to the following related resources:\n\n- [WatchFaceKotlin sample](https://github.com/android/wear-os-samples/tree/deprecated/WatchFaceKotlin)"]]