Quản lý lối tắt

Sau khi tạo lối tắt, bạn có thể cần phải quản lý các lối tắt đó trong suốt thời gian hoạt động của ứng dụng. Ví dụ: bạn có thể muốn tối ưu hoá ứng dụng bằng cách xác định tần suất người dùng hoàn tất các thao tác cụ thể thông qua lối tắt. Trong trường hợp khác, bạn có thể quyết định vô hiệu hoá một lối tắt được ghim để ngăn ứng dụng của bạn thực hiện các thao tác lỗi thời hoặc bị thiếu. Đối với các lối tắt được đề cập trong cuộc trò chuyện, bạn có thể muốn theo dõi mức sử dụng để cung cấp tín hiệu giúp cải thiện thứ hạng của lối tắt.

Trang này mô tả những cách này và một số cách phổ biến khác để quản lý lối tắt.

Hành vi của lối tắt

Các phần sau đây chứa thông tin chung về hành vi của lối tắt, bao gồm khả năng hiển thị, thứ tự hiển thị và thứ hạng.

Chế độ hiển thị lối tắt

Lối tắt tĩnh và lối tắt động sẽ xuất hiện trong một trình chạy hoặc trợ lý được hỗ trợ khi người dùng thực hiện một cử chỉ hoặc lệnh thoại cụ thể. Trên các trình chạy được hỗ trợ, cử chỉ là thao tác chạm và giữ biểu tượng trình chạy của ứng dụng, nhưng cử chỉ có thể khác đối với các ứng dụng trình chạy khác. Đối với Trợ lý Google, các lối tắt có thể được hiển thị trong Trợ lý hoặc chạy thông qua lệnh thoại của người dùng.

Lớp LauncherApps cung cấp API để các ứng dụng trình chạy truy cập vào lối tắt.

Do lối tắt được ghim xuất hiện trong chính trình chạy, nên các lối tắt đó sẽ luôn hiển thị. Lối tắt được ghim chỉ bị xoá khỏi trình chạy trong các trường hợp sau:

• Người dùng xoá lối tắt.
• Đã gỡ cài đặt ứng dụng liên kết với lối tắt.
• Người dùng xoá dữ liệu của một ứng dụng bằng cách vào Cài đặt > Ứng dụng và thông báo, chọn ứng dụng rồi nhấn vào Bộ nhớ > Xoá bộ nhớ.

Mục tiêu chia sẻ là một nhóm nhỏ các lối tắt động xuất hiện trong hàng chia sẻ trực tiếp của trang chia sẻ Android.

Thứ tự hiển thị lối tắt

Khi trình chạy hiển thị lối tắt của ứng dụng, các lối tắt đó phải xuất hiện theo thứ tự sau:

1. Lối tắt tĩnh: lối tắt có phương thức isDeclaredInManifest() trả về true.
2. Lối tắt động: lối tắt có phương thức ShortcutInfo.isDynamic() trả về true.

Trong mỗi loại lối tắt (tĩnh và động), các lối tắt sẽ được sắp xếp theo thứ tự tăng dần thứ hạng theo ShortcutInfo.getRank. Trợ lý Google cũng xem xét thứ hạng lối tắt khi xác định các lối tắt theo ngữ cảnh để hiển thị cho người dùng.

Thứ hạng là số nguyên không âm, liên tiếp nhau. Các lối tắt tĩnh được xếp hạng từ đầu đến cuối theo thứ tự xuất hiện trong tệp shortcuts.xml của bạn. Đối với lối tắt động, bạn có thể cập nhật thứ hạng của các lối tắt hiện có khi gọi updateShortcuts(Context, List), addDynamicShortcuts(Context, List), pushDynamicShortcut(Context, ShortcutInfoCompat) hoặc setDynamicShortcuts(Context, List).

Thứ tự của các mục tiêu chia sẻ dựa trên nhiều yếu tố, bao gồm cả nhật ký hoạt động trước đây của người dùng, số ngày gần đây, tần suất, gợi ý về thứ hạng, mức sử dụng ứng dụng và mức độ ưu tiên được đặt cho cuộc trò chuyện liên kết với một lối tắt để chia sẻ. Các mục tiêu chia sẻ được tạo bằng Sharing Shortcuts API sẽ được ưu tiên hơn các mục tiêu chia sẻ do ChooserTargetService tạo ra (không còn được dùng trong Android 11). Trong Android 12 trở lên, các mục tiêu chia sẻ do ChooserTargetService không dùng nữa tạo ra sẽ không còn xuất hiện trong bảng chia sẻ.

Hầu hết trình chạy đều hiển thị tối đa 4 lối tắt. Đối với mọi tổ hợp lối tắt tĩnh và lối tắt động được xác định, trình chạy sẽ hiển thị tối đa 2 lối tắt tĩnh và 2 lối tắt động. Ví dụ: nếu bạn xác định 4 lối tắt tĩnh và tạo 3 lối tắt động theo phương thức lập trình, thì trình chạy sẽ hiển thị 2 lối tắt tĩnh đầu tiên và 2 lối tắt động có thứ hạng cao nhất.

Quản lý nhiều ý định và hoạt động

Nếu muốn ứng dụng thực hiện nhiều thao tác khi người dùng kích hoạt một lối tắt, bạn có thể định cấu hình ứng dụng đó để kích hoạt các hoạt động liên tiếp. Tuỳ thuộc vào loại lối tắt, bạn có thể thực hiện việc này bằng cách gán nhiều ý định, bắt đầu một Hoạt động từ một hoạt động khác hoặc đặt cờ cho ý định.

Bắt đầu một hoạt động từ một hoạt động khác

Lối tắt tĩnh không thể có cờ ý định tuỳ chỉnh. Ý định đầu tiên của một lối tắt tĩnh luôn đặt Intent.FLAG_ACTIVITY_NEW_TASK và Intent.FLAG_ACTIVITY_CLEAR_TASK. Điều này có nghĩa là khi ứng dụng của bạn đang chạy, tất cả các hoạt động hiện có trong ứng dụng sẽ bị huỷ bỏ khi một lối tắt tĩnh được chạy. Nếu không muốn hành vi này, bạn có thể sử dụng một hoạt động gián tiếp (trampoline) (một hoạt động ẩn bắt đầu một hoạt động khác) bằng cách gọi finish bên trong một khối khởi chạy hoặc onCreate trước khi nội dung Compose được đặt:

1. Trong AndroidManifest.xml file, hãy thêm thuộc tính được gán cho android:taskAffinity="" vào hoạt động gián tiếp.

2. Trong tệp tài nguyên lối tắt, hãy tham chiếu đến hoạt động gián tiếp trong ý định trong lối tắt tĩnh.

Để biết thêm thông tin về các hoạt động gián tiếp, hãy xem phần Bắt đầu một hoạt động từ một hoạt động khác.

Đặt cờ cho ý định

Bạn có thể xuất bản lối tắt động với bất kỳ bộ cờ nào trong số các cờ Intent. Tốt nhất là bạn nên chỉ định tổ hợp Intent.FLAG_ACTIVITY_SINGLE_TOP và Intent.FLAG_ACTIVITY_CLEAR_TOP trong ý định của lối tắt. Điều này đảm bảo rằng nếu ComponentActivity của bạn đã hoạt động, thì nó sẽ được đưa lên nền trước và dùng lại mà không bị huỷ, cho phép cấu trúc một hoạt động xử lý sự kiện lối tắt một cách linh hoạt thông qua onNewIntent().

Để tìm hiểu thêm về tác vụ và cờ ý định, hãy xem phần Tác vụ và ngăn xếp lui.

Cập nhật lối tắt

Biểu tượng trình chạy của mỗi ứng dụng có thể chứa tối đa một số lượng lối tắt tĩnh và động kết hợp bằng với giá trị mà getMaxShortcutCountPerActivity trả về. Không có giới hạn về số lượng lối tắt được ghim mà một ứng dụng có thể tạo.

Khi lối tắt động được ghim, ngay cả khi nhà xuất bản xoá lối tắt động đó, thì lối tắt được ghim vẫn hiển thị và có thể khởi chạy. Điều này cho phép một ứng dụng có nhiều số lượng getMaxShortcutCountPerActivity lối tắt.

Hãy xem ví dụ sau, giả sử giá trị mà getMaxShortcutCountPerActivity trả về là 4:

1. Một ứng dụng trò chuyện xuất bản 4 lối tắt động, tương ứng với 4 cuộc trò chuyện gần đây nhất: c1, c2, c3 và c4.
2. Người dùng ghim tất cả 4 lối tắt.
3. Sau đó, người dùng bắt đầu thêm 3 cuộc trò chuyện khác: c5, c6 và c7. Ứng dụng của nhà xuất bản sẽ xuất bản lại các lối tắt động. Danh sách lối tắt động mới là: c4, c5, c6 và c7.

Ứng dụng phải xoá c1, c2 và c3 vì ứng dụng chỉ được phép hiển thị tối đa 4 lối tắt động. Tuy nhiên, c1, c2 và c3 vẫn được ghim và người dùng có thể truy cập và chạy.

Sau đó, người dùng có thể truy cập vào tổng cộng 7 lối tắt liên kết đến các hoạt động trong ứng dụng của nhà xuất bản. Nguyên nhân là do tổng số này bao gồm cả số lượng lối tắt tối đa và 3 lối tắt được ghim.

1. Ứng dụng có thể dùng updateShortcuts(Context, List) để cập nhật bất kỳ lối tắt nào trong số 7 lối tắt hiện có. Ví dụ: bạn có thể cập nhật nhóm lối tắt này khi biểu tượng của các ứng dụng trò chuyện ngang hàng thay đổi.
2. Bạn có thể sử dụng phương thức addDynamicShortcuts(Context, List) và setDynamicShortcuts(Context, List) để cập nhật các lối tắt hiện có có cùng mã nhận dạng. Tuy nhiên, bạn không thể dùng các phương thức này để cập nhật lối tắt không động, được ghim vì hai phương thức này chuyển đổi danh sách các lối tắt thành lối tắt động.

Không có giới hạn về số lượng lối tắt có thể đẩy để hiển thị trên các ứng dụng trợ lý như Trợ lý Google. Sử dụng phương thức pushDynamicShortcut của thư viện ShortcutManagerCompat Jetpack để tạo và cập nhật lối tắt để sử dụng trên các ứng dụng trợ lý. Ngoài ra, hãy thêm thư viện Tích hợp lối tắt của Google vào ứng dụng để các đường liên kết động đủ điều kiện xuất hiện trên Trợ lý Google.

Để tìm hiểu thêm về nguyên tắc lối tắt ứng dụng, bao gồm cả cách cập nhật lối tắt, hãy xem phần Các phương pháp hay nhất cho lối tắt.

Xử lý các thay đổi về ngôn ngữ của hệ thống

Các ứng dụng phải cập nhật các lối tắt động và được ghim khi nhận được thông báo Intent.ACTION_LOCALE_CHANGED cho biết ngôn ngữ (locale) của hệ thống đã thay đổi.

Theo dõi việc sử dụng lối tắt

Để xác định những tình huống mà lối tắt tĩnh và động sẽ xuất hiện, trình chạy sẽ kiểm tra nhật ký kích hoạt của các lối tắt. Đối với các lối tắt tĩnh, bạn có thể theo dõi thời điểm người dùng hoàn tất các thao tác cụ thể trong ứng dụng bằng cách gọi phương thức reportShortcutUsed và truyền vào mã nhận dạng của một lối tắt khi một trong hai sự kiện sau xảy ra:

• Người dùng chọn lối tắt có ID được cung cấp.
• Trong ứng dụng, người dùng hoàn tất thủ công thao tác ứng với cùng một lối tắt.

Ứng dụng theo dõi việc sử dụng lối tắt động bằng cách gọi phương thức pushDynamicShortcut và truyền vào mã nhận dạng của lối tắt khi sự kiện liên quan xảy ra. Việc đẩy lối tắt động bằng phương thức này cho phép các ứng dụng trợ lý như Trợ lý Google đề xuất lối tắt liên quan cho người dùng. Vì phương thức pushDynamicShortcut báo cáo việc sử dụng khi được gọi, nên bạn không nên gọi phương thức reportShortcutUsed cho cùng những lối tắt đó.

Đối với các lối tắt liên quan đến cuộc trò chuyện, bạn cần theo dõi mức sử dụng cho tin nhắn đi và tin nhắn đến. Để biết thông tin chi tiết, hãy xem các phương pháp hay nhất cho người dùng và cuộc trò chuyện.

Vô hiệu hoá lối tắt

Do ứng dụng và người dùng ứng dụng có thể ghim các lối tắt trên trình chạy của thiết bị, nên các lối tắt được ghim này có thể điều hướng người dùng đến các thao tác đã lỗi thời hoặc không còn tồn tại trong ứng dụng. Để xử lý trường hợp này, bạn có thể vô hiệu hoá các lối tắt mà bạn không muốn người dùng chọn bằng cách gọi disableShortcuts. Phương thức này sẽ xoá các lối tắt được chỉ định khỏi danh sách lối tắt tĩnh và động, đồng thời vô hiệu hoá các bản sao lối tắt đã ghim. Bạn cũng có thể sử dụng một phiên bản nạp chồng của phương thức này. Phiên bản này chấp nhận CharSequence dưới dạng thông báo lỗi tuỳ chỉnh. Sau đó, thông báo lỗi sẽ xuất hiện khi người dùng cố gắng chạy bất kỳ lối tắt bị vô hiệu hoá nào.

Giới hạn tốc độ

Khi sử dụng các phương thức setDynamicShortcuts, addDynamicShortcuts hoặc updateShortcuts, bạn chỉ có thể gọi các phương thức này một số lần nhất định trong ứng dụng nền – một ứng dụng không có hoạt động hoặc dịch vụ nào ở nền trước. Giới hạn về số lần mà bạn có thể gọi các phương thức này được gọi là giới hạn số lần gọi. Tính năng này ngăn ShortcutManagerCompat sử dụng quá nhiều tài nguyên thiết bị.

Khi đang áp dụng giới hạn số lần gọi, isRateLimitingActive sẽ trả về giá trị đúng (true). Tuy nhiên, giới hạn số lần gọi sẽ được đặt lại trong một số sự kiện nhất định, vì vậy, ngay cả các ứng dụng nền cũng có thể gọi các phương thức ShortcutManager cho đến khi đạt giới hạn số lần gọi. Những sự kiện này bao gồm:

• Ứng dụng chạy ở nền trước.
• Ngôn ngữ bản địa hoá của hệ thống thay đổi.
• Người dùng thực hiện thao tác trả lời trực tiếp trên một thông báo.

Nếu gặp phải tình trạng giới hạn số lần gọi trong quá trình phát triển hoặc kiểm thử, bạn có thể vào Tuỳ chọn cho nhà phát triển > Đặt lại giới hạn tốc độ trong ShortcutManager trong phần cài đặt của thiết bị hoặc bạn có thể nhập lệnh sau trong adb:

$ adb shell cmd shortcut reset-throttling [ --user <var>your-user-id</var> ]

Sao lưu và khôi phục

Bạn có thể cho phép người dùng thực hiện các thao tác sao lưu và khôi phục trong ứng dụng khi thay đổi thiết bị bằng cách đưa vào thuộc tính được gán android:allowBackup="true" trong tệp kê khai của ứng dụng. Nếu bạn hỗ trợ tính năng sao lưu và khôi phục, hãy lưu ý những điểm sau về lối tắt ứng dụng:

• Các lối tắt tĩnh được tự động xuất bản lại, nhưng chỉ sau khi người dùng cài đặt lại ứng dụng trên thiết bị mới.
• Lối tắt động không được sao lưu, vì vậy, hãy đưa logic vào ứng dụng để xuất bản lại các lối tắt đó khi người dùng mở ứng dụng trên một thiết bị mới.
• Các lối tắt được ghim sẽ tự động khôi phục trên trình chạy của thiết bị, nhưng hệ thống không sao lưu các biểu tượng liên kết với lối tắt được ghim. Do đó, hãy lưu hình ảnh của lối tắt được ghim trong ứng dụng để có thể nhanh chóng khôi phục trên các thiết bị mới.

Đoạn mã sau đây hướng dẫn cách tốt nhất để khôi phục lối tắt động của ứng dụng và cách kiểm tra xem lối tắt được ghim của ứng dụng có được lưu giữ hay không:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts(this).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}