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

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

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

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

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

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

כדי ליצור קישור לתוכן של האפליקציה, מוסיפים למניפסט מסנן 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>

חשוב לשים לב ששני מסנני Intent שונים רק ברכיב <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, אפשר להשתמש בנתונים שסופקו על ידי Intent כדי לקבוע מה צריך לעבד. קוראים לשיטות getData() ו-getAction() כדי לאחזר את הנתונים והפעולה שמשויכים ל-Intent הנכנס. אפשר לקרוא ל-methods האלה בכל שלב במהלך מחזור החיים של הפעילות, אבל בדרך כלל כדאי לעשות זאת במהלך שיחות חוזרות (callback) מוקדמות כמו 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 שהגדרתם למעלה מגדירים את הקשר בין האפליקציה לאתר ואת הפעולה שצריך לבצע עם קישורים נכנסים. עם זאת, כדי שהמערכת תתייחס לאפליקציה כ-handler ברירת המחדל לקבוצה של מזהי URI, צריך לבקש גם שהמערכת תאמת את החיבור הזה. בשיעור הבא מוסבר איך מטמיעים את האימות הזה.

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