Cung cấp mục tiêu Chia sẻ trực tiếp

Sử dụng các mục tiêu Chia sẻ trực tiếp để giúp người dùng các ứng dụng khác chia sẻ URL, hình ảnh hoặc các loại dữ liệu khác với ứng dụng của bạn một cách dễ dàng và nhanh chóng hơn. Tính năng Chia sẻ trực tiếp hoạt động bằng cách hiển thị danh bạ từ các ứng dụng nhắn tin và mạng xã hội ngay trên Trang chia sẻ của Android mà người dùng không cần phải chọn ứng dụng rồi tìm kiếm danh bạ.

ShortcutManagerCompat là một API AndroidX cung cấp Lối tắt chia sẻ và có khả năng tương thích ngược với API ChooserTargetService không dùng nữa. Đây là cách ưu tiên để phát hành cả Lối tắt để chia sẻ và ChooserTargets. Để xem hướng dẫn, hãy xem phần Sử dụng AndroidX để cung cấp cả Lối tắt chia sẻ và ChooserTargets trên trang này.

Xuất bản mục tiêu Chia sẻ trực tiếp

Hàng Chia sẻ trực tiếp trên trang Chia sẻ chỉ hiển thị các lối tắt động do API Lối tắt chia sẻ cung cấp. Hãy hoàn tất các bước sau để phát hành mục tiêu Chia sẻ trực tiếp.

1. Trong tệp tài nguyên XML của ứng dụng, hãy khai báo các phần tử 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. Khi ứng dụng khởi chạy, hãy sử dụng setDynamicShortcuts để sắp xếp các lối tắt động theo mức độ quan trọng.

   Chỉ số càng thấp thì càng quan trọng. Nếu bạn đang tạo một ứng dụng giao tiếp, thì các cuộc trò chuyện đó có thể là các cuộc trò chuyện hàng đầu được sắp xếp theo thứ tự gần đây nhất khi xuất hiện trong ứng dụng của bạn. Đừng xuất bản lối tắt đã cũ; một cuộc trò chuyện không có hoạt động của người dùng trong 30 ngày qua được coi là cũ.

   Kotlin

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

   Java

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

3. Nếu bạn đang phát triển một ứng dụng giao tiếp, hãy báo cáo việc sử dụng lối tắt thông qua pushDynamicShortcut ngay lập tức mỗi khi người dùng nhận hoặc gửi tin nhắn cho một người liên hệ. Hãy xem phần Báo cáo việc sử dụng lối tắt cho ứng dụng liên lạc trên trang này để biết thêm thông tin. Ví dụ: báo cáo mức sử dụng cho các tin nhắn do người dùng gửi bằng cách chỉ định các liên kết chức năng trong lối tắt thông qua ShortcutInfoCompat.Builder#addCapabilityBinding với chức năng actions.intent.SEND_MESSAGE.

   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. Nếu người dùng xoá một người liên hệ, hãy sử dụng removeLongLivedShortcut. Đây là cách ưu tiên để xoá lối tắt, bất kể lối tắt đó có được lưu vào bộ nhớ đệm của các dịch vụ hệ thống hay không. Đoạn mã sau đây cho thấy ví dụ về cách thực hiện việc này.

   Kotlin

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

   Java

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

Cải thiện thứ hạng của mục tiêu Chia sẻ trực tiếp

Trang chia sẻ nội dung trên Android hiển thị một số mục tiêu Chia sẻ trực tiếp cố định. Các đề xuất này được sắp xếp theo thứ hạng. Bạn có thể cải thiện thứ hạng của lối tắt bằng cách làm như sau:

• Đảm bảo tất cả shortcutIds đều là duy nhất và không bao giờ được sử dụng lại cho các mục tiêu khác nhau.
• Đảm bảo lối tắt tồn tại lâu dài bằng cách gọi setLongLived(true).
• Đối với các lối tắt liên quan đến cuộc trò chuyện, hãy báo cáo việc sử dụng lối tắt cho tin nhắn đến và đi bằng cách phát hành lại các lối tắt tương ứng thông qua ShortcutManagerCompat.pushDynamicShortcut. Hãy xem phần Báo cáo mức sử dụng lối tắt cho ứng dụng liên lạc trên trang này để biết thông tin chi tiết.
• Tránh cung cấp các mục tiêu Chia sẻ trực tiếp không liên quan hoặc lỗi thời, ví dụ: người liên hệ mà người dùng không nhắn tin trong vòng 30 ngày qua.
• Đối với ứng dụng SMS, hãy tránh cung cấp lối tắt cho mã ngắn hoặc cuộc trò chuyện được xác định là có khả năng là nội dung rác. Người dùng rất ít khi chia sẻ vào những cuộc trò chuyện đó.
• Gọi setCategories() để liên kết lối tắt với các thuộc tính mimeType thích hợp. Ví dụ: đối với ứng dụng SMS, nếu người liên hệ không bật RCS hoặc MMS, bạn sẽ không liên kết lối tắt tương ứng với các loại MIME không phải văn bản như image/* và video/*.
• Đối với một cuộc trò chuyện nhất định, sau khi một lối tắt động được đẩy và báo cáo về mức sử dụng, bạn không được thay đổi mã lối tắt. Điều này giúp đảm bảo việc giữ lại dữ liệu sử dụng để xếp hạng.

Nếu người dùng nhấn vào bất kỳ mục tiêu Chia sẻ trực tiếp nào, ứng dụng của bạn phải đưa họ đến một giao diện người dùng nơi họ có thể thực hiện hành động trực tiếp trên chủ đề của mục tiêu. Đừng hiển thị cho người dùng giao diện người dùng phân định và đừng đặt họ vào giao diện người dùng không liên quan đến mục tiêu được nhấn. Ví dụ: trong một ứng dụng nhắn tin, khi nhấn vào mục tiêu Chia sẻ trực tiếp, người dùng sẽ được chuyển đến chế độ xem cuộc trò chuyện với người mà họ đã chọn. Bàn phím sẽ hiển thị và thông báo được điền sẵn bằng dữ liệu đã chia sẻ.

API Lối tắt chia sẻ

Kể từ Android 10 (API cấp 29), ShortcutInfo.Builder đã thêm các phương thức và tính năng nâng cao để cung cấp thêm thông tin về mục tiêu chia sẻ:

setCategories()

Kể từ Android 10, các danh mục cũng được dùng để lọc các lối tắt có thể xử lý ý định hoặc hành động chia sẻ. Hãy xem phần Khai báo mục tiêu chia sẻ để biết thông tin chi tiết. Trường này là bắt buộc đối với các lối tắt dùng làm mục tiêu chia sẻ.

setLongLived()

Chỉ định xem một lối tắt có hợp lệ hay không khi ứng dụng đã huỷ phát hành hoặc ẩn lối tắt đó (dưới dạng lối tắt động hoặc lối tắt được ghim). Nếu một lối tắt có thời gian tồn tại lâu, thì nhiều dịch vụ hệ thống có thể lưu lối tắt đó vào bộ nhớ đệm ngay cả khi lối tắt đó đã bị huỷ xuất bản dưới dạng lối tắt động.

Việc tạo một lối tắt có thời gian tồn tại lâu có thể cải thiện thứ hạng của lối tắt đó. Hãy xem bài viết Nhận thứ hạng tốt nhất để biết thông tin chi tiết.

setShortLabel(), setLongLabel()

Khi phát hành lối tắt đến một cá nhân, vui lòng thêm tên đầy đủ của họ vào setLongLabel() và bất kỳ tên ngắn nào, chẳng hạn như biệt hiệu hoặc tên, vào setShortLabel().

Hãy xem ví dụ về cách phát hành Lối tắt chia sẻ trên GitHub.

Cung cấp hình ảnh lối tắt

Để tạo lối tắt Chia sẻ, bạn cần thêm hình ảnh thông qua setIcon().

Lối tắt chia sẻ có thể xuất hiện trên các nền tảng hệ thống và có thể được định hình lại. Ngoài ra, một số thiết bị chạy Android phiên bản 7, 8 hoặc 9 (API cấp 25, 26, 27 và 28) có thể hiển thị các biểu tượng chỉ bitmap mà không có nền, làm giảm đáng kể độ tương phản. Để đảm bảo lối tắt của bạn trông như mong đợi, hãy cung cấp bitmap thích ứng bằng cách sử dụng IconCompat.createWithAdaptiveBitmap().

Đảm bảo bitmap thích ứng tuân theo cùng nguyên tắc và kích thước được đặt cho biểu tượng thích ứng. Cách phổ biến nhất để thực hiện việc này là điều chỉnh tỷ lệ bitmap hình vuông dự kiến thành 72x72 dp và căn giữa trong canvas trong suốt 108x108 dp. Nếu biểu tượng của bạn có các vùng trong suốt, bạn cần thêm màu nền; nếu không, các vùng trong suốt sẽ có màu đen.

Không cung cấp hình ảnh được che thành một hình dạng cụ thể. Ví dụ: trước Android 10 (API cấp 29), thông thường, bạn sẽ cung cấp hình đại diện của người dùng cho các ChooserTarget Chia sẻ trực tiếp được che thành hình tròn. Trang chia sẻ của Android và các nền tảng hệ thống khác trong Android 10 hiện đã định hình và tạo hình ảnh lối tắt theo giao diện. Phương thức ưu tiên để cung cấp Lối tắt chia sẻ, thông qua ShortcutManagerCompat, sẽ tự động định hình các đối tượng ChooserTarget Chia sẻ trực tiếp có khả năng tương thích ngược thành hình tròn cho bạn.

Khai báo mục tiêu chia sẻ

Bạn phải khai báo mục tiêu chia sẻ trong tệp tài nguyên của ứng dụng, tương tự như định nghĩa lối tắt tĩnh. Thêm định nghĩa mục tiêu chia sẻ bên trong phần tử gốc <shortcuts> trong tệp tài nguyên, cùng với các định nghĩa lối tắt tĩnh khác. Mỗi phần tử <share-targets> chứa thông tin về loại dữ liệu được chia sẻ, các danh mục phù hợp và lớp mục tiêu sẽ xử lý ý định chia sẻ. Mã XML sẽ có dạng như sau:

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

Phần tử dữ liệu trong mục tiêu chia sẻ tương tự như quy cách dữ liệu trong bộ lọc ý định. Mỗi mục tiêu chia sẻ có thể có nhiều danh mục. Các danh mục này chỉ được dùng để so khớp lối tắt đã xuất bản của ứng dụng với định nghĩa mục tiêu chia sẻ. Danh mục có thể có bất kỳ giá trị nào do ứng dụng xác định.

Trong trường hợp người dùng chọn Lối tắt chia sẻ trong Trang chia sẻ nội dung trên Android khớp với mục tiêu chia sẻ mẫu ở trên, ứng dụng sẽ nhận được ý định chia sẻ sau:

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>

Nếu người dùng mở mục tiêu chia sẻ từ lối tắt của trình chạy, ứng dụng sẽ nhận được ý định được tạo khi thêm lối tắt chia sẻ vào ShortcutManagerCompat. Vì đây là một ý định khác, nên Intent.EXTRA_SHORTCUT_ID sẽ không hoạt động và bạn sẽ phải truyền mã nhận dạng theo cách thủ công nếu cần.

Báo cáo việc sử dụng lối tắt cho ứng dụng liên lạc

Nếu đang phát triển một ứng dụng giao tiếp, bạn có thể cải thiện thứ hạng của mình trong Android Sharesheet bằng cách báo cáo mức sử dụng cho cả tin nhắn gửi đi và tin nhắn nhận được. Để làm như vậy, hãy phát hành lại lối tắt cuộc trò chuyện đại diện cho người liên hệ thông qua ShortcutManagerCompat.pushDynamicShortcut.

Việc sử dụng lối tắt và liên kết chức năng có khả năng tương thích ngược với Android 5.0 (API 21).

Báo cáo việc sử dụng lối tắt cho tin nhắn đi

Việc báo cáo mức sử dụng cho tin nhắn do người dùng gửi có chức năng tương tự như việc nhấp vào nút "gửi" sau khi tạo tin nhắn.

Để kích hoạt tính năng báo cáo mức sử dụng, hãy chỉ định các liên kết chức năng trong lối tắt thông qua ShortcutInfoCompat.Builder#addCapabilityBinding với chức năng actions.intent.SEND_MESSAGE.

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

Nếu tin nhắn gửi đi là cho cuộc trò chuyện nhóm, thì bạn cũng phải thêm giá trị tham số Audience vì loại recipient được liên kết với chức năng này.

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

Báo cáo việc sử dụng lối tắt cho tin nhắn đến

Để kích hoạt tính năng báo cáo mức sử dụng khi người dùng nhận được một thông báo như SMS, tin nhắn trò chuyện, email hoặc thông báo, bạn phải chỉ định thêm các liên kết chức năng trong lối tắt thông qua ShortcutInfoCompat.Builder#addCapabilityBinding bằng chức năng actions.intent.RECEIVE_MESSAGE.

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

Nếu thư đến là từ một cuộc trò chuyện nhóm, bạn cũng phải thêm giá trị tham số Audience vì loại sender được liên kết với chức năng này.

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

Sử dụng AndroidX để cung cấp cả Lối tắt chia sẻ và ChooserTargets

Để có thể làm việc với thư viện tương thích AndroidX, tệp kê khai của ứng dụng phải chứa bộ chọn siêu dữ liệu-mục tiêu-dịch vụ và bộ lọc ý định. Xem API Chia sẻ trực tiếp ChooserTargetService hiện tại.

Dịch vụ này đã được khai báo trong thư viện tương thích, vì vậy, người dùng không cần khai báo dịch vụ này trong tệp kê khai của ứng dụng. Tuy nhiên, bạn phải tính đến đường liên kết từ hoạt động chia sẻ đến dịch vụ dưới dạng nhà cung cấp mục tiêu bộ chọn.

Trong ví dụ sau, cách triển khai ChooserTargetService là androidx.core.content.pm.ChooserTargetServiceCompat, đã được xác định trong AndroidX:

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

Câu hỏi thường gặp về lối tắt để chia sẻ

Dữ liệu về việc sử dụng lối tắt được lưu trữ như thế nào và dữ liệu đó có rời khỏi thiết bị không?

Lối tắt được lưu trữ hoàn toàn trên thiết bị trong thư mục dữ liệu hệ thống trong một phân vùng ổ đĩa được mã hoá. Chỉ các dịch vụ hệ thống và chính ứng dụng phát hành lối tắt mới có thể truy cập vào thông tin trong lối tắt, chẳng hạn như biểu tượng, ý định và tên của người dùng và tài nguyên.

Tính năng Chia sẻ trực tiếp đã trải qua những thay đổi gì?

Chúng tôi đã giới thiệu tính năng Chia sẻ trực tiếp trong Android 6.0 (API cấp 23) để cho phép các ứng dụng cung cấp đối tượng ChooserTarget thông qua ChooserTargetService. Kết quả được truy xuất theo yêu cầu, dẫn đến thời gian tải mục tiêu chậm.

Trong Android 10 (API cấp 29), chúng tôi đã thay thế các API Chia sẻ trực tiếp ChooserTargetService bằng API Lối tắt chia sẻ mới. Thay vì truy xuất kết quả phản ứng theo yêu cầu, API Lối tắt chia sẻ cho phép các ứng dụng phát hành trước các mục tiêu Chia sẻ trực tiếp. Điều này giúp đẩy nhanh quá trình truy xuất mục tiêu Chia sẻ trực tiếp khi chuẩn bị ShareSheet. Cơ chế Chia sẻ trực tiếp ChooserTargetService sẽ tiếp tục hoạt động, nhưng hệ thống sẽ xếp hạng các mục tiêu được cung cấp theo cách này thấp hơn bất kỳ mục tiêu nào sử dụng API Lối tắt chia sẻ.

Android 11 (API cấp 30) đã ngừng sử dụng dịch vụ ChooserTargetService và API Lối tắt chia sẻ là cách duy nhất để cung cấp mục tiêu Chia sẻ trực tiếp.

Lối tắt được phát hành cho mục tiêu chia sẻ khác với lối tắt trình chạy như thế nào (cách sử dụng thông thường của lối tắt khi nhấn và giữ biểu tượng ứng dụng trong trình chạy)?

Mọi lối tắt được phát hành cho mục đích "mục tiêu chia sẻ" cũng là một lối tắt trình chạy và sẽ xuất hiện trong trình đơn khi bạn nhấn và giữ biểu tượng ứng dụng. Giới hạn số lượng lối tắt tối đa trên mỗi hoạt động cũng áp dụng cho tổng số lối tắt mà một ứng dụng đang phát hành (kết hợp các mục tiêu chia sẻ và lối tắt trình chạy cũ).

Hướng dẫn về số lượng lối tắt chia sẻ mà người dùng nên xuất bản.

Số lượng lối tắt chia sẻ bị ràng buộc theo giới hạn tương tự của lối tắt động có sẵn thông qua getMaxShortcutCountPerActivity(android.content.Context). Bạn có thể phát hành bất kỳ số lượng nào trong giới hạn đó, nhưng phải lưu ý rằng lối tắt chia sẻ có thể hiển thị trong thao tác nhấn và giữ trình chạy ứng dụng và trong trang chia sẻ. Hầu hết trình chạy ứng dụng khi nhấn và giữ sẽ hiển thị tối đa 4 hoặc 5 lối tắt ở chế độ dọc và 8 lối tắt ở chế độ ngang. Hãy xem phần Câu hỏi thường gặp này để biết thêm thông tin chi tiết và hướng dẫn về cách chia sẻ lối tắt.