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

시계 화면 푸시를 위해 Wear OS 앱 구성
컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시계 화면 푸시를 사용하면 앱이 Wear OS 기기에서 시계 화면을 관리할 수 있습니다. 여기에는 시계 화면 추가, 업데이트, 삭제, 활성 시계 화면 설정이 포함됩니다. Watch Face Push API를 사용하도록 Wear OS 앱을 구성합니다.

설정

필요한 종속 항목을 포함합니다.

implementation("androidx.wear.watchface:watchface-push:1.3.0-alpha07")

AndroidManifest.xml에 다음을 추가합니다.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- Required to use the Watch Face Push API.  -->
    <uses-permission android:name="com.google.wear.permission.PUSH_WATCH_FACES" />

    <!-- Required to be able to call the setWatchFaceAsActive() method. -->
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />

</manifest>

관리자 인스턴스에 대한 참조 가져오기

WatchFacePushManager 인스턴스를 가져옵니다.

val manager = WatchFacePushManager(context)

WatchFacePushManager는 워치 페이스 푸시와 상호작용하는 모든 메서드에 대한 액세스를 제공합니다.

슬롯 작업

시계 화면 푸시를 사용할 때의 핵심 개념은 시간대입니다. 슬롯은 애플리케이션에 속한 설치된 시계 화면을 처리하는 방법입니다. 시스템은 마켓플레이스에 있을 수 있는 최대 슬롯 수를 설정합니다. Wear OS 6에서는 한도가 1입니다.

시계 화면을 업데이트하거나 삭제할 때 slotId는 작업을 실행할 시계 화면을 식별하는 데 사용됩니다.

시계 화면 목록

설치된 시계 화면 세트를 나열하려면 listWatchFaces()를 사용하세요.

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
val remainingSlots = response.remainingSlots

이렇게 하면 슬롯을 사용할 수 있는지 또는 시계 화면을 추가하려면 기존 시계 화면을 교체해야 하는지 확인할 수 있습니다. 목록에는 설치된 시계 화면에 관한 세부정보도 표시됩니다. 예를 들어 특정 시계 화면 패키지가 설치되어 있는지 확인하려면 다음을 실행합니다.

suspend fun isInstalled(packageName: String) = watchFacePush.listWatchFaces()
    .installedWatchFaceDetails.any { it.packageName == packageName }

시계 화면 추가

listWatchFaces 응답에 따라 사용 가능한 슬롯이 있는 경우 addWatchFace() 메서드를 사용해야 합니다.

try {
    // Supply the validation token along with the watch face package data itself.
    val slot = watchFacePushManager.addWatchFace(parcelFileDescriptor, token)
    Log.i(TAG, "${slot.packageName} (${slot.versionCode}) added in slot ${slot.slotId}")
} catch (e: AddWatchFaceException) {
    // Something went wrong adding the watch face.
}

시계 화면 업데이트

시계 화면을 업데이트하면 지정된 슬롯의 콘텐츠를 새 패키지로 대체할 수 있습니다. 동일한 시계 화면을 최신 버전으로 업그레이드하거나 시계 화면을 완전히 다른 시계 화면으로 교체할 수 있습니다.

// Replacing the com.example.watchfacepush.green watch face with
// com.example.watchfacepush.red.
val slotId = watchFacePushManager.listWatchFaces().installedWatchFaceDetails.
    firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId

try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: UpdateWatchFaceException) {
    // Something went wrong updating the watch face.
}

시계 화면 삭제하기

시계 화면을 삭제하려면 다음 단계를 따르세요.

// Remove the com.example.watchfacepush.green watch face.
val slotId = watchFacePushManager.listWatchFaces().installedWatchFaceDetails.
    firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: RemoveWatchFaceException) {
    // Something went wrong removing the watch face.
}

이렇게 하면 시계 화면이 항상 시스템 시계 화면 선택 도구에서 찾을 수 있고, 로고를 눈에 잘 띄게 표시할 수 있으며, 휴대전화에서 마켓플레이스 앱을 실행하는 버튼을 표시할 수도 있습니다.

시계 화면이 활성 상태인지 확인하기

마켓플레이스에 활성 시계 화면이 설정되어 있는지 확인하는 것은 사용자가 원활한 환경을 이용할 수 있도록 하는 데 중요합니다. 마켓플레이스에 이미 활성 시계 화면이 설정되어 있으면 사용자가 다른 시계 화면을 선택하려는 경우 마켓플레이스 앱을 통해 현재 시계 화면을 교체하기만 하면 됩니다. 그러나 마켓플레이스에 활성 시계 화면이 설정되어 있지 않으면 휴대전화 앱에서 사용자에게 추가 안내를 제공해야 합니다. 이 사용자 환경을 처리하는 방법에 관한 자세한 내용은 전화 앱 섹션을 참고하세요.

마켓플레이스에 활성 워치 페이스가 설정되어 있는지 확인하려면 다음 단계를 따르세요.

기본 시계 화면 제공

워치 페이스 푸시는 마켓플레이스 앱이 설치될 때 기본 시계 화면을 설치하는 기능을 제공합니다. 이렇게 해도 기본 시계 화면이 활성 상태로 설정되지는 않지만 (활성 시계 화면 설정 참고) 시스템 시계 화면 선택 도구에서 시계 화면을 사용할 수 있습니다.

이 기능을 사용하려면

Wear OS 앱 빌드에서 다음 경로에 기본 시계 화면을 포함합니다. assets/default_watchface.apk

AndroidManifest.xml에 다음 항목을 추가합니다.

<application ...>
<meta-data
    android:name="com.google.android.wearable.marketplace.DEFAULT_WATCHFACE_VALIDATION_TOKEN"
    android:value="@string/default_wf_token" />

활성 시계 화면 설정

워치 페이스 푸시는 마켓플레이스 앱이 활성 워치 페이스를 설정하는 수단을 제공합니다.

즉, 현재 활성 시계 화면이 마켓플레이스에 속하지 않는 경우 앱에서 활성 시계 화면을 마켓플레이스에 속한 시계 화면으로 설정할 수 있습니다. 마켓플레이스에 이미 활성 시계 화면이 있는 경우 updateWatchFace를 호출하여 시계 화면 슬롯의 콘텐츠를 다른 시계 화면으로 교체하여 다른 시계 화면으로 변경합니다.

활성 시계 화면을 설정하는 방법은 두 단계로 이루어집니다.

활성 시계 화면을 설정하는 데 필요한 Android 권한을 획득합니다.
setWatchFaceAsActive 메서드를 호출합니다.

활성 워치 페이스 설정 권한 획득

필요한 권한은 SET_PUSHED_WATCH_FACE_AS_ACTIVE이며 매니페스트에 추가해야 합니다.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    ...
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />
</manifest>

런타임 권한이므로 앱이 실행될 때 사용자에게 이 권한을 요청해야 합니다 (이 작업을 지원하는 Accompanist 라이브러리를 고려하세요).

워치 페이스를 활성 워치 페이스로 설정

권한이 부여되면 활성 상태여야 하는 시계 화면의 슬롯 ID에서 setWatchFaceAsActive를 호출합니다.

watchFacePushManager.setWatchFaceAsActive(slotId)

이 방법이 사용되면 휴대전화 앱에서 활성 시계 화면을 수동으로 설정하는 방법을 안내해야 합니다.

시계 화면 APK에서 추가 메타데이터 읽기

WatchFaceSlot 객체는 시계 화면에서 선언할 수 있는 추가 정보를 가져오는 수단도 제공합니다.

이는 동일한 시계 화면의 사소한 변형이 있는 경우에 특히 유용합니다. 예를 들어 다음과 같이 시계 화면을 정의할 수 있습니다.

Package name: com.myapp.watchfacepush.mywatchface
패키지 버전: 1.0.0

하지만 이 시계 화면은 4가지 서로 다른 APK로 제공될 수 있습니다. 모두 거의 동일하지만 기본 색상(워치 페이스 형식 XML의 ColorConfiguration에 설정된 빨간색, 노란색, 녹색, 파란색)이 다릅니다.

그러면 이러한 약간의 변형이 4개의 APK 각각에 반영됩니다.

<!-- For watch face com.myapp.watchfacepush.mywatchface -->
<property
        android:name="default_color"
        android:value="red" />

맞춤 속성을 사용하면 앱에서 다음 변형 중 어떤 변형이 설치되어 있는지 확인할 수 있습니다.

watchFaceDetails
    .getMetaDataValues("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()

고려사항

앱에서 시계 화면 푸시를 구현할 때 중요한 고려사항은 전원 소모, 캐싱, 번들 시계 화면 업데이트, 대표적인 기본 시계 화면 제공에 중점을 두는 것입니다.

전원

Wear OS에서 실행되는 앱의 경우 전력 소모가 중요한 고려사항입니다. 마켓플레이스 앱의 Wear OS 구성요소:

앱은 사용자가 직접 상호작용하는 경우가 아니라면 최대한 적게 실행되어야 합니다. 여기에는 다음이 포함됩니다.
- 전화 앱에서 앱을 깨우는 작업 최소화
- WorkManager 작업 실행 최소화
시계가 충전 중일 때 분석 보고를 예약합니다.
1. Wear OS 앱 또는 기타 측정항목의 사용 통계를 보고하려면 requiresCharging 제약조건과 함께 WorkManager를 사용하세요.
시계가 충전 중일 때 업데이트를 예약하고 Wi-Fi를 활용:
1. 설치된 시계 화면의 버전을 확인하고 자동으로 업데이트하는 것이 좋습니다. 다시 requiresNetworkType에 requiresCharging 제약 조건과 UNMETERED 네트워크 유형을 사용합니다.
2. 충전 중일 때는 기기가 Wi-Fi에 액세스할 가능성이 높습니다. 업데이트된 APK를 빠르게 다운로드하기 위해 Wi-Fi를 요청하고 완료되면 네트워크를 해제합니다.
3. 마켓플레이스에서 오늘의 시계 화면을 제공하는 경우에도 동일한 안내가 적용됩니다. 시계가 충전되는 동안 이를 미리 다운로드하세요.
활성 시계 화면을 확인하는 작업을 예약하지 마세요.
1. 마켓플레이스에 활성 시계 화면이 있는지, 어떤 시계 화면인지 정기적으로 확인하면 배터리가 소모됩니다. 이 접근 방식은 피해야 합니다.
시계에서 알림을 사용하지 마세요.
1. 앱에서 알림을 사용하는 경우 사용자 작업으로 휴대전화 앱이 열려 여정을 계속할 수 있는 휴대전화에 알림을 표시합니다. setLocalOnly를 사용하여 시계 앱으로 브리징되지 않도록 합니다.

캐싱

표준 마켓플레이스 예시에서는 시계 화면이 휴대전화에서 시계로 전송됩니다. 이 연결은 일반적으로 블루투스 연결이며 속도가 매우 느릴 수 있습니다.

더 나은 사용자 환경을 제공하고 재전송 전력을 보존하려면 Wear OS 기기에 소규모 캐시를 구현하여 APK를 몇 개 저장하는 것이 좋습니다.

사용자가 다른 시계 화면을 사용해 본 후 이전에 선택한 시계 화면으로 되돌리기로 결정하는 경우 이 작업은 거의 즉시 이루어집니다.

마찬가지로 Wear OS 기기가 충전되는 동안 시계 화면이 다운로드되는 오늘의 시계 화면 또는 유사한 스킴의 미리 캐싱에도 사용할 수 있습니다.

번들 시계 화면 업데이트

앱에는 앞에서 설명한 대로 기본 시계 화면 애셋이 포함될 수 있습니다. 마켓플레이스 앱이 설치될 때 이 시계 화면이 시스템에 설치되지만, 마켓플레이스 앱 업데이트에 최신 버전이 번들로 제공되는 경우 시계 화면은 업데이트되지 않습니다.

이 상황을 처리하려면 마켓플레이스 앱이 MY_PACKAGE_REPLACED 브로드캐스트 작업을 수신 대기하고 패키지 애셋에서 번들 시계를 업데이트해야 하는지 확인해야 합니다.

대표적인 기본 시계 화면

기본 시계 화면은 사용자가 마켓플레이스를 찾고 사용하는 데 도움이 되는 좋은 방법입니다. 마켓플레이스가 설치되면 시계 화면도 설치되므로 사용자가 시계 화면 갤러리에서 찾을 수 있습니다.

기본 시계 화면을 사용할 때 고려해야 할 사항은 다음과 같습니다.

사용자가 마켓플레이스 앱에서 시계 화면을 제거하도록 선택한 경우 removeWatchFace를 사용하지 마세요. 대신 이 경우 updateWatchFace를 사용하여 시계 화면을 기본 시계 화면으로 되돌립니다. 이렇게 하면 사용자가 갤러리에서 시계 화면을 찾아 설정할 수 있습니다.
로고와 테마 설정을 통해 기본 시계 화면을 간단하고 즉시 알아볼 수 있도록 만듭니다. 이렇게 하면 사용자가 시계 화면 갤러리에서 시계 화면을 쉽게 찾을 수 있습니다.
기본 시계 화면에 버튼을 추가하여 휴대전화 앱을 엽니다. 이 작업은 두 단계로 할 수 있습니다.
1. 시계 화면에 Launch 요소를 추가하여 Wear OS 앱을 사용하여 인텐트를 실행합니다. 예를 들면 다음과 같습니다.
  
  <Launch target="com.myapp/com.myapp.LaunchOnPhoneActivity" />
2. LaunchOnPhoneActivity에서 RemoteActivityHelper를 사용하여 전화 앱을 실행합니다.