Để quảng bá các tính năng của ứng dụng đồng thời giúp người dùng dễ sử dụng hơn, bạn có thể đề xuất khẩu lệnh nhanh của Trợ lý cho người dùng. Khẩu lệnh nhanh cho Trợ lý là những cụm từ súc tích mà người dùng có thể nói để kích hoạt chức năng trong ứng dụng của bạn.
Mặc dù người dùng có thể tự tạo khẩu lệnh nhanh cho Trợ lý, nhưng SDK quảng cáo trong ứng dụng cho phép bạn chủ động đề xuất và triển khai khẩu lệnh nhanh cho Trợ lý. Bằng cách đề xuất khẩu lệnh nhanh, bạn có thể cung cấp cho người dùng đường dẫn rõ ràng, đơn giản để quay lại các hoạt động họ yêu thích trong ứng dụng mà không cần phải thiết lập khẩu lệnh nhanh.
Ví dụ: nếu người dùng tìm kiếm nội dung "heavy metal workout" ("nhạc heavy metal để tập thể dục") trong một ứng dụng âm nhạc, bạn có thể đề xuất một khẩu lệnh nhanh cho Trợ lý trực tiếp đến các kết quả tìm kiếm đó trong tương lai. Khi bạn đề xuất khẩu lệnh nhanh, một lời nhắc sẽ xuất hiện trong ứng dụng và hiển thị cụm từ đề xuất cho khẩu lệnh nhanh đó để hỏi liệu người dùng có muốn tạo khẩu lệnh nhanh không.
Trong ví dụ này, bạn đề xuất cụm từ "start my heavy metal workout" (mở nhạc heavy metal để tập thể dục). Người dùng chấp nhận đề xuất và sau đó có thể kích hoạt khẩu lệnh nhanh bằng cách nói "Hey Google, start my heavy metal workout" (Ok Google, mở nhạc heavy metal để tập thể dục).
Để biết thêm thông tin về những cách thu hút người dùng mới cho ứng dụng của bạn, hãy xem bài viết Phát triển ứng dụng bằng hành động trong ứng dụng.
SDK quảng cáo trong ứng dụng cung cấp các phương thức sau:
lookupShortcut: sẽ kiểm tra xem khẩu lệnh nhanh mà bạn muốn đề xuất có tồn tại hay không. Phương thức này cũng sẽ kiểm tra và phát hiện mọi vấn đề khiến bạn không tạo được khẩu lệnh nhanh. Nếu không tạo được khẩu lệnh nhanh,lookupShortcutsẽ cho biết lý do.createShortcutSuggestionIntent: trả về một ý định. Bạn có thể sử dụng ý định này để nhắc người dùng tạo khẩu lệnh nhanh đề xuất.createShortcutSettingsIntent: trả về một ý định. Bạn có thể sử dụng ý định này để di chuyển người dùng đến phần cài đặt khẩu lệnh nhanh cho Trợ lý trên ứng dụng của bạn.
Điều kiện tiên quyết và giới hạn
Phần này mô tả các yêu cầu và điều kiện tiên quyết để sử dụng đề xuất cũng như các giới hạn mà bạn có thể gặp phải.
Các điều kiện tiên quyết về phát triển
Để sử dụng đề xuất, môi trường phát triển của bạn phải đáp ứng các điều kiện tiên quyết sau.
Mở rộng ứng dụng Android để sử dụng Hành động trong ứng dụng.
Đưa
com.google.android.googlequicksearchboxvào thẻ<queries>trong tệp kê khai. Ví dụ:<manifest ...> <queries> <package android:name="com.google.android.googlequicksearchbox" /> </queries> ... </manifest>Sử dụng Android App Bundle để phát hành ứng dụng.
Yêu cầu về thiết bị
Để kiểm thử đề xuất trên thiết bị, thiết bị của bạn phải được cài đặt:
Phiên bản mới nhất của ứng dụng Google
Android 6.0 (API cấp 23) trở lên
Các hạn chế đã biết
Tính năng Đề xuất chỉ được hỗ trợ bằng tiếng Anh. Để người dùng nhìn thấy nội dung đề xuất, họ phải thiết lập ngôn ngữ của Trợ lý trên thiết bị thành tiếng Anh.
Triển khai đề xuất
Để triển khai các đề xuất, bạn cần cập nhật tệp build.gradle, thiết lập ứng dụng cho đề xuất rồi xác định các đề xuất mà bạn muốn cung cấp cho người dùng.
Thêm phần phụ thuộc thư viện vào tệp
build.gradle.dependencies { ... implementation "com.google.assistant.appactions:suggestions:1.0.0" }Xác định thực thể của
AssistantShortcutSuggestionsClient.Kotlin
val shortcutsClient = AssistantShortcutSuggestionsClient.builder() .setContext(CONTEXT: Context) .setVerifyIntents(VERIFY_INTENTS: Boolean) .setCustomExecutor(CUSTOM_EXECUTOR: Object) .build()Java
AssistantShortcutSuggestionsClient shortcutsClient = AssistantShortcutSuggestionsClient.builder() .setContext(CONTEXT: Context) .setVerifyIntents(VERIFY_INTENTS: Boolean) .setCustomExecutor(CUSTOM_EXECUTOR: Object) .build();Trong ví dụ này:
CONTEXT(bắt buộc) là ngữ cảnh ứng dụng.VERIFY_INTENTS(bắt buộc) xác định xem có xác minh mọi ý định đã tạo khi đề xuất khẩu lệnh nhanh cho người dùng hay không. Khi giá trị làtrue, các ý định doAssistantShortcutSuggestionsClienttạo sẽ được xác minh. Nếu một ý định được cho là không hợp lệ, hệ thống sẽ trả về một trường hợp ngoại lệ.CUSTOM_EXECUTOR(không bắt buộc) là trình thực thi tùy chỉnh để chạy các tác vụ không đồng bộ. Nếu không có trình thực thi này, SDK sẽ sử dụng trình thực thi luồng đơn cho tác vụ.
Sử dụng phương thức
lookupShortcutđể xác định xem khẩu lệnh nhanh mà bạn muốn đề xuất có hợp lệ không, cũng như xác định xem khẩu lệnh nhanh đó đã tồn tại hay chưa.Tạo ý định cho khẩu lệnh nhanh trong ứng dụng (app shortcut intent). Ý định cho khẩu lệnh nhanh (shortcut intent) đại diện cho khẩu lệnh nhanh mà bạn muốn đề xuất cho người dùng. Trong ví dụ sau, một ý định được tạo cho một khẩu lệnh nhanh để đặt đồ uống.
Kotlin
val menuItem = mapOf( "@type" to "MenuItem", "@context" to "http://schema.googleapis.com", "name" to "Fresh Lemon Honey Jasmine Green Tea", ) val appShortcutIntent = AppShortcutIntent.builder() .setIntentName("actions.intent.ORDER_MENU_ITEM") .setPackageName("my.app.package") .setIntentParamName("menuItem") .setIntentParamValue(menuItem) .build()Java
Map
Truyền ý định trong lối tắt sang phương thức
lookupShortcut.Kotlin
val result = shortcutsClient.lookupShortcut(appShortcutIntent).await() if (!result.isShortcutPresent) { // App can suggest creating a shortcut } else { // App can remind the user that they have a shortcut for this app action }Java
shortcutsClient.lookupShortcut(appShortcutIntent) .addOnSuccessListener(shortcutLookupResult -> { if (!shortcutLookupResult.isShortcutPresent()) { // App can suggest creating a shortcut } else { // App can remind the user that they have a shortcut for this app action } }) .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));
Tạo đề xuất bằng cách dùng ý định cho khẩu lệnh nhanh (shortcut intent). Bạn có thể tạo đề xuất bằng 2 phương thức sau:
createShortcutSuggestionIntent: trả về một ý định trên Android. Bạn sử dụng ý định này để bắt đầu hoạt động đề xuất khẩu lệnh nhanh trong bối cảnh ứng dụng của mình.Kotlin
val orderShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand(PHRASE: String) .build() val intent = shortcutsClient.createShortcutSuggestionIntent(orderShortcut).await() application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))Java
AppShortcutSuggestion orderShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand(PHRASE: String) .build(); shortcutsClient.createShortcutSuggestionIntent(orderShortcut) .addOnSuccessListener(intent -> getApplication().startActivity( intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)); ) .addOnFailureListener(e -> Log.e(TAG, "Failed to get shortcut suggestion intent", e); );Trong ví dụ này, PHRASE là câu nói mà bạn muốn đề xuất cho người dùng dưới dạng một khẩu lệnh nhanh. Chẳng hạn nếu bạn muốn người dùng nói "Hey Google, order my bubble tea" (Ok Google, đặt trà sữa cho tôi) dưới dạng một khẩu lệnh nhanh, hãy thay thế PHRASE bằng
"order my bubble tea".Kotlin
val orderShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand("order my bubble tea") .build()Java
AppShortcutSuggestion orderShortcut = AppShortcutSuggestion.builder() .setAppShortcutIntent(appShortcutIntent) .setCommand("order my bubble tea") .build();createShortcutSettingsIntent: trả về một ý định trên Android nhằm chuyển người dùng đến giao diện cài đặt khẩu lệnh nhanh trong ứng dụng Trợ lý.Kotlin
val intent = shortcutsClient.createShortcutSettingsIntent().await() application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
Java
shortcutsClient.createShortcutSettingsIntent() .addOnSuccessListener(intent -> getApplication().startActivity( intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)); ) .addOnFailureListener(e -> Log.e(TAG, "Failed to get shortcut settings intent", e); );
Gọi
startActivitybằng cách sử dụng ý định trên Android đã trả về ở bước trước đó.
Khắc phục sự cố về đề xuất
Phần này liệt kê các vấn đề và ngoại lệ mà bạn có thể gặp phải khi đề xuất khẩu lệnh nhanh.
"GoogleInstallationUnsupportedException: Cannot bind to service"
Do tính năng lọc chế độ hiển thị gói, ngoại lệ "GoogleInstallationUnsupportedException: Cannot bind to service" ("GoogleInstallationUnsupportedException: Không thể liên kết với dịch vụ") có thể xuất hiện trên Android 11 trở lên. Hãy đảm bảo com.google.android.googlequicksearchbox có trong thẻ <queries> trong tệp kê khai của bạn:
<manifest ...>
<queries>
<package android:name="com.google.android.googlequicksearchbox" />
</queries>
...
</manifest>
"Không xác minh được chữ ký APK"
Lỗi sau đây có thể xảy ra nếu bạn không gửi ứng dụng chính thức của mình dưới dạng một gói ứng dụng:
Failed to verify the APK signature. If this is a development build, please
make sure to update the preview of your app in App Actions Test Tool.
Vui lòng đảm bảo bạn sẽ gửi ứng dụng dưới dạng một Android App Bundle.
"Failed to get user shortcuts"
Thông báo lỗi "Failed to get user shortcuts" (Không tải được khẩu lệnh nhanh cho người dùng) sẽ xuất hiện nếu bạn vừa thêm tài khoản vào thiết bị, và nếu dữ liệu khẩu lệnh nhanh của tài khoản mới đó chưa được lưu vào bộ nhớ đệm trên thiết bị.
Để đồng bộ hoá dữ liệu khẩu lệnh nhanh trên thiết bị, hãy thêm hoặc xoá một khẩu lệnh nhanh cho Trợ lý bằng giao diện của ứng dụng Trợ lý.
Hoạt động tạo khẩu lệnh nhanh đóng ngay lập tức mà không hiển thị nội dung nào
Hoạt động tạo khẩu lệnh nhanh có thể đóng mà không hiển thị nội dung nào nếu bạn không tạo bản xem trước bằng Công cụ kiểm thử hành động trong ứng dụng hoặc nếu bản xem trước đã hết hạn. Hãy cập nhật bản xem trước của bạn rồi thử lại.