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

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

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

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

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

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

https://example.page.link/m9Mm

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

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

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

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

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

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

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

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

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

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

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

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

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

סקירה כללית של שלבי המיגרציה

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

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

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

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

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

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

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

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

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

בחירת דומיין

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

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

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

בשלב הבא, צריך להגדיר את מופע Firebase Hosting.

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

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

יצירה ואירוח של קובצי ההגדרות של קישורי עומק לאפליקציה בדומיין האירוח החדש

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

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

   אפשר גם להשתמש בApp Links Assistant ב-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 לקישורים לאפליקציה הוא עדכון של אפליקציית 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", שמאפשר לכם להגדיר את האפליקציה בתור handler ברירת המחדל לסוג הקישור הזה.

לבסוף, תצטרכו להוסיף את הקוד ב-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 Assistant ב-Android Studio, או להשתמש בפקודה הבאה לכתובת URL של קישור לאפליקציה שהגדרתם, כדי לוודא שהיא מפעילה את ה-Activity התואם בצורה נכונה:

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

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

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

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

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

יצירה ואירוח של קובצי ההגדרה של הקישורים האוניברסליים בדומיין האירוח החדש

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

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

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

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

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

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 deploy כדי לארח את השינויים.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כדי לעשות את זה, קודם מעדכנים את הקובץ AppDelegate.swift כדי להגיב לקישור אוניברסלי על ידי הוספת הקוד הבא:

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)
}

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

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

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

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

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

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

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

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

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

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

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

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

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