Moondev

[Android] Server-Sent Events(SSE)를 활용한 실시간 화면 동기화

Moondev — Mon, 17 Nov 2025 00:47:54 +0900

보따리 프로젝트에서는 팀원 입장/퇴장, 물건 추가/삭제/편집, 체크 상태 등 팀에 대한 여러 변경 사항이 발생했을 때 그 화면을 보고 있는 다른 사람의 화면에도 변경 사항이 즉시 반영되어야 했다. 즉, 앱은 서버에서 발생한 변경 사항을 지연 없이 실시간으로 반영해야 한다.

이 글에서는 우선 안드로이드에서 사용 가능한 실시간 처리 방식들을 비교한 뒤,

왜 그중 Server-Sent Events를 선택했는지, 그리고 안드로이드에서 어떻게 구현했는지까지 정리한다.

실시간 처리 방법 비교

아래는 서버와 클라이언트 사이에서 실시간으로 데이터를 주고받는 대표적인 방식들이다.

1) Short Polling

가장 단순한 방식이다.

클라이언트가 일정 주기마다 서버에 요청을 보내며 변화가 있는지 직접 확인한다.

"변경 사항이 있나요?"를 5초마다 반복해서 묻는 방식

장점

구현 난이도가 매우 낮다
서버나 클라이언트 모두 특별한 프로토콜이나 인프라 없이 도입 가능하다

단점

불필요한 요청이 과도하게 발생한다
주기 사이에 늦게 전달되는 "최소 지연" 문제가 있다
네트워크, 배터리 리소스 낭비가 크다

즉, "쉽지만 비효율적인 방식"이라는 한계가 명확하다.

2) Long Polling

Short Polling의 비효율을 개선한 방식이다.

클라이언트가 요청을 보낸 뒤 서버가 새로운 데이터가 생길 때까지 응답을 지연한다.

"변경되면 알려줘"라고 말하고 기다리는 방식

장점

Short Polling 대비 지연 시간이 크게 감소한다
서버가 이벤트가 생겼을 때만 응답하므로 효율성이 증가한다.

단점

요청-응답 사이클을 여전히 반복된다
서버사 연결을 오래 유지해야 하므로 커넥션 부담이 증가한다

실시간에 준하는 성능을 얻을 수 있지만 구조적 한계는 여전히 존재한다.

3) WebSocket

클라이언트와 서버 간의 상시 양방향 통신 채널을 유지하는 방식이다.

하나의 커넥션이 열리면 양쪽 모두 자유롭게 메시지를 주고받을 수 있다.

장점

세 가지 방식 중 지연이 가장 짧다
실제 실시간 서비스 경험에 가장 적합하다
양방향 통신이 자연스럽게 이뤄진다

단점

구현 난이도가 높다 (프로토콜, 핑-퐁 관리, 재연결 등)
서버 및 인프라 부담 증가
모바일 환경에서는 백그라운드 제약, 네트워크 전환 등 모바일 특성을 고려가 필요하다

가장 실시간답지만 개발, 운영 비용이 크고 모바일에서는 신중한 선택이 필요하다.

4) Server-Sent Events

SSE(Server-Sent Events)는 HTTP 기반의 단방향 실시간 스트리밍 기술로 WebSocket 처럼 별도의 복잡한 프로토콜을 사용하지 않아도 서버에서 클라이언트로 이벤트를 지속적으로 전송할 수 있는 방식이다.

특히, "서버 -> 클라이언트"의 단방향 흐름만 필요할 때 매우 효율적이며 구조가 단순해 적용 난이도가 낮다.

장점

HTTP 기반
Polling 방식 대비 효율적
WebSocket 대비 단순

Server-Sent Events를 선택한 이유

서비스 요구사항을 다시 살펴보자.

사용자 A가 물건을 추가하면
서버가 변경 사항을 저장하고
사용자 B, C, D의 화면에 즉시 반영되어야 한다

"양방향 통신은 필요하지 않다"

"폴링 방식의 불필요한 요청·리소스 낭비를 최소화하고 싶다"

서버 -> 클라이언트 단방향으로 변경된 데이터를 스트리밍 해주기만 하면 된다.

이를 위해 `Server-Sent Events`를 선택하게 되었다.

안드로이드에서 SSE (Server-Sent Events) 처리 흐름

우선 구현에 앞서 어떤 흐름으로 SSE가 처리되는지를 살펴보자.

최초 HTTP 요청으로 서버와 스트림이 연결되었다면 OkHttp에서는 `source.exhausted()`라는 메서드로 스트림 종료 여부를 판단하게 된다. 이 값을 통해 스트림이 유지되는 동안 새로운 텍스트 라인이 들어왔을 때 이를 SSE 규약에 맞게 파싱하여 원하는 처리를 할 수 있도록 구현하면 된다. SSE는 id, event, data 등의 규약이 존재하며 빈 줄(두 개의 개행)로 이벤트를 구분하게 된다.

우선 OkHttp를 사용해 SSE에 대한 모든 처리를 구현하는 방식과 OkHttp-SSE를 사용하여 어느 정도 SSE에 대한 처리가 되어있는 라이브러리를 사용하는 방식을 택할 수 있다. 여기서는 서버 측과 논의 하에 SSE 규약의 Prefix 등을 변경할 필요가 있다면 직접 구현하고 아니라면 OkHttp-SSE를 사용해도 무방하다고 생각한다.

단, OkHttp-SSE는 아직 실험적 단계이기 때문에 스펙 변경에 유의할 필요가 있다.

해당 글에서는 OkHttp-SSE를 사용하는 방식을 사용한다.

안드로이드에서 SSE (Server-Sent Events) 구현

OkHttp-SSE는 SSE(Server-Sent Events) 통신에서 가장 번거로운 부분인 스트림 연결 유지, 라인 파싱, 이벤트 조립 등을 내부적으로 처리해 준다. 이를 위해 라이브러리 내부에는 몇 가지 핵심 타입들이 역할을 분담하고 있으며, 그 구조를 이해하면 SSE 구현 방식이 훨씬 명확해질 것이다.

아래 3개의 코드가 바로 oKhttp-sse의 핵심 엔트리 포인트이다.

object EventSources {
  @JvmStatic
  fun createFactory(client: OkHttpClient): EventSource.Factory {
    return EventSource.Factory { request, listener ->
      val actualRequest =
        if (request.header("Accept") == null) {
          request.newBuilder().addHeader("Accept", "text/event-stream").build()
        } else {
          request
        }

      RealEventSource(actualRequest, listener).apply {
        connect(client)
      }
    }
  }

  @JvmStatic
  fun processResponse(response: Response, listener: EventSourceListener) {
    val eventSource = RealEventSource(response.request, listener)
    eventSource.processResponse(response)
  }
}

interface EventSource {
  fun request(): Request

  fun cancel()

  fun interface Factory {
    fun newEventSource(request: Request, listener: EventSourceListener): EventSource
  }
}

abstract class EventSourceListener {
  open fun onOpen(eventSource: EventSource, response: Response) {}

  open fun onEvent(eventSource: EventSource, id: String?, type: String?, data: String) {}

  open fun onClosed(eventSource: EventSource) {}

  open fun onFailure(eventSource: EventSource, t: Throwable?, response: Response?) {}
}

우선 `EventSources.createFactory()`를 호출하여 `EventSource.Factory` 객체를 생성한다.

이 팩토리는 SSE 규약에 맞는 `Accept: text/event-stream` 헤더를 자동으로 추가한 뒤, `RealEventSource(request, listener)`를 만들어 OkHttp의 `Call.enqueue(callback)`을 사용해 비동기 요청을 수행하도록 구성된다.

이때 callback 내부에서는 SSE 스트림을 라인 단위로 파싱하고 완성된 이벤트를 `ServerSentEventListener`로 전달하도록 처리된다.

단, `createFactory()` 호출 시점에서는 아직 SSE 연결이 시작되지 않는다.

실제 스트림 연결은 `EventSource.Factory.newEventSource(request, listener)`를 호출할 때야 비로소 수행된다.

이렇게 ServerSentEventListener로 전달된 이벤트들은 그 이벤트(open, close, failure, event)에 맞는 처리를 한 후 Flow를 통해 UI까지 전달되도록 하면 실시간성을 확보할 수 있다.

이 글의 내용은 우아한테크코스에서 진행한 테코톡 세션에서도 발표한 바 있다.

혹시 글만으로 이해가 어렵다면 발표 자료나 영상을 함께 참고해 보면 전체 흐름을 더 쉽게 파악할 수 있을 것이다.

[10분 테코톡] 다이스의 Server-Sent Events for Android

보따리 레포지토리

[Android] AppLink 인앱 브라우저 호환 문제 처리

Moondev — Wed, 29 Oct 2025 22:45:18 +0900

들어가며

앱을 개발하다 보면 "URL을 눌렀을 때 앱이 바로 열리게 하고 싶다"는 요구를 자주 듣습니다.

이를 가능하게 하는 기술이 바로 `DeepLink`입니다.

최근 진행하고 있는 `보따리`라는 프로젝트에서도 초대 링크를 눌렀을 때 앱이 열리도록 `AppLink`를 적용했지만

카카오톡이나 인스타그램 등 인앱 브라우저에서는 정상적으로 동작하지 않는 문제가 있었습니다.

이 글에서는 DeepLink의 개념부터 AppLink가 등장한 이유,

그리고 보따리 앱에서 이 문제를 어떻게 해결했는지를 차례로 정리합니다.

DeepLink란?

`DeepLink`는 말 그대로 "사용자를 특정 앱으로 이동시켜서 원하는 화면을 보여주거나, 사용자 액션을 유도하는 링크"입니다.

웹의 URL처럼 보이지만 브라우저 대신 앱을 직접 실행시켜 특정 화면으로 진입하게 만듭니다.

예를 들어 아래 링크를 클릭하면 앱의 상세 화면이 열리도록 구성할 수 있습니다.

myapp://detail/123

이 링크는 앱 외부(ex. 브라우저, 메시지, 이메일 등)에서 클릭해도 해당 앱이 설치되어 있다면 바로 열리고

설치되어 있지 않다면 브라우저가 대신 처리하게 됩니다.

DeepLink의 세 가지 형태

시간이 지나면서 DeepLink는 보안성과 사용자 경험을 보완하기 위해 발전했습니다.

현재 Android에서 사용할 수 있는 DeepLink는 크게 세 가지 형태로 나뉩니다.

Custom Scheme DeepLink

출처: https://docs.tosspayments.com/blog/android-ios-webview-deeplink

Scheme을 통해 실행시킬 앱을 특정하고 Path를 통해 들어가고 싶은 페이지를 특정합니다.

이 Custom Scheme 방식의 DeepLink가 가진 문제점은 서로 다른 앱에서 같은 Scheme을 가질 수 있다는 점입니다.

다행히 Android에서는 동일한 Scheme을 가진 앱이 여러 개 존재한다면 어떤 앱을 실행할 지에 대한 UI가 노출됩니다.

AppLink

https://myapp.com/detail/123

Custom Scheme 방식과 달리 표준 웹링크 형태를 가졌습니다.

AppLink는 PlayConsole를 통해 발급받은 `assetlinks.json` 파일을 통해 도메인을 인증하는 식으로 링크에 대한 검증을 수행합니다.

Intent Scheme DeepLink

intent://bottari.app/team
   #Intent;
      package=com.bottari.bottari; -> 앱의 패키지명
      scheme=https;
      S.browser_fallback_url=${encodeURIComponent(PLAY_STORE_LINK)}; -> 앱이 설치되어 있지 않을 때 이동할 URL
   end;

Intent URI 형식을 사용해 앱을 직접 실행하는 방식입니다.

AppLink처럼 OS 수준의 검증은 없지만 In-App 브라우저 환경에서도 작동한다는 점이 가장 큰 장점입니다.

해당 링크를 클릭하면 Android System이 다음 단계를 수행합니다.

1. `scheme=bottari`를 가진 앱이 설치되어 있다면 -> 앱을 실행

2. 앱이 설치되어 있지 않다면 -> Play Store를 열도록 처리

보따리 앱에서의 AppLink 문제

`보따리` 앱에서는 `AppLink`를 통해 팀 초대 링크를 클릭하면 앱을 바로 열고 팀에 참가하는 기능을 구현했습니다.

예를 들어 사용자가 친구에게 다음과 같은 링크를 보냈다고 가정해 보겠습니다.

https://bottari.app/team?code=ABCDEFGH

`AndroidManifest.xml`에서는 다음과 같은 `AppLink` 설정을 해두었습니다.

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    
    <data
        android:scheme="https"
        android:host="bottari.app"
        android:pathPrefix="/team" />
</intent-filter>

✅ Chrome과 Slack에서는 정상 작동했습니다.

`https://bottari.app/team?code=ABCDEFGH`를 클릭하면 앱 설치 여부에 따라 앱 혹은 스토어로 이동했습니다.

❌ 하지만 카카오톡, 인스타그램 등 내장 브라우저에서는 앱이 실행되지 않았습니다.

왜 내장 브라우저에서는 AppLink가 동작하지 않을까?

문제의 핵심은 AppLink는 OS 수준에서 앱과 도메인 소유권을 검증한 뒤 브라우저가 이를 대신 실행해 주는 구조이기 때문입니다.

- Chrome, Samsung Internet 등 OS 브라우저에서는 앱 링크를 인식하고 Intent를 전달합니다.

- 하지만 카카오톡, 인스타그램 등의 In-App 브라우저는 독립된 WebView 기반으로 동작하기 때문에 OS 레벨의 앱 소유 검증을 수행하지 않습니다.

"OS가 아닌 앱 내부 브라우저에서는 AppLink를 신뢰하지 않기 때문에 앱을 직접 실행하지 않는다."

"결과적으로 사용자는 앱이 설치되어 있어도 웹 페이지만 열리는 현상이 발생한다."

In-App 브라우저 환경에서는 앱링크의 동작이 제한적이고 불확실하다.

해결 전략

`보따리`에서는 이를 해결하기 위해 중간 랜딩 페이지를 추가했습니다.

기존 구조는 `[카카오톡에서 링크 클릭] -> [브라우저 열림]`

개선된 구조는 `[카카오톡에서 링크 클릭] -> [랜딩 페이지 (Web)] -> [앱 설치 여부 확인] -> 앱 실행 or PlayStore로 이동`

구현 방식

`https://bottari.app/team` 경로로 요청이 오는 경우 사용자에게 아래 코드들이 포함된 Html 파일을 응답하도록 했습니다.

다음 함수로 안드로이드 기기인지를 판단하였습니다.

function isAndroid() {
    return /Android/i.test(navigator.userAgent || '');
}

`intentUrl`은 위에서 언급한 DeepLink의 세 가지 유형 중 `Intent Scheme DeepLink`에 해당합니다.

const intentUrl = `${intentBaseUrl}#Intent;scheme=https;package=${CONFIG.APP_PACKAGE_NAME};S.browser_fallback_url=${encodeURIComponent(PLAY_STORE_LINK)};end`;

`intentUrl`으로 앱 실행을 시도했을 때 앱이 실행되지 않는다면 설치되지 않았다고 판단하고 플레이스토어를 열도록 하였습니다.

function openApp(id) {
    const { httpsUrl, intentUrl } = buildLinks(id || '');

    if (isAndroid()) {
        // Android: Intent로 앱 실행 시도 → 미설치 시 Play 스토어
        const fallback = setTimeout(() => {
            window.location.href = PLAY_STORE_LINK;
        }, CONFIG.FALLBACK_DELAY);

        // 사용자가 앱으로 전환하면 폴백 취소
        document.addEventListener('visibilitychange', () => {
            if (document.hidden) {
                clearTimeout(fallback);
            }
        });

        window.location.href = intentUrl;
    } else {
        // 다른 환경: HTTPS URL로 이동
        window.location.href = httpsUrl;
    }
}

마무리하며

AppLink는 분명 강력한 기능이지만 모든 환경에서 동일하게 동작하지 않는다는 점을 직접 경험하며 크게 배웠습니다.

보따리 앱의 초대 기능은 대부분 카카오톡을 통해 공유되는데,

AppLink가 인앱 브라우저에서 동작하지 않아서 사용자들은 초대 코드를 직접 복사해 입력해야 하는 불편함을 겪었습니다.

이 문제를 해결하기 위해 중간 랜딩 페이지를 추가하면서,

사용자가 어떤 환경에서 링크를 열든 앱으로 자연스럽게 이동할 수 있도록 개선했습니다.

단순한 기술적 조치였지만 결과적으로는 초대 기능의 접근성과 완성도를 한 단계 끌어올릴 수 있었습니다.

참고 자료

Android, iOS 웹뷰에서 딥링크 열기 | 토스페이먼츠 개발자센터

각 딥링크 유형의 특징과 차이점을 자세히 알아보고, Android와 iOS 웹뷰에서 딥링크로 국내 카드앱·은행앱으로 이동하는 예시를 살펴볼게요.

docs.tosspayments.com

앱 링크 정보 | App architecture | Android Developers

이 페이지는 Cloud Translation API를 통해 번역되었습니다. 앱 링크 정보 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요. Android 앱 링크는 Android 6 이상에서 제공되

developer.android.com

GitHub - woowacourse-teams/2025-bottari: 당신의 여행, 행사, 일상 속 든든한 짐 친구 `보따리`

당신의 여행, 행사, 일상 속 든든한 짐 친구 `보따리`. Contribute to woowacourse-teams/2025-bottari development by creating an account on GitHub.

github.com

Build Logic으로 멀티모듈 공통 빌드 설정 효율적으로 관리하기

Moondev — Tue, 14 Oct 2025 17:26:11 +0900

프로젝트의 기능이 확장되면서 모듈 구조의 복잡도가 급격히 높아졌다.

초기에는 단일 모듈(:app)로 시작했지만 기능별 책임을 분리하기 위해 멀티모듈 구조로 리팩터링을 진행했다.

그러나 시간이 지날수록 공통 빌드 설정이 여러 모듈에 중복되면서 관리 포이트가 늘어나는 문제가 발생했다.

멀티 모듈 프로젝트 구조

Stacko/
 ├── app/                        # Entry point (Application)
 ├── feature/
 │   ├── home/                   # 홈 화면
 │   ├── search/                 # 검색 기능
 │   ├── detail/                 # 상세 화면
 │   └── settings/               # 설정 화면
 ├── core/
 │   ├── designsystem/           # Compose 기반 디자인 시스템
 │   ├── data/                   # Repository 및 DataSource 계층
 │   ├── domain/                 # UseCase 계층
 │   ├── network/                # Retrofit 기반 네트워크 모듈
 │   ├── database/               # Room 기반 로컬 DB
 │   └── testing/                # 테스트 유틸리티 및 Fixture
 ├── build-logic/                # 공통 빌드 로직 관리 (BuildLogic)
 ├── build.gradle.kts
 ├── settings.gradle.kts
 └── gradle/
     └── libs.versions.toml      # 버전 카탈로그

각 모듈은 역할에 따라 잘 분리되어 있었지만 `build.gradle.kts`의 코드 중복이 심했다.

모든 모듈이 동일한 설정을 반복 선언하고 있었고 새로운 모듈을 추가할 때마다 기존 설정을 복사해 붙여 넣는 비효율적인 과정이 필요했다.

build.gradle.kts (:feature:home)

plugins {
    alias(libs.plugins.android.library)
    alias(libs.plugins.jetbrains.kotlin.android)
    ...
}

android {
    namespace = "com.devbuds.feature.home"
    compileSdk = libs.versions.projectCompileSdkVersion.get().toInt()

    defaultConfig {
        minSdk = libs.versions.projectMinSdkVersion.get().toInt()
        ...
    }
    ...
}

dependencies {
    ...
}

build.gradle.kts (:feature:detail)

plugins {
    alias(libs.plugins.android.library)
    alias(libs.plugins.jetbrains.kotlin.android)
    ...
}

android {
    namespace = "com.devbuds.feature.detail"
    compileSdk = libs.versions.projectCompileSdkVersion.get().toInt()

    defaultConfig {
        minSdk = libs.versions.projectMinSdkVersion.get().toInt()
        ...
    }
    ...
}

dependencies {
    ...
}

이 글에서는 이런 반복되는 Gradle 설정, 버전 불일치, 새로운 모듈 추가의 부담을 해결하기 위해 도입된 `build-logic 모듈`의 설계와 적용 과정을 다룬다.

문제 원인 분석

프로젝트가 모듈화되면서 코드 레벨에서는 책임이 명확해지고 유지보수가 쉬워졌다.

하지만 빌드 설정 수준에서는 각 모듈이 `build.gradle.kts`가 독립적으로 존재하게 되면서 오히려 복잡도가 증가했다.

예를 들어 대부분의 모듈이 다음과 같은 공통 항목을 반복 선언하고 있었다.

- Android SDK 버전 (compileSdk, minSdk, targetSdk, ...)

- Compose 관련 설정

- 코드 스타일 및 정적 분석 도구 설정

- 테스트 관련 의존성

- ...

이런 중복은 단순히 보기 불편한 수준을 넘어서 실제 문제를 유발했다.

- 동일한 의존성을 여러 곳에서 관리하면서 버전 불일치와 충돌 위험 증가

- 새로운 모듈로 추가할 때마다 기존 설정을 복사, 붙여 넣는 비효율적인 작업 반복

- ...

결국 문제의 본질은 모듈 구조는 정리됐지만 빌드 로직은 여전히 분산되어 있다는 점이다.

해결 과정

1️⃣ `build-logic` 모듈 생성

먼저, 프로젝트 루트에 `build-logic` 모듈을 생성한다.

이 모듈은 다은 모듈과 달리 애플리케이션 코드가 아닌 Gradle 설정을 관리하는 전용 모듈이다.

여기서는 Convention Plugin을 정의하여 공통 빌드 설정을 한 곳에서 관리한다.

settings.gradle.kts(프로젝트 루트)

enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")

pluginManagement {
    includeBuild("build-logic")
    ...
}

Gradle이 일반 Kotlin Module과 Build Module을 구별할 수 있도록 `includeBuild("build-logic")`을 작성해야 한다.

2️⃣ `build-logic` 모듈 설정

build.gradle.kts(Included build: :build-logic)

plugins {
    `kotlin-dsl`
}

group = "com.devbuds.buildlogic"

dependencies {
    compileOnly(libs.android.gradlePlugin)
    compileOnly(libs.android.tools.common)
    compileOnly(libs.kotlin.gradlePlugin)
    ...
}

Convention Plugin으로 정의할 관련 의존성을 추가한다.

`build-logic`에서 생성되는 플러그인은 컴파일 중에만 사용되기 때문에 `implementation` 대신 `compileOnly`를 사용했다.

3️⃣ Version Catalog 참조

`build-logic` 내부에서도 `libs.version.toml`을 그대로 참조하도록 설정했다.

이를 통해 모든 모듈이 동일한 버전 카탈로그(libs)를 사용할 수 있다.

settings.gradle(:build-logic)

versionCatalogs {
    create("libs") {
        from(files("../gradle/libs.versions.toml"))
    }
}

Extensions.kt

internal val Project.libs: VersionCatalog
    get() = extensions.getByType<VersionCatalogsExtension>().named("libs")

4️⃣ Convention Plugin 구조 설계

새로운 모듈을 추가할 때, build.gradle.kts 파일에 플러그인 한 줄만 추가하면 끝나도록 하자.

각 모듈이 어떤 성격을 가지는지에 따라 공통 설정을 자동으로 해주는 Convention Plugin을 설계했다.

예를 들어, Applicaiton, Feature, Testing 등으로 나누면 다음과 같은 구조가 된다.

build-logic/
 ├── build.gradle.kts
 ├── settings.gradle.kts
 └── src/main/kotlin/
     ├── AndroidApplicationConventionPlugin.kt // Entry point (Application ID, Signing, Compose 등)
     ├── AndroidFeatureConventionPlugin.kt // 공통 Android UI 설정 (Compose, ViewModel, Navigation 등)
     ├── AndroidTestConventionPlugin.kt // 테스트 환경 설정 (JUnit, Kotest, Mockk 등)
     └── Extensions.kt

각 플러그인은 Gradle의 Plugin Interface를 구현하며,

플러그인 적용 시 자동으로 필요한 설정(ex. android, plugins, dependencies)을 주입한다.

5️⃣ Convention Plugin 구현 (Application)

internal fun Project.configureKotlin() {
    extensions.configure<JavaPluginExtension> {
        sourceCompatibility = ApplicationConfig.JavaVersion
        targetCompatibility = ApplicationConfig.JavaVersion
    }

    extensions.configure<KotlinProjectExtension> {
        jvmToolchain(ApplicationConfig.JavaVersionAsInt)
    }
}

internal fun Project.configureAndroid(commonExtension: CommonExtension<*, *, *, *, *, *>) {
    commonExtension.apply {
        compileSdk = libs.findVersion("projectCompileSdkVersion").get().toString().toInt()

        defaultConfig.minSdk = libs.findVersion("projectMinSdkVersion").get().toString().toInt()

        configureKotlin()
    }
}

class AndroidApplicationConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        target.run {
            pluginManager.run {
                apply(plugin = "com.android.application")
                apply(plugin = "org.jetbrains.kotlin.android")
            }

            extensions.configure<ApplicationExtension> {
                defaultConfig {
                    applicationId = libs.findVersion("projectApplicationId").get().toString()
                    targetSdk =libs.findVersion("projectTargetSdkVersion").get().toString().toInt()
                    versionCode = libs.findVersion("projectVersionCode").get().toString().toInt()
                    versionName = libs.findVersion("projectVersionName").get().toString()
                }

                configureAndroid(this)

                // BuildTypes, BuildFeatures ...
            }
        }
    }
}

6️⃣ Convention Plugin 적용 (Application)

정의한 Convention Plugin을 다른 모듈에서 사용하기 위해서는 `build-logic` 내부의 `resources/main/META_INF/gradle-plugins/` 경로에 각 플러그인 ID와 연결될 properties 파일이 존재해야 한다.

해당 파일은 아래 설정으로 생성할 수 있다.

build.gradle.kts (:build-logic)

gradlePlugin {
    plugins {
        register("android-application") {
            id = libs.plugins.devbuds.android.application.asProvider().get().pluginId
            implementationClass = "com.devbuds.buildlogic.plugin.AndroidApplicationConventionPlugin"
        }

        ...
    }
}

build.gradle.kts (:app)

plugins {
    id("com.devbuds.android.application")
}

마무리

빌드 로직을 도입하면서 멀티 모듈 환경의 복잡한 Gradle 설정을 단 한 줄로 단순화할 수 있었다.

이제 공통 설정은 중앙에서 일관되게 관리되고 각 모듈은 오직 자신의 역할에만 집중하면 되는 구조가 되었다.

중복된 빌드 스크립트를 제거함으로써 유지보수성이 높아지고 새로운 요구사항에 대응하기 위한 확장성도 확보되었다.

무엇보다 가장 큰 변화는 새로운 모듈을 생성하는 과정이 훨씬 단순해졌다는 점이다.

복잡한 설정 대신 명확한 규칙만 따르면 누구나 일관된 환경에서 개발을 시작할 수 있다.

이는 단순한 설정 정리가 아니라 프로젝트 구조 전반의 개발 경험을 개선한 변화라고 생각한다.

[Comopse] Android Compose Theme 살펴보기

Moondev — Wed, 1 Oct 2025 01:43:00 +0900

왜 Theme가 필요한가?

안드로이드 개발에서 UI는 앱의 첫인상을 결정합니다.

하지만 화면이 많아질수록 색상, 글꼴, 모서리 둥글기 같은 스타일을 각 화면마다 직접 지정하는 방식은 유지보수가 매우 어렵습니다.

이를 해결하기 위해 Compose는 Theme 개념을 도입하여 앱 전반에 일관된 디자인을 주입합니다.

일관성: 버튼, 텍스트, 카드 등 공통 UI 컴포넌트가 동일한 스타일로 표현
재사용성: 여러 화면에서 동일한 색상/글꼴/모양을 공유
유지보수성: 브랜드 리뉴얼, 다크 모드 대응 시 코드 수정 범위 최소화

특히 Compose는 Material Design 3(M3)를 기본 권장하며, MaterialTheme를 통해 색상, 글꼴, 모양을 한 번에 관리할 수 있습니다.

MaterialTheme 살펴보기

MaterialTheme는 세 가지 주요 토큰으로 구성됩니다.

ColorScheme: 앱의 주요 색상(primary, secondary, surface, background 등)
Typography: 글꼴 스타일 (body, title, display 등)
Shapes: 컴포넌트 모서리 곡률 (RoundedCorner 등)

Compose는 이 값들을 CompositionLocal을 통해 트리 전체에 전달합니다.

따라서 하위 컴포넌트는 어디서든 MaterialTheme.colorScheme.primary처럼 호출할 수 있습니다.

세부 속성은 Material 3 공식 문서에서 확인 가능합니다.

기본 Theme 구조

새로운 Compose 프로젝트를 생성하면 `<프로젝트명>Theme`라는 기본 테마 래퍼가 자동으로 만들어집니다.

기본적으로 아래와 같이 앱 전체 UI에 적용할 색상, 타이포그래피 등을 묶어서 제공하는 "테마 래퍼"가 생성됩니다.

@Composable
fun BottariTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    // Dynamic color is available on Android 12+
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            val context = LocalContext.current
            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
        }

        darkTheme -> DarkColorScheme
        else -> LightColorScheme
    }

    MaterialTheme(
        colorScheme = colorScheme,
        typography = Typography,
        content = content
    )
}

@Composable
fun BottariTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
)

darkTheme: 다크 모드 적용 여부 (기본값은 isSystemInDarkTheme())
dynamicColor: Android 12 이상에서 제공하는 Dynamic Color 적용 여부
content: 실제 UI를 그리는 Composable

즉, 이 래퍼는 앱의 색상 팔레트 결정 → MaterialTheme 적용 → 하위 UI에 주입의 역할을 담당합니다.

MaterialTheme 내부 동작

MaterialTheme는 내부적으로 CompositionLocalProvider를 이용해 Local 값들을 설정합니다.

object MaterialTheme {
    val colorScheme: ColorScheme
        @Composable 
        @ReadOnlyComposable 
        get() = LocalColorScheme.current

    val typography: Typography
        @Composable 
        @ReadOnlyComposable 
        get() = LocalTypography.current

    val shapes: Shapes
        @Composable 
        @ReadOnlyComposable 
        get() = LocalShapes.current
}

@Composable
fun MaterialTheme(
    colorScheme: ColorScheme = MaterialTheme.colorScheme,
    shapes: Shapes = MaterialTheme.shapes,
    typography: Typography = MaterialTheme.typography,
    content: @Composable () -> Unit
) {
    val rippleIndication = rippleOrFallbackImplementation()
    val selectionColors = rememberTextSelectionColors(colorScheme)

    CompositionLocalProvider(
        LocalColorScheme provides colorScheme,
        LocalIndication provides rippleIndication,
        LocalRippleTheme provides CompatRippleTheme,
        LocalShapes provides shapes,
        LocalTextSelectionColors provides selectionColors,
        LocalTypography provides typography,
    ) {
        ProvideTextStyle(value = typography.bodyLarge, content = content)
    }
}

MaterialTheme.colorScheme.primary를 호출하면 내부적으로 LocalColorScheme.current.primary를 가져오는 구조입니다.

결과적으로 모든 하위 UI는 자동으로 Theme 값을 상속받게 되며 이를 통해 전체 앱의 디자인 일관성을 보장할 수 있습니다.

Bottari 서비스의 Custom Theme 적용

이번에 진행하고 있는 "보따리" 앱에서는 MaterialTheme를 기반으로 자체 Color, Typography, Extra Tokens를 추가해 사용합니다.

ColorScheme

private val BottariLightColors = lightColorScheme(
    primary = Color(0xFF0064FF),
    secondary = Color(0xFF6EBA76),
    tertiary = Color(0xFF00AEFF),

    background = Color(0xFFFFFFFF),
    surface = Color(0xFFF8F8F8),
    onPrimary = Color.White,
    onSecondary = Color.Black,
    onTertiary = Color.White,
    onBackground = Color.Black,
    onSurface = Color.Black,

    error = Color(0xFFFF3B30),
    onError = Color.White
)

다크 모드 지원 계획이 없기 때문에 LightColors만 정의해 줍니다.

여기서 간단히 각 색상이 무엇은 의미하는지 살펴보겠습니다.

primary: 앱 대표 파랑 (#0064FF) → 주요 버튼, 강조 색상
secondary: 개인 외의 상태(예: 공유 보따리, 협업 기능) → 초록 계열
tertiary: 특정 구분(예: 할당된 보따리) → 하늘색 계열
error: 에러 메시지, 삭제 버튼 → soft red (#FF3B30)
background / surface: 기본 흰색과 회색 계열 → 앱 바탕/카드 배경

-> 자세한 설명은 M3 Color Rules에서 확인할 수 있습니다.

추가적으로, 세부 상태 값은 BottariExtraColors라는 별도 CompositionLocal로 관리합니다.

@Immutable
data class BottariExtraColors(
    val gray50: Color = Color(0xFFF8F8F8),
    val gray100: Color = Color(0xFFF2F2F5),
    val gray200: Color = Color(0xFFEEEEEE),
    val gray300: Color = Color(0xFFD1DEE8),
    val gray400: Color = Color(0xFFC4C4C4),
    val gray500: Color = Color(0xFFA6A6A6),
    val gray600: Color = Color(0xFF999999),
    val gray700: Color = Color(0xFF787878),

    val productTypePersonal: Color = Color(0xFF0064FF),
    val productTypeShared: Color = Color(0xFF6EBA76),
    val productTypeAssigned: Color = Color(0xFF00AEFF),
)

Typography

val Pretendard =
    FontFamily(
        Font(R.font.pretendard_regular, FontWeight.W400),
        Font(R.font.pretendard_medium, FontWeight.W500),
        Font(R.font.pretendard_semibold, FontWeight.W600),
        Font(R.font.pretendard_bold, FontWeight.W700),
    )

보따리 앱에서는 Pretendard 폰트를 모든 스타일의 기본 폰트로 사용합니다.

FontWeight에 따라 Regular, Medium, SemiBold, Bold 리소스를 지정했습니다.

@Immutable
data class BottariTextStyle(
    val fontFamily: FontFamily = Pretendard,
    val fontWeight: FontWeight = FontWeight.Medium,
    val fontSize: Dp = Dp.Unspecified,
    val lineHeight: Dp = Dp.Unspecified,
    val letterSpacing: TextUnit = 0.em,
    val color: Color = Color.Unspecified,
    val textAlign: TextAlign = TextAlign.Start,
)

시스템 글자 크기 변경에 영향을 받지 않고 항상 동일한 크기로 보이고 싶었기에 Material3의 Typography를 그대로 쓰는 대신, 보따리 앱에 맞는 Typography를 새로 만들었습니다. (권장은 sp 사용)

MaterialTheme.typography 대신, Dp 기반으로 커스텀 폰트 크기/줄 높이를 지정할 수 있는 구조
toTextStyle() 메서드를 통해 TextStyle로 변환할 때 LocalDensity를 이용해 Dp → Sp 변환

Material3의 Typography는 15개의 스타일로 구성되어 있습니다.

각 스타일은 역할 기반 네이밍(Display, Headline, Title, Body, Label) + 크기 구분(Large/Medium/Small)으로 정의됩니다.

val BottariTypography = Typography(
    displayLarge = TextStyle(
        fontFamily = Pretendard,
        fontWeight = FontWeight.W700,
        fontSize = 32.sp,
        lineHeight = 40.sp
    ),
    displayMedium = TextStyle(
        fontFamily = Pretendard,
        fontWeight = FontWeight.W700,
        fontSize = 28.sp,
        lineHeight = 36.sp
    ),
    displaySmall = TextStyle(
        fontFamily = Pretendard,
        fontWeight = FontWeight.W700,
        fontSize = 24.sp,
        lineHeight = 32.sp
    ),
    ...
)

Spacing

@Immutable
data class BottariSpacing(
    val extraSmall: Dp = 8.dp,     
    val small: Dp = 12.dp,     
    val medium: Dp = 16.dp,      
    val large: Dp = 20.dp,     
    val extraLarge: Dp = 24.dp, 
)

일관된 간격을 위해 별도로 정의하여 사용하도록 했습니다.

BottariTheme

마지막으로 위에서 정의한 내용들을 바탕으로 테마 래핑을 변경하면 됩니다.

val LocalBottariExtraColors = staticCompositionLocalOf { BottariExtraColors() }
val LocalBottariSpacing = staticCompostionLocalOf { BottariSpacing() }

@Composable
fun BottariTheme(
    content: @Composable () -> Unit
) {
    CompositionLocalProvider(
        LocalBottariExtraColors provides BottariExtarColors()
        LocalBottariSpacing provides BottariSpacing()
    ) {
        MaterialTheme(
            colorScheme = BottariLightColors,
            typography = BottariTypography,
            content = content
        )
    }
}

적용 예시

@Composable
fun BottariCard() {
    Card(
        shape = MaterialTheme.shapes.medium,
        colors = CardDefaults.cardColors(
            containerColor = LocalBottariExtraColors.current.gray100
        ),
        modifier = Modifier.padding(
            horizontal = LocalBottariSpacing.current.medium,
            vertical = LocalBottariSpacing.current.small,
        ),
    ) {
        Text(
            text = "내 보따리",
            style = LocalBottariTypographySystem.current.bold20.toTextStyle(),
            color = MaterialTheme.colorScheme.primary
        )
    }
}

이런 식으로 MaterialTheme + LocalBottari*를 함께 조합하여 UI 컴포넌트를 구성할 수 있습니다.

사례: Now in Android

구글의 Now in Android 프로젝트는 GradientColors, BackgroundTheme 같은 추가 토큰을 Theme에 통합해 복잡한 UI에서도 일관성을 유지합니다.

@Composable
fun NiaTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    androidTheme: Boolean = false,
    disableDynamicTheming: Boolean = true,
    content: @Composable () -> Unit,
) {
    // Color scheme
    val colorScheme = when {
        androidTheme -> if (darkTheme) DarkAndroidColorScheme else LightAndroidColorScheme
        !disableDynamicTheming && supportsDynamicTheming() -> {
            val context = LocalContext.current
            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
        }

        else -> if (darkTheme) DarkDefaultColorScheme else LightDefaultColorScheme
    }
    // Gradient colors
    val emptyGradientColors = GradientColors(container = colorScheme.surfaceColorAtElevation(2.dp))
    val defaultGradientColors = GradientColors(
        top = colorScheme.inverseOnSurface,
        bottom = colorScheme.primaryContainer,
        container = colorScheme.surface,
    )
    val gradientColors = when {
        androidTheme -> if (darkTheme) DarkAndroidGradientColors else LightAndroidGradientColors
        !disableDynamicTheming && supportsDynamicTheming() -> emptyGradientColors
        else -> defaultGradientColors
    }
    // Background theme
    val defaultBackgroundTheme = BackgroundTheme(
        color = colorScheme.surface,
        tonalElevation = 2.dp,
    )
    val backgroundTheme = when {
        androidTheme -> if (darkTheme) DarkAndroidBackgroundTheme else LightAndroidBackgroundTheme
        else -> defaultBackgroundTheme
    }
    val tintTheme = when {
        androidTheme -> TintTheme()
        !disableDynamicTheming && supportsDynamicTheming() -> TintTheme(colorScheme.primary)
        else -> TintTheme()
    }
    // Composition locals
    CompositionLocalProvider(
        LocalGradientColors provides gradientColors,
        LocalBackgroundTheme provides backgroundTheme,
        LocalTintTheme provides tintTheme,
    ) {
        MaterialTheme(
            colorScheme = colorScheme,
            typography = NiaTypography,
            content = content,
        )
    }
}

정리

화면이 많아질수록 개별 스타일을 직접 지정하는 방식에는 분명 한계가 있고, 테마를 통해 공통 규칙을 주입해야만 확장 가능한 구조를 만들 수 있습니다.

결국 Theme의 존재 이유는 앱의 첫인상을 지배하는 UI를 “관리 가능한 코드”로 만드는 것입니다.

이는 단순한 디자인 요소의 모음이 아니라, 앱 전체 UI의 일관성과 유지보수성을 책임지는 핵심 장치라고 할 수 있습니다.

더 배우고 싶다면 Compose Theming CodeLab을 추천합니다.

[Git] Github Labels 한 번에 적용하는 방법

Moondev — Wed, 27 Nov 2024 23:53:35 +0900

Github Repo를 생성할 때마다 수동으로 추가하던 Label을 한 번에 적용하는 방법을 알게 되어 소개하려고 합니다.

준비물

git-labels.json

"name": "라벨 이름",
"color": "라벨 색상",
"description": "라벨 설명"

[
  {
    "name": "⚙ Setting",
    "color": "e3dede",
    "description": "개발 환경 세팅"
  },
  {
    "name": "✨ Feature",
    "color": "a2eeef",
    "description": "기능 개발"
  },
  {
    "name": "  Deploy",
    "color": "C2E0C6",
    "description": "배포 관련"
  },
  {
    "name": "  UI Design",
    "color": "FEF2C0",
    "description": "UI 및 스타일링 관련"
  },
  {
    "name": "  BugFix",
    "color": "d73a4a",
    "description": "버그 수정"
  },
  {
    "name": "  Docs",
    "color": "1D76DB",
    "description": "문서 작성 및 수정 (README.md 등)"
  },
  {
    "name": "  API",
    "color": "D4C5F9",
    "description": "서버 API 통신"
  },
  {
    "name": "  Refactor",
    "color": "f29a4e",
    "description": "코드 리팩토링"
  },
  {
    "name": " ‍♂️ Question",
    "color": "9ED447",
    "description": "추가 정보 요청"
  },
  {
    "name": "✅ Test",
    "color": "ccffc4",
    "description": "테스트 관련(JUnit, Espresso 등)"
  }
]

Github Personal Access Token

Github -> Settings -> Developer Settings -> Personal Access Tokens -> Classic

Repository 관련 Scope만 체크하면 됩니다.

실행 방법

1️⃣ 위에서 생성한 git-labels.json이 위치한 폴더로 이동합니다.

2️⃣ 아래 명령어를 통해 라벨을 한 번에 적용합니다.

npx github-label-sync --access-token {AccessToken} --labels ./git-labels.json {사용자 이름}/{레포지터리 이름}

조직에 속한 Repository의 Label를 업데이트하고 싶은 경우는 아래와 같이 입력하면 됩니다.

npx github-label-sync --access-token {AccessToken} --labels ./git-labels.json {조직 이름}/{레포지터리 이름}

Financial-Times/github-label-sync

자세한 설명은 해당 링크를 참조해 주세요!

GitHub - Financial-Times/github-label-sync: Synchronise your GitHub labels with as few destructive operations as possible

Synchronise your GitHub labels with as few destructive operations as possible - Financial-Times/github-label-sync

github.com

[Compose] 한국 이름 입력을 위한 TextField 구현 (+천지인)

Moondev — Wed, 20 Nov 2024 00:24:14 +0900

한국에서 이름 입력 시, 천지인 키보드와 삼성 한손모아키 키보드의 호환성을 고려해야 합니다.

특히, 두 키보드에서 미들닷(ㆍᆢ)의 표현이 다르기 때문에 이를 적절히 처리하는 정규표현식을 사용해야 합니다.

정규표현식

입력 필터링을 위한 정규표현식은 다음과 같습니다:

val regex = Regex("^[가-힣ㆍᆞᆢㄱ-ㅎㅏ-ㅣ]*$")

이 정규표현식은 한글 문자(가-힣), 미들닷(ㆍ, ᆢ), 그리고 자음(ㄱ-ㅎ)과 모음(ㅏ-ㅣ)을 포함하여

오직 한국어만 입력받도록 설정합니다.

미들닷(ㆍ)이 두 개인 이유는 삼성의 한손모아키에서 사용되는 미들닷(ㆍ)이 천지인과 다르기 때문에

이를 모두 대응하기 위해 추가하였습니다.

예시 코드

아래는 Compose를 사용하여 한국어 입력을 처리하는 KoreanTextField 컴포저블 함수의 예시입니다.

@Composable
fun KoreanTextField(
    value: String,
    onValueChange: (String) -> Unit,
    modifier: Modifier = Modifier,
    textStyle: TextStyle = TextStyle.Default
) {
    val regex = Regex("^[가-힣ㆍᆞᆢㄱ-ㅎㅏ-ㅣ]*$")
    
    BasicTextField(
        value = value,
        onValueChange = { newValue ->
            if (newValue.isEmpty() || regex.matches(newValue)) {
                onValueChange(newValue)
            }
        },
        modifier = modifier
            .fillMaxWidth()
            .border(1.dp, Color.Gray)
            .padding(8.dp),
        textStyle = textStyle,
        singleLine = true,
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Text)
    )
}

사용 예시

아래는 KoreanTextField를 사용하는 화면의 예시입니다.

@Composable
fun Screen() {
    var text by remember { mutableStateOf("") }
    
    KoreanTextField(
        value = text,
        onValueChange = { text = it }
    )
}

정리

이 코드는 천지인 키보드와 삼성 한손모아키 키보드에서 한글 이름을 올바르게 입력받을 수 있도록 도와줍니다.

정규표현식을 통해 입력값을 필터링하고, 사용자가 입력한 내용이 유효할 경우에만 상태를 업데이트합니다.

[Git] CHANGELOG.md Generate

Moondev — Sat, 26 Oct 2024 06:03:34 +0900

지난 포스트에서 AngularJS Commit Convention에 대해 정리했습니다.

이번에는 정리한 내용 중에서 CHANGELOG.md를 직접 생성해보려 합니다.

CHANGELOG.md

생성하기에 앞서 CHANGELOG.md가 뭔지 설명해 보겠습니다.

CHANGELOG.md는 Release 시점에 Commit Message를 <type> 및 <scope> 별로 정리해 놓은

Markdown 형식의 파일입니다.

따라서, 프로젝트의 feature, bug fix, refactor 등으로부터 변경된 변화를 한눈에 파악할 수 있습니다.

간단한 생성 방법

이전 글에서도 소개해드렸는데 Git 명령어를 통해 생성하는 방법입니다.

git log --pretty="- %s" > CHANGELOG.md

위와 같이 명령어를 입력 후 실행하면 --pretty 설정에 맞춰 CHANGELOG.md가 생성됩니다.

%s 는 요약이라는 의미입니다.

아래 이미지는 위 명령어로 생성한 CHANGELOG입니다.

pretty 확장 옵션

아래는 pretty의 확장 옵션 종류 및 설명입니다.

%H: 커밋 해시
%h: 축약된 커밋 해시
%T: 트리 해쉬
%t: 축약된 트리 해시
%P: 부모 해시들
%p: 축약된 부모 해시들
%an: 저자 이름
%aN: 저자 이름 (존칭)
%ae: 저자 이메일
%aE: 저자 이메일 (존칭)
%al: 저자 이메일 local-part (the part before the @ sign)
%aL: 저자 local-part (see %al) respecting .mailmap, see git-shortlog[1] or git-blame[1])
%ad: 저자 날짜 (format respects --date= option)
%aD: 저자 날짜, RFC2822 style
%ar: 저자 날짜, 상대적인
%at: 저자 날짜, UNIX timestamp
%ai: 저자 날짜, ISO 8601-like format
%aI: 저자 날짜, strict ISO 8601 format
%as: 저자 날짜, short format (YYYY-MM-DD)
%ah: 저자 날짜, human style (like the --date=human option of git-rev-list[1])
%cn: 커미터 이름
%cN: 커미터 이름 (존칭)
%ce: 커미터 이메일
%cE: 커미터 이메일 (존칭)
%cl: 커미터 이메일 local-part (the part before the @ sign)
%cL: 커미터 local-part (see %cl) 존칭
%cd: 커미터 날짜 (format respects --date= option)
%cD: 커미터 날짜, RFC2822 style
%cr: 커미터 날짜, relative
%ct: 커미터 날짜, UNIX timestamp
%ci: 커미터 날짜, ISO 8601-like format
%cI: 커미터 날짜, strict ISO 8601 format
%cs: 커미터 날짜, short format (YYYY-MM-DD)
%ch: 커미터 날짜, human style
%d: 참조 이름
%D: " (", ")"처럼 래핑 없는 참조 이름
%S: 커맨드 라인상에서 제공하는 참조이름 (= git log --source), git log에서만 동작
%e: 인코딩
%s: 주제
%f: 파일 이름에 적합한 정리된 제목 줄
%b: 바디
%B: raw body (unwrapped subject and body)
%N: commit notes
%GG: 서명된 커밋에 대한 GPG의 raw verification message
%G?: 좋은 (유효한) 서명을 위해 "G"표시
%GS: 서명된 커밋의 서명자 이름 표시
%GK: 서명된 커밋에 서명하는 데 사용되는 키 표시
%GF: show the fingerprint of the key used to sign a signed commit
%GP: 서명된 커밋에 서명하는 데 사용된 키의 지문 표시
%GT: 서명된 커밋에 서명하는 데 사용되는 키의 신뢰 수준을 표시
%gD: reflog selector
%gd: shortened reflog selector; %gD와 동일, 하지만 참조 이름 부분은 사람의 가독성을 위해 단축되었습니다. (그래서 refs/heads/master는 master가 됨)
%gn: 신분 이름을 reflog
%gN: 신분 이름을 reflog (존칭)
%ge: 신원 이메일 거부
%gE: 신원 이메일 거부 (존칭)
%gs: 주제를 reflog

라이브러리를 활용한 생성 방법

저는 generate-changelog라는 라이브러리를 통해 CHANGELOG.md를 생성해보려고 합니다.

1. Node.js 설치

Node.js — Download Node.js®

Node.js® is a JavaScript runtime built on Chrome's V8 JavaScript engine.

nodejs.org

2. generate-changelog 설치

# 글로벌
npm i generate-changelog -g

# 특정 프로젝트에서만
npm i generate-changelog -D

저는 다른 프로젝트에서도 사용할 수 있도록 Global로 설치했습니다.

3. package.json 생성

해당 라이브러리는 Node.js 기반이기 때문에 package.json이 없으면 정상적으로 실행되지 않습니다.

때문에 Project Root에 package.json을 생성해 주세요.

Intellij IEDA의 경우 New > package.json을 선택하면 생성할 수 있습니다.

4. 생성 명령어 실행

changelog generate

위 명령어를 실행하면 CHANGELOG.md가 생성된 것을 확인할 수 있습니다.

[Git] AngularJS Commit Conventions

Moondev — Sat, 26 Oct 2024 05:43:20 +0900

우아한테크코스 프리코스 진행을 하면서 요구사항 중 AngularJS Commit Convention을 참고하여

커밋 메시지를 작성하라는 요구사항이 있었습니다.

그래서 이번 기회에 정리해보며 사용 방법을 익혀보려고 합니다.

자료는 해당 링크를 참고했습니다.

CHANGELOG.md 생성

변경 기록에는 다음 세 가지의 내용이 포함되어 있습니다.

1. New Feature

2. Bug Fixes

3. Breaking Changes

사용자가 정의한 여러 스크립트에 따라 다양한 형식의 CHANGELOG를 생성할 수 있습니다.

아래 명령어로 간단한 형태의 CHANGELOG.md를 생성할 수 있습니다.

git log --pretty="- %s" > CHANGELOG.md

중요하지 않은 Commit 식별

중요하지 않은 커밋은 주로 기존에 작성된 로직에 변화가 없는 Commit을 뜻합니다.

주로 공백이나 빈 줄의 추가, 제거, 들여쓰기 같은 포맷의 변경이나 세미콜론 누락, 주석 등

중요하지 않은 커밋은 이진 탐색을 진행할 때 제외하도록 할 수 있습니다.

아래 명령어는 "irrelevant"라는 단어가 포함된 커밋 메시지를 찾아 제외하도록 합니다.

git bisect skip $(git rev-list --grep irrelevant <good place> HEAD)

히스토리 조회 시 더 많은 정보 제공

Fix small typo in docs widget (tutorial instructions)
Fix test for scenario.Application - should remove old iframe
docs - various doc fixes
docs - stripping extra new lines
Replaced double line break with single when text is fetched from Google
Added support for properties in documentation

위 커밋 메시지들은 어떤 변경이 발생했는지 명시하려 하지만, 공통적인 규약이 있지는 않습니다.

fix comment stripping
fixing broken links
Bit of refactoring
Check whether links do exist and throw exception
Fix sitemap include (to work on case sensitive linux)

이번 커밋 메시지만 보고는 변경된 점을 알 수 없습니다.

따라서, docs, docs-parser, compiler, senario-runner 같이 어디가 변경되었는지 알려주는 게 좋다고 합니다.

커밋 메시지의 형식

가장 집중해서 본 내용입니다.

평소에는 Commit 시에 <type>과 <subject>만 작성하였습니다.

이번 기회에 Commit 메시지가 어디까지 활용될 수 있는지 알게되었습니다.

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

<type>

feat: 새로운 기능 추가
fix: 버그 추가
docs: 문서 관련 작업
style: 스타일 변경 (들여쓰기, 공백 제거 등)
refactor: 리팩토링
test: 테스트 관련 코드 작업
chore: 자잘한 수정

그런데, Augular 9 Convention에서는 chore type이 제거되는 대신 build, ci, perf가 추가되었다고 합니다.

build: 빌드 관련 작업
ci: CI 설정 관련 작업
perf: 성능 개선

<scope>

개인적으로 가장 유용했던 부분이었던 것 같습니다.

기존에는 변경한 위치를 header에 작성 했었는데 <scope>를 통해 변경된 위치를 알려줌으로써

커밋 내역에 대한 가독성이 크게 향상되는 것을 경험할 수 있었습니다.

scope에는 어디가 변경되었는지가 작성되는데,

변경된 부분은 모두 들어가는 게 가능합니다.

location
browser
compile
rootScope
ngHref
ngClick
ngView
등등

생략도 가능합니다.

변경된 클래스명 혹은 함수명을 작성하면 좋을 것 같습니다.

<subject> or <short summary> or <header>

명령문, 현재 시제로 작성합니다.

영문으로 작성 시 "Add"나 "Change"로 시작합니다.

주의할 점은 다음과 같습니다.

첫 글자를 대문자로 작성하지 마세요.
마지막에 마침표를 붙이지 마세요.

<body>

명령문, 현재 시제로 작성합니다.

변경한 이유와 변경 전과의 차이점을 설명합니다.

<footer>

모든 주요 변경 내역(Breaking Change)들은 다음과 함께 footer에 언급되어야 합니다.

변경점
변경 사유
마이그레이션 지시

해결된 이슈(Referencing Issues)는 Commit Message 최하단에 Closes #이슈번호 와 같이 작성되어야 합니다.

해결된 이슈가 여러 개인 경우에는 Closes #123, #23, #44와 같이 작성할 수 있습니다.

커밋 메시지 예시

style($location): add couple of missing semi colons

feat(directive): ng:disabled, ng:checked, ng:multiple, ng:readonly, ng:selected

New directives for proper binding these attributes in older browsers (IE).
Added coresponding description, live examples and e2e tests.

Closes #351

docs(guide): updated fixed docs from Google Docs

Couple of typos fixed:
- indentation
- batchLogbatchLog -> batchLog
- start periodic checking
- missing brace

feat($compile): simplify isolate scope bindings

Changed the isolate scope binding options to:
  - @attr - attribute binding (including interpolation)
  - =model - by-directional model binding
  - &expr - expression execution binding

This change simplifies the terminology as well as
number of choices available to the developer. It
also supports local name aliasing from the parent.

BREAKING CHANGE: isolate scope bindings definition has changed and
the inject option for the directive controller injection was removed.

To migrate the code follow the example below:

Before:

scope: {
  myAttr: 'attribute',
  myBind: 'bind',
  myExpression: 'expression',
  myEval: 'evaluate',
  myAccessor: 'accessor'
}

After:

scope: {
  myAttr: '@',
  myBind: '@',
  myExpression: '&',
  // myEval - usually not useful, but in cases where the expression is assignable, you can use '='
  myAccessor: '=' // in directive's template change myAccessor() to myAccessor
}

The removed `inject` wasn't generaly useful for directives so there should be no code using it.

[Compose] SMS Retriever API - SMS 인증번호 자동입력

Moondev — Tue, 1 Oct 2024 03:05:04 +0900

Google Play Service에는 SMS 기반 확인 프로세스를 간소화하는 데 사용할 수 있는 두 가지 API가 있습니다.

SMS Retriever API
SMS User Consent API

SMS Retriever API는 정말 자동화된 사용자 경험을 제공하므로 가능한 경우 사용하는 것이 좋습니다.

하지만 메시지 본문에 사용자 정의 해시 코드를 입력해야 하며, 해당 메시지를 보낸 사람이 아니라면 이 작업을 하는 것이 어려울 수 있습니다.

메시지의 내용을 제어할 수 없는 경우(예: 앱이 앱 내에서 결제 거래를 승인하기 전에 사용자 전화번호를 인증할 수 있는 금융 기관과 협력하는 경우) 커스텀 해시 코드가 필요하지 않은 SMS User Consent API를 사용할 수 있습니다.

그러나 사용자에게 앱의 인증 코드가 포함된 메시지에 대한 액세스 요청은 승인해야 합니다.

사용자에게 잘못된 메시지가 표시될 가능성을 최소화하기 위해 SMS 사용자 동의 기능은 메시지에 적어도 하나의 숫자를 포함한 4~10자리의 영숫자 코드가 포함되어 있는지 확인합니다.

자동 SMS 인증 흐름

SMS Retriever API를 사용하면 사용자가 직접 인증 코드를 입력하지 않아도 되며, 추가 앱 권한이 없어도 Android 앱에서 SMS 기반 사용자 인증을 자동으로 실행할 수 있습니다.

앱에서 자동 SMS 인증을 구현하면 인증 흐름은 다음과 같습니다.

간단히 흐름을 정리하자면,

1. 전화번호 인증 요청

사용자가 인증할 전화번호를 서버에 전달하며 인증번호 발송을 요청합니다.

2. SMS Retriever API 사용
동시에 앱은 SMS Retriever API를 사용하여 SMS를 리슨 합니다.

3. 서버에서 SMS 발송
서버는 사용자에게 일회용 코드와 앱을 식별하는 해시가 포함된 SMS 메시지를 발송합니다.

4. SMS 수신 및 확인
사용자의 기기에서 SMS 메시지를 수신하면 Google Play 서비스는 앱 해시를 사용하여 메시지가 앱을 대상으로 하는 것인지 확인하고, SMS Retriever API를 통해 메시지 텍스트를 제공합니다.

5. 인증 코드 파싱
앱은 메시지 텍스트에서 일회용 코드(인증 코드)를 파싱하여 서버로 인증 요청을 합니다.

6. 인증 확인
서버는 앱에서 전달받은 일회용 코드(인증 코드)를 확인한 후 사용자가 계정을 성공적으로 인증했음을 기록합니다.

구현 방법

필요 버전

minSdkVersion 19 이상
compileSdkVersion 28 또는 이후 버전

Dependency

implementation("com.google.android.gms:play-services-auth:21.2.0")
implementation("com.google.android.gms:play-services-auth-api-phone:18.1.0")

SMS 규칙

1. SMS 내용은 140byte 이하여야 합니다.
2. SMS 맨 앞은 <#>라는 Text로 시작해야 합니다.
3. SMS 맨 마지막은 앱을 식별하는 11글자 해시 문자열로 끝나야 합니다.

ex) <#> [앱 이름] 인증번호는 [123456] 입니다. bzXF9SEFPHs

규칙 1, 2, 3을 제외한 나머지 부분은 변경해도 상관없습니다.

ex) <#> 인증번호: 123456 bzXF9SEFPHs

해시키 구하는 코드

class AppSignatureHelper(context: Context?) : ContextWrapper(context) {

    val appSignatures: List<String>
        get() {
            val appCodes = mutableListOf<String>()

            try {
                val packageName = packageName
                val signatures = getPackageSignatures(packageName)

                signatures.forEach { signature ->
                    hashSignature(packageName, signature)?.let { appCodes.add(it) }
                }
            } catch (e: PackageManager.NameNotFoundException) {
                Log.e(TAG, "패키지를 찾을 수 없어 해시를 가져올 수 없습니다.", e)
            }

            return appCodes
        }


    private fun getPackageSignatures(packageName: String): Array<Signature> {
        val packageManager = packageManager
        return packageManager.getPackageInfo(packageName, PackageManager.GET_SIGNATURES).signatures
    }

    private fun hashSignature(packageName: String, signature: Signature): String? {
        return hash(packageName, signature.toCharsString())
    }

    private fun hash(packageName: String, signature: String): String? {
        val appInfo = "$packageName $signature"
        return try {
            val messageDigest = MessageDigest.getInstance(HASH_TYPE)
            messageDigest.update(appInfo.toByteArray(StandardCharsets.UTF_8))
            val hashSignature = messageDigest.digest().take(NUM_HASHED_BYTES).toByteArray()
            encodeToBase64(hashSignature)
        } catch (e: NoSuchAlgorithmException) {
            Log.e(TAG, "해시 알고리즘을 찾을 수 없습니다.", e)
            null
        }
    }

    private fun encodeToBase64(hashSignature: ByteArray): String {
        val base64Hash = Base64.encodeToString(hashSignature, Base64.NO_PADDING or Base64.NO_WRAP)
        return base64Hash.take(NUM_BASE64_CHAR)
    }

    companion object {
        private val TAG: String = AppSignatureHelper::class.java.simpleName
        private const val HASH_TYPE = "SHA-256"
        private const val NUM_HASHED_BYTES = 9
        private const val NUM_BASE64_CHAR = 11
    }
}

BroadcastReceiver

첫 번째로 SMS 수신을 확인하기 위해 BroadcastReceiver 코드를 작성.

본인의 SMS 형식에 맞춰 파싱 함수를 수정해야 합니다.

class AuthSmsReceiver : BroadcastReceiver() {

    private var otpReceiver: OtpReceiveListener? = null

    interface OtpReceiveListener {
        fun onSmsReceived(otp: String)
    }

    private fun extractVerificationCode(message: String): String? {
        if (message.contains("app_name")) {
            val regex = """\d{6}""".toRegex()
            return regex.find(message)?.value
        }
        return null
    }

    override fun onReceive(context: Context, intent: Intent) {
        if (SmsRetriever.SMS_RETRIEVED_ACTION == intent.action) {
            intent.extras?.let { bundle ->
                val status = bundle.get(SmsRetriever.EXTRA_STATUS) as Status

                when (status.statusCode) {
                    CommonStatusCodes.SUCCESS -> {
                        val otpSms = bundle.getString(SmsRetriever.EXTRA_SMS_MESSAGE, "")

                        if (otpReceiver != null && otpSms.isNotEmpty()) {
                            val otp = extractVerificationCode(otpSms)
                            if (!otp.isNullOrEmpty()) {
                                otpReceiver!!.onSmsReceived(otp)
                            }
                        }
                    }
                }
            }
        }
    }

    fun setSmsListener(receiver: OtpReceiveListener) {
        this.otpReceiver = receiver
    }

    fun doFilter() = IntentFilter().apply {
        addAction(SmsRetriever.SMS_RETRIEVED_ACTION)
    }
}

View & ViewModel

많은 예제들이 Activity에서 구현하고 있지만, 저는 프로젝트에서 특정 뷰에서만 사용하기를 원했고

Multi Module + Single Activity 구조의 프로젝트였기에 app 모듈에 있는 MainActivity를 가져오기 힘들었습니다.

때문에 LocalContext.current를 통해 Context를 가져와서 activity로 캐스팅하고 ViewModel에 매개변수로 넘겨 사용했습니다.

DisposableEffect를 사용해 activity의 smsReceiver를 생성 및 제거했습니다.

DisposableEffect(LocalLifecycleOwner.current) {
    (context as? Activity)?.let { viewModel.startSmsRetriever(it) }
    onDispose { (context as? Activity)?.let { viewModel.stopSmsRetriever() } }
}

ViewModel에서는 AuthSmsReceiver.OtpReceiveListener를 상속받아 구현했습니다.

그냥 apply에서 this.setSmsListener(object: AuthSmsReceiver.OtpReceiveListener { /* override fun onSmsReceived... */})로 작성해도 상관없습니다.

    private var smsReceiver: AuthSmsReceiver? = null
    private var weakActivity: WeakReference<Activity>? = null

    @SuppressLint("UnspecifiedRegisterReceiverFlag")
    fun startSmsRetriever(activity: Activity) {
        weakActivity = WeakReference(activity)
        SmsRetriever.getClient(activity).startSmsRetriever().also { task ->
            task.addOnSuccessListener {
                if (smsReceiver == null) {
                    smsReceiver = AuthSmsReceiver().apply {
                        setSmsListener(this@MobileSendAuthViewModel)
                    }
                }

                if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE){
                    weakActivity?.get()?.registerReceiver(smsReceiver, smsReceiver!!.doFilter(), RECEIVER_EXPORTED)
                } else {
                    weakActivity?.get()?.registerReceiver(smsReceiver, smsReceiver!!.doFilter())
                }
            }

            task.addOnFailureListener {
                setEffect { AuthEffect.ShowToast(
                    message = it.message.toString(),
                    type = SnackBarType.ERROR
                ) }
            }
        }
    }

    override fun onSmsReceived(otp: String) {
        setAction(AuthAction.AutoFillCode(otp))
        stopSmsRetriever()
    }

    fun stopSmsRetriever() {
        weakActivity?.get()?.let { activity ->
            if (smsReceiver != null) {
                activity.unregisterReceiver(smsReceiver)
                smsReceiver = null
            }
        }
    }

여기서 주의할 점은 API 34부터 registerReceiver를 사용할 때

RECEIVER_EXPORTED 또는 RECEIVER_NOT_EXPORTED를 넣어줘야 합니다.

해당 값을 넣어주지 않으면 아래와 같은 Exception이 발생한다고 합니다.

java.lang.SecurityException: package: One of RECEIVER_EXPORTED or RECEIVER_NOT_EXPORTED should be specified when a receiver isn’t being registered exclusively for system broadcasts

해당 내용에 대한 자세한 설명은 여기를 참고해 주세요.

예시 화면

인증 코드 재전송 시 다시 Receive를 받기 위해서는 기존 receiver를 제거하고 새로운 receiver를 등록해야지만 정상적으로 동작합니다.

또 다른 방법으로는 AndroidManifest.xml에서 아래처럼 Receiver를 정적으로 등록해도 동작합니다.

다만, 특정 뷰에서만 해당 기능이 필요하기 때문에 동적으로 Receiver를 등록하는 게 좋을 것 같습니다.

<receiver
    android:name="com.weave.intro.utils.AuthSmsReceiver"
    android:exported="true"
    android:permission="com.google.android.gms.auth.api.phone.permission.SEND">
    <intent-filter>
        <action android:name="com.google.android.gms.auth.api.phone.SMS_RETRIEVED"/>
    </intent-filter>
</receiver>

[Compose] SnackBar Duration Custom

Moondev — Tue, 1 Oct 2024 00:58:44 +0900

https://m3.material.io/components/snackbar/guidelines#74ae61e1-a27a-4543-b3ba-b2391cfe0308

SnackBar란?

SnackBar는 간단한 메시지를 사용자에게 전달하는 UI 구성 요소로, 주로 아래와 같은 용도로 사용됩니다.

정보 전달: 작업의 결과나 상태에 대한 피드백을 제공합니다.
사용자 액션 유도: 사용자가 특정 작업을 수행하도록 유도할 수 있습니다(예: "취소" 또는 "다시 시도" 버튼 포함).

SnackBar 구현하기

Android Compose에서 SnackBar를 사용하기 위해서는 `Scaffold`와 `SnackbarHost`를 이용해야 합니다.

아래는 기본적인 SnackBar 구현 예제입니다.

val scope = rememberCoroutineScope()
val snackbarHostState = remember { SnackbarHostState() }

Scaffold(
    snackbarHost = {
        SnackbarHost(hostState = snackbarHostState)
    },
    floatingActionButton = {
        ExtendedFloatingActionButton(
            text = { Text("Show snackbar") },
            icon = { Icon(Icons.Filled.Image, contentDescription = "") },
            onClick = {
                scope.launch {
                    snackbarHostState.showSnackbar("Snackbar")
                }
            }
        )
    }
) { contentPadding ->
    // content
}

위 코드에서는 SnackbarHostState를 생성하고 Scaffold 컴포넌트를 사용하여 SnackBar를 표시하는 구조입니다.

버튼 클릭 시 CoroutineScope를 이용하여 SnackBar를 나타내게 됩니다.

Snackbar Duration Custom

Snackbar 자체의 커스텀은 넘어가도록 하고,

Snackbar를 사용하면서 가장 불편했던 점인 노출 시간을 조절해보려고 합니다.

기본적으로 SnackBar의 지속 시간은 다음과 같은 세 가지 옵션이 있습니다.

enum class SnackbarDuration {
    /** Show the Snackbar for a short period of time */
    Short, // 4000L

    /** Show the Snackbar for a long period of time */
    Long, // 10000L

    /** Show the Snackbar indefinitely until explicitly dismissed or action is clicked */
    Indefinite // Long.MAX_VALUE
}

가장 짧은Short 옵션도 여전히 4초나 지속되어 다소 긴 것으로 느껴질 수 있습니다.

사용자에게 무의미한 대기 시간을 최소화하기 위해 맞춤형 지속 시간이 필요할 수 있습니다.

우선, showSnackbar 함수가 suspend 함수이기 때문에 Snackbar는 CoroutineScope안에서 동작합니다.

CoroutineScope안이라서 Job를 통해 새로운 코루틴을 생성하고 cancel()을 통해 중단할 수 있습니다.

예를 들어, 다음과 같이 코드를 작성할 수 있습니다.

LaunchedEffect(viewModel.uiEffect) {
    viewModel.uiEffect.collect { effect ->
        when (effect) {
            ...
            is AuthEffect.ShowMessage -> coroutineScope.launch {
                val job = launch {
                    snackState.showSnackbar(effect.message)
                }
                delay(1000L) // 원하는 시간 설정
                job.cancel()
            }
            ...
        }
    }
}

위 코드에서 delay(1000L)을 사용하여 1초 후에 SnackBar가 자동으로 사라지도록 설정합니다.

필요한 대기 시간이 달라질 수 있으므로 적절한 시간을 설정하여 사용자 경험을 개선할 수 있습니다.

아래는 추가 예시 코드입니다.

val scope = rememberCoroutineScope()
val snackBarMsg = stringResource(id = R.string.error_msg)

scope.launch {
    val job = scope.launch {
        snackbarHostState.showSnackbar(
            message = snackBarMsg,
            duration = SnackbarDuration.Indefinite,
        )
    }
    delay(1000)
    job.cancel()
}

Reference

jetpack compose Scaffold Possible to override the standard durations of SnackBar?

How can override the standard durations of the Scaffold SnackBar to apply my own durations in MS. I can't see a way to do it is EventsToAddAlbumScreen.ShowSnackbarEventToAddAlbumScreen ->

stackoverflow.com

스낵바(snackbar) | Jetpack Compose | Android Developers

이 페이지는 Cloud Translation API를 통해 번역되었습니다. 스낵바(snackbar) 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요. 스낵바 구성요소는 화면 하단에 위치합

developer.android.com