도움말 풍선

도움말 풍선을 사용하면 사용자가 손쉽게 대화를 보고 참여할 수 있습니다.

도움말 풍선은 알림 시스템에 내장되어 있으며, 다른 앱 콘텐츠 위를 떠다니며 어디든 사용자가 이동하는 곳으로 따라갑니다. 버블을 펼쳐 앱 기능과 정보를 살펴볼 수 있으며 사용하지 않을 때는 접을 수 있습니다.

기기가 잠겨 있거나 항상 켜져 있는 화면이 활성화되어 있으면 일반적인 알림이 표시될 때처럼 버블이 나타납니다.

버블은 선택 해제 기능입니다. 앱에 첫 번째 버블이 표시되면 다음 두 가지 선택사항을 제공하는 권한 대화상자가 표시됩니다.

앱에 표시되는 버블을 모두 차단 - 알림이 차단되지는 않지만 버블로 표시되지 않습니다.
앱에서 모든 버블 허용 - BubbleMetaData를 포함해 전송한 모든 알림이 버블로 표시됩니다.

Bubble API

도움말 풍선은 알림 API를 통해 생성되며, 종전처럼 알림을 전송할 수 있습니다. 알림을 도움말 풍선으로 표시하려면 알림에 추가 데이터를 연결해야 합니다.

도움말 풍선 펼쳐 보기는 개발자가 선택하는 활동에서 생성됩니다. 활동을 도움말 풍선으로 올바르게 표시되도록 구성해야 합니다. 활동은 크기 조절이 가능해야 하고 삽입된 형태여야 합니다. 이러한 요구사항 중 하나라도 부족하면 활동이 도움말 풍선이 아니라 알림으로 표시됩니다.

다음 코드에서는 간단한 버블을 구현하는 방법을 보여줍니다.

<activity
  android:name=".bubbles.BubbleActivity"
  android:theme="@style/AppTheme.NoActionBar"
  android:label="@string/title_activity_bubble"
  android:allowEmbedded="true"
  android:resizeableActivity="true"
/>

여러 대화 상대와의 다중 채팅 대화와 같이 유형이 같은 여러 개의 버블이 앱에 표시되는 경우 해당 활동에서 여러 인스턴스를 실행할 수 있어야 합니다. Android 10을 실행하는 기기에서는 documentLaunchMode를 명시적으로 "always"로 설정하지 않으면 알림이 도움말 풍선으로 표시되지 않습니다. Android 11부터는 시스템에서 모든 대화의 documentLaunchMode를 자동으로 "always"로 설정하므로 이 값을 명시적으로 설정할 필요가 없습니다.

버블을 전송하려면 다음 단계를 따르세요.

평소처럼 알림을 생성합니다.
BubbleMetadata.Builder(PendingIntent, Icon) 또는 BubbleMetadata.Builder(String)를 호출하여 BubbleMetadata 객체를 생성합니다.
setBubbleMetadata()를 사용하여 알림에 메타데이터를 추가합니다.
Android 11 이상을 타겟팅하는 경우 도움말 풍선 메타데이터 또는 알림은 공유 단축키를 참조해야 합니다.

Kotlin

// Create bubble intent
val target = Intent(context, BubbleActivity::class.java)
val bubbleIntent = PendingIntent.getActivity(context, 0, target, 0 /* flags */)
val category = "com.example.category.IMG_SHARE_TARGET"

val chatPartner = Person.Builder()
    .setName("Chat partner")
    .setImportant(true)
    .build()

// Create sharing shortcut
val shortcutId = generateShortcutId()
val shortcut =
   ShortcutInfo.Builder(mContext, shortcutId)
       .setCategories(setOf(category))
       .setIntent(Intent(Intent.ACTION_DEFAULT))
       .setLongLived(true)
       .setShortLabel(chatPartner.name)
       .build()

// Create bubble metadata
val bubbleData = Notification.BubbleMetadata.Builder(bubbleIntent,
            Icon.createWithResource(context, R.drawable.icon))
    .setDesiredHeight(600)
    .build()

// Create notification, referencing the sharing shortcut
val builder = Notification.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(smallIcon)
    .setBubbleMetadata(bubbleData)
    .setShortcutId(shortcutId)
    .addPerson(chatPartner)

자바

// Create bubble intent
Intent target = new Intent(mContext, BubbleActivity.class);
PendingIntent bubbleIntent =
    PendingIntent.getActivity(mContext, 0, target, 0 /* flags */);

private val CATEGORY_TEXT_SHARE_TARGET =
    "com.example.category.IMG_SHARE_TARGET"

Person chatPartner = new Person.Builder()
        .setName("Chat partner")
        .setImportant(true)
        .build();

// Create sharing shortcut
private String shortcutId = generateShortcutId();
ShortcutInfo shortcut =
   new ShortcutInfo.Builder(mContext, shortcutId)
       .setCategories(Collections.singleton(CATEGORY_TEXT_SHARE_TARGET))
       .setIntent(Intent(Intent.ACTION_DEFAULT))
       .setLongLived(true)
       .setShortLabel(chatPartner.getName())
       .build();

// Create bubble metadata
Notification.BubbleMetadata bubbleData =
    new Notification.BubbleMetadata.Builder(bubbleIntent,
            Icon.createWithResource(context, R.drawable.icon))
        .setDesiredHeight(600)
        .build();

// Create notification, referencing the sharing shortcut
Notification.Builder builder =
    new Notification.Builder(mContext, CHANNEL_ID)
        .setContentIntent(contentIntent)
        .setSmallIcon(smallIcon)
        .setBubbleMetadata(bubbleData)
        .setShortcutId(shortcutId)
        .addPerson(chatPartner);

버블이 전송될 때 앱이 포그라운드에 있는 경우 중요도가 무시되고 버블이 항상 표시됩니다(사용자가 앱에서 버블이나 알림을 차단하지 않은 경우).

펼친 버블 만들기

버블이 자동으로 펼침 상태로 표시되도록 구성할 수 있습니다. 사용자가 버튼을 탭하여 새 채팅을 시작하는 것과 같이 버블이 표시되게 하는 작업을 실행하는 경우에만 이 기능을 사용하는 것이 좋습니다. 이 경우 버블이 생성될 때 전송되는 초기 알림을 숨기는 것도 괜찮습니다.

setAutoExpandBubble()이나 setSuppressNotification()과 같은 동작을 활성화하는 플래그를 설정하는 데 사용할 수 있는 메서드가 있습니다.

Kotlin

val bubbleMetadata = Notification.BubbleMetadata.Builder()
    .setDesiredHeight(600)
    .setIntent(bubbleIntent)
    .setAutoExpandBubble(true)
    .setSuppressNotification(true)
    .build()

자바

Notification.BubbleMetadata bubbleData =
    new Notification.BubbleMetadata.Builder()
        .setDesiredHeight(600)
        .setIntent(bubbleIntent)
        .setAutoExpandBubble(true)
        .setSuppressNotification(true)
        .build();

버블 콘텐츠 수명 주기

버블이 펼쳐지면 콘텐츠 활동이 일반 프로세스 수명 주기를 거치므로 애플리케이션이 포그라운드 프로세스가 됩니다(아직 포그라운드 프로세스가 아닌 경우).

버블이 접히거나 닫히면 활동이 삭제됩니다. 그러면 앱에 실행 중인 다른 포그라운드 구성요소가 있는지 여부에 따라 프로세스가 캐시되고 나중에 종료될 수 있습니다.

도움말 풍선이 표시되는 상황

사용자에게 방해되는 경우를 줄이기 위해 도움말 풍선은 특정 상황에서만 표시됩니다.

Android 11 이상을 타겟팅하는 앱에서는 대화 요구사항을 충족하지 않으면 알림이 도움말 풍선으로 표시되지 않습니다. 앱이 Android 10을 타겟팅하는 경우 다음 조건 중 하나 이상이 충족되는 경우에만 알림이 도움말 풍선으로 표시됩니다.

알림에서 MessagingStyle을 사용하며, 알림에 추가된 사용자가 있습니다.
알림이 Service.startForeground에 대한 호출에서 발생하고, CATEGORY_CALL의 카테고리와 추가된 사용자를 가지고 있습니다.
알림이 전송되었을 때 앱이 포그라운드에 있습니다.

위 조건이 충족되지 않으면 도움말 풍선 대신 알림이 표시됩니다.

권장사항

버블은 화면 공간을 차지하고 다른 앱 콘텐츠를 가립니다. 진행 중인 커뮤니케이션과 같이 중요도가 높거나 사용자가 일부 콘텐츠에 대해 버블을 명시적으로 요청한 경우에만 알림을 버블로 전송해야 합니다.
버블은 사용자가 비활성화할 수 있습니다. 이 경우 버블 알림은 일반적인 알림으로 표시됩니다. 버블 알림이 일반적인 알림으로도 작동하는지 항상 확인해야 합니다.
버블에서 실행하는 프로세스(예: 활동 및 대화상자)는 버블 컨테이너 안에 표시됩니다. 이는 즉, 버블에 작업 스택이 있을 수 있음을 의미합니다. 버블 내에 기능이나 탐색이 많이 있는 경우 상황이 복잡해질 수 있습니다. 기능을 가능한 한 구체적이고 가볍게 유지하는 것이 좋습니다.
도움말 풍선 활동에서 onBackPressed를 재정의할 때 super.onBackPressed를 호출해야 합니다. 그러지 않으면 도움말 풍선이 제대로 작동하지 않을 수 있습니다.
접힌 도움말 풍선에 업데이트된 메시지가 수신되면 읽지 않은 메시지를 나타내는 배지 아이콘이 도움말 풍선에 표시됩니다. 사용자가 연결된 앱에서 메시지를 열면 다음 단계를 따르세요.
- BubbleMetadata를 업데이트하여 알림을 숨깁니다. BubbleMetadata.Builder.setSupressNotification()을 호출합니다. 그러면 배지 아이콘이 삭제되어 사용자가 메시지에 반응했음을 나타냅니다.
- Notification.Builder.setOnlyAlertOnce()를 true로 설정하여 BubbleMetadata 업데이트에 수반되는 소리나 진동을 중단합니다.

샘플 앱

People 샘플 앱은 도움말 풍선을 사용하는 간단한 대화 앱입니다. 이 앱에서는 시연을 위해 채팅 봇을 사용합니다. 실제 애플리케이션에서는 봇이 아닌 사람이 작성하는 메시지에만 도움말 풍선을 사용해야 합니다.