🍎 WidgetKit 이란 ?

WidgetKit | Apple Developer

🔒 잠금화면 위젯 만들기 - WidgetKit
🎸 Live Activity 사용해 보기

이번 글에서는 WidgetKit에 대해서 다뤄볼 예정이다.

주로 Flutter에 관한 글만 작성하는 편인데, 다른 언어나 프레임워크에 대해서 작성해 놓지 않다보니 가끔 사용하려고 할 때마다 잊어버려서 정리하는 차원에서 작성을 해보려고 한다.

WidgetKit

WidgetKit이란 iOS 14 버전부터 도입된 프레임워크로, 사용자가 홈 화면 및 잠금화면에서 손쉽게 정보를 확인할 수 있는 위젯을 개발하는데 사용되는 기능이다.

iOS 14 이하를 타겟 한다면 당연히 예외처리를 진행해 주어야 하기 때문에 이 부분을 놓치지 말아야 한다. 여기서는 iOS 14 이상만 타겟하기에 고려하지 않을 예정이다.

Static ? Intent ?

WidgetKit에서 위젯을 설정하는 방법이 두 가지가 있다.

Static Configuration과 Intent Configuration이다.

Static Configuration

먼저 Static에 대해서 살펴보자면, 의미 그대로 고정된 위젯이다.

위젯의 데이터가 고정되어서 정적이거나 주기적으로 업데이트만 필요한 경우에 사용할 수 있는 위젯 종류이다.

Intent Configuration

그렇다면 Intent는 당연히 반대 개념일 것이다.

위젯의 데이터가 고정적이지 않고 변경할 수 있으며 사용자 개인화가 가능한 위젯을 적용하고 싶을 때에 사용할 수 있는 방법이다.

글로 보면 이해가 안될 수 있지만 iOS에서는 위젯의 편집 기능이 있는 경우와 없는 경우 딱 두 가지만 사용할 수 있기 때문에 그 차이라고 보면 된다.

즉 Static Configuration은 애플 기본 앱 중 날씨, 캘린더, 배터리 위젯과 같이 정해놓은 데이터만 업데이트하여 보여지게 되고 반면 미리알림, 단축어, 팟캐스트 처럼 위젯에서 보여질 데이터를 사용자가 직접 선택하여 위젯을 편집할 수 있는 방법이 Intent Configuration인 것이다.

당연히 Intent Configuration이 구조가 더 복잡하고 구현하기가 상대적으로 복잡하게 된다.

Components

WidgetKit을 사용하기 앞서 핵심 구성 요소에 대해서 우선 알아보도록 하겠다.

TimelineProvider, Entry, Timeline 이렇게 3 가지의 핵심 구성 요소가 있고, 데이터를 제공하고 관리하는데 핵심적인 역할을 수행하는 영역이다.

TimelineProvider

위젯에 필요한 데이터를 제공하는 프로토콜로, 어떤 데이터를 언제 표시할지를 정의하는 요소이다.

placeholder
위젯의 초기 상태를 나타내며 네트워크 요청시 요청이 완료되기 전까지 보여줄 기본 데이터를 설정한다.

getSnapshot
미리보기 또는 빠른 업데이트를 위해 현재 데이터를 제공하며, 위젯을 추가하거나 설정에서 미리보기시에 호출되는 메서드이다.

getTimeline
일정 간격으로 데이터를 업데이트할 때를 포함한 타임라인을 제공하며, 여러 TimelineEntry를 포함한 Timeline 객체를 생성하여 반환해 주기적으로 위젯의 데이터를 업데이트하는 데 사용된다.

Entry

Entry는 TimelineEntry 프로토콜을 준수하는 객체로, 위젯에 표시될 데이터를 나타내며 생성된 각 Entry는 특정 시간에 어떤 데이터를 표시할지를 정의하게 된다.

date 프로퍼티를 사용해 시간을 생성할 수 있으며, 데이터 필드를 추가하여 보여줄 데이터를 나타낼 수 있다.

Timeline

여러 개의 Entry로 구성된 객체로, 특정 시간에 어떤 데이터를 표시할지를 정의하는데 사용된다.

entries
TimelineEntry 객체의 배열로 각 Entry는 특정 시간에 표시될 데이터와 시간을 포함한다.

reloadPolicy
리로드 되어야하는 시점을 정의하며 .atEnd, .after, .never를 사용할 수 있다.

Add WidgetKit

이제 XCode에 프로젝트를 생성한 뒤에 본격적으로 WidgetKit을 사용해보도록 하자.

아래 경로에서 WidgetExtension을 추가해 주도록 하자.

File > Target > ios

원하는 WidgetKit 이름을 추가해주면 되는데, 여기서 중요한 부분이 바로 "include Configuration App Intent" 부분이다.

위에서 설명한 것처럼 WidgetKit은 StaticConfiguration과 IntentConfiguration 이렇게 두 가지 설정이 있다고 했었다.

이 부분을 체크하게 되면 IntentConfiguration으로 생성되는 것이기 때문에, 우선 체크를 해제하고 StaticConfiguration으로 생성해 주도록 하자.

이제 간단한 예제가 작성된 파일이 생성된 것을 확인할 수 있다.

프로젝트를 빌드한 후에 위젯을 추가해보면, 위젯을 선택할 수 있도록 나타내는 것을 확인할 수 있다.

UI

간단하게 UI 적인 부분을 가볍게 살펴보도록 하자.

WidgetFamily

먼저 사이즈이다. WidgetKit의 사이즈는 총 4가지 타입을 사용하도록 되어 있으며, 원하는 사이즈만을 임의로 지정할 수도 있다.

.systemSmall
.systemMedium
.systemLarge
.systemExtraLarge (only iPad)

원하는 사이즈만을 지정하고 싶다면 supportedFamilies 프로퍼티를 사용해 배열로 enum 타입의 사이즈를 추가해 주면 된다.

struct StaticWidgetKit: Widget {
    let kind: String = "StaticWidgetKit"
    
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: Provider()) { entry in
            StaticWidgetKitEntryView(entry: entry)
                .containerBackground(.fill.tertiary, for: .widget)
        }
        .configurationDisplayName("My Widget")
        .description("This is an example widget.")
        .supportedFamilies([.systemSmall, .systemLarge])
    }
}

사이즈별로 UI를 분기하고 싶다면 환경변수를 사용하면 된다.

struct MyWidgetEntryView : View {
    var entry: Provider.Entry

    @Environment(\.widgetFamily) var family

    var body: some View {
        switch family {
        case .systemSmall:
            SmallWidgetView()
        case .systemMedium:
            MediumWidgetView()
        case .systemLarge:
            LargeWidgetView()
        case .systemExtraLarge:
            ExtraLargeWidgetView()
        @unknown default:
            SmallWidgetView()
        }
    }
}

Display

위젯을 선택할 때에 상단에 타이틀과 설명이 노출되는 것을 알 수 있는데, 이 부분을 변경하고 싶다면 각각 configurationDisplayName, description 프로퍼티에 텍스트를 변경해주면 된다.

TimelineProvider

TimelineProvider 객체에 대해서 확인해 보도록 하자.

TimelineEntry 부분의 emoji 대신 텍스트를 받아오도록 수정하고, TimelineProvider 메서드들의 상태를 가져오도록 하자.

struct SimpleEntry: TimelineEntry {
    let date: Date
    let text: String
}

placeholder, getSnapshot, getTimeline 메서드 에서 TimelineEntry 를 호출할 때에 각 상태를 텍스트로 넣어주도록 하자.

    func placeholder(in context: Context) -> SimpleEntry {
        SimpleEntry(date: Date(), text: "placeholder")
    }
    
    func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> ()) {
        let entry = SimpleEntry(date: Date(), text: "getSnapshot")
        completion(entry)
    }
    
    func getTimeline(in context: Context, completion: @escaping (Timeline<Entry>) -> ()) {
        var entries: [SimpleEntry] = []
        
        let currentDate = Date()
        for hourOffset in 0 ..< 5 {
            let entryDate = Calendar.current.date(byAdding: .hour, value: hourOffset, to: currentDate)!
            let entry = SimpleEntry(date: entryDate, text: "getTimeline")
            entries.append(entry)
        }
        
        let timeline = Timeline(entries: entries, policy: .atEnd)
        completion(timeline)
    }

이제 다시 빌드한 후에 상태를 확인해보면, 위젯을 추가하려고 할 때에 getSnapshot 메서드의 TimelineEntry를 사용하고, 위젯이 추가된 후에 데이터를 불러오고 나면 getTimeline 메서드가 호출되는 것을 확인할 수 있다.

placeholder 메서드가 호출되지 않는 경우가 많은데, 데이터를 불러오는데 초기에 로딩이 발생하는 경우에만 나타나기 때문에 일반적으로는 빈 데이터를 넣어서 보여주는 용도로 사용된다.

getTimeline 메소드를 수정해서 시간에 따른 업데이트 시점을 조정해보도록 하자.

반복문을 사용해서 5개의 Entry 객체를 3초 간격으로 업데이트 하도록 변경하는 코드이다.

    func getTimeline(in context: Context, completion: @escaping (Timeline<SimpleEntry>) -> ()) {
        var entries: [SimpleEntry] = []

        let currentDate = Date()
        for i in 0..<5 {
            let entryDate = Calendar.current.date(byAdding: .second, value: i * 3, to: currentDate)!
            let entry = SimpleEntry(date: entryDate, text: "getTimeline")
            entries.append(entry)
        }

        let timeline = Timeline(entries: entries, policy: .atEnd)
        completion(timeline)
    }

3초 마다	2초 마다

getTimeline 메서드안에서 Entry 객체의 date 프로퍼티의 설정에 따라 시간을 원하는 주기로 생성해 줄 수 있다.

policy

policy에 대한 부분을 살펴보도록 하겠다.

리로드 시기를 설정하는 부분인데, .atEnd, .after(Date), .never 3가지의 기준을 사용할 수 있다.

타임라인에 대한 기준을 나타내는 플로우이다.

atEnd
atEnd는 마지막 타임라인 이 후에 새로운 타임라인을 요청하게 된다.
만약에 [now, 1hr, 2hr] 이렇게 타임라인을 생성 하였다면, 새로운 타임라인을 요청하여 [2hr, 3hr, 4hr]의 타임라인을 다시 생성하여 주기적으로 업데이트 할 수 있게 된다.

after(Date)
after는 특정 시점 이 후에 새로운 타임라인을 요청하게 되는 방식이다.
[now, 1hr, 2hr] 타임라인을 생성하고 after를 1시간 후로 설정하게 되면, 타임라인을 지금으로 부터 1시간 뒤에 다시 생성한다는 의미이다.

never
never는 더 이상 새로운 타임라인을 요청하고 싶지 않을 때 사용하면 되며, never 사용시 더 이상 데이터를 업데이트 하지 않는다.

policy 기준은 만들고자 하는 기능에 맞게 기준을 테스트 해보면서 적당한 타입을 사용해서 생성되어야 하고 WidgetKit은 생성된 타임라인에 의해 정확히 업데이트가 되지 않을 수 있기 때문에 이 부분도 반드시 고려하고 있어야 한다.

위젯은 여러 서비스의 앱들이 지원하여 사용되다 보니 모든 위젯의 업데이트 시기가 자주 호출된다면 디바이스가 과부화 걸릴 수도 있기 때문에 애플은 배터리 수명을 최적화하기 위해 대략 15분 단위로 권장하고 있고 절대적인 규칙은 아니라고 한다.

지금은 테스트를 하기 위해서 업데이트를 초단위로 해도 문제가 없지만 실제 운영되는 앱은 업데이트 시점을 공격적으로 사용하지 않도록 고려해서 설계해야 문제가 없다.

Intent Configuration

이어서 IntentConfiguration 위젯을 사용할 때에 추가된 부분을 살펴보도록 하자.

WidetKit 추가시 "include Configuration App Intent" 를 체크해서 생성해주면 된다.

코드를 살펴보면 TimelineEntry 객체에 ConfigurationAppIntent 객체를 필수로 받아오도록 하는 것을 볼 수 있다.

이 부분이 StaticConfiguration 과의 다른 점이다.

struct SimpleEntry: TimelineEntry {
    let date: Date
    let configuration: ConfigurationAppIntent
}

ConfigurationAppIntent 코드도 작성되어 있는 것을 확인할 수 있다.

extension ConfigurationAppIntent {
    fileprivate static var smiley: ConfigurationAppIntent {
        let intent = ConfigurationAppIntent()
        intent.favoriteEmoji = "😀"
        return intent
    }
    
    fileprivate static var starEyes: ConfigurationAppIntent {
        let intent = ConfigurationAppIntent()
        intent.favoriteEmoji = "🤩"
        return intent
    }
}

AppIntent 라는 파일안에 ConfigurationAppIntent에 대한 코드가 여기에서 작성되어 있다.

import WidgetKit
import AppIntents

struct ConfigurationAppIntent: WidgetConfigurationIntent {
    static var title: LocalizedStringResource = "Configuration"
    static var description = IntentDescription("This is an example widget.")

    // An example configurable parameter.
    @Parameter(title: "Favorite Emoji", default: "😃")
    var favoriteEmoji: String
}

Intent	Static

결국 WidgetConfigurationIntent 객체를 사용하여 위젯 편집을 만들어 줄 수 있다.

선택창을 만들어 위젯의 백그라운드 컬러를 변경할 수 있도록 해보자.

먼저 WidgetConfigurationIntent를 사용해서 편집창을 선택 가능하도록 수정해 주자.

struct SelectColorAppIntent : WidgetConfigurationIntent {
    static var title: LocalizedStringResource = "Select Color"
    
    @Parameter(title: "color",default: .redType)
    var type : SelectColorType
}

SelectColorType을 생성해 주도록 하자.

enum SelectColorType: String, AppEnum {
    case redType, blueType, orangeType

    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Color Type"
    static var caseDisplayRepresentations: [SelectColorType : DisplayRepresentation] = [
        .redType: "Red",
        .blueType:"Blue",
        .orangeType: "Oragnge",
    ]
}

생성한 WidgetConfigurationIntent 객체를 확장해 주고, 해당하는 타입의 컬러로 백그라운드 컬러를 만들어주자.

struct IntentWidgetKit: Widget {
    let kind: String = "IntentWidgetKit"

    var body: some WidgetConfiguration {
        AppIntentConfiguration(kind: kind, intent: SelectColorAppIntent.self, provider: Provider()) { entry in
            IntentWidgetKitEntryView(entry: entry)
                .containerBackground(entry.configuration.type == .redType ? .red : entry.configuration.type  == .blueType ? .blue : .orange, for: .widget)
        }
    }
}

extension SelectColorAppIntent {
    fileprivate static var redType : SelectColorAppIntent {
        let intent = SelectColorAppIntent()
        intent.type = .redType
        return intent
    }
    fileprivate static var blueType : SelectColorAppIntent {
        let intent = SelectColorAppIntent()
        intent.type = .blueType
        return intent
    }
    fileprivate static var orangeType : SelectColorAppIntent {
        let intent = SelectColorAppIntent()
        intent.type = .orangeType
        return intent
    }
}

간단하게 구성해 봤는데, 선택 위젯 외에도 텍스트 입력, 스위치 등의 다양한 구성을 편집기능으로 사용할 수 있으니 추가적으로 해당 부분은 별도로 글을 작성해 보도록 하겠다.

WidgetURL

이어서 위젯을 클릭했을 때에 처리할 수 있는 딥링크를 추가해 주도록 하자.

먼저 WidgetKit의 View 객체에서 원하는 터치 포인트에 widgetUrl을 사용해 주면 된다.

URL 타입을 사용하여 원하는 스킴을 만들어 주면 된다.

struct IntentWidgetKitEntryView : View {
    var entry: Provider.Entry

    var body: some View {
        VStack {
            Text(entry.date, style: .time)
        }.widgetURL(URL(string: "widgetSample://test.com"))
    }
}

생성한 스킴을 수신하기 위해 WidowGroup 하위 위젯에 onOpenURL을 사용해 스킴 정보를 수신받아 처리해주면 된다.

import SwiftUI

@main
struct WidgetKitSampleApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL(perform: { url in
                    print(url)
                })
        }
    }
}

WidgetCenter

위젯의 일부 또는 전체 타임라인을 다시 로드하거나 구성을 가져오는 데 사용되는 기능으로 위젯에 있는 데이터를 동적으로 업데이트 또는 상태를 확인할 수 있는 기능이다.

해당 기능도 iOS 14 이상에서만 동작하는 WidgetKit의 일부 기능이다.

예를 들어 위젯에 사용자의 주식 수익률을 보여주고 있다고 가정해보자.
해당 사용자의 인증 여부에 따라 위젯을 업데이트 해주어야 하는데, 사용자의 계정이 로그아웃 되더라도 타임라인이 즉각 업데이트 된다는 보장이 없기 때문에 별도로 로그아웃 처리시 WidgetCenter를 사용해 데이터나 상태를 즉시 업데이트 시켜줄 수 있게 된다.

getCurrentConfigurations

현재 위젯의 상태를 확인할 수 있는 기능이다.

WidgetCenter.shared.getCurrentConfigurations { result in
    switch result {
    case .success(let widgetInfos):
        for widgetInfo in widgetInfos {
            print("Widget kind: \(widgetInfo.kind)")
            print("Widget family: \(widgetInfo.family)")
        }
    case .failure(let error):
        print("Error fetching widget configurations: \(error.localizedDescription)")
    }
}

reloadTimelines

WidgetKit에서 사용 중인 특정 위젯의 타임라인을 다시 생성할 때에 사용할 수 있다.

WidgetCenter.shared.reloadTimelines(ofKind: "MyWidget")

WidgetKit에서 사용 중인 kind와 일치하여야 하는데, kind는 WidgetKit에서 설정할 수 있다.

reloadAllTimelines

특정 위젯이 아닌 전체 WidgetKit의 타임라인을 다시 생성해 줄 때에 사용할 수 있다.

WidgetCenter.shared.reloadAllTimelines()

AppGroup

이번에는 앱에 숫자를 증가시켜 UserDefaults를 사용해 증가한 값을 저장하고 WidgetKit에서 해당 데이터를 가져와 업데이트 시점에 증가된 카운트 값을 보여줄 수 있도록 해보자.

WidgetKit에서 가져오는 UserDefaults 값이 공유되지 못하고 있는 것을 알 수 있다.

이유는 WidgetKit의 환경이 앱과는 독립적으로 작동되기 때문에 환경이 완전히 분리되어 있는 상태이다. 즉 동일 환경에 위치한 앱이 아닌 것이다.

이러한 문제를 해결하기 위해서는 공유 컨테이너를 사용해 데이터가 공유될 수 있도록 메커니즘을 제공해 주어야 한다.

AppGroup을 추가해 UserDefaults환경을 공유시켜 주도록 하자.

TARGETS을 클릭해서 Capablility를 추가해 주도록 하자.

App Groups를 추가해 주면 된다.

App Groups가 추가된 것이 보이는데, Apple Developer에서 동일 계정으로 사용중인 App Groups 목록이 모두 보여지는데, 새롭게 그룹을 생성하고 싶다면 "+"를 클릭해 주도록 하자.

해당 프로젝트에서 사용하고 싶은 그룹의 이름을 자유롭게 지정해 주면된다.

새롭게 추가된 App Group을 선택해 체크해주자.

환경을 공유하고 싶은 Widget의 타겟을 변경하여 동일하게 App Groups를 추가해 준뒤, 앞서 체크한 그룹의 동일한 그룹을 여기서도 체크해 주도록 하자.

이제 UserDefaults 인스턴스시 suiteName에 추가한 App Group을 사용하면 된다.

UserDefaults(suiteName: "group.tyger.widgetSample")

이제 정상적으로 로컬 데이터베이스에 있는 데이터가 공유된 것을 확인할 수 있다.

마무리

iOS의 WidgetKit에 대해서 글을 작성했는데, 한 번에 다룰 내용이 많아서 디테일하게 다뤄봐야 할 내용이나 사용 방법들을 전부 작성하지는 못하였다.

추가적인 부분에 대해서는 별도로 글을 작성할 예정이고, Android에서 사용하는 위젯에 대한 내용과 Flutter에서 iOS, Android의 위젯을 연결해 사용할 수 있는지에 대해서도 작성해 보도록 하겠다.

긴 글 읽어주셔서 감사합니다 !