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 nê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 tham chiếu trong cuộc trò chuyện, bạn nê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 lối tắt.

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

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

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

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

Lưu ý quan trọng: Mọi thông tin về lối tắt đều được lưu trữ trong bộ nhớ mã hoá xác thực. Chính vì vậy mà ứng dụng sẽ không thể truy cập vào các lối tắt của người dùng cho đến khi họ mở khoá thiết bị.

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 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ẻ nội dung trên Android.

Hình 1. Trang chia sẻ nội dung trong Android. Mục tiêu chia sẻ trực tiếp xuất hiện ở hàng đầu tiên, tiếp theo là các ứng dụng được xếp hạng rồi đến danh sách Ứng dụng.

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ề giá trị true.
2. Lối tắt động: lối tắt có phương thức ShortcutInfo.isDynamic() trả về giá trị 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. Lối tắt tĩnh được xếp hạng từ đầu tiên đến cuối cùng theo thứ tự xuất hiện trong tệp shortcuts.xml. Đố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 nhật ký trước đây của người dùng, mức độ gần đây, tần suất, gợi ý xếp 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 lối tắt chia sẻ. Mục tiêu chia sẻ được tạo bằng API Lối tắt chia sẻ được ưu tiên hơn mục tiêu chia sẻ do ChooserTargetService tạo ra (đã ngừng hoạt động trong Android 11). Trên 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 trang 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 bất kỳ tổ hợp lối tắt tĩnh và lối tắt động nào được xác định, trình chạy sẽ hiển thị tối đa hai lối tắt tĩnh và hai 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.

Lưu ý: Thứ hạng được điều chỉnh tự động nên từng loại lối tắt (tĩnh hoặc động) sẽ có thứ hạng riêng biệt. Ví dụ như nếu có 3 lối tắt động có thứ hạng 0, 1 và 2, thì việc thêm một lối tắt động khác có thứ hạng là 1 có nghĩa là lối tắt này sẽ được đặt ở vị trí thứ hai. Theo đó, thứ hạng của các lối tắt trước đây được xếp hạng 1 và 2 sẽ chuyển thành 2 và 3.

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 mà 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 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 đang chạy, thì tất cả hoạt động hiện tại trong ứng dụng sẽ bị huỷ bỏ khi chạy một lối tắt tĩnh. Nếu không muốn, bạn có thể sử dụng một hoạt động gián tiếp (trampoline) – một hoạt động ẩn mà 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="" trong hoạt động gián tiếp.

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

Để biết thêm thông tin về 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à được sử dụng lại mà không bị huỷ, cho phép cấu trúc hoạt động đơn của bạn 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 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ụ như 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ó mà có cùng mã nhận dạng. Tuy nhiên, bạn không thể dùng các phương thức đó để 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 Jetpack ShortcutManagerCompat để 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 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 cho 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 lối tắt động và lối tắt được ghim khi nhận được thông báo Intent.ACTION_LOCALE_CHANGED cho biết ngôn ngữ 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 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 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.

Lưu ý: Bạn cần có Thư viện tích hợp lối tắt của Google để cho phép các đường liên kết động mà ứng dụng đẩy vào để chúng đủ điều kiện xuất hiện trên các nền tảng của Google như Trợ lý Google. Khi thêm thư viện này vào ứng dụng, bạn cho phép Trợ lý nhận các đường liên kết động và đề xuất những đường liên kết đó cho người dùng trong ứng dụng Trợ lý.

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á mọi bản sao lối tắt đã ghim. Bạn cũng có thể sử dụng phiên bản nạp chồng của phương thức này. Phương thức này chấp nhận CharSequence dưới dạng thông báo lỗi tuỳ chỉnh. 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.

Lưu ý: Nếu bạn xoá một số lối tắt tĩnh trên ứng dụng khi cập nhật ứng dụng, thì hệ thống sẽ tự động vô hiệu hoá những lối tắt này.

Giới hạn số lần gọi

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 đang chạy ở 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 cùng dòng trong 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 Tùy 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 your-user-id ]

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 vấn đề sau liên quan 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 nên bạn phải đưa logic vào ứng dụng để xuất bản lại khi người dùng mở ứng dụng trên 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. Chính vì vậy mà bạn nên 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.getShortcuts(this, ShortcutManagerCompat.FLAG_MATCH_PINNED).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}
ShortcutsSnippets.kt