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

워치 페이스 형식 설정

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

기본 요건

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

Android 14 (API 수준 34) 이상용 SDK를 설치합니다. 시계 화면이 버전 2 관련 기능이나 동작에 의존하지 않는다면 대신 Android 13용 SDK (API 수준 33)를 설치하면 됩니다.

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개 만드세요. 앱의 버전을 구성하는 방법을 자세히 알아보세요.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<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"
        ...>
        <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>
    <!-- Only "Preview" is required. -->
    <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" >

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

이 단계는 다양한 크기의 시계 화면에 서로 다른 동작을 지원하려는 경우에만 필요합니다. 시계 화면이 시계 크기에 맞게 조정되도록 하려면 이 단계를 건너뛰세요.

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

<WatchFaces>
    <!-- The default shape is "CIRCLE". -->
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>

시계 화면 세부정보 선언

앱의 res/raw 리소스 디렉터리에서 시계 화면 모양 지원을 선언할 때 사용되는 file 속성 값에 상응하는 파일을 만듭니다.

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

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

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

루트 요소는 항상 WatchFace입니다.

<WatchFace width="450" height="450" clipShape="CIRCLE">
    <!-- Remainder of your Watch Face Format definition here. -->
    <!-- If this file defines a watch face for a circular device shape, place
         resources used in this file in the "/res/drawable-nodpi" directory. -->
    <!-- If this file defines a watch face for a rectangular or other
         non-circular shape, place resources ued in this file in the
         "/res/drawable-notround-nodpi" directory. -->
</WatchFace>

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

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

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

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

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

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

시계 화면 App Bundle 빌드

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

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