정보 표시에 데이터 노출

정보 표시 데이터 소스는 시계 화면 정보 표시에 정보를 노출하여 시계 화면에서 렌더링할 수 있는 텍스트, 이미지, 숫자를 제공합니다.

데이터 소스 서비스는 SuspendingComplicationDataSourceService를 확장하여 유용한 정보를 시계 화면에 직접 전달합니다.

시작하기

앱 모듈에 다음 종속 항목을 추가합니다. 

dependencies {
  implementiation("androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1")
}

데이터 소스 서비스 만들기

정보 표시 데이터가 필요한 경우 Wear OS 시스템이 데이터 소스에 업데이트 요청을 전송합니다. 업데이트 요청에 응답하기 위해 데이터 소스는 SuspendingComplicationDataSourceService 클래스의 onComplicationRequest() 메서드를 구현해야 합니다.

Wear OS 시스템은 데이터 소스의 데이터가 필요한 경우(예: 데이터 소스를 사용하는 정보 표시가 활성화될 때나 일정 시간이 경과할 때) onComplicationRequest()를 호출합니다.

참고: 데이터 소스가 데이터를 제공하면 시계 모드에서 원시 값을 수신합니다. 시계 화면은 표시할 데이터를 포맷하는 역할을 합니다.

다음 코드 스니펫은 샘플 구현을 보여줍니다.

class MyComplicationDataSourceService : SuspendingComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationData? {
        // Retrieve the latest info for inclusion in the data.
        val text = getLatestData()
        return shortTextComplicationData(text)
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, and title.
            .build()

    // ...
}

매니페스트 선언 및 권한

데이터 소스는 앱 매니페스트에 특정 선언을 포함해야만 Android 시스템에서 데이터 소스로 간주될 수 있습니다. 이 섹션에서는 데이터 소스의 필수 설정에 관해 설명합니다.

앱 매니페스트에 서비스를 선언하고 업데이트 요청 작업의 인텐트 필터를 추가합니다. 또한 매니페스트는 Wear OS 시스템만 제공자 서비스에 결합할 수 있도록 BIND_COMPLICATION_PROVIDER 권한을 추가하여 이 서비스를 보호해야 합니다.

또한 단일 색상 흰색 아이콘을 제공하는 service 요소에 android:icon 속성을 포함합니다. 아이콘에는 벡터 드로어블을 사용하는 것이 좋습니다. 아이콘은 데이터 소스를 나타내며 정보 표시 선택기에 표시됩니다.

예를 들면 다음과 같습니다. 

<service
    android:name=".snippets.complication.MyComplicationDataSourceService"
    android:exported="true"
    android:label="@string/my_complication_service_label"
    android:icon="@drawable/complication_icon"
    android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER">
    <intent-filter>
        <action android:name="android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST" />
    </intent-filter>

    <!-- Supported types should be comma-separated, for example: "SHORT_TEXT,SMALL_IMAGE" -->
    <meta-data
        android:name="android.support.wearable.complications.SUPPORTED_TYPES"
        android:value="SHORT_TEXT" />
    <meta-data
        android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
        android:value="300" />

    <!-- Optionally, specify a configuration activity, where the user can configure your complication. -->
    <meta-data
        android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION"
        android:value="MY_CONFIG_ACTION" />

</service>

메타데이터 요소

매니페스트 파일에서 다음 메타데이터 요소를 확인하세요.

  • android:name="android.support.wearable.complications.SUPPORTED_TYPES": 데이터 소스에서 지원하는 정보 표시 데이터의 유형을 지정합니다.
  • android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS": 시스템에서 데이터 업데이트를 확인해야 하는 빈도를 지정합니다.

정보 표시 데이터 데이터 소스가 활성 상태이면 UPDATE_PERIOD_SECONDS는 시스템에서 데이터 업데이트를 확인할 빈도를 지정합니다. 정보 표시에 나타나는 정보를 규칙적인 일정에 따라 업데이트하지 않아도 되는 경우(예: 푸시 업데이트를 사용 중인 경우) 이 값을 0으로 설정하세요.

UPDATE_PERIOD_SECONDS를 0으로 설정하지 않으면 300(5분) 이상의 값을 사용해야 합니다. 이 값은 기기 배터리 수명을 보존하기 위해 시스템에서 시행하는 최소 업데이트 기간입니다. 또한 기기가 대기 모드에 있거나 기기를 착용하지 않은 경우에는 업데이트 요청이 줄어듭니다.

구성 활동 추가

필요한 경우 데이터 소스는 사용자가 정보 표시 선택기에서 특정 데이터 소스를 선택할 때 사용자에게 표시되는 구성 활동을 포함할 수 있습니다. 예를 들어 세계 시계 데이터 소스에는 사용자가 표시할 도시나 시간대를 선택할 수 있는 구성 활동이 있을 수 있습니다.

예시 매니페스트에는 PROVIDER_CONFIG_ACTION 키가 있는 meta-data 요소가 포함되어 있습니다. 이 요소의 값은 구성 활동을 실행하는 데 사용되는 작업입니다.

구성 활동을 만들고 매니페스트 파일에 구성 활동의 작업과 일치하는 인텐트 필터를 추가합니다. 

<intent-filter>
    <action android:name="MY_CONFIG_ACTION" />
    <category android:name="android.support.wearable.complications.category.PROVIDER_CONFIG" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

활동은 활동의 onCreate() 메서드 내에서 인텐트로부터 구성 중인 시계 화면 설정 슬롯의 세부정보를 가져올 수 있습니다. 

// Keys defined on ComplicationDataSourceService
val id = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_ID, -1)
val type = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_TYPE, -1)
val source = intent.getStringExtra(EXTRA_CONFIG_DATA_SOURCE_COMPONENT)

구성 활동은 제공자와 동일한 패키지 내에 있어야 합니다. 구성 활동은 데이터 소스 설정 여부를 시스템에 알리기 위해 RESULT_OK 또는 RESULT_CANCELED를 반환해야 합니다. 

setResult(RESULT_OK) // Or RESULT_CANCELED to cancel configuration
finish()

푸시 업데이트 사용

앱 매니페스트에서 업데이트 간격을 지정하는 대신 ComplicationDataSourceUpdateRequester 인스턴스를 사용하여 동적으로 업데이트를 시작할 수 있습니다. 업데이트를 요청하려면 requestUpdate()를 호출합니다.

주의: 기기 배터리 수명을 보존하려면 ComplicationDataSourceUpdateRequester의 인스턴스에서 requestUpdate()를 평균 5분 간격보다 더 자주 호출하지 마세요.

시간 종속 값 제공

일부 정보 표시에는 현재 시간에 관련된 값이 표시되어야 합니다. 그 예로는 현재 날짜, 다음 미팅까지의 시간 또는 다른 시간대의 시간이 있습니다.

이러한 값을 최신 상태로 유지하기 위해 정보 표시를 1초 또는 1분마다 업데이트하지 마세요. 그 대신, 시간 종속 텍스트를 사용하여 현재 날짜나 시간에 상대적인 값을 지정하세요. 다음 클래스를 사용하면 이러한 시간 종속 값을 만들 수 있습니다.

타임라인 데이터

사전 정의된 시간에 값의 시퀀스를 제공하는 시계 화면 데이터 소스의 경우 SuspendingTimelineComplicationDataSourceService를 사용합니다.

이러한 예로는 캘린더 앱의 '다음 이벤트' 데이터 소스가 있습니다. 시스템이 다음 이벤트를 위해 데이터 소스를 정기적으로 폴링하는 대신 데이터 소스가 이벤트 타임라인을 한 번 제공할 수 있으며, 캘린더가 변경되면 데이터 소스가 업데이트를 시작할 수 있습니다. 이렇게 하면 시스템의 부하가 최소화되고, 컴플리케이션이 적시에 올바른 이벤트를 표시할 수 있습니다. 

class MyTimelineComplicationDataSourceService : SuspendingTimelineComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationDataTimeline? {
        if (request.complicationType != ComplicationType.SHORT_TEXT) {
            return ComplicationDataTimeline(
                defaultComplicationData = NoDataComplicationData(),
                timelineEntries = emptyList()
            )
        }
        // Retrieve list of events from your own datasource / database.
        val events = getCalendarEvents()
        return ComplicationDataTimeline(
            defaultComplicationData = shortTextComplicationData("No event"),
            timelineEntries = events.map {
                TimelineEntry(
                    validity = TimeInterval(it.start, it.end),
                    complicationData = shortTextComplicationData(it.name)
                )
            }
        )
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, title etc
            .build()

    // ...
}

SuspendingTimelineComplicationDataSourceService의 동작은 다음과 같습니다.

  • 현재 시간이 타임라인의 항목의 시작 시간과 종료 시간 사이에 있으면 시계 화면에서 해당 값을 사용합니다.
  • 현재 시간이 타임라인의 항목에 속하지 않으면 기본값이 사용됩니다. 예를 들어 캘린더 앱에서는 '일정 없음'일 수 있습니다.
  • 현재 시간이 여러 이벤트에 속하는 경우 가장 짧은 이벤트가 사용됩니다.

동적 값 제공

Wear OS 4부터 일부 정보 표시는 플랫폼에서 직접 사용할 수 있는 값을 기반으로 더 자주 새로고침되는 값을 표시할 수 있습니다. 정보 표시에서 이 기능을 제공하려면 동적 값을 허용하는 ComplicationData 필드를 사용하세요. 플랫폼은 정보 표시 제공자를 실행하지 않고도 이러한 값을 자주 평가하고 업데이트합니다.

예시 필드에는 GoalProgressComplicationData의 동적 값 필드와 DynamicComplicationText이 포함되며, 이는 ComplicationText 필드에서 사용할 수 있습니다. 이러한 동적 값은 androidx.wear.protolayout.expression 라이브러리를 기반으로 합니다.

특정 상황에서는 플랫폼에서 동적 값을 평가할 수 없습니다.