이 페이지는 Cloud Translation API를 통해 번역되었습니다.

워치 페이스 형식 설정
컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

참고: 이 페이지에서는 시계 화면 구성을 수동으로 관리하는 프로세스의 단계를 보여줍니다. WYSIWYG(What You See Is What You Get) 스타일 도구를 사용하여 시계 화면을 디자인하려면 먼저 시계 화면 스튜디오 가이드를 확인하세요.

이 가이드에는 워치 페이스 형식을 사용하여 시계 화면을 구성하는 데 필요한 도구에 관한 단계, 프로젝트 구조에 관한 몇 가지 제안사항, 해당 구조를 만드는 도구를 적용하는 단계별 안내가 포함되어 있습니다.

기본 요건

워치 페이스 형식을 사용하기 위한 개발 환경을 준비하려면 다음 설정 단계를 완료하세요.

Android 14 (API 수준 34) 이상용 SDK를 설치합니다. 시계 화면이 버전 2에만 해당하는 기능 또는 동작을 사용하지 않는 경우 Android 13 (API 수준 33)용 SDK를 대신 설치할 수 있습니다.

SDK에는 aapt2 및 android.jar를 비롯한 다른 필수 도구가 포함되어 있습니다.
또는 이러한 도구를 제공할 수 있는 Android 스튜디오를 설치합니다.

프로젝트 구조

워치 페이스 형식을 사용하는 맞춤 시계 화면을 만들 때 맞춤 시계 화면 파일이 포함된 Android App Bundle은 Wear OS 앱 로직이 포함된 Android App Bundle과 완전히 분리되어야 합니다. Google Play를 비롯한 일부 앱 스토어에서는 Wear OS 로직과 맞춤 시계 화면을 둘 다 포함하는 Android App Bundle을 업로드할 수 없습니다.

시계 화면 번들 만들기

시계 화면 파일이 포함된 Android App Bundle을 만들려면 다음 섹션에 나온 단계를 완료하세요.

워치 페이스 형식 사용 선언

새 앱의 매니페스트 파일 (AndroidManifest.xml)에 워치 페이스 형식의 용도를 나타내는 애플리케이션 속성을 추가합니다. Wear OS 5 이상을 실행하는 기기의 시계 화면에 대한 액세스를 제한하려는 경우가 아니라면 버전 2를 지원하는 시계 화면 APK와 버전 1을 지원하는 시계 화면 APK를 각각 2개 만듭니다. 앱의 버전을 구성하는 방법을 자세히 알아보세요.

<manifest ...>
    <!--
        Use SDK version 34 for version 2 of WFF, and SDK version 33 for version
        1 of WFF
    -->
    <uses-sdk
        android:minSdkVersion="34"
        android:targetSdkVersion="34" />

    <!--
        WFF is a resource-only format, so the hasCode attribute should be set to
        false to reflect this.
    -->
    <application
        android:label="@string/watch_face_name"
        android:hasCode="false"
        ...>
        <meta-data android:name="com.google.android.wearable.standalone"
            android:value="true" />
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="2" />
    </application>
</manifest>

시계 화면 메타데이터 선언

앱의 res/xml 리소스 디렉터리에 watch_face_info.xml이라는 새 파일을 만듭니다. 여기에서 시계 화면의 메타데이터를 정의합니다.

<?xml version="1.0" encoding="utf-8"?>
<WatchFaceInfo>

    <Preview value="@drawable/watch_face_preview" />
    <Category value="CATEGORY_EMPTY" />
    <AvailableInRetail value="true" />
    <MultipleInstancesAllowed value="true" />
    <Editable value="true" />
</WatchFaceInfo>

이 파일의 필드는 다음 세부정보를 나타냅니다.

Preview

시계 화면의 미리보기 이미지가 포함된 드로어블을 참조합니다.

Category

시계 화면의 카테고리를 정의합니다. 문자열이거나 문자열 참조(예: @string/ref_name)여야 합니다. 각 기기 제조업체는 고유한 시계 화면 카테고리 집합을 정의할 수 있습니다.

기본값은 empty_category_meta로, 이 시계 화면을 시계 화면 선택 도구 뷰 하단에 있는 다른 '빈 카테고리' 시계 화면과 함께 그룹화합니다.

AvailableInRetail

기기의 소매 데모 모드에서 시계 화면을 사용할 수 있는지 여부입니다. 불리언 값이거나 불리언 값 참조(예: @bool/watch_face_available_in_retail)여야 합니다.

기본값은 false입니다.

MultipleInstancesAllowed

시계 화면에 즐겨찾기가 여러 개 있을 수 있는지 여부입니다. 불리언 값이거나 불리언 값 참조(예: @bool/watch_face_multiple_instances_allowed)여야 합니다.

기본값은 false입니다.

Editable

시계 화면을 수정할 수 있는지 여부입니다. 즉, 시계 화면에 설정 또는 하나 이상의 고정되지 않은 정보 표시가 있습니다. 즐겨찾기 목록에서 시계 화면의 수정 버튼을 표시하거나 숨기는 데 사용됩니다.

기본값은 false입니다.

시계 화면 이름 선언

앱의 매니페스트 파일(AndroidManifest.xml)에서 android:label 속성을 시계 화면의 이름으로 설정합니다.

<application android:label="@string/watch_face_name" >

시계 화면 세부정보 선언

기본 WFF 시계 화면 문서의 구조는 다음과 같습니다.

<WatchFace width="450" height="450">
  <Scene>
    <!-- Content to be rendered -->
  </Scene>
</WatchFace>

단일 시계 화면을 사용하는 경우 시계 화면을 구성할 때 이 XML 파일을 res/raw/watchface.xml로 만듭니다. 다양한 화면 모양과 크기를 지원하려면 여러 모양과 크기 지원을 선언하세요.

루트 요소는 항상 WatchFace입니다. height 및 width는 시계 화면에 사용할 좌표 공간의 범위를 정의하며, 시계 화면은 사용 중인 기기에 맞게 크기가 조정됩니다. height 및 width는 실제 픽셀을 나타내지 않습니다.

워치 페이스 형식은 시계 화면에 관한 여러 세부정보를 구성합니다.

시계 화면의 미리보기 이미지에 표시되는 시간 및 걸음 수와 같은 메타데이터
시계 화면의 다양한 색상 테마, 사용자가 전환할 수 있는 요소, 여러 요소 중에서 선택할 수 있는 옵션 등 사용자 구성 시계 화면 형식 버전 2에서는 사용자 구성 내에 표시될 수 있는 버전을 도입합니다. 각 버전은 시계 화면의 시간과 함께 표시되는 요소의 유형과 스타일을 지정하는 사전 설정된 사용자 구성을 지정합니다. 이러한 사전 설정을 사용하면 시각적으로 보기 좋은 요소 그룹을 더 쉽게 만들 수 있습니다. Wear OS 호환 앱에서 사용자는 스크롤 가능한 행을 따라 시계 화면의 다양한 버전을 볼 수 있습니다.
시계 화면의 시각적 요소가 포함된 장면입니다. 장면의 끝부분에 더 가까운 요소는 다른 요소 위에 표시되므로 일반적인 순서는 다음과 같습니다.
- 아날로그 시계의 시침, 분침 또는 디지털 시계의 텍스트
- 요일 또는 사용자의 걸음 수와 같은 추가 정보를 보여주는 정보 표시
- 야영장 이미지와 같이 시계 화면에 시각적 흥미나 장식을 제공하는 기타 그래픽
요소의 그룹: 여러 요소를 동시에 수정할 수 있습니다. 장면 내에서 이러한 그룹의 대안을 만들 수 있습니다. 이를 통해 시스템이 절전 화면 모드로 전환될 때 콘텐츠를 선택적으로 숨기거나 수정할 수 있습니다.

속성은 엄격한 유형이 적용되어 있으며 시계 화면을 만들 때 발생할 수 있는 오류의 원인을 최대한 없애기 위해 빈도 및 유효한 값에 대한 가이드라인이 지정되어 있습니다.

시계 화면 모양 지원 선언 (선택사항)

이 단계는 시계 화면 크기에 따라 다른 동작을 지원하려는 경우에만 필요합니다. 시계 화면이 시계 크기에 맞게 크기 조절되도록 하려면 이 단계를 건너뛰어도 됩니다.

앱의 res/xml 리소스 디렉터리에서 watch_face_shapes.xml에서 지원되는 시계 화면 모양 집합을 선언합니다.

<WatchFaces>

    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>

    <!-- Remove any references to rectangular watch faces -->
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>

그런 다음 각 시계 화면 모양의 시계 화면 모양과 동작을 정의합니다. 도형 파일을 정의하지 않은 경우 watchface.xml 파일 하나만 만들면 됩니다.

이 섹션의 예를 사용하면 원시 XML 파일은 다음과 같습니다.

res/raw/watchface.xml
res/raw/watchface_large_circle.xml
~~res/raw/watchface_rectangle.xml~~

시계 화면 게시자 식별(선택사항)

필요한 경우 앱의 매니페스트 파일에서 시계 화면의 게시자 또는 사용 중인 도구 이름과 버전을 식별하는 데 사용할 수 있는 임의의 문자열을 선언하세요.

<application ...>
    ...
    <property
        android:name="com.google.wear.watchface.format.publisher"
        android:value="<var>{toolName}-{toolVersion}</var>" />
</application>

시계 화면의 정확성 및 성능 확인

개발 중 및 Google Play에 업로드하기 전에 검사기 도구를 사용하여 시계 화면에 오류가 없고 메모리 사용 권장사항을 준수하는지 확인합니다.

게시를 준비할 때 메모리 사용량 최적화 및 메모리 사용량 확인에 대해 자세히 알아보세요.
개발 주기의 일부로 XML 검사기를 사용하는 방법을 자세히 알아보세요.

시계 화면 App Bundle 빌드

시계 화면이 포함된 Android App Bundle을 빌드하려면 Gradle 빌드 시스템을 사용하세요. Gradle을 사용하여 앱을 빌드하는 방법을 자세히 알아보세요.

이는 GitHub 샘플에서 확인할 수 있습니다.