직접 공유 타겟 제공

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

ShortcutManagerCompat는 공유 바로가기를 제공하고 지원 중단된 ChooserTargetService API와 호환되는 AndroidX API입니다. 공유 바로가기 및 ChooserTargets를 둘 다 게시하는 경우 선호되는 방법입니다. 자세한 내용은 이 페이지의 AndroidX를 사용하여 공유 바로가기와 ChooserTargets 모두 제공하기를 참고하세요.

직접 공유 타겟 게시하기

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, ..))

   자바

   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)

   자바

   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))

   자바

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

직접 공유 타겟의 순위 향상

Android Sharesheet에는 정해진 수의 직접 공유 타겟이 표시됩니다. 여기 제안되는 항목은 순위별로 정렬됩니다. 다음을 수행하여 바로가기의 순위를 향상할 수 있습니다.

• 모든 shortcutIds가 고유하고 다른 타겟에 재사용되지 않는지 확인합니다.
• setLongLived(true)를 호출하여 바로가기가 오래 지속되는지 확인합니다.
• 대화 관련 바로가기의 경우 ShortcutManagerCompat.pushDynamicShortcut를 통해 상응하는 바로가기를 다시 게시하여 발신 및 수신 메시지의 바로가기 사용을 보고합니다. 자세한 내용은 이 페이지의 커뮤니케이션 앱의 바로가기 사용 보고를 참고하세요.
• 관련성 없거나 오래된 Direct Share 타겟을 제공하지 마세요. 예를 들어 사용자가 지난 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 Sharesheet 및 Android 10의 다른 시스템 화면은 바로가기 이미지의 도형과 테마를 설정합니다. 공유 바로가기를 제공하는 데 선호되는 메서드인 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가 필요한 경우 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 Direct Share 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 Direct Share API가 새로운 Sharing Shortcuts API로 대체되었습니다. 요구에 따라 사후 대응적으로 결과를 검색하는 대신 공유 바로가기 API를 사용하여 앱에서 직접 공유 타겟을 미리 게시할 수 있습니다. 그 결과 ShareSheet를 준비할 때 직접 공유 타겟을 가져오는 프로세스가 빠르게 빨라졌습니다. ChooserTargetService 직접 공유 메커니즘은 계속 작동하지만, 시스템은 이 방식으로 제공되는 타겟을 Sharing Shortcuts API를 사용하는 타겟보다 순위가 낮게 매깁니다.

Android 11 (API 수준 30)에서는 ChooserTargetService 서비스를 지원 중단했으며 Sharing Shortcuts API는 직접 공유 타겟을 제공하는 유일한 방법입니다.

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

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

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

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