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

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

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

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

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

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

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

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

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

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

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

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

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

val componentName = ...

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

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. בתיבת הדו-שיח Add Deep Link שמופיעה, מזינים את הפרטים של קישור העומק.

   חשוב לזכור:

   • מזהי URI ללא סכימה נחשבים כ-http או כ-https. לדוגמה, הערך www.google.com תואם גם ל-http://www.google.com וגם ל-https://www.google.com.
   • placeholder של פרמטר נתיב בפורמט {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(), כמו בדוגמה הבאה:

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

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

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

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

Codelabs

• Codelab בנושא ניווט

סרטונים

• Android Jetpack: ניהול הניווט בממשק המשתמש באמצעות Navigation Controller (Google I/O 2018)