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

כשקישור שנלחץ עליו או בקשה פרוגרמטית מפעילים כוונה של 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 ממוזגים יחד כדי להביא בחשבון את כל הווריאציות של המאפיינים המשולבים. לדוגמה: 

<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, לא מובטח איזו פעילות תטפל בקישור.

אחרי שמוסיפים מסנני Intent עם מזהי 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

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

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