Dev Note

갤럭시 측면 버튼 '앱 열기'에 activity-alias 아이콘이 안 뜨는 이유

모모아이는 통화와 회의 녹음을 올리면 AI가 전사·요약·할 일을 정리해 주는 앱입니다. Android 버전에 앱 안에서 바로 녹음하는 네이티브 녹음기를 넣으면서, 녹음 시작까지 걸리는 동작을 하나로 줄이는 데 공을 들였습니다. 빠른 설정 타일, 홈 화면 위젯, 아이콘 길게 누르기 바로가기, 잠금 화면 위에 뜨는 녹음 화면을 만들었고, 마지막으로 갤럭시의 측면 버튼 두 번 누르기에 녹음을 연결하려고 했습니다.

이 마지막 항목만 설계대로 동작하지 않았습니다. activity-alias로 런처 아이콘을 하나 더 만들어 측면 버튼에 연결하려는 분이라면 같은 함정을 밟을 수 있어 기록해 둡니다.

설계: 기능 하나만 여는 두 번째 런처 아이콘

갤럭시의 설정 > 유용한 기능 > 측면 버튼 > 두 번 누르기에는 '앱 열기'라는 선택지가 있습니다. 이름 그대로 앱을 고르는 기능이라, 앱 안의 특정 동작으로 바로 보내려면 그 동작만 하는 런처 진입점이 따로 있어야 한다고 판단했습니다.

그래서 녹음 화면으로 곧장 가는 진입점을 activity-alias로 하나 더 만들고, 측면 버튼 목록에서 그걸 고르게 하기로 했습니다.

<!-- 녹음 화면: 바깥에는 닫혀 있고, 잠금 화면 위에 뜬다 (일부 속성 생략) -->
<activity
    android:name=".recorder.RecorderActivity"
    android:exported="false"
    android:launchMode="singleTask"
    android:showWhenLocked="true"
    android:turnScreenOn="true"
    android:theme="@style/RecorderTheme" />

<!-- '모모아이 녹음' 런처 아이콘. 기본은 꺼져 있다 -->
<activity-alias
    android:name=".recorder.RecorderLauncher"
    android:enabled="false"
    android:exported="true"
    android:icon="@drawable/ic_recorder_launcher"
    android:label="@string/recorder_label"
    android:targetActivity=".recorder.RecorderActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity-alias>

공식 문서에 따르면 별칭은 대상 액티비티를 독립된 컴포넌트처럼 보여 주고, 자기만의 인텐트 필터를 가질 수 있습니다. 대상 액티비티에 런처 필터가 없어도 별칭에 MAIN/LAUNCHER를 달면 런처에 아이콘이 생깁니다. 그래서 녹음 화면은 exported="false"로 닫아 두고, 바깥에서 들어오는 문은 별칭 하나만 열었습니다.

또 icon, label처럼 별칭에도 있는 속성은 대상의 값을 물려받지 않지만, 별칭에 없는 속성(showWhenLocked, launchMode, theme 등)은 대상의 값이 그대로 적용됩니다. 그래서 별칭으로 열어도 녹음 화면은 잠금 화면 위에 뜨고 꺼진 화면을 켭니다.

녹음 화면은 ACTION_MAIN으로 열리면 곧바로 녹음을 시작합니다. MAIN으로 들어오는 길은 별칭뿐이기 때문입니다. 최근 앱 목록에서 다시 연 경우는 뺐습니다.

private fun handleLaunch(intent: Intent?) {
    val fromHistory = (intent?.flags ?: 0) and Intent.FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY != 0
    val wantsStart = when (intent?.action) {
        ACTION_START -> true        // 타일·위젯이 보내는 앱 전용 액션
        Intent.ACTION_MAIN -> true  // '모모아이 녹음' 아이콘(측면 버튼 '앱 열기')
        else -> false
    }
    if (wantsStart && !fromHistory && !RecorderState.snapshot.isActive) {
        startRecordingWithPermission()
    }
}

녹음 화면의 "측면 버튼으로 바로 녹음" 카드에서 기능을 켜면 별칭이 켜지고 삼성 측면 버튼 설정이 열립니다. 처음 안내 문구는 "'앱 열기' → '모모아이 녹음'을 고르세요"였습니다.

증상: 목록에는 앱 이름 하나뿐

실제로 써 보니 안내대로 할 수 없었습니다. 별칭을 켜면 앱 서랍에는 '모모아이 녹음' 아이콘이 생기는데, 측면 버튼의 '앱 열기' 목록에는 'Momoi' 항목 하나만 있었습니다. 그걸 고르면 측면 버튼은 녹음 화면이 아니라 앱 본 화면을 열었습니다.

앱 서랍과 측면 버튼 목록이 같은 목록일 거라는 가정이 틀린 것이었습니다.

진단 1: 별칭이 런처 진입점으로 등록됐나

먼저 MAIN/LAUNCHER에 응답하는 컴포넌트를 adb로 조회합니다. 이 명령은 순서까지 보여 주는데, 뒤에서 보듯 이번 문제의 핵심이 그 순서였습니다.

adb shell cmd package query-activities --brief --components \
  -a android.intent.action.MAIN -c android.intent.category.LAUNCHER | grep com.example.app

# 출력 형식 예시: 한 줄에 '앱 ID/컴포넌트' 하나
com.example.app/com.example.app.MainActivity

앱 ID(applicationId)와 코드 패키지(namespace)가 다른 앱은 앱 ID/코드 패키지.클래스 꼴로 나옵니다. 셸 명령에 컴포넌트를 적을 때도 이 형식을 따라야 합니다.

진단 2: 측면 버튼은 무엇을 저장했나

다음은 측면 버튼 설정이 실제로 저장한 값입니다. 제가 쓴 갤럭시 탭에서는 이 값이 Global 설정에 문자열로 남아 있어 adb로 읽을 수 있었습니다(읽기만 합니다).

adb shell settings list global | grep function_key

# 출력 예시 (값은 바꿈)
function_key_config_doublepress=1
function_key_config_doublepress_type=2
function_key_config_doublepress_value=com.example.app/com.example.app.MainActivity

제 기기에서는 _type이 2일 때가 '앱 열기'였고, _value에는 컴포넌트 이름이 그대로 들어 있었습니다. 측면 버튼은 앱이 아니라 컴포넌트를 저장합니다. 고른 순간 열 컴포넌트가 정해지고, 앱이 업데이트로 매니페스트를 바꿔도 저장된 값은 그대로입니다. 이 키와 형식은 삼성이 공개한 것이 아니라 제 기기에서 본 것이라 다른 기기에서는 다를 수 있습니다.

진단 3: 목록은 어떻게 만들어지나

남은 질문은 "왜 별칭이 목록에 안 나오나"였습니다. 삼성 문서에서는 이 목록이 어떻게 만들어지는지 찾지 못해서, 갤럭시 탭 S7(Android 13, One UI 5.1.1)에서 설정 앱과 services.jar를 꺼내 dexdump로 읽어 보았습니다. 제가 확인한 범위의 동작은 이렇습니다.

  • 목록을 채우는 로더는 LauncherApps.getActivityList()로 런처 진입점을 전부 받아 옵니다. 여기까지는 일반 런처와 같습니다.
  • 그런데 결과를 패키지 이름을 키로 하는 맵에 넣으면서, 같은 패키지가 이미 들어 있으면 건너뜁니다. 한 앱에서 진입점이 몇 개가 나오든 첫 번째 하나만 남습니다.
  • 항목을 고르면 그 진입점의 컴포넌트를 앞에서 본 설정 값에 저장합니다.
  • 측면 버튼은 저장된 컴포넌트를 ACTION_MAIN + CATEGORY_LAUNCHER, 플래그 0x10200000(FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_RESET_TASK_IF_NEEDED)으로 엽니다. 엑스트라는 붙이지 않습니다.

즉 이 목록은 런처 아이콘 목록이 아니라 앱 목록입니다. 앱마다 getActivityList()가 돌려준 순서에서 맨 앞에 온 진입점 하나가 대표가 됩니다.

마지막 항목은 다른 우회로도 막습니다. 인텐트에 홈 화면 아이콘과 같은 액션·카테고리만 있고 엑스트라가 없으니, 앱 본 화면이 측면 버튼 실행을 알아채고 녹음으로 분기할 수 없습니다. 단서는 어떤 컴포넌트가 열렸는가뿐이라, 별칭이 저장되게 하는 수밖에 없습니다. 아이콘 길게 누르기 바로가기(shortcuts.xml)도 답이 아니었습니다. 제가 본 로더는 런처 진입점만 돌았습니다.

같은 앱 안의 순서는 Android 문서가 보장하지 않지만, 제 기기에서는 매니페스트에 선언한 순서를 따랐습니다. 고치기 전에는 MainActivity가 먼저, 별칭이 그 뒤였습니다. 그래서 목록의 항목은 늘 MainActivity를 가리켰고 별칭은 두 번째라 빠졌습니다.

우선순위로는 안 된다

먼저 떠오르는 건 인텐트 필터의 android:priority입니다. 하지만 <intent-filter> 문서에 따르면 권한 없는(non-privileged) 앱이 0보다 큰 우선순위를 요청하면 그 값은 무시되고 0으로 잘립니다. 일반 앱에는 막힌 길입니다.

같은 문서에는 한 앱 안의 필터 순서를 정하는 android:order(API 28 이상)도 있지만, 이 값이 삼성 목록에 영향을 주는지는 시험하지 않았습니다. 이번에는 확인된 동작인 선언 순서만으로 고쳤습니다.

해결 1: 별칭을 MainActivity보다 먼저 선언한다

녹음 화면과 별칭을 <application> 안에서 MainActivity보다 위로 옮겼습니다. 녹음 화면(대상)은 별칭보다도 먼저 두어야 합니다. 문서에는 targetActivity가 별칭보다 앞에 선언된 <activity>의 이름과 같아야 한다고 적혀 있습니다.

<application ...>
    <!-- 1. 별칭의 대상. 별칭보다 먼저 선언해야 한다 -->
    <activity android:name=".recorder.RecorderActivity" android:exported="false" ... />

    <!-- 2. 별칭. MainActivity보다 먼저 선언해야
         측면 버튼 목록의 이 앱 항목이 켜진 별칭을 가리킨다 -->
    <activity-alias
        android:name=".recorder.RecorderLauncher"
        android:enabled="false"
        android:exported="true"
        android:targetActivity=".recorder.RecorderActivity" ...>
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity-alias>

    <!-- 3. 앱 본 화면 -->
    <activity android:name=".MainActivity" android:exported="true" ...>
        ...
    </activity>
</application>

이제 동작은 별칭의 상태에 따라 갈립니다.

  • 별칭이 꺼져 있을 때: 꺼진 컴포넌트는 런처 진입점 조회에 나오지 않으므로 첫 진입점은 MainActivity입니다. 목록의 앱 항목은 예전처럼 앱을 엽니다.
  • 별칭이 켜져 있을 때: 첫 진입점이 별칭이 됩니다. 목록에는 여전히 이 앱의 항목 하나만 보이지만, 그걸 고르면 별칭이 저장되고 측면 버튼이 녹음 화면을 엽니다.

그 한 항목이 어떤 이름으로 보일지는 목록 구현에 달려 있어, 안내 문구를 "목록에 '모모아이 녹음'이 있으면 그걸, 없으면 'Momoi'를 고르세요"로 바꾸고 전에 Momoi를 골라 뒀어도 한 번 더 눌러 달라는 문장을 더했습니다. 업데이트 전에 골라 둔 사람의 설정에는 MainActivity가 그대로 남아 있기 때문입니다.

해결 2: 앱의 정문을 INFO로 따로 세운다

순서를 바꾸면 다른 문제가 생깁니다. 패키지 이름만으로 앱을 여는 코드는 대개 PackageManager.getLaunchIntentForPackage()를 씁니다. 이 메서드의 문서에는 현재 구현이 CATEGORY_INFO인 MAIN 액티비티를 먼저 찾고, 없으면 CATEGORY_LAUNCHER인 MAIN 액티비티를 찾는다고 적혀 있습니다. AOSP 구현은 조회 결과의 첫 항목을 고르기 때문에, INFO가 없는 앱에서 별칭이 첫 런처 진입점이 되면 이 메서드는 녹음 화면을 돌려줄 수 있습니다.

모모아이 안에서 이 메서드를 쓰는 곳만 셋이었습니다.

  • FCM 알림: firebase-messaging의 알림 빌더는 메시지에 click_action이나 링크가 없으면 getLaunchIntentForPackage()로 열 화면을 정합니다(25.1.2 바이트코드에서 확인).
  • 로컬 알림: flutter_local_notifications 17.2.4의 Android 구현도 알림을 눌렀을 때의 인텐트를 같은 메서드로 만듭니다.
  • 직접 만든 알림: 통화가 끝나면 "통화 요약할까요?" 알림을 띄우는 서비스도 원래 같은 메서드를 썼습니다.

그대로 두면 측면 버튼 기능을 켠 사람은 알림을 누를 때마다 녹음이 시작됩니다.

직접 만든 알림은 별칭을 처음 추가할 때 이미 MainActivity를 명시한 인텐트로 바꿔 두었습니다. 라이브러리 안의 호출은 고칠 수 없으니 MainActivity에 MAIN + CATEGORY_INFO 필터를 하나 더 달았습니다.

<activity android:name=".MainActivity" android:exported="true" ...>
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>
    <!-- 앱의 '정문'. getLaunchIntentForPackage()는 INFO 진입점을 먼저 고른다.
         이게 없으면 별칭이 켜졌을 때 알림 탭이 녹음 화면을 연다 -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.INFO"/>
    </intent-filter>
    ...
</activity>
// 앱 안에서 만드는 알림은 정문에도 기대지 않고 대상을 명시한다
fun openAppIntent(context: Context): Intent =
    Intent(context, MainActivity::class.java)
        .setAction(Intent.ACTION_MAIN)
        .addCategory(Intent.CATEGORY_LAUNCHER)
        .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)

CATEGORY_INFO는 문서에서 런처 목록에 나타나지 않으면서 사용자에게 정문을 제공하는 용도로 설명하는 카테고리입니다. LAUNCHER가 아니므로 아이콘이 늘지 않고 측면 버튼 목록에도 영향이 없습니다. 반면 getLaunchIntentForPackage()는 INFO를 먼저 보므로 별칭 순서와 상관없이 MainActivity를 돌려줍니다. 런처 순서는 측면 버튼 목록용으로, 패키지 단위로 여는 경로는 INFO로 떼어 놓은 셈입니다.

부작용: 런처 아이콘이 두 개가 된다

별칭 방식의 대가는 앱 서랍에 아이콘이 하나 더 생긴다는 점입니다. 측면 버튼을 쓰지 않는 사람에게는 정체를 알 수 없는 중복 아이콘입니다.

기본은 꺼 두고, 쓰겠다고 할 때만 켠다

별칭은 enabled="false"로 시작하고, 사용자가 녹음 화면의 카드에서 켤 때만 setComponentEnabledSetting()으로 켭니다. 이때 DONT_KILL_APP 플래그를 넘깁니다. 문서상 이 플래그는 컴포넌트를 담은 앱을 종료하지 말라는 뜻이라, 빼면 버튼을 누르는 순간 앱이 꺼질 수 있습니다.

fun setLauncherAliasEnabled(context: Context, enabled: Boolean) {
    context.packageManager.setComponentEnabledSetting(
        ComponentName(context, LAUNCHER_ALIAS),  // 별칭의 전체 이름(코드 패키지 기준)
        if (enabled) PackageManager.COMPONENT_ENABLED_STATE_ENABLED
        else PackageManager.COMPONENT_ENABLED_STATE_DISABLED,
        PackageManager.DONT_KILL_APP,
    )
}

켜는 순간 설정 화면으로 데려간다

켜기 버튼은 별칭을 켠 뒤 측면 버튼 설정을 바로 엽니다. 이 화면은 com.samsung.android.intent.action.SIDE_KEY_SETTINGS 액션으로 열 수 있는데, 다른 제조사 기기에는 없으므로 resolveActivity()로 먼저 확인합니다. Android 11 이상에서는 패키지 가시성 규칙 때문에 매니페스트의 <queries>에 이 액션을 선언해 두어야 조회가 됩니다. 조회에 실패하면 삼성이 아닌 기기로 보고, 버튼에 앱을 연결하는 설정이 있다면 '모모아이 녹음'을 고르라는 일반 안내로 바꿉니다.

<queries>
    <intent>
        <action android:name="com.samsung.android.intent.action.SIDE_KEY_SETTINGS" />
    </intent>
</queries>
private fun sideKeySettingsIntent(): Intent? {
    val intent = Intent(SAMSUNG_SIDE_KEY_SETTINGS).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
    return if (intent.resolveActivity(packageManager) != null) intent else null
}

끌 때는 측면 버튼 설정도 되돌리게 한다

별칭을 꺼도 측면 버튼 설정에는 별칭의 컴포넌트 이름이 남습니다. 그대로 두면 눌러도 아무것도 열리지 않을 수 있어, 끄기 버튼은 "'두 번 누르기'를 다른 동작으로 바꿔 달라"는 안내를 띄우고 측면 버튼 설정을 다시 엽니다. 외부 설정 값은 앱이 고칠 수 없으니 고칠 화면까지 데려다주는 데서 멈췄습니다.

두 번째 아이콘에도 쓸모를 준다

켜진 '모모아이 녹음' 아이콘은 누르면 바로 녹음이 시작되는 아이콘이기도 합니다. 중복 아이콘이 아니라 기능이 분명한 아이콘으로 읽히도록 이름과 아이콘 모양을 따로 주었습니다.

검증

1. 선언 순서를 테스트로 묶는다

이유를 모르는 사람 눈에 선언 순서는 아무래도 좋은 것으로 보입니다. 누군가 정리한다며 MainActivity를 맨 위로 올리면 빌드도 앱도 멀쩡한 채로 조용히 원래대로 돌아갑니다. 그래서 매니페스트를 XML로 읽어 순서와 필터를 확인하는 JVM 단위 테스트를 넣었습니다.

class RecorderLauncherManifestTest {
    private val android = "http://schemas.android.com/apk/res/android"

    // <application> 바로 아래의 activity / activity-alias 를 선언 순서대로
    private val components: List<Element> by lazy {
        val factory = DocumentBuilderFactory.newInstance().apply { isNamespaceAware = true }
        val doc = factory.newDocumentBuilder().parse(File("src/main/AndroidManifest.xml"))
        val app = doc.getElementsByTagName("application").item(0) as Element
        val nodes = app.childNodes
        (0 until nodes.length)
            .mapNotNull { nodes.item(it) as? Element }
            .filter { it.tagName == "activity" || it.tagName == "activity-alias" }
    }

    private fun indexOf(name: String): Int =
        components.indexOfFirst { it.getAttributeNS(android, "name") == name }
            .also { assertTrue("$name 이 매니페스트에 없다", it >= 0) }

    @Test
    fun `녹음 별칭이 앱 본 화면보다 먼저 선언된다`() {
        assertTrue(indexOf(".recorder.RecorderLauncher") < indexOf(".MainActivity"))
    }

    @Test
    fun `별칭의 대상 화면은 별칭보다 먼저 선언된다`() {
        assertTrue(indexOf(".recorder.RecorderActivity") < indexOf(".recorder.RecorderLauncher"))
    }

    // 이 밖에 별칭이 MAIN/LAUNCHER 를 갖고 기본으로 꺼져 있는지,
    // MainActivity 에 MAIN/INFO 정문이 있는지도 같은 방식으로 확인한다.
}

이 테스트는 소스 매니페스트만 보므로, 병합된 최종 APK의 순서는 기기에서 따로 확인했습니다.

2. 기기에서 진입점 순서와 정문 확인

# 런처 진입점: 별칭이 켜져 있으면 별칭이 먼저 나와야 한다
adb shell cmd package query-activities --brief --components \
  -a android.intent.action.MAIN -c android.intent.category.LAUNCHER | grep com.example.app

# 정문: 별칭 상태와 상관없이 MainActivity 하나여야 한다
adb shell cmd package query-activities --brief --components \
  -a android.intent.action.MAIN -c android.intent.category.INFO | grep com.example.app

갤럭시 탭 S7(Android 13)에서 별칭을 켠 상태로 조회하니 런처 진입점은 RecorderLauncher, MainActivity 순서로 나왔고, INFO 조회는 MainActivity로 풀렸습니다. 별칭을 끄면 런처 조회에는 MainActivity만 남고 INFO는 그대로 MainActivity입니다.

셸에서 별칭을 직접 켜고 끄려면 제 환경에서는 testOnly 빌드가 필요했습니다. 일반 빌드에서는 셸의 컴포넌트 상태 변경이 거부됩니다.

./gradlew assembleDebug -Pandroid.injected.testOnly=true
adb install -r -t app-debug.apk
adb shell pm enable com.example.app/com.example.app.recorder.RecorderLauncher

3. 측면 버튼이 보내는 인텐트를 그대로 재현

확인한 인텐트 모양을 am start로 똑같이 만들어, 화면을 끄고 잠근 상태에서 보냈습니다.

adb shell am start -a android.intent.action.MAIN \
  -c android.intent.category.LAUNCHER -f 0x10200000 \
  -n com.example.app/com.example.app.recorder.RecorderLauncher

태블릿에서는 녹음 화면이 잠금 화면 위에 뜨고 녹음이 시작됐습니다. 다만 이것은 측면 버튼이 별칭을 저장했다는 전제 위의 재현이라, 목록에서 다시 고른 뒤 무엇이 저장됐는지는 앞의 settings list global로 보는 것이 확실합니다. 또 모든 확인은 One UI 5.1.1 태블릿 한 대에서 했고, 최신 One UI 휴대폰이 같은 방식인지는 확인하지 못했습니다.

같은 문제를 피하는 체크리스트

  • 제조사 설정의 '앱 고르기' 목록은 앱 서랍과 같은 목록이 아닐 수 있습니다. 앱 서랍에 아이콘이 보인다고 그 목록에도 나올 거라고 가정하지 마세요.
  • 시스템이 앱을 열 때 보내는 인텐트에 무엇이 들어 있는지부터 확인하세요. 엑스트라가 없다면 앱이 구별할 수 있는 건 컴포넌트 이름뿐입니다.
  • 측면 버튼 같은 설정은 고른 시점의 컴포넌트를 문자열로 저장합니다. 매니페스트를 바꿔도 이미 저장된 값은 바뀌지 않으니, 사용자에게 다시 고르라고 안내해야 합니다.
  • 런처 진입점이 둘 이상인 앱은 MAIN + INFO 정문을 하나 두세요. getLaunchIntentForPackage()를 쓰는 SDK가 엉뚱한 진입점을 고르지 않게 됩니다.
  • 선언 순서처럼 겉보기에 의미 없는 매니페스트 사항이 동작을 좌우한다면 테스트로 묶어 두세요.
  • 두 번째 런처 아이콘은 기본으로 꺼 두고, 끌 때는 외부 설정에 남은 참조까지 정리하도록 안내하세요.

앱 서랍은 진입점을 보여 주고, 측면 버튼 설정은 앱을 보여 줍니다. 이 차이를 확인하고 나니 고치는 데는 선언 순서 변경과 INFO 필터 하나면 충분했습니다.

모모아이 — 통화·회의 녹음을 올리면 AI가 전사·요약·할 일·일정을 정리합니다. Google Play에서 받기
← 블로그 목록으로