יצירת קישורי עומק לתוכן האפליקציה

כשקישור שנלחץ עליו או בקשה פרוגרמטית מפעילים כוונה של URI באינטרנט, מערכת Android מנסה לבצע כל אחת מהפעולות הבאות, בסדר כרונולוגי, עד שהבקשה מצליחה:

  1. פותחים את האפליקציה המועדפת של המשתמש שיכולה לטפל ב-URI, אם הוגדרה כזו.
  2. פותחים את האפליקציה היחידה שזמינה ויכולה לטפל ב-URI.
  3. מאפשרים למשתמש לבחור אפליקציה מתיבת דו-שיח.

כדי ליצור ולבדוק קישורים לתוכן שלכם, פועלים לפי השלבים הבאים. אפשר גם להשתמש בכלי להוספת קישורים לאפליקציות ב-Android Studio כדי להוסיף קישורים לאפליקציות ל-Android.

הערה: החל מ-Android 12 (רמת API 31), כוונה רגילה לאינטרנט מנותבת לפעילות באפליקציה רק אם האפליקציה אושרה לדומיין הספציפי שמכיל את הכוונה הזו לאינטרנט. אם האפליקציה לא אושרה לדומיין, כוונה האינטרנט תנותב במקום זאת לאפליקציית הדפדפן שמוגדרת כברירת מחדל של המשתמש.

הוספת מסנני כוונה לקישורים נכנסים

כדי ליצור קישור לתוכן של האפליקציה, מוסיפים למניפסט מסנן Intent שמכיל את הרכיבים ואת ערכי המאפיינים הבאים:

<action>
מציינים את פעולת ה-Intent‏ ACTION_VIEW כדי שאפשר יהיה להגיע לסינון ה-Intent מחיפוש Google.
<data>
מוסיפים תג <data> אחד או יותר, שכל אחד מהם מייצג פורמט URI שמפנה לפעילות. לכל הפחות, התג <data> חייב לכלול את המאפיין android:scheme.

אפשר להוסיף עוד מאפיינים כדי לצמצם עוד יותר את סוג ה-URI שהפעילות מקבלת. לדוגמה, יכול להיות שיש לכם כמה פעילויות שמקבלות כתובות URI דומות, אבל שונות רק על סמך שם הנתיב. במקרה כזה, צריך להשתמש במאפיין android:path או בוריאנטים שלו pathPattern או pathPrefix כדי להבדיל בין הפעילויות שהמערכת צריכה לפתוח לנתיבים שונים של URI.

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

יש לכלול גם את הקטגוריה DEFAULT. כך האפליקציה תוכל להגיב לכוונות משתמשים מרומזות. בלי זה, אפשר להפעיל את הפעילות רק אם ה-Intent מציין את שם הרכיב של האפליקציה.

קטע ה-XML הבא מראה איך אפשר לציין מסנן כוונה במניפסט לקישור עומק. מזהי ה-URI “example://gizmos” ו-“http://www.example.com/gizmos” מפנים לפעילות הזו.

<activity
    android:name="com.example.android.GizmosActivity"
    android:label="@string/title_gizmos" >
    <intent-filter android:label="@string/filter_view_http_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "http://www.example.com/gizmos” -->
        <data android:scheme="http"
              android:host="www.example.com"
              android:pathPrefix="/gizmos" />
        <!-- note that the leading "/" is required for pathPrefix-->
    </intent-filter>
    <intent-filter android:label="@string/filter_view_example_gizmos">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- Accepts URIs that begin with "example://gizmos” -->
        <data android:scheme="example"
              android:host="gizmos" />
    </intent-filter>
</activity>

שימו לב: ההבדל בין שני מסנני הכוונה הוא רק ברכיב <data>. אפשר לכלול כמה אלמנטים מסוג <data> באותו מסנן, אבל חשוב ליצור מסננים נפרדים אם אתם רוצים להצהיר על כתובות URL ייחודיות (למשל, שילוב ספציפי של scheme ו-host). הסיבה לכך היא שכמה אלמנטים מסוג <data> באותו מסנן כוונה למעשה מתמזגים יחד כדי להביא בחשבון את כל הווריאציות של המאפיינים המשולבים שלהם. לדוגמה: 

<intent-filter>
  ...
  <data android:scheme="https" android:host="www.example.com" />
  <data android:scheme="app" android:host="open.my.app" />
</intent-filter>

נראה שהאפשרות הזו תומכת רק ב-https://www.example.com וב-app://open.my.app. עם זאת, בפועל יש תמיכה בשני הקודמים, ובנוסף בקודים הבאים: app://www.example.com ו-https://open.my.app.

אזהרה: אם כמה פעילויות מכילות מסנני Intent שמפנים לאותו קישור מאומת ל-Android App Link, אין ערובה לאיזו פעילות יתבצע הטיפול בקישור.

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

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

קריאת נתונים מכוונות נכנסות

אחרי שהמערכת מפעילה את הפעילות דרך מסנן כוונה, תוכלו להשתמש בנתונים שסופקו על ידי Intent כדי לקבוע מה צריך להציג. קוראים לשיטות getData() ו-getAction() כדי לאחזר את הנתונים והפעולה שמשויכים ל-Intent הנכנס. אפשר להפעיל את השיטות האלה בכל שלב במחזור החיים של הפעילות, אבל בדרך כלל כדאי לעשות זאת במהלך קריאות חזרה מוקדמות, כמו onCreate() או onStart().

לפניכם קטע קוד שמראה איך לאחזר נתונים מ-Intent:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    val action: String? = intent?.action
    val data: Uri? = intent?.data
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent = getIntent();
    String action = intent.getAction();
    Uri data = intent.getData();
}

כדי לשפר את חוויית המשתמש, כדאי לפעול לפי השיטות המומלצות הבאות:

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

בדיקה של קישורי העומק

אפשר להשתמש ב-Android Debug Bridge עם הכלי activity manager‏ (am) כדי לבדוק שכתובות ה-URI של מסנן הכוונה שציינתם לקישורי עומק מנותבות לפעילות הנכונה באפליקציה. אפשר להריץ את הפקודה adb במכשיר או במהדמ.

התחביר הכללי לבדיקה של URI של מסנן כוונה באמצעות adb הוא:

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d <URI> <PACKAGE>

לדוגמה, הפקודה הבאה מנסה להציג פעילות של אפליקציית יעד שמשויכת ל-URI שצוין.

$ adb shell am start
        -W -a android.intent.action.VIEW
        -d "example://gizmos" com.example.android

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

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