직접 공유 타겟 제공

다른 앱의 사용자가 URL, 이미지 또는 다른 종류의 데이터를 앱과 더 쉽고 빠르게 공유할 수 있도록 직접 공유 타겟을 사용하세요. Direct Share는 사용자가 앱을 선택한 후 연락처를 검색할 필요 없이 메시지 및 소셜 앱의 연락처를 Android Sharesheet에 바로 표시하는 방식으로 작동합니다.

ShortcutManagerCompat는 공유 바로가기를 제공하는 AndroidX API로, 지원 중단된 ChooserTargetService API와 호환됩니다. 공유 바로가기와 ChooserTargets를 모두 게시하는 데 권장되는 방법입니다. 자세한 내용은 이 페이지의 AndroidX를 사용하여 공유 바로가기와 선택자 타겟 모두 제공을 참고하세요.

직접 공유 타겟 게시하기

Sharesheet 직접 공유 행에는 공유 바로가기 API에서 제공하는 동적 바로가기만 표시됩니다. 직접 공유 타겟을 게시하려면 다음 단계를 완료하세요.

1. 앱의 XML 리소스 파일에서 share-target 요소를 선언합니다.

   <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
   <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity">
       <data android:mimeType="text/plain" />
       <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" />
   </share-target>
   </shortcuts>
   

2. 앱을 초기화할 때 setDynamicShortcuts를 사용하여 중요도에 따라 동적 바로가기를 정렬합니다.

   지수가 낮을수록 중요도가 더 높습니다. 커뮤니케이션 앱을 만드는 경우 이러한 대화는 앱에 표시되는 최신성순으로 정렬된 인기 대화가 될 수 있습니다. 오래된 바로가기는 게시하지 마세요. 지난 30일 동안 사용자 활동이 없는 대화는 비활성으로 간주됩니다.

   Kotlin

   ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))
   

   Java

   List<ShortcutInfoCompat> shortcuts = new ArrayList<>();
   shortcuts.add(shortcut1);
   shortcuts.add(shortcut2);
   ...
   ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);
   
   

3. 커뮤니케이션 앱을 개발하는 경우 사용자가 연락처로 메시지를 받거나 보낼 때마다 pushDynamicShortcut를 통해 바로가기 사용을 즉시 보고합니다. 자세한 내용은 이 페이지의 커뮤니케이션 앱의 바로가기 사용 보고를 참고하세요. 예를 들어 actions.intent.SEND_MESSAGE 기능이 있는 ShortcutInfoCompat.Builder#addCapabilityBinding를 통해 바로가기에서 기능 결합을 지정하여 사용자가 전송한 메시지의 사용량을 보고합니다.

   Kotlin

   val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
     ...
     .setShortLabel(firstName)
     .setLongLabel(fullName)
     .setCategories(matchedCategories)
     .setLongLived(true)
   .addCapabilityBinding("actions.intent.SEND_MESSAGE").build()
   ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
   

   Java

   ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
     ...
     .setShortLabel(firstName)
     .setLongLabel(fullName)
     .setCategories(matchedCategories)
     .setLongLived(true)
     .addCapabilityBinding("actions.intent.SEND_MESSAGE")
     .build();
   
   ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
   

4. 사용자가 연락처를 삭제하면 removeLongLivedShortcut를 사용합니다. 이는 시스템 서비스에서 바로가기를 캐시하는지와 관계없이 바로가기를 삭제하는 데 선호되는 방법입니다. 다음 코드 스니펫은 이 작업을 실행하는 방법의 예를 보여줍니다.

   Kotlin

   val deleteShortcutId = "..."
   ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
   

   Java

   String deleteShortcutId = "...";
   ShortcutManagerCompat.removeLongLivedShortcuts(
       myContext, Arrays.asList(deleteShortcutId));
   
   

직접 공유 타겟의 순위 향상

Android Sharesheet에는 정해진 수의 직접 공유 타겟이 표시됩니다. 이러한 추천은 순위별로 정렬됩니다. 다음을 실행하여 바로가기의 순위를 개선할 수 있습니다.

• 모든 shortcutIds가 고유하고 여러 대상에 재사용되지 않는지 확인합니다.
• setLongLived(true)를 호출하여 바로가기가 오래 지속되는지 확인합니다.
• 대화 관련 바로가기의 경우 ShortcutManagerCompat.pushDynamicShortcut를 통해 상응하는 바로가기를 다시 게시하여 발신 및 수신 메시지의 바로가기 사용을 보고합니다. 자세한 내용은 이 페이지의 커뮤니케이션 앱의 바로가기 사용 보고를 참고하세요.
• 관련이 없거나 오래된 직접 공유 타겟(예: 지난 30일 동안 사용자가 메시지를 보내지 않은 연락처)은 제공하지 마세요.
• SMS 앱의 경우 잠재적인 스팸으로 식별된 짧은 코드나 대화의 바로가기를 제공하지 마세요. 사용자는 이러한 대화에 공유할 가능성이 매우 낮습니다.
• setCategories()를 호출하여 바로가기를 적절한 mimeType 속성과 연결합니다. 예를 들어 SMS 앱의 경우 연락처에 RCS 또는 MMS가 사용 설정되지 않은 경우 상응하는 바로가기를 image/* 및 video/*와 같은 텍스트가 아닌 MIME 유형과 연결하지 않습니다.
• 특정 대화의 경우 동적 바로가기가 푸시되고 사용이 보고되면 바로가기 ID를 변경하지 마세요. 이렇게 하면 순위를 위한 사용 데이터를 보관할 수 있습니다

사용자가 직접 공유 타겟을 탭하면 앱은 타겟 대상에서 직접 작업을 실행할 수 있는 UI로 사용자를 안내해야 합니다. 사용자에게 명확성 UI를 표시하지 말고 탭한 타겟과 관련 없는 UI에 배치하지 마세요. 예를 들어 메시지 앱에서 직접 공유 타겟을 탭하면 사용자가 선택한 사람과의 대화형 뷰로 이동합니다. 키보드가 표시되고 메시지가 공유 데이터로 미리 채워집니다.

Sharing Shortcuts API

Android 10 (API 수준 29)부터 ShortcutInfo.Builder에는 공유 타겟에 관한 추가 정보를 제공하는 메서드와 개선사항이 추가되었습니다.

setCategories()

Android 10부터 공유 인텐트 또는 작업을 처리할 수 있는 바로가기를 필터링하는 데도 카테고리가 사용됩니다. 자세한 내용은 공유 타겟 선언을 참고하세요. 이 필드는 공유 타겟으로 사용할 바로가기에 필요합니다.

setLongLived()

동적 바로가기 또는 고정된 바로가기로 게시되지 않았거나 앱에 표시되지 않게 된 경우 바로가기가 유효한지 여부를 지정합니다. 바로가기가 수명이 긴 경우 동적 바로가기로 게시 취소된 후에도 다양한 시스템 서비스에 의해 캐시될 수 있습니다.

바로가기가 오래 지속되도록 하면 바로가기의 순위가 향상될 수 있습니다. 자세한 내용은 최고 순위 획득하기를 참고하세요.

setShortLabel(), setLongLabel()

개별 사용자의 바로가기를 게시할 때는 setLongLabel()에 전체 이름을 포함하고 setShortLabel()에 닉네임이나 이름과 같은 짧은 이름을 포함하세요.

GitHub에 공유 바로가기를 게시하는 예를 확인해 보세요.

바로가기 이미지 제공

공유 바로가기를 만들려면 setIcon()를 통해 이미지를 추가해야 합니다.

공유 바로가기는 시스템 표시 경로 전반에 표시될 수 있으며 그 형태를 변경할 수 있습니다. 또한 Android 버전 7, 8 또는 9 (API 수준 25, 26, 27, 28)를 실행하는 일부 기기는 배경 없이 비트맵 전용 아이콘을 표시할 수 있으며, 이로 인해 대비가 크게 감소합니다. 바로가기가 의도한 대로 표시되도록 하려면 IconCompat.createWithAdaptiveBitmap()를 사용하여 적응형 비트맵을 제공합니다.

적응형 비트맵은 적응형 아이콘의 가이드라인 및 크기 집합을 따라야 합니다. 이를 달성하는 가장 일반적인 방법은 의도한 정사각형 비트맵을 72x72dp로 조정하고 이 비트맵을 108x108dp 투명 캔버스 내의 중앙에 배치하는 것입니다. 아이콘에 투명한 영역이 포함된 경우 배경 색상을 포함해야 합니다. 그렇지 않으면 투명한 영역이 검은색으로 표시됩니다.

특정 도형으로 마스킹된 이미지를 제공하지 마세요. 예를 들어 Android 10 (API 수준 29) 이전에는 직접 공유 ChooserTarget의 경우 원으로 마스킹된 사용자 아바타를 제공하는 것이 일반적이었습니다. 이제 Android 10의 Android Sharesheet 및 기타 시스템 노출 영역에서 바로가기 이미지의 도형과 테마를 설정합니다. 공유 바로가기를 제공하는 데 선호되는 방법은 ShortcutManagerCompat를 통해 이전 버전과 호환되는 직접 공유 ChooserTarget 객체의 도형을 원으로 자동 설정합니다.

공유 타겟 선언하기

정적 바로가기 정의와 마찬가지로 앱의 리소스 파일에서 공유 타겟을 선언해야 합니다. 리소스 파일의 <shortcuts> 루트 요소 내에 공유 타겟 정의를 다른 정적 바로가기 정의와 함께 추가합니다. 각 <share-targets> 요소에는 공유 데이터 유형, 일치하는 카테고리, 공유 인텐트를 처리할 타겟 클래스에 관한 정보가 포함됩니다. XML 코드는 다음과 같습니다.

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity">
    <data android:mimeType="text/plain" />
    <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" />
  </share-target>
</shortcuts>

공유 타겟의 데이터 요소는 인텐트 필터의 데이터 사양과 비슷합니다. 각 공유 타겟에는 여러 카테고리가 있을 수 있으며, 이러한 카테고리는 앱의 게시된 바로가기를 공유 타겟 정의와 일치시키는 데만 사용됩니다. 카테고리는 임의의 앱 정의 값을 가질 수 있습니다.

사용자가 Android Sharesheet에서 위의 타겟 공유 예와 일치하는 공유 바로가기를 선택하면 앱은 다음과 같은 공유 인텐트를 가져옵니다.

Action: Intent.ACTION_SEND
ComponentName: {com.example.android.sharingshortcuts /
                com.example.android.sharingshortcuts.SendMessageActivity}
Data: Uri to the shared content
EXTRA_SHORTCUT_ID: <ID of the selected shortcut>

사용자가 런처 바로가기에서 공유 타겟을 열면 앱은 ShortcutManagerCompat에 공유 바로가기를 추가할 때 생성된 인텐트를 가져옵니다. 인텐트가 다르기 때문에 Intent.EXTRA_SHORTCUT_ID를 사용할 수 없으며 필요한 경우 ID를 수동으로 전달해야 합니다.

커뮤니케이션 앱의 바로가기 사용 보고

커뮤니케이션 앱을 개발하는 경우 보내는 메시지와 수신 메시지 모두의 사용량을 보고하여 Android Sharesheet에서 순위를 높일 수 있습니다. 이렇게 하려면 ShortcutManagerCompat.pushDynamicShortcut를 통해 연락처를 나타내는 대화 바로가기를 다시 게시합니다.

바로가기 사용 및 기능 결합은 Android 5.0(API 21)과 호환됩니다.

발신 메일에 대한 바로가기 사용 보고

사용자가 보낸 메시지 사용량 보고는 메시지를 만든 후 '보내기' 버튼을 클릭하는 것과 기능적으로 유사합니다.

사용량 보고를 트리거하려면 actions.intent.SEND_MESSAGE 기능이 있는 ShortcutInfoCompat.Builder#addCapabilityBinding를 통해 바로가기에서 기능 결합을 지정합니다.

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
.addCapabilityBinding("actions.intent.SEND_MESSAGE").build()
ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

발신 메시지가 그룹 채팅용인 경우 recipient 유형이 기능과 연결되어 있으므로 Audience 매개변수 값도 추가해야 합니다.

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", listOf("Audience")).build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", Arrays.asList("Audience"))
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

수신 메시지의 바로가기 사용 보고

사용자가 SMS, 채팅 메시지, 이메일 또는 알림과 같은 메시지를 수신할 때 사용량 보고를 트리거하려면 actions.intent.RECEIVE_MESSAGE 기능이 있는 ShortcutInfoCompat.Builder#addCapabilityBinding를 통해 바로가기에서 기능 결합을 추가로 지정해야 합니다.

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE").build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

메시지가 그룹 채팅에서 온 것이라면 sender 유형이 기능과 연결되어 있으므로 Audience 매개변수 값도 추가해야 합니다.

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", listOf("Audience")).build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", Arrays.asList("Audience"))
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

AndroidX를 사용하여 공유 바로가기와 ChooserTargets 모두 제공

AndroidX 호환성 라이브러리로 작업하려면 앱의 매니페스트에 메타데이터 선택기 대상 서비스와 인텐트 필터 집합이 포함되어야 합니다. 현재 ChooserTargetService 직접 공유 API를 참고하세요.

이 서비스는 호환성 라이브러리에 이미 선언되어 있으므로 사용자가 앱의 매니페스트에서 서비스를 선언할 필요가 없습니다. 그러나 공유 활동에서 서비스로 연결되는 링크를 선택기 타겟 제공자로 고려해야 합니다.

다음 예에서 ChooserTargetService 구현은 AndroidX에 이미 정의되어 있는 androidx.core.content.pm.ChooserTargetServiceCompat입니다.

<activity
    android:name=".SendMessageActivity"
    android:label="@string/app_name"
    android:theme="@style/SharingShortcutsDialogTheme">
    <!-- This activity can respond to Intents of type SEND -->
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
    <!-- Only needed if you import the sharetarget AndroidX library that
         provides backwards compatibility with the old DirectShare API.
         The activity that receives the Sharing Shortcut intent needs to be
         taken into account with this chooser target provider. -->
    <meta-data
        android:name="android.service.chooser.chooser_target_service"
        android:value="androidx.sharetarget.ChooserTargetServiceCompat" />
</activity>

공유 바로가기 FAQ

바로가기 사용 데이터는 어떻게 저장되며 기기 외부로 전송되나요?

바로가기는 기기 내 암호화된 디스크 파티션의 시스템 데이터 디렉터리에 완전히 저장됩니다. 아이콘, 인텐트, 사용자 및 리소스 이름과 같은 바로가기의 정보는 시스템 서비스와 바로가기를 게시하는 동일한 앱에서만 액세스할 수 있습니다.

직접 공유의 역사는 어떻게 되나요?

Android 6.0 (API 수준 23)에서는 앱이 ChooserTargetService를 통해 ChooserTarget 객체를 제공할 수 있도록 직접 공유를 도입했습니다. 요청 시 사후 대응적으로 결과를 검색했기 때문에 타겟의 로드 시간이 느려졌습니다.

Android 10 (API 수준 29)에서는 ChooserTargetService 직접 공유 API를 새로운 공유 바로가기 API로 대체했습니다. 요청 시 사후 대응적으로 결과를 검색하는 대신 Sharing Shortcuts API를 사용하여 앱에서 직접 공유 타겟을 미리 게시할 수 있습니다. 그 결과 ShareSheet를 준비할 때 직접 공유 타겟을 가져오는 프로세스가 빠르게 빨라졌습니다. ChooserTargetService 직접 공유 메커니즘은 계속 작동하지만 시스템에서 이러한 방식으로 제공되는 타겟의 순위를 공유 바로가기 API를 사용하는 타겟보다 낮게 지정합니다.

Android 11 (API 수준 30)에서는 ChooserTargetService 서비스가 지원 중단되었으며 공유 바로가기 API는 직접 공유 타겟을 제공하는 유일한 방법입니다.

공유 타겟과 관련하여 게시된 바로가기는 런처 바로가기 (런처에서 앱 아이콘을 길게 누를 때 사용되는 일반적인 바로가기)와 어떻게 다른가요?

'공유 타겟' 목적으로 게시되는 모든 바로가기는 런처 바로가기이기도 하며 앱의 아이콘을 길게 누를 때 메뉴에 표시됩니다. 활동당 최대 바로가기 수 제한은 앱이 게시하는 총 바로가기 수에도 적용됩니다 (공유 타겟과 기존 런처 바로가기 결합).

게시해야 하는 공유 바로가기 수에 관한 안내는 무엇인가요?

공유 바로가기 수는 getMaxShortcutCountPerActivity(android.content.Context)를 통해 사용할 수 있는 동적 바로가기의 동일한 제한으로 제한됩니다. 이 제한까지 원하는 수를 게시할 수 있지만 앱 런처 길게 누르기 및 공유 시트에 공유 바로가기가 표시될 수 있다는 점에 유의해야 합니다. 길게 누르기의 앱 런처는 대부분 세로 모드에서 최대 4~5개의 바로가기를 표시하고 가로 모드에서는 8개를 표시합니다. 바로가기 공유에 관한 자세한 내용과 안내는 이 FAQ를 참고하세요.