מעבר מקישורים דינמיים לקישורים לאפליקציה & קישורים אוניברסליים

המדריך להעברת נתונים מתמקד בשימוש בקישורים לאפליקציות ובקישורים אוניברסליים, אם רוצים, אפשר להשתמש באירוח ב-Firebase כדי לארח את קובצי השיוך של אתרי האפליקציות.

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

אם אתם עדיין זקוקים לתכונות אחרות של Firebase Dynamic Link להעברה, שלא נתמכות במדריך הזה, תוכלו לעיין בתרחישי העברה אחרים במסמכי העזרה של Dynamic Links Deprecation FAQ.

נניח שיש לכם קישור דינמי ב-Firebase שנראה כך:

המטרה של המדריך הזה היא להחליף קישורים דינמיים ב-Firebase בצורה הזו:

https://example.page.link/m9Mm

באמצעות קישורי עומק של קישור לאפליקציה או קישור אוניברסלי שנראים כך:

https://your-project-domain.web.app/welcome

שימו לב: קישור העומק של האפליקציה או הקישור האוניברסלי יספק למשתמשים את הפרטים הבאים:

• קישור עומק שאפשר ללחוץ עליו כדי לפתוח את האפליקציה אם היא כבר מותקנת
• המשך התהליך שעובר המשתמש מפנה אותם לחלק ספציפי באפליקציה כשהיא פתוחה

עם זאת, קישור העומק של הקישור לאפליקציה או של הקישור האוניברסלי לא יספק למשתמשים את ההתנהגויות הבאות (שקישורים דינמיים של Firebase סיפקו בעבר):

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

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

לפני שמתחילים

קישורים דינמיים ב-Firebase משתמשים בקישורים לאפליקציה (ב-Android) ובקישורים אוניברסליים (ב-iOS) בהטמעה בסיסית שלהם, כדי לספק פונקציונליות של קישורי עומק אחרי שהאפליקציה כבר מותקנת.

במדריך הזה מוסבר איך ליצור קישורי App Links ו-Universal Links משלכם באמצעות Firebase Hosting, כדי להחליף את החלק הזה של הפונקציונליות שקישור דינמי ב-Firebase מספק, תוך העברה של קישורים דינמיים ב-Firebase לפתרון ההעברה החדש של קישורי App Links או Universal Links.

צריך את הפרטים הבאים כדי להשלים את ההעברה:

• הקישורים הדינמיים ב-Firebase שאתם מתכוונים להעביר
• הפרמטרים של כתובת ה-URL של קישור העומק שכלולים בקישורים הדינמיים
• הדומיין שבו אתם מתכננים להשתמש כדי להחליף את הדומיין הקודם של הקישורים הדינמיים של Firebase (אם רלוונטי)

אתם יכולים להיעזר במדריך לייצוא מטא-נתונים של קישורים דינמיים כדי לייצא את המטא-נתונים הקיימים של הקישורים ולקבל את המידע שמפורט למעלה.

סקירה כללית של שלבי ההעברה

1. הקצאת דומיין חדש (אם עדיין אין לכם דומיין שבו אתם רוצים להשתמש) לאירוח קובצי התצורה של קישורי האפליקציה או הקישורים האוניברסליים באמצעות אירוח ב-Firebase.

2. יוצרים ומארחים את קובצי התצורה של App Link או Universal Link בדומיין האירוח.

3. יוצרים קישורים חדשים לאפליקציה או קישורים אוניברסליים חדשים שתואמים לסכימת קישורי העומק שמשמשת בקישורים הדינמיים ב-Firebase.

4. מעדכנים את האפליקציות ל-Android או ל-iOS ואת קוד האפליקציה כדי לקבל קישורי עומק.

5. בדיקת השילובים של קישורי אפליקציות או קישורים אוניברסליים.

6. מחליפים את הקישורים הדינמיים ב-Firebase שפורסמו או ששותפו בקישורי אפליקציות ובקישורים אוניברסליים.

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

• שלבים להעברה בקישורים לאפליקציות ל-Android
• שלבי ההעברה של קישורים אוניברסליים ל-iOS

הקצאת דומיין חדש לאירוח קובצי התצורה של קישורי האפליקציה או הקישורים האוניברסליים באמצעות אירוח ב-Firebase

בחירת דומיין

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

אם אתם משתמשים באירוח ב-Firebase, תת-דומיינים של פרויקטים בפורמט your-project-domain.web.app או your-project-domain.firebaseapp.com מוקצים באופן אוטומטי ללא עלות. אפשר גם להשתמש בדומיין מותאם אישית עם או בלי אירוח ב-Firebase כדי לארח את קובצי התצורה של App Link או Universal Link.

הגדרת אירוח ב-Firebase

בשלב הבא תצטרכו להגדיר את המכונה של Firebase Hosting ולהגדיר אותה.

עד שתסיימו להגדיר את האירוח ב-Firebase, יהיה לכם דומיין שדומה ל-your-project-domain.web.app, או דומיין מותאם אישית אם אתם מעדיפים.

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

יוצרים ומארחים את קובצי התצורה של App Link בדומיין האירוח החדש

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

שלבים ליצירה ולאירוח של קובץ assetlinks.json

קובץ assetlinks.json מאפשר לנו לספק רשימה של אפליקציות מורשות שיכולות לטפל בתוכן של דומיין האינטרנט שבו נשתמש לקישור האפליקציות. הקובץ assetlinks.json עצמו צריך להתארח ברמה הבסיסית (root) של דומיין האינטרנט שבנתיב: /.well-known.

כדי להשלים את ההגדרה הזו, פועלים לפי השלבים הבאים:

1. יוצרים את התיקייה .well-known בתיקייה הציבורית בתיקיית השורש של האירוח ב-Firebase.

2. יוצרים קובץ בשם assetlinks.json בתיקייה .well-known.

3. מעתיקים את התוכן הבא לקובץ assetlinks.json, תוך שמירה על המשמעות של כל שדה שמופיע בהמשך:

   [{
     "relation": ["delegate_permission/common.handle_all_urls"],
     "target": {
       "namespace": "android_app",
       "package_name": "com.example.android",
       "sha256_cert_fingerprints":
         ["01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF"]
     }
   }]
   

   • namespace – שם האפליקציה שרוצים לספק
   • package_name – מתייחס ל-applicationId שמוצהר בקובץ build.gradle של האפליקציה
   • sha256_cert_fingerprints - מתייחס לטביעת האצבע SHA256 של קובץ מאגר המפתחות שבו משתמשים לחתימה על האפליקציה.

   אפשר להשתמש בקובץ debug.keystore שמשמש את Android Studio כדי ליצור רשומת sha256_cert_fingerprints למטרות ניפוי באגים. הקובץ נמצא ב-/Users/<username>/.android/debug.keystore ב-Mac וב-Linux וב-C:\Users\<username>\.android\debug.keystore ב-Windows.

   ממאגר המפתחות הזה אפשר לאחזר את הערך SHA256 באמצעות כלי המפתח.

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

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

4. מעדכנים את קובץ firebase.json כדי להוסיף את הקובץ לאינדקס לצורך אירוח.

   "headers": [
     {
       "source": "/.well-known/assetlinks.json",
       "headers": [
         {
           "key": "Content-Type",
           "value": "application/json"
         }
       ]
     }
   ]
   

5. עכשיו, אחרי שהגדירו את הקובץ assetlinks.json, מריצים את הפקודה firebase deploy כדי לארח את השינויים.

   שימו לב: כדי להריץ את פקודת הפריסה שלמעלה, צריך להתקין את Firebase CLI.

   firebase deploy --only hosting
   

6. מאמתים את קובץ assetlinks.json בדף https://your-project-domain.web.app/.well-known/assetlinks.json

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

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

לדוגמה, נניח שיש לכם את הקישור הדינמי הבא ב-Firebase:

במקרה כזה, צריך לחלץ את הפרמטר של קישור העומק – כלומר https://example.web.app/welcome – ולהשתמש בו עכשיו כפרמטר של קישור האפליקציה.

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

לדוגמה, עיינו בקבוצה הבאה של קישורים מקוצרים, פרמטרים של קישורי עומק וערכים של קישורי עומק שהועברו מהקישורים הדינמיים ב-Firebase:

בשלב הבא, תצטרכו להחליף את כל המופעים של קישורים דינמיים ב-Firebase שפורסמו או ששותפו בקישורי העומק החדשים שהועברו, כדי שהמשתמשים ילחצו על קישורי האפליקציה האלה במקום על הקישורים הדינמיים הקודמים ב-Firebase.

עדכון האפליקציה ל-Android וקוד האפליקציה כדי לקבל קישורי עומק

אחרי שבוחרים דומיין, סכימה של קישור עומק ומעבירים את הקישורים הדינמיים של Firebase לקישורי App, השלבים הבאים הם עדכון האפליקציה ל-Android וקידוד האפליקציה כך שיקבלו את הקישורים העומק החדשים.

מומלץ לפעול לפי מסמכי התיעוד המלאים של הקישורים לאפליקציות, או להיעזר במדריך ל-Android Studio להגדרת האפליקציה לטיפול בקישורי עומק, אבל השלבים העיקריים כוללים:

1. זיהוי הפעילויות שצריכות לטפל בקישורי העומק המתאימים
2. הוספת מסנן Intent לפעילויות האלה בקובץ AndroidManifest.xml
3. קבלת קישור העומק בקוד האפליקציה של הפעילויות

נניח שרצית להשתמש ב-MainActivity כדי לטפל בחלק מהקישורים העמוקים. כדי לעשות זאת, צריך להוסיף את מסנן ה-Intent הבא ל-MainActivity בקובץ AndroidManifest.xml:

<activity android:name=".MainActivity"
   android:exported="true">
   <intent-filter>
       <action android:name="android.intent.action.MAIN" />
       <category android:name="android.intent.category.LAUNCHER" />
   </intent-filter>
   <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:host="example.web.app" android:scheme="http"
           android:pathPrefix="/welcome" />
       <data android:host="example.web.app" android:scheme="https"
           android:pathPrefix="/welcome" />
   </intent-filter>
</activity>

בשלב הזה מציינים ש-MainActivity הוא היעד לטיפול בקישורי עומק מהדומיין wxample.web.app, ושהוא כולל את הקידומת של הנתיב ‎/welcome. שימו לב: תצטרכו גם לציין את המאפיין android:autoVerify="true", שמאפשר לכם להגדיר את האפליקציה כמתן הטיפול שמוגדר כברירת מחדל לסוג הקישור הזה.

לסיום, מוסיפים את הקוד לפעילות הראשית (MainActivity) כדי לאחזר את הנתונים של קישורי העומק ולהשתמש בהם כדי לשפר את חוויית קישורי העומק באפליקציה. הדבר דומה ללוגיקה שכבר קודדתם באפליקציה כששילבתם עם קישורים דינמיים ב-Firebase.

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

  val  data: Uri? = intent?.data

  val toast = Toast.makeText(this, data, duration)
  toast.show()
}

בדיקת קישורים לאפליקציות

תוכלו לבדוק את הקישורים לאפליקציות שיצרתם על ידי הפעלת האפליקציה במכשיר פיזי או באמולטור Android.

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

לחלופין, תוכלו גם לבדוק את השילוב של App Links באמצעות App Links Assistant ב-Android Studio, או להשתמש בפקודה הבאה עבור כתובת URL של קישור לאפליקציה שהגדרתם כדי להבטיח שהיא מפעילה את פעילות ההתאמה בצורה תקינה:

adb shell am start -a android.intent.action.VIEW -d <your_deep_link_url>

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

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

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

שלבי ההעברה של קישורים אוניברסליים ב-iOS

יוצרים ומארחים את קובצי התצורה של Universal Links בדומיין האירוח החדש

כדי להשתמש בקישורים אוניברסליים, צריך לארח קובץ תצורה שעוזר ליצור שיוך מאובטח בין הדומיין שבו נעשה שימוש בקישורים לבין האפליקציה. בקישורים אוניברסליים, זהו קובץ apple-app-site-association (שנקרא גם קובץ AASA).

שלבים ליצירה ולאירוח של קובץ apple-app-site-association

קובץ ה-AASA מאפשר לנו לספק רשימה של אפליקציות מורשות שיכולות לטפל בתוכן של דומיין האינטרנט שבו נשתמש לקישורים האוניברסליים. קובץ ה-AASA עצמו צריך להתארח בספריית הבסיס של דומיין האינטרנט, בנתיב: ‎/.well-known.

כדי להשלים את ההגדרה הזו, פועלים לפי השלבים הבאים:

1. יוצרים את התיקייה ‎.well-known מתחת לתיקייה הציבורית בספריית השורש של Firebase Hosting.

2. יוצרים קובץ בשם apple-app-site-association בתיקייה ‎.well-known.

3. מעתיקים את התוכן הבא לקובץ apple-app-site-association, תוך שמירה על המשמעות של כל שדה שמופיע בהמשך:

   {
     "applinks": {
       "apps": [],
       "details": [
         {
           "appId": "$TEAM_ID.com.firebase.UniversalLinks",
           "paths": [
             "NOT /_/*",
             "/*"
           ]
         }
       ]
     }
   }
   

   • $Team_ID.BundleId – שם האפליקציה המוגדר במלואו ומורשה לטפל בקישורים

4. מעדכנים את קובץ firebase.json כדי להוסיף את הקובץ לאינדקס לצורך אירוח.

   "headers": [
     {
       "source": "/.well-known/apple-app-site-association",
       "headers": [
         {
           "key": "Content-Type",
           "value": "application/json"
         }
       ]
     }
   ]
   

5. עכשיו, אחרי שיצרנו את קובץ ה-AASA, צריך לפרוס את firebase כדי לארח את השינויים.

6. כדי לאמת את קובץ ה-AASA, עוברים לכתובת https://your-project-domain.web.app/.well-known/app-app-site-association

יוצרים קישורים אוניברסליים חדשים שתואמים לסכימת קישורי העומק שמשמשת את הקישורים הדינמיים ב-Firebase.

בשלב הזה, תייצרו מחדש את הקישורים לעומק מהקישורים הדינמיים ב-Firebase באמצעות כתובות URL רגילות של קישורי עומק שתואמות לדומיין החדש שיצרתם ל-Universal Links.

לדוגמה, נניח שיש לכם את הקישור הדינמי הבא ב-Firebase:

במקרה כזה, צריך לחלץ את הפרמטר של קישור העומק, כלומר https://example.web.app/welcome, ולהשתמש בו בתור הפרמטר של קישור העומק לאפליקציה.

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

לדוגמה, עיינו בקבוצה הבאה של קישורים מקוצרים, פרמטרים של קישורי עומק וערכים של קישורי עומק שהועברו מהקישורים הדינמיים ב-Firebase:

בשלב הבא, תצטרכו להחליף את כל המופעים של קישורים דינמיים ב-Firebase שפורסמו או ששותפו בקישורי העומק החדשים שהועברו, כדי שהמשתמשים ילחצו על קישורי Universal האלה במקום על הקישורים הדינמיים הקודמים ב-Firebase.

עדכון האפליקציה ל-iOS וקוד האפליקציה כדי לקבל קישורי עומק

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

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

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

2. קבלת קישור העומק בקוד האפליקציה

כדי לעדכן את הגדרות הפרויקט כך שהאפליקציה תוכל לטפל בקישורים עומק, צריך להוסיף לדומיין שבו אתם מתכננים לארח את הקובץ apple-app-site-associate עוד דומיין משויך לפרויקט ב-xCode.

כדי לעשות זאת, אפשר:

1. פתיחת Xcode
2. בחירת הפרויקט בחלונית הניווט של הקבצים
3. ניווט לכרטיסייה Signing & Capabilities (חתימה ויכולות) בהגדרות הפרויקט
4. גוללים למטה לקטע 'דומיינים משויכים'.
5. לוחצים על הלחצן + כדי להוסיף את הדומיין הנוסף לפרויקט בפורמט 'applinks:‎'.

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

כדי לעשות זאת, קודם צריך לעדכן את הקובץ AppDelegate.swift כך שתהיה לו תגובה ל-Universal Link. לשם כך, מוסיפים את הקוד הבא:

func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  AppDelegate.showReceivedUrl(userActivity: userActivity);
  return true
}

static func showReceivedUrl(userActivity: NSUserActivity) {
  if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
    let url = userActivity.webpageURL!
    print(url.absoluteString)
}

הקוד שלמעלה מבטל את השיטה של Universal Link להפעלה חוזרת (callback) ומתעדה ביומן את כתובת ה-URL של קישור העומק, אם הוא קיים.

עכשיו נפעיל את אותה שיטה showReceivedUrl גם מהקלאס SceneDelegate, כי אם האפליקציה כבר פתוחה כשהמשתמש לוחץ על הקישור האוניברסלי, תיגרם קריאה חוזרת (callback) לקישור האוניברסלי ב-SceneDelegate.

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  AppDelegate.showReceivedUrl(userActivity: userActivity)
}

בדיקת קישורים אוניברסליים

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

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

תמיכה במודעות באנר חכמות לאפליקציות

מומלץ מאוד להשתמש בבאנרים חכמים לאפליקציות כדי לספק למשתמשים חוויה דומה לזו של קישורים דינמיים של Firebase.

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

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

השלב האחרון בהעברה יהיה החלפת הקישורים הדינמיים של Firebase שפורסמו או ששותפו בקישורים אוניברסליים, במידת האפשר, והמשך השימוש בקישורים אוניברסליים.

השלמת השלב הזה משתנה בהתאם למיקום ולאופן שבהם פרסמתם את הקישורים הדינמיים ב-Firebase.

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