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

Hình 1: Hàng Chia sẻ trực tiếp trong Trang chia sẻ nội dung, như minh hoạ trong 1

Sử dụng đích 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 nhanh chóng và dễ dàng hơn. Tính năng Chia sẻ trực tiếp hoạt động bằng cách trình bày danh bạ từ các ứng dụng nhắn tin và mạng xã hội ngay trên Trang chia sẻ nội dung của Android mà người dùng không phải chọn ứng dụng sau đó tìm kiếm người liên hệ.

Lưu ý: Kể từ Android 11 (API cấp 30), bạn chỉ có thể cung cấp các mục tiêu Chia sẻ trực tiếp thông qua API Chia sẻ lối tắt như mô tả ở phần sau của trang này.

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. Để biết hướng dẫn, hãy xem phần Sử dụng AndroidX để cung cấp cả Lối tắt chia sẻ và Chọn mục tiêu 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ẻ nội dung chỉ hiển thị các lối tắt động do API Lối tắt chia sẻ cung cấp. 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 của bạn 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ì mức độ quan trọng càng cao. Nếu bạn đang tạo một ứng dụng liên lạc, đó có thể là các cuộc trò chuyện hàng đầu được sắp xếp theo thời gian gần đây khi chúng xuất hiện trong ứng dụng của bạn. Đừng phát hành lối tắt đã lỗi thời; một cuộc trò chuyện không có hoạt động của người dùng trong 30 ngày qua sẽ bị coi là lỗi thời.

   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 liên lạc, 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 giao tiếp 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 thông báo 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 bằng 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 địa chỉ 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 dịch vụ hệ thống lưu vào bộ nhớ đệm 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 Android hiển thị số lượng 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 các 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 mức sử dụng lối tắt cho thư đi và thư đến bằng cách xuất bản lại lối tắt tương ứng thông qua ShortcutManagerCompat.pushDynamicShortcut. Xem phần Báo cáo mức sử dụng lối tắt cho các ứ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 phù hợp hoặc đã lỗi thời, ví dụ: các mục liên hệ mà người dùng chưa nhắn tin trong 30 ngày qua.
• Đối với ứng dụng SMS, tránh cung cấp lối tắt cho các mã ngắn hoặc cuộc trò chuyện được xác định là có khả năng là tin nhắn rác. Người dùng ít có khả năng chia sẻ với các 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 cụ thể, sau khi một lối tắt động được đẩy và mức sử dụng được báo cáo, đừng thay đổi mã lối tắt. Điều này đả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 mục tiêu Chia sẻ trực tiếp bất kỳ, ứng dụng của bạn phải đưa họ đến giao diện người dùng để họ có thể thực hiện thao tác trực tiếp trên đối tượng mục tiêu. Không cung cấp cho người dùng giao diện người dùng phân định và không đặt chúng 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à tin nhắn được điền sẵn bằng dữ liệu được chia sẻ.

API Chia sẻ lối tắt

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 nhằm 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 lối tắt có thể xử lý ý định hoặc hành động chia sẻ. Xem bài viết 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 để được dùng làm mục tiêu chia sẻ.

setLongLived()

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

Việc tạo lối tắt tồn tại lâu dài có thể cải thiện thứ hạng của lối tắt. Xem phần Nhận thứ hạng tốt nhất để biết thông tin chi tiết.

setShortLabel(), setLongLabel()

Khi xuất bản lối tắt cho một cá nhân, vui lòng cung cấp tên đầy đủ của người đó trong setLongLabel() và mọi tên ngắn (chẳng hạn như biệt hiệu hoặc tên) trong setShortLabel().

Hãy xem ví dụ về cách xuất bản 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 một hình ảnh 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 thay đổi hình dạng. 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ị biểu tượng chỉ có bitmap mà không có nền, điều này làm giảm đáng kể độ tương phản. Để đảm bảo lối tắt hiển thị như dự kiến, 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 thiết lập cho biểu tượng thích ứng. Cách phổ biến nhất để thực hiện việc này là mở rộng tỷ lệ bitmap 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 bao gồm các vùng trong suốt, bạn cần đưa màu nền vào; 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 kín theo một hình dạng cụ thể. Ví dụ: trước Android 10 (API cấp 29), thông thường, bạn cung cấp hình đại diện của người dùng cho ChooserTarget mà tính năng Chia sẻ trực tiếp được che kín trong một vòng tròn. Trang chia sẻ nội dung của Android và các nền tảng hệ thống khác trong Android 10 nay có hình dạng và hình ảnh lối tắt giao diện. Phương thức ưu tiên để cung cấp Lối tắt chia sẻ, thông qua ShortcutManagerCompat, tự động định hình các đối tượng ChooserTarget có khả năng tương thích trực tiếp với nhau cho các vòng kết nối cho bạn.

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

Bạn phải khai báo đích 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 các định nghĩa về mục tiêu chia sẻ bên trong phần tử gốc <shortcuts> của 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 dùng chung, các danh mục trùng khớ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. Những danh mục này chỉ dùng để so khớp các lối tắt đã phát hành của ứng dụng với các định nghĩa mục tiêu chia sẻ tương ứng. Danh mục có thể có bất kỳ giá trị tuỳ ý 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 Android khớp với ví dụ về lượt chia sẻ mục tiêu ở trên, thì ứng dụng sẽ nhận được ý định chia sẻ sau đây:

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ừ các lối tắt của trình chạy, thì ứ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 có sẵn và bạn sẽ phải truyền mã nhận dạng này theo cách thủ công nếu cần.

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

Nếu đang phát triển một ứng dụng liên lạc, thì bạn có thể cải thiện thứ hạng của mình trong Trang chia sẻ nội dung Android bằng cách báo cáo mức sử dụng cho cả tin nhắn đi và tin nhắn đến. Để thực hiện việc này, hãy đăng lại lối tắt trò chuyện đại diện cho người liên hệ thông qua ShortcutManagerCompat.pushDynamicShortcut.

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

Báo cáo việc sử dụng phím tắt cho thư đi

Tính năng báo cáo mức sử dụng 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 bằng 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);

Nếu tin nhắn gửi đi là dành cho một 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 đó.

Kotlin

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)

Java

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 phím 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 tin nhắn, chẳng hạn 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 tính năng actions.intent.RECEIVE_MESSAGE.

Kotlin

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_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.RECEIVE_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

Nếu tin nhắn đế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 tính năng đó.

Kotlin

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)

Java

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à Chọn mục tiêu

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

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ụ trong tệp kê khai của ứng dụng. Tuy nhiên, bạn phải xem xét đường liên kết từ hoạt động chia sẻ đến dịch vụ dưới dạng trình cung cấp đích nhắm mục tiêu của trình 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ề việc chia sẻ lối tắt

Dữ liệu sử dụng lối tắt được lưu trữ như thế nào và chúng 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 đã mã hoá. Chỉ dịch vụ hệ thống và cùng một ứng dụng phát hành lối tắt mới có thể truy cập vào thông tin trong các lối tắt như biểu tượng, ý định, tên người và tài nguyên.

Lịch sử của tính năng Chia sẻ trực tiếp là gì?

Chúng tôi đã ra mắt 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 các đối tượng ChooserTarget thông qua một ChooserTargetService. Kết quả được truy xuất một cách linh hoạ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ế 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ả 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 mục tiêu Chia sẻ trực tiếp. Việc này giúp đẩy nhanh quá trình truy xuất các mục tiêu Chia sẻ trực tiếp khi chuẩn bị Trang chia sẻ nội dung. 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 Share Shortcuts API (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 đích chia sẻ khác với lối tắt của 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 "chia sẻ mục tiêu" cũng là lối tắt của trình chạy và sẽ hiển thị 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 (mục tiêu chia sẻ và lối tắt trình chạy cũ kết hợp với nhau).

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

Số lượng lối tắt chia sẻ bị ràng buộc trong cùng một giới hạn các lối tắt động có sẵn thông qua getMaxShortcutCountPerActivity(android.content.Context). Bạn có thể xuất bản bất kỳ số nào đến giới hạn đó, nhưng phải lưu ý rằng lối tắt chia sẻ có thể hiển thị khi nhấn và giữ trình chạy ứng dụng và trong trang tính chia sẻ. Hầu hết trình chạy ứng dụng khi nhấn và giữ đều 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. 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.