יצירת קישור עומק ליעד

ב-Android, קישור עומק הוא קישור שמפנה ישירות ליעד ספציפי באפליקציה.

רכיב הניווט מאפשר ליצור שני סוגים שונים של קישורי עומק: מפורשים ומרומזים.

יצירת קישור עומק מפורש

קישור עומק מפורש הוא מופע יחיד של קישור עומק שמשתמש ב-PendingIntent כדי להעביר משתמשים למיקום ספציפי באפליקציה. לדוגמה, אפשר להציג קישור עומק מפורש כחלק מהתראה או מווידג'ט של אפליקציה.

כשמשתמש פותח את האפליקציה באמצעות קישור עומק מפורש, מקבץ החזרה של המשימה נמחק ומוחלף ביעד של קישור העומק. כשמקפלים גרפים, היעד ההתחלתי מכל רמה של קיפול – כלומר היעד ההתחלתי מכל רכיב <navigation> בהיררכיה – מתווסף גם הוא לסטאק. כלומר, כשמשתמש לוחץ על הלחצן 'הקודם' מיעד של קישור עומק, הוא חוזר אחורה בערימה של הניווט בדיוק כמו שהוא נכנס לאפליקציה מנקודת הכניסה שלה.

תוכלו להשתמש במחלקה NavDeepLinkBuilder כדי ליצור PendingIntent, כמו בדוגמה הבאה. שימו לב שאם ההקשר שסופק הוא לא Activity, ה-constructor משתמש ב-PackageManager.getLaunchIntentForPackage() כפעילות ברירת המחדל להפעלה, אם היא זמינה.

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();

כברירת מחדל, NavDeepLinkBuilder מפעיל את קישור העומק המפורש אל הפעלת ברירת המחדל Activity, שמוצהרת במניפסט של האפליקציה. אם NavHost נמצא בפעילות אחרת, צריך לציין את שם הרכיב שלו כשיוצרים את ה-builder של קישורי העומק:

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();

אם יש לכם ComponentName, תוכלו להעביר אותו ישירות ל-builder:

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();

אם יש לכם NavController קיים, תוכלו ליצור קישור עומק גם באמצעות NavController.createDeepLink().

יצירת קישור עומק מרומז

קישור עומק משתמע מתייחס ליעד ספציפי באפליקציה. כשהקישור העומק מופעל – למשל, כשמשתמש לוחץ על קישור – מערכת Android יכולה לפתוח את האפליקציה שלכם ביעד המתאים.

אפשר להתאים קישורי עומק לפי URI, פעולות של כוונת השימוש וסוגים של MIME. אפשר לציין כמה סוגי התאמה לקישור עומק אחד, אבל חשוב לזכור שהעדיפות הראשונה היא להתאמה של ארגומנטים של URI, ואחריה להתאמה של פעולה ואז להתאמה של סוג MIME.

דוגמה לקישור עומק שמכיל URI, פעולה וסוג 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>

אפשר גם להשתמש בעורך הניווט כדי ליצור קישור עומק מרומז ליעד באופן הבא:

  1. בכרטיסייה design בעורך הניווט, בוחרים את היעד של קישור העומק.
  2. לוחצים על + בקטע קישורים עומק בחלונית מאפיינים.

  3. בתיבת הדו-שיח הוספת קישור עומק שמופיעה, מזינים את המידע על קישור העומק.

    חשוב לזכור:

    • מזהי URI ללא סכימה נחשבים ל-http או ל-https. לדוגמה, הערך www.google.com תואם גם ל-http://www.google.com וגם ל-https://www.google.com.
    • placeholders של פרמטרים של נתיבים בצורת {placeholder_name} תואמים לתו אחד או יותר. לדוגמה, http://www.example.com/users/{id} תואם ל-http://www.example.com/users/4. רכיב הניווט מנסה לנתח את ערכי ה-placeholder לסוגי נתונים מתאימים על ידי התאמת שמות ה-placeholder לארגומנטים שהוגדרו ליעד של קישור העומק. אם לא מגדירים ארגומנט עם אותו שם, המערכת משתמשת בסוג String שמוגדר כברירת מחדל לערך הארגומנט. אפשר להשתמש בתו הכללי .* כדי להתאים לאפס תווים או יותר.
    • אפשר להשתמש ב-placeholders של פרמטרים של שאילתות במקום בפרמטרים של נתיבים או בשילוב עם אותם. לדוגמה, http://www.example.com/users/{id}?myarg={myarg} תואם ל-http://www.example.com/users/4?myarg=28.
    • אין צורך להתאים את placeholder של פרמטר השאילתה למשתנים שמוגדרים עם ערכי ברירת מחדל או ערכי nullable. לדוגמה, הערך http://www.example.com/users/{id}?arg1={arg1}&arg2={arg2} תואם לערך http://www.example.com/users/4?arg2=28 או לערך http://www.example.com/users/4?arg1=7. המצב שונה לגבי פרמטרים של נתיב. לדוגמה, הערך http://www.example.com/users?arg1=7&arg2=28 לא תואם לדפוס שלמעלה כי פרמטר הנתיב הנדרש לא סופק.
    • פרמטרים מיותרים של שאילתות לא משפיעים על ההתאמה של URI של קישור עומק. לדוגמה, http://www.example.com/users/{id} תואם ל-http://www.example.com/users/4?extraneousParam=7, למרות ש-extraneousParam לא מוגדר בדפוס ה-URI.

  4. (אופציונלי) מסמנים את התיבה אימות אוטומטי כדי לחייב את Google לאמת שאתם הבעלים של ה-URI. מידע נוסף זמין במאמר אימות קישורים לאפליקציות ל-Android.

  5. לוחצים על הוספה. סמל קישור מופיע מעל היעד שנבחר כדי לציין שיש ליעד הזה קישור עומק.

  6. לוחצים על הכרטיסייה Code כדי לעבור לתצוגת ה-XML. נוסף ליעד רכיב <deepLink> בתצוגת עץ:

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

כדי להפעיל קישורי עומק מרומזים, צריך גם להוסיף פריטים לקובץ manifest.xml של האפליקציה. מוסיפים רכיב <nav-graph> יחיד לפעילות שמצביעה על תרשים ניווט קיים, כמו בדוגמה הבאה:

<?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>

כשיוצרים את הפרויקט, רכיב הניווט מחליף את הרכיב <nav-graph> ברכיבי <intent-filter> שנוצרו, כדי שיתאימו לכל קישורי העומק בתרשים הניווט.

כשמפעילים קישור עומק מרומז, המצב של המקבץ האחורי תלוי בשאלה אם Intent המשתמע הופעל עם הדגל Intent.FLAG_ACTIVITY_NEW_TASK:

  • אם הדגל מוגדר, סטאק החזרה לאחור של המשימות נמחק ומוחלף ביעד של הקישור המעמיק. בדומה לקישור עומק מפורש, כשמקפלים גרפים, גם יעד ההתחלה מכל רמה של קיפול – כלומר יעד ההתחלה מכל אלמנט <navigation> בהיררכיה – מתווסף למחסנית. כלומר, כשמשתמש לוחץ על הלחצן 'הקודם' מיעד של קישור עומק, הוא חוזר אחורה בערימה של הניווט בדיוק כאילו נכנס לאפליקציה מנקודת הכניסה שלה.
  • אם הדגל לא מוגדר, המערכת תישאר בסטאק המשימות של האפליקציה הקודמת שבה הופעל קישור העומק המרומז. במקרה כזה, לחיצה על הלחצן 'הקודם' תחזיר אתכם לאפליקציה הקודמת, ואילו לחיצה על הלחצן 'למעלה' תפעיל את המשימה של האפליקציה ביעד ההורה ההיררכי בתרשים הניווט.

טיפול בקישורי עומק

מומלץ מאוד להשתמש תמיד בברירת המחדל launchMode של standard כשמשתמשים בניווט. כשמשתמשים במצב ההפעלה של standard, הניווט מטפל אוטומטית בקישורי עומק על ידי קריאה ל-handleDeepLink() כדי לעבד קישורי עומק מפורשים או מרומזים בתוך Intent. אבל, זה לא יקרה באופן אוטומטי אם עושים שימוש חוזר ב-Activity כשמשתמשים ב-launchMode חלופי, כמו singleTop. במקרה כזה, צריך להפעיל את handleDeepLink() באופן ידני ב-onNewIntent(), כמו בדוגמה הבאה:

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);
}

מקורות מידע נוספים

מידע נוסף על ניווט זמין במקורות המידע הבאים.

דוגמיות

Codelabs

סרטונים