바로가기 관리

바로가기를 만들고 나면 앱의 전체 수명 주기에 걸쳐 바로가기를 관리해야 할 수 있습니다. 예를 들어 사용자가 얼마나 자주 바로가기로 특정 작업을 완료하는지 확인하여 앱을 최적화하는 것이 좋습니다. 또 다른 경우에는 고정된 바로가기를 사용 중지하여 앱이 오래되거나 누락된 작업을 실행하는 것을 방지할 수 있습니다. 이 가이드에서는 바로가기를 관리하는 이러한 방법을 비롯하여 여러 다른 일반적인 관리 방법을 설명합니다.

바로가기 동작

다음 섹션에는 공개 상태, 표시 순서, 순위를 포함하여 바로가기 동작에 관한 일반 정보가 포함되어 있습니다.

바로가기 공개 상태

중요 보안 참고사항: 모든 바로가기 정보는 사용자 인증 정보 암호화 저장소에 저장되므로 사용자가 기기를 잠금 해제할 때까지 앱에서 사용자의 바로가기에 액세스할 수 없습니다.

정적 바로가기 및 동적 바로가기는 사용자가 특정 동작 또는 음성 명령을 실행할 때 지원되는 런처 또는 어시스턴트에 표시됩니다. 지원되는 런처에서는 동작이 앱의 런처 아이콘 길게 누르기이지만 다른 런처 앱에서는 실제 동작이 다를 수 있습니다. Google 어시스턴트를 사용하면 바로가기가 어시스턴트 내에 표시되거나 사용자 음성 명령으로 시작될 수 있습니다.

LauncherApps 클래스는 런처 앱이 바로가기에 액세스할 수 있는 API를 제공합니다.

고정된 바로가기는 런처 자체에 나타나므로 항상 표시됩니다. 고정된 바로가기는 다음 경우에만 런처에서 삭제됩니다.

사용자가 고정된 바로가기를 삭제하는 경우
고정된 바로가기와 연결된 앱이 제거되는 경우
사용자가 설정 > 앱 및 알림으로 이동하여 앱을 선택한 다음 저장소 > 저장소 삭제를 눌러 앱의 데이터를 삭제한 경우

바로가기 표시 순서

런처가 앱의 바로가기를 표시할 때는 다음 순서로 표시되어야 합니다.

정적 바로가기: isDeclaredInManifest() 메서드가 true를 반환합니다.
동적 바로가기: ShortcutInfo.isDynamic() 메서드가 true를 반환합니다.

각 바로가기 유형(정적 및 동적) 내에서 바로가기는 ShortcutInfo.getRank()에 따라 증가하는 순위순으로 정렬됩니다. Google 어시스턴트는 사용자에게 표시할 컨텍스트 바로가기를 결정할 때 바로가기 순위도 고려합니다.

순위는 음이 아닌 순차적 정수입니다. updateShortcuts(Context, List), addDynamicShortcuts(Context, List) 또는 setDynamicShortcuts(Context, List)를 호출할 때 기존 바로가기의 순위를 업데이트할 수 있습니다.

참고: 순위는 각 바로가기 유형(정적 또는 동적)마다 다를 수 있도록 자동으로 조정됩니다. 예를 들어 순위가 0, 1, 2인 동적 바로가기가 3개 있는 경우 순위가 1인 다른 동적 바로가기를 추가하면 이 바로가기를 두 번째 위치에 배치하라는 요청으로 해석할 수 있습니다. 이에 대응하여 세 번째 및 네 번째 바로가기가 바로가기 목록의 하단 쪽으로 이동하고 순위도 각각 2와 3으로 변경됩니다.

여러 인텐트 및 활동 관리

사용자가 바로가기를 활성화할 때 앱에서 여러 작업을 실행하려면 연속적인 활동을 트리거하도록 앱을 구성하면 됩니다. 이렇게 하려면 바로가기 유형에 따라 여러 인텐트를 할당하거나 특정 활동을 다른 활동에서 시작하거나 인텐트 플래그를 설정합니다.

여러 인텐트 할당

ShortcutInfoCompat.Builder로 바로가기를 만들 때 setIntent() 대신 setIntents()를 사용할 수 있습니다. setIntents()를 호출하면 사용자가 바로가기를 선택할 때 앱 내에서 여러 활동을 실행하여 마지막 활동을 제외한 모든 활동을 백 스택의 목록에 배치할 수 있습니다. 그런 다음 사용자가 기기의 뒤로 버튼을 누르려고 하면 기기의 런처로 돌아가는 대신 앱의 다른 활동이 사용자에게 표시됩니다.

참고: 사용자가 바로가기를 선택하고 '뒤로' 키를 누르면 앱에서 리소스 파일에 나열된 바로가기의 마지막에서 두 번째 인텐트와 일치하는 활동을 실행합니다. 이 동작 패턴은 바로가기에서 만든 백 스택을 사용자가 삭제할 때까지 뒤로 버튼을 반복해서 누를 때 계속됩니다. 다음에 사용자가 뒤로 버튼을 누르면 시스템은 사용자를 런처로 다시 이동합니다.

다른 활동에서 활동 시작

정적 바로가기는 맞춤 인텐트 플래그를 보유할 수 없습니다. 정적 바로가기의 첫 번째 인텐트에는 항상 Intent.FLAG_ACTIVITY_NEW_TASK와 Intent.FLAG_ACTIVITY_CLEAR_TASK가 설정됩니다. 즉, 앱이 이미 실행 중이면 정적 바로가기가 실행될 때 앱의 기존 활동이 모두 제거됩니다. 이 동작을 원하지 않는 경우 트램펄린 활동 또는 표시되지 않는 활동(Activity.onCreate(Bundle)에서 다른 활동을 시작하는 활동)을 사용하여 Activity.finish()를 호출할 수 있습니다.

AndroidManifest.xml 파일의 트램펄린 활동에는 속성 할당 android:taskAffinity=""가 포함되어야 합니다.
바로가기 리소스 파일에서 정적 바로가기 내의 인텐트는 트램펄린 활동을 참조해야 합니다.

트램펄린 활동에 관한 자세한 내용은 다른 활동에서 활동 시작하기를 참조하세요.

인텐트 플래그 설정

동적 바로가기는 어떤 설정의 Intent 플래그로도 게시될 수 있습니다. 다른 플래그와 함께 Intent.FLAG_ACTIVITY_CLEAR_TASK를 지정하는 것이 좋습니다. 그렇게 하지 않고 앱이 실행되는 동안 다른 작업을 시작하려고 하면 타겟 활동이 표시되지 않을 수 있습니다.

작업 및 인텐트 플래그에 관한 자세한 내용은 작업 및 백 스택 가이드를 참조하세요.

바로가기 업데이트

각 앱의 런처 아이콘에는 기껏해야 정적 및 동적 바로가기를 합한 getMaxShortcutCountPerActivity() 수가 포함될 수 있습니다. 그러나 앱이 만들 수 있는 고정된 바로가기의 수에는 제한이 없습니다.

동적 바로가기가 고정되면 게시자가 동적 바로가기로 삭제하더라도 고정된 바로가기는 여전히 표시되고 실행할 수 있습니다. 이렇게 해서 앱에는 getMaxShortcutCountPerActivity() 수보다 많은 바로가기가 있을 수 있습니다.

예를 들어 getMaxShortcutCountPerActivity()가 4라고 가정해보겠습니다.

채팅 앱이 최근 대화(c1, c2, c3, c4)를 표시하는 동적 바로가기를 4개 게시합니다.
사용자는 바로가기를 4개 모두 고정합니다.
나중에 사용자가 추가 대화를 3개(c5, c6, c7) 시작했으므로 게시자 앱은 동적 바로가기를 다시 게시합니다. 새로운 동적 바로가기 목록은 c4, c5, c6, c7입니다.

앱에서는 c1, c2, c3을 삭제해야 합니다. 동적 바로가기를 4개를 초과하여 표시할 수 없기 때문입니다. 그러나 c1, c2, c3은 여전히 사용자가 액세스하고 실행할 수 있는 고정된 바로가기입니다.

이제 사용자는 게시자 앱의 활동에 연결되는 총 7개의 바로가기에 액세스할 수 있습니다. 총계에는 최대 바로가기 수와 고정된 바로가기 3개가 모두 포함되기 때문입니다.
앱에서 updateShortcuts(Context, List)를 사용하여 기존 7개 바로가기를 모두 업데이트할 수 있습니다. 예를 들어 채팅 동종 앱의 아이콘이 변경된 경우 이 바로가기 세트를 업데이트할 수 있습니다.
addDynamicShortcuts(Context, List)와 setDynamicShortcuts(Context, List) 메서드는 동일한 ID로 기존 바로가기를 업데이트하는 데 사용할 수도 있습니다. 그러나 이 메서드는 비동적 고정된 바로가기의 업데이트에 사용할 수 없습니다. 이 두 메서드가 주어진 바로가기 목록을 동적 바로가기로 변환하려고 하기 때문입니다.

Google 어시스턴트와 같은 어시스턴트 앱에서 표시하기 위해 푸시할 수 있는 바로가기 개수에는 제한이 없습니다. ShortcutManagerCompat Jetpack 라이브러리의 pushDynamicShortcut() 메서드를 사용하여 어시스턴트 앱에서 사용할 바로가기를 만들고 업데이트할 수 있습니다. 또한, 동적 링크가 Google 어시스턴트에 표시되려면 앱에 Google 바로가기 통합 라이브러리를 추가해야 합니다.

바로가기 업데이트를 포함하여 앱 바로가기 가이드라인에 관한 자세한 내용은권장사항을 참고하세요.

시스템 언어 변경 처리

앱에서 시스템 언어가 변경된 것을 표시하는 Intent.ACTION_LOCALE_CHANGED 브로드캐스트를 수신하면 동적 및 고정된 바로가기를 업데이트해야 합니다.

바로가기 사용 추적

런처는 바로가기의 활성화 내역을 검사하여 정적 및 동적 바로가기를 표시할 상황을 알아냅니다. 정적 바로가기의 경우 다음 이벤트 중 하나가 발생할 때 reportShortcutUsed() 메서드를 호출하고 바로가기 ID를 전달하여 사용자가 앱 내에서 특정 작업을 언제 완료하는지 계속 추적할 수 있습니다.

사용자가 주어진 ID로 바로가기를 선택합니다.
앱 내에서 사용자는 동일한 바로가기에 상응하는 작업을 수동으로 완료합니다.

앱은 관련 이벤트가 발생할 때 pushDynamicShortcut() 메서드를 호출하고 바로가기 ID를 전달하여 동적 바로가기 사용을 추적합니다. 이 방법으로 동적 바로가기 사용을 푸시하면 Google 어시스턴트와 같은 어시스턴트 앱에서 사용자에게 관련 바로가기를 추천할 수 있습니다. pushDynamicShortcut() 메서드는 호출되었을 때 사용량을 보고하므로 동일한 바로가기의 reportShortcutUsed() 메서드도 호출하면 안 됩니다.

참고: 앱에서 푸시하는 동적 링크가 Google 어시스턴트와 같은 Google 표시 경로에 표시되도록 하려면 Google 바로가기 통합 라이브러리가 필요합니다. 이 라이브러리를 앱에 추가하면 어시스턴트가 동적 링크를 수집하여 어시스턴트 앱에서 사용자에게 추천하도록 허용할 수 있습니다.

바로가기 사용 중지

앱과 그 사용자는 바로가기를 기기의 런처에 고정할 수 있으므로, 이렇게 고정된 바로가기가 오래되거나 더 이상 존재하지 않는 앱 내의 작업으로 사용자를 안내할 수도 있습니다. 이 상황을 관리하려면 사용자가 선택하지 않았으면 하는 바로가기에 대해 disableShortcuts()를 호출하여 바로가기를 사용 중지하면 됩니다. 이 방법은 지정된 바로가기를 정적 및 동적 바로가기 목록에서 삭제하고 이러한 바로가기의 고정된 복사본을 모두 사용 중지합니다. 이 메서드의 오버로드된 버전도 사용할 수 있습니다. 이 버전은 CharSequence를 맞춤 오류 메시지로 허용합니다. 그러면 사용자가 사용 중지된 바로가기를 실행하려고 할 때 이 오류 메시지가 표시됩니다.

참고: 앱을 업데이트할 때 앱의 정적 바로가기를 삭제하면 시스템에서 자동으로 삭제된 바로가기를 사용 중지합니다.

비율 제한

setDynamicShortcuts(), addDynamicShortcuts() 또는 updateShortcuts() 메서드를 사용한다면 포그라운드에서 현재 활동이나 서비스가 없는 앱인 백그라운드 앱에서 특정 횟수만큼만 이러한 메서드를 호출할 수 있다는 점에 유의하세요. 이러한 메서드를 호출할 수 있는 특정 횟수 제한을 비율 제한이라고 합니다. 이 기능은 ShortcutManagerCompat가 기기 리소스를 과도하게 사용하는 것을 방지합니다.

비율 제한이 활성화되면 isRateLimitingActive()가 true를 반환합니다. 그러나 비율 제한은 특정 이벤트 중에 재설정되므로 비율 제한에 다시 도달할 때까지 백그라운드 앱에서도 ShortcutManager 메서드를 호출할 수 있습니다. 이러한 이벤트에는 다음이 포함됩니다.

앱이 포그라운드로 옵니다.
시스템 언어가 변경됩니다.
사용자가 알림에서 인라인 답장 작업을 실행합니다.

개발 또는 테스트 중에 비율 제한이 발생하면 기기 설정에서 개발자 옵션 > ShortcutManager 비율 제한 재설정을 선택하거나 adb에서 다음 명령어를 입력할 수 있습니다.

$ adb shell cmd shortcut reset-throttling [ --user your-user-id ]

백업 및 복원

앱의 매니페스트 파일에 android:allowBackup="true" 속성 할당을 포함하여 사용자가 기기를 변경할 때 앱에서 백업 및 복원 작업을 실행하도록 허용할 수 있습니다. 백업 및 복원을 허용한다면 앱 바로가기에 관한 다음 사항에 유의하세요.

정적 바로가기는 사용자가 새로운 기기에 앱을 다시 설치한 후에만 자동으로 다시 게시됩니다.
동적 바로가기는 백업되지 않으므로 앱에 로직을 포함하여 사용자가 새로운 기기에서 앱을 열 때 다시 게시되도록 해야 합니다.
고정된 바로가기는 기기의 런처에 자동으로 복원되지만 시스템에서는 고정된 바로가기와 연결된 아이콘을 백업하지 않습니다. 따라서 앱에 고정된 바로가기의 이미지를 저장하여 새로운 기기에서 복원하기 쉽도록 해야 합니다.

다음 코드 스니펫은 앱의 동적 바로가기를 복원하는 가장 좋은 방법과 앱의 고정된 바로가기가 유지되었는지 확인하는 방법을 보여줍니다.

Kotlin

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.dynamicShortcuts.size == 0) {
            // Application restored. Need to re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts have been restored. Use
                // updateShortcuts() to make sure they contain
                // up-to-date information.
            }

        }
    }
    // ...
}

자바

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Need to re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts have been restored. Use
                // updateShortcuts() to make sure they contain
                // up-to-date information.
            }
        }
    }
    // ...
}

추가 리소스

Android AppShortcuts 샘플은 이 페이지에서 다룬 워크플로의 사용을 더 자세히 보여줍니다.