הוספת מסנני Intent לקישורי אפליקציות

קישורי עומק לאפליקציות הם קישורים שמשתמשים בסכימת HTTP או HTTPS ומאומתים על ידי Android כקישורים שמשויכים לאתר שלכם. כדי להירשם לטיפול בקישורי אפליקציות, פועלים לפי השלבים הבאים:

1. מוסיפים לקובץ המניפסט של האפליקציה מסנן Intent אחד או יותר שמציין את הדומיין או כתובות ה-URL של האתר.
2. מוסיפים את autoVerify="true"attribute לרכיבי מסנן ה-Intent. הפעולה הזו מסמנת למערכת שהיא צריכה לנסות לאמת את הסכימה ואת דומיין המארח מול ההגדרה של assetlinks.json באתר שלכם.
3. הצהרה על שיוכים לאתרים.

הדוגמה הבאה מציגה הצהרה של קישור עומק לאפליקציה עם סכימות ומארחים, וגם autoVerify="true:

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <!-- Make sure you explicitly set android:autoVerify to "true". -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- If a user clicks on a link that uses the "http" scheme, your
             app should be able to delegate that traffic to "https". -->
        <!-- Do not include other schemes, as this will prevent verification. -->
        <data android:scheme="http" />
        <data android:scheme="https" />

        <!-- Include one or more domains that should be verified. -->
        <data android:host="www.example.com" />
        <data android:host="*.example.com" />
    </intent-filter>
</activity>

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

• ‫AutoVerify: חובה להוסיף את המאפיין android:autoVerify="true" לקישורי עומק לאפליקציה. הוא מסמן למערכת שהיא צריכה לנסות לאמת את השיוך בין האפליקציה לבין הסכמות והדומיינים שצוינו בתגי <data>. מומלץ להוסיף autoVerify="true" לכל מסנן Intent שרוצים לאמת.
• רכיבי נתונים: כל מסנן Intent של קישורי אפליקציה חייב לכלול רכיב <data> אחד או יותר שמציין את הסכימות ואת פורמטים המארחים שתואמים לדומיין האתר שניתן לאימות.
• סכמות: מסנן ה-Intent חייב לכלול רכיבי <data> גם לסכמות http וגם לסכמות https.

• מארחים: אפשר להוסיף רכיבי <data> כדי להתאים למארח אחד או יותר. אפשר להשתמש בתו כללי לחיפוש (*) כדי להתאים לכמה תת-דומיינים (למשל *.example.com). המערכת תנסה לאמת כל מארח מול הקובץ assetlinks.json באתר שלכם. חשוב לזכור שניתוב ברמת הנתיב צריך להתבצע באמצעות הקובץ assetlinks.json (ראו את קטע השיטות המומלצות בהמשך).

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

• מסנני Intent מרובים: חשוב ליצור מסננים נפרדים כשרוצים להצהיר על כתובות URL ייחודיות (למשל שילוב ספציפי של Scheme ומארח), כי כמה רכיבי <data> באותו מסנן Intent עוברים מיזוג כדי להביא בחשבון את כל הווריאציות של המאפיינים המשולבים שלהם.

שיקולים לגבי כללי סינון של קובץ מניפסט

אם אתם מגדירים מסננים לשימוש בקישורי עומק דינמיים לאפליקציות ב-Android 15 ובגרסאות מתקדמות יותר, חשוב לזכור שהכללים הדינמיים שמוצהרים בקובץ assetlinks.json בצד השרת לא יכולים להרחיב את היקף הכללים של כתובות ה-URL שמוצהרים באופן סטטי בקובץ מניפסט של אפליקציה.

לכן, אנחנו ממליצים להשתמש בגישה הזו:

• במניפסט של האפליקציה, מגדירים את ההיקף הרחב ביותר האפשרי, למשל על ידי הצהרה על scheme ועל domain בלבד.
• להסתמך על הכללים של assetlinks.json בצד השרת כדי לבצע שיפורים נוספים, כמו ניתוב ברמת הנתיב.

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

תמיכה בקישורים לאפליקציות למספר מארחים

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

לדוגמה, אפליקציה עם מסנני הכוונות הבאים תעבור אימות רק עבור https://www.example.com אם קובץ assetlinks.json יימצא בנתיב https://www.example.com/.well-known/assetlinks.json, אבל לא בנתיב https://www.example.net/.well-known/assetlinks.json:

<application>

  <activity android:name=”MainActivity”>
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="http" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
    </intent-filter>
  </activity>
  <activity android:name="SecondActivity">
    <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
     <data android:host="www.example.net" />
    </intent-filter>
  </activity>

</application>

תמיכה בקישור אפליקציות למספר תת-דומיינים

פרוטוקול Digital Asset Links מתייחס לתתי-דומיין במסנני Intent כמארחים ייחודיים ונפרדים. לכן, אם מסנן Intent שלכם מפרט מספר מארחים עם תתי-דומיינים שונים, אתם צריכים לפרסם רשומת assetlinks.json תקינה בכל דומיין. לדוגמה, מסנן ה-Intent הבא כולל את www.example.com ואת mobile.example.com כמארחים קבילים של כתובות URL של Intent. לכן, צריך לפרסם assetlinks.json תקף גם בכתובת https://www.example.com/.well-known/assetlinks.json וגם בכתובת https://mobile.example.com/.well-known/assetlinks.json.

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
      <data android:host="mobile.example.com" />
    </intent-filter>
  </activity>
</application>

לחלופין, אם אתם מצהירים על שם המארח באמצעות תבנית wildcard (כמו *.example.com), אתם צריכים לפרסם את הקובץ assetlinks.json בשם המארח של השורש (example.com). לדוגמה, אפליקציה עם מסנן ה-Intent הבא תעבור אימות לכל שם משנה של example.com (כמו foo.example.com) כל עוד הקובץ assetlinks.json מתפרסם בכתובת https://example.com/.well-known/assetlinks.json:

<application>
  <activity android:name="MainActivity">
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" />
      <data android:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

בדיקה אם יש כמה אפליקציות שמשויכות לאותו דומיין

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

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

תאימות לאחור של קישורי עומק דינמיים לאפליקציה ב-Android מגרסה 14 ומטה

התכונות של קישורי עומק דינמיים לאפליקציות, כולל כללי התאמה מתקדמים ב-assetlinks.json והשימוש ב-<uri-relative-filter-group>, נתמכות באופן מלא רק ב-Android 15 (רמת API‏ 35) ומעלה.

ב-Android 14 (רמת API‏ 34) ומטה, המערכת מתייחסת רק ל-scheme ול-host שהוצהרו ברכיבי <data> במניפסט לצורך אימות קישורי עומק לאפליקציה. כללים, החרגות ועדכונים דינמיים ספציפיים לנתיב מתוך assetlinks.json לא מוחלים.

המשמעות היא שאם במניפסט שלכם מוגדרים רק scheme ו-host, יכול להיות שהאפליקציה שלכם תתעד באופן לא צפוי את כל הנתיבים של הדומיין המאומת ב-Android 14 ובגרסאות קודמות, ללא קשר לכללים הספציפיים לנתיב שהוגדרו ב-assetlinks.json עבור Android 15 וגרסאות חדשות יותר.

צריך להגדיר אסטרטגיית חזרה לגרסאות Android ישנות יותר בלי קישורי עומק

כדי למנוע מהאפליקציה לטפל בכל הקישורים לדומיין ב-Android מגרסה 14 ומטה, כשאתם מתכוונים להשתמש בקישורי עומק דינמיים לאפליקציה לנתיבים ספציפיים יותר ב-Android מגרסה 15 ומעלה, צריך לכלול נתיב לא תואם במסנן הכוונות במניפסט. מוסיפים רכיב <data> עם מאפיין android:path שסביר להניח שלעולם לא יהיה נתיב תקין לקישורים שלכם. כך מוודאים שמסנן Intent לא יתאים לכל הנתיבים בגרסאות נמוכות יותר.

דוגמה:

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="http" />
        <data android:scheme="https" />
        <data android:host="www.example.com" />

        <!-- Add a non-matching path for backward compatibility -->
        <data android:path="/no_match_for_older_android_versions" />

        <uri-relative-filter-group android:allow="true">
          <data android:pathPattern="/.*"/>
        </uri-relative-filter-group>
    </intent-filter>
</activity>

הוספת <data android:path="/no_match_for_older_android_versions" /> מבטיחה שב-Android בגרסה 14 ומטה, מסנן ה-Intent הזה לא יתאים לאף קישור נכנס, אבל עדיין יאפשר לאמת את הדומיין לשימוש בקישורי עומק דינמיים לאפליקציה ב-Android בגרסה 15 ומעלה, על סמך כללי ההתאמה המתקדמים בכללי assetlinks.json.

העברה של קישורי אפליקציות קיימים

אם כבר יש לכם קישורי עומק לאפליקציה עם כללי נתיב ספציפיים (כמו android:pathPrefix) בקובץ המניפסט ואתם רוצים להתחיל להשתמש בקישורי עומק דינמיים לאפליקציה ב-Android 15 ומגרסאות חדשות יותר, אתם יכולים להוסיף בבטחה את רכיב <uri-relative-filter-group> ישירות למסנני ה-Intent הקיימים.

מערכות Android מגרסה 14 ומטה מתעלמות מהרכיב <uri-relative-filter-group>, ולכן קישורי העומק הקיימים לאפליקציה ימשיכו לפעול בדיוק כמו שהם פועלים עכשיו במכשירים עם גרסאות קודמות של Android.

עם זאת, חשוב לשים לב איך מערכת Android מגרסה 15 ואילך מעריכה את ההגדרה 'מעורבת':

• סינון בשתי שכבות: ב-Android 15 ואילך, המערכת מעריכה את מסנני הכוונות כאיחוד. כתובת URL עוברת את בדיקת המניפסט אם היא עומדת בדרישות של תגי <data> סטטיים מדור קודם או בכללים הרחבים בקובץ <uri-relative-filter-group>. אחרי שכתובת ה-URL עוברת את הבדיקה הראשונית של המניפסט, המערכת מחילה את הכללים הדינמיים שמוגדרים בקובץ assetlinks.json כשכבה שנייה של סינון מדויק. כלומר, כללי ה-JSON בצד השרת קובעים בסופו של דבר אילו מכתובות ה-URL התואמות האלה יפתחו את האפליקציה.

דוגמה להגדרה היברידית:

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data android:scheme="https" />
    <data android:host="www.example.com" />

    <!-- Legacy rule: Android 14 and lower use this. Android 15 and higher
         also use this. -->
    <data android:pathPrefix="/store" />

    <!--
      Dynamic rule: Android 14 and lower ignore this. Android 15 and higher
      evaluate this as a union between all paths and the configuration
      specified in the assetlinks.json file. Make sure to apply further
      refinements in the assetlinks.json file to prevent all URL paths from
      opening in the app.
    -->
    <uri-relative-filter-group android:allow="true">
        <data android:pathPrefix="/" />
    </uri-relative-filter-group>
</intent-filter>