Tạo liên kết sâu đến một đích đến

Trên Android, đường liên kết sâu là đường đưa bạn đến thẳng một đích đến cụ thể trong ứng dụng.

Bạn có thể hỗ trợ 2 loại đường liên kết sâu trong ứng dụng: tường minh và ngầm ẩn. Cách bạn triển khai đường liên kết sâu sẽ khác nhau tuỳ thuộc vào loại biểu đồ mà ứng dụng của bạn sử dụng – XML or programmatic.

Tạo đường liên kết sâu tường minh

Đường liên kết sâu tường minh là một thực thể của đường liên kết sâu sử dụng PendingIntent để đưa người dùng đến một vị trí cụ thể trong ứng dụng. Ví dụ: bạn có thể hiển thị đường liên kết sâu tường minh trong thông báo hoặc tiện ích ứng dụng.

Khi người dùng mở ứng dụng thông qua một đường liên kết sâu tường minh, ngăn xếp lui của tác vụ sẽ bị xoá và thay thế bằng đích đến của đường liên kết sâu đó. Khi lồng ghép biểu đồ, đích xuất phát từ mỗi cấp độ lồng ghép – tức là đích xuất phát từ mỗi phần tử <navigation> trong hệ phân cấp – cũng được thêm vào ngăn xếp. Tức là khi nhấn nút Back (Quay lại) từ một đích đến của đường liên kết sâu, người dùng sẽ trở lại ngăn xếp điều hướng mà họ đã vào từ điểm truy cập của ứng dụng.

Biểu đồ có lập trình

Nếu biểu đồ điều hướng được xác định theo phương thức lập trình (như thường thấy trong Navigation Compose hoặc Kotlin DSL), bạn nên dùng TaskStackBuilder để tạo PendingIntent đường liên kết sâu.

val id = "exampleId"
val context = LocalContext.current
val deepLinkIntent = Intent(
    Intent.ACTION_VIEW,
    "https://www.example.com/profile/$id".toUri(),
    context,
    MyActivity::class.java
)

val pendingIntent: PendingIntent? = TaskStackBuilder.create(context).run {
    addNextIntentWithParentStack(deepLinkIntent)
    getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT)
}

Biểu đồ XML

Bạn có thể sử dụng lớp NavDeepLinkBuilder để tạo PendingIntent, như minh hoạ trong ví dụ bên dưới. Lưu ý nếu ngữ cảnh được cung cấp không phải là Activity, hàm tạo sẽ sử dụng PackageManager.getLaunchIntentForPackage() làm hoạt động mặc định để khởi chạy nếu có.

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .createPendingIntent();

Theo mặc định, NavDeepLinkBuilder sẽ chạy đường liên kết sâu tường minh đến lần chạy mặc định Activity được khai báo trong tệp kê khai của ứng dụng. Nếu NavHost nằm trong tác vụ khác, bạn phải chỉ định tên thành phần khi tạo trình tạo đường liên kết sâu:

Kotlin

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(DestinationActivity::class.java)
    .createPendingIntent()

Java

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(DestinationActivity.class)
        .createPendingIntent();

Nếu có ComponentName, bạn có thể chuyển trực tiếp đến trình tạo:

Kotlin

val componentName = ...

val pendingIntent = NavDeepLinkBuilder(context)
    .setGraph(R.navigation.nav_graph)
    .setDestination(R.id.android)
    .setArguments(args)
    .setComponentName(componentName)
    .createPendingIntent()

Java

ComponentName componentName = ...;

PendingIntent pendingIntent = new NavDeepLinkBuilder(context)
        .setGraph(R.navigation.nav_graph)
        .setDestination(R.id.android)
        .setArguments(args)
        .setComponentName(componentName)
        .createPendingIntent();

Nếu đã có sẵn NavController, bạn cũng có thể tạo một đường liên kết sâu bằng cách sử dụng NavController.createDeepLink().

Tạo đường liên kết sâu ngầm ẩn

Đường liên kết sâu ngầm ẩn dùng để chỉ một đích đến cụ thể trong ứng dụng. Khi đường liên kết sâu được gọi (ví dụ: khi người dùng nhấp vào một đường liên kết), Android có thể mở ứng dụng tại đích đến tương ứng.

Đường liên kết sâu có thể được so khớp theo URI, hành động theo ý định và loại MIME. Bạn có thể chỉ định nhiều kiểu khớp cho một đường liên kết sâu, nhưng lưu ý việc so khớp URI sẽ được ưu tiên trước tiên, sau đó là thao tác, rồi đến loại MIME.

Biểu đồ có lập trình

Nếu xác định biểu đồ điều hướng theo phương thức lập trình (bằng Navigation Compose hoặc Kotlin DSL), bạn sẽ xác định đường liên kết sâu trong mã.

Soạn thư

Trong thành phần Điều hướng trong Compose, bạn có thể xác định đường liên kết sâu trong trình tạo đích đến composable() bằng cách sử dụng tham số deepLinks. Thành phần này chấp nhận một danh sách các đối tượng NavDeepLink mà bạn có thể tạo bằng hàm navDeepLink():

@Serializable
data class Profile(val id: String)

val uri = "https://www.example.com"

composable<Profile>(
  deepLinks = listOf(
    navDeepLink<Profile>(basePath = "$uri/profile")
  )
) { backStackEntry ->
  val profile: Profile = backStackEntry.toRoute()
  ProfileScreen(id = profile.id)
}

Kotlin DSL

Khi sử dụng Kotlin DSL, bạn có thể xác định các đường liên kết sâu bằng hàm tạo deepLink() trong khối đích:

@Serializable
data class Profile(val id: String)

val uri = "https://www.example.com"

fragment<ProfileFragment, Profile> {
    deepLink<Profile>(basePath = "$uri/profile")
}

Thêm bộ lọc ý định cho biểu đồ có lập trình

Vì biểu đồ điều hướng có lập trình được tạo trong thời gian chạy, nên thành phần Điều hướng không thể tự động tạo các phần tử <intent-filter> phù hợp trong AndroidManifest.xml. Thay vào đó, bạn phải tự thêm các phần tử <intent-filter> thích hợp.

Để bật đường liên kết sâu trong các ví dụ trước, hãy thêm nội dung sau vào bên trong phần tử <activity> tương ứng trong tệp kê khai:

<activity …>
  <intent-filter>
    ...
    <data android:scheme="https" android:host="www.example.com" />
  </intent-filter>
</activity>

Biểu đồ XML

Để tạo một đường liên kết sâu ngầm ẩn trong biểu đồ dựa trên XML, bạn có thể xác định phần tử <deepLink> ngay trong XML hoặc dùng Trình chỉnh sửa điều hướng.

Dưới đây là một ví dụ về đường liên kết sâu chứa URI, thao tác và loại MIME:

<fragment android:id="@+id/a"
          android:name="com.example.myapplication.FragmentA"
          tools:layout="@layout/a">
        <deepLink app:uri="www.example.com"
                app:action="android.intent.action.MY_ACTION"
                app:mimeType="type/subtype"/>
</fragment>

Bạn cũng có thể sử dụng Trình chỉnh sửa điều hướng để tạo đường liên kết sâu ngầm ẩn đến một đích đến như sau:

  1. Trong thẻ Thiết kế của Trình chỉnh sửa điều hướng, hãy chọn đích đến cho đường liên kết sâu.
  2. Nhấp vào dấu + ở mục Đường liên kết sâu trong bảng Thuộc tính.

  3. Trong hộp thoại Thêm đường liên kết sâu xuất hiện, hãy nhập thông tin cho đường liên kết sâu.

    Xin lưu ý những điều sau:

    • Các URI không có lược đồ được giả định là http hoặc https. Ví dụ: www.google.com khớp với cả http://www.google.com và https://www.google.com.
    • Trình giữ chỗ tham số ở dạng {placeholder_name} khớp với một hoặc nhiều ký tự. Ví dụ: http://www.example.com/users/{id} khớp với: http://www.example.com/users/4. Thành phần Điều hướng cố gắng phân tích giá trị trình giữ chỗ thành các loại thích hợp bằng cách so khớp tên của trình giữ chỗ với đối số đã được xác định cho đích đến của đường liên kết sâu. Nếu không có đối số nào có cùng tên được xác định, hệ thống sẽ sử dụng loại String mặc định cho giá trị đối số. Bạn có thể dùng ký tự đại diện .* để khớp với tối thiểu 0 ký tự.
    • Bạn có thể sử dụng trình giữ chỗ tham số truy vấn thay vì hoặc kết hợp với các tham số đường dẫn. Ví dụ: http://www.example.com/users/{id}?myarg={myarg} khớp với: http://www.example.com/users/4?myarg=28.
    • Trình giữ chỗ thông số truy vấn không bắt buộc phải có cho các biến được xác định bằng giá trị mặc định hoặc giá trị rỗng. Ví dụ: http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2} khớp với http://www.example.com/users/4?arg2=28 hoặc http://www.example.com/users/4?arg1=7. Điều này không đúng với các tham số đường dẫn. Ví dụ: http://www.example.com/users?arg1=7&arg2=28 không khớp với mẫu trên vì tham số đường dẫn bắt buộc không được cung cấp.
    • Các tham số truy vấn không liên quan sẽ không ảnh hưởng đến việc so khớp URI liên kết sâu. Ví dụ: http://www.example.com/users/{id} phù hợp với http://www.example.com/users/4?extraneousParam=7, mặc dù extraneousParam không được xác định trong mẫu URI.

  4. (không bắt buộc) Đánh dấu vào Tự động xác minh để yêu cầu Google xác minh rằng bạn là chủ sở hữu của URI đó. Để biết thêm thông tin, hãy xem bài viết Xác minh đường liên kết ứng dụng Android.

  5. Nhấp vào Thêm. Biểu tượng đường liên kết xuất hiện phía trên đích đến đã chọn cho biết đích đến này có đường liên kết sâu.

  6. Nhấp vào thẻ Mã để chuyển sang chế độ xem XML. Đã thêm một phần tử <deepLink> lồng ghép vào đích đến:

    <deepLink app:uri="https://www.google.com" />

Để bật tính năng liên kết sâu ngầm định cho các biểu đồ dựa trên XML, bạn cũng phải thêm các tệp vào manifest.xml của ứng dụng. Thêm một phần tử <nav-graph> duy nhất vào một hoạt động trỏ đến một biểu đồ điều hướng hiện có, như minh hoạ trong ví dụ sau:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapplication">

    <application ... >

        <activity name=".MainActivity" ...>
            ...

            <nav-graph android:value="@navigation/nav_graph" />

            ...

        </activity>
    </application>
</manifest>

Khi tạo dự án, thành phần Điều hướng sẽ thay thế thành phần <nav-graph> bằng các thành phần <intent-filter> đã tạo để khớp với mọi đường liên kết sâu trong biểu đồ điều hướng.

Đường liên kết sâu ngầm ẩn và ngăn xếp lui

Khi kích hoạt một đường liên kết sâu ngầm ẩn, trạng thái của ngăn xếp lui phụ thuộc vào việc Intent được ra mắt cùng với cờ Intent.FLAG_ACTIVITY_NEW_TASK:

  • Nếu bị gắn cờ, ngăn xếp lui tác vụ sẽ bị xoá và thay thế bằng đích đến của đường liên kết sâu. Như với đường liên kết sâu rõ ràng, khi lồng ghép biểu đồ, đích xuất phát từ mỗi cấp độ lồng ghép – tức là đích xuất phát từ mỗi cấp phần tử <navigation> trong hệ phân cấp cũng được thêm vào ngăn xếp. Tức là khi nhấn nút Back (Quay lại) từ một đích đến của đường liên kết sâu, người dùng sẽ trở lại ngăn xếp điều hướng mà họ đã vào từ điểm truy cập của ứng dụng.
  • Nếu cờ này không được đặt, bạn sẽ vẫn ở trên ngăn xếp tác vụ của ứng dụng trước, nơi đường liên kết sâu ngầm ẩn đã được kích hoạt. Trong trường hợp đó, nút Back (Quay lại) sẽ đưa bạn trở lại ứng dụng trước, còn nút Up (Mũi tên lên) bắt đầu tác vụ của ứng dụng trên đích đến phân cấp gốc trong biểu đồ điều hướng.

Xử lý đường liên kết sâu

Luôn dùng launchMode mặc định trong standard khi sử dụng tính năng Điều hướng. Khi sử dụng chế độ chạy standard, tính năng Điều hướng tự động xử lý các đường liên kết sâu, bằng cách gọi handleDeepLink() để xử lý mọi đường liên kết sâu rõ ràng hoặc tiềm ẩn trong Intent. Tuy nhiên, việc này không tự động xảy ra nếu Activity được sử dụng lại khi sử dụng launchMode thay thế, chẳng hạn như singleTop. Trong trường hợp đó, bạn cần gọi handleDeepLink() theo cách thủ công trong onNewIntent(), như minh hoạ trong ví dụ bên dưới:

Kotlin

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    navController.handleDeepLink(intent)
}

Java

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    navController.handleDeepLink(intent);
}