워치 페이스 형식 설정

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

기본 요건

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

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

    SDK에는 aapt2, android.jar 등 다른 필수 도구가 포함되어 있습니다.

  2. 또는 이러한 기능을 제공할 수 있는 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을 지원합니다. 앱 버전을 구성하는 방법을 자세히 알아보세요.

<?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" shape="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에 업로드하기 전에 유효성 검사기를 사용하세요. 도구를 사용하여 시계 화면에 오류가 없는지, 메모리 사용 권장사항을 준수해야 합니다

시계 화면 App Bundle 빌드

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

이는 GitHub 샘플에 나와 있습니다.