יצירת קישורים דינמיים ב-iOS

אפשר ליצור Dynamic Links קצרים או ארוכים באמצעות Firebase Dynamic Links Builder API. ה-API הזה מקבל Dynamic Link ארוך או אובייקט שמכיל פרמטרים של Dynamic Link, ומחזיר כתובות URL כמו בדוגמאות הבאות:

https://example.com/link/WXYZ
https://example.page.link/WXYZ

דרישות מוקדמות

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

שימוש ב-Swift Package Manager כדי להתקין ולנהל יחסי תלות ב-Firebase.

  1. ב-Xcode, כשפרויקט האפליקציה פתוח, עוברים אל קובץ > הוספת חבילות.
  2. כשמופיעה בקשה, מוסיפים את המאגר של Firebase SDK לפלטפורמות של Apple:
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. בוחרים את הספרייה Dynamic Links.
  4. מוסיפים את הדגל -ObjC לקטע Other Linker Flags (דגלים אחרים של קישור) בהגדרות ה-build של היעד.
  5. כדי ליהנות מחוויית שימוש אופטימלית ב-Dynamic Links, מומלץ להפעיל את Google Analytics בפרויקט Firebase ולהוסיף את Firebase SDK for Google Analytics לאפליקציה. אפשר לבחור בספרייה ללא איסוף של מזהי IDFA או עם איסוף של מזהי IDFA.
  6. בסיום, Xcode יתחיל לפתור את יחסי התלות ולהוריד אותם באופן אוטומטי ברקע.

עכשיו מבצעים כמה שלבי הגדרה:

  1. במסוף Firebase, פותחים את הקטע Dynamic Links.

  2. אם עדיין לא אישרתם את התנאים וההגבלות והגדרתם קידומת URI ל-Dynamic Links, עליכם לעשות זאת כשתופיע בקשה לעשות זאת.

    אם כבר יש לכם קידומת URI של Dynamic Links, ציינו אותה. צריך לספק אותו כשיוצרים את Dynamic Links באופן פרוגרמטי.

  3. מומלץ: לציין את תבניות כתובות ה-URL שמותר להשתמש בהן בקישורים העמוקים ובקישורי החלופות. כך תוכלו למנוע מצדדים לא מורשים ליצור Dynamic Links שמעבירים את הגולשים מהדומיין שלכם לאתרים שאתם לא שולטים בהם. התרת תבניות ספציפיות של כתובות URL

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

    כדי לוודא שפרויקט Firebase מוגדר כראוי לשימוש ב-Dynamic Links באפליקציה ל-iOS, פותחים את הקובץ apple-app-site-association שמתארח בדומיין Dynamic Links. Firebase יציג את הקובץ apple-app-site-association מהשורש של הדומיין וגם מהספרייה המשנית .well-known. לדוגמה:

        https://example.com/apple-app-site-association
    https://example.com/.well-known/apple-app-site-association

    אם האפליקציה מחוברת, הקובץ apple-app-site-association מכיל הפניה למזהה החבילה ולתחילית של מזהה האפליקציה. לדוגמה:

    {"applinks":{"apps":[],"details":[{"appID":"1234567890.com.example.ios","paths":["/*"]}]}}

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

הוספת Firebase לאפליקציה

  1. מייבאים את המודול FirebaseCore ב-UIApplicationDelegate, וגם את כל המודולים האחרים של Firebase שבהם משתמש הנציג של האפליקציה. לדוגמה, כדי להשתמש ב-Cloud Firestore וב-Authentication:

    SwiftUI

    import SwiftUI
import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...

    Swift

    import FirebaseCore
import FirebaseFirestore
import FirebaseAuth
// ...

    Objective-C

    @import FirebaseCore;
@import FirebaseFirestore;
@import FirebaseAuth;
// ...
  2. מגדירים מופע משותף של FirebaseApp בשיטה application(_:didFinishLaunchingWithOptions:) של הנציג של האפליקציה:

    SwiftUI

    // Use Firebase library to configure APIs
FirebaseApp.configure()

    Swift

    // Use Firebase library to configure APIs
FirebaseApp.configure()

    Objective-C

    // Use Firebase library to configure APIs
[FIRApp configure];
  3. אם אתם משתמשים ב-SwiftUI, עליכם ליצור נציג אפליקציה ולצרף אותו למבנה App באמצעות UIApplicationDelegateAdaptor או NSApplicationDelegateAdaptor. צריך גם להשבית את החלפת הקוד של נציג האפליקציה. מידע נוסף זמין בהוראות ל-SwiftUI.

    SwiftUI

    @main
struct YourApp: App {
  // register app delegate for Firebase setup
  @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

שימוש במסוף Firebase

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

שימוש ב-iOS Builder API

אפשר להשתמש ב-iOS Builder API כדי ליצור Dynamic Links מפרמטרים, או כדי לקצר Dynamic Link ארוך.

כדי ליצור Dynamic Link, יוצרים אובייקט DynamicLinkComponents חדש ומציינים את הפרמטרים של Dynamic Link על ידי הגדרת המאפיינים המתאימים של האובייקט. לאחר מכן, מקבלים את הקישור הארוך מהנכס url של האובייקט, או את הקישור הקצר על ידי קריאה ל-shorten().

בדוגמה המינימלית הבאה נוצר Dynamic Link ארוך ל-https://www.example.com/my-page שנפתח עם אפליקציית iOS ב-iOS והאפליקציה com.example.android ב-Android:

Swift

הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
guard let link = URL(string: "https://www.example.com/my-page") else { return }
let dynamicLinksDomainURIPrefix = "https://example.com/link"
let linkBuilder = DynamicLinkComponents(link: link, domainURIPrefix: dynamicLinksDomainURIPRefix)
linkBuilder.iOSParameters = DynamicLinkIOSParameters(bundleID: "com.example.ios")
linkBuilder.androidParameters = DynamicLinkAndroidParameters(packageName: "com.example.android")

guard let longDynamicLink = linkBuilder.url else { return }
print("The long URL is: \(longDynamicLink)")

Objective-C

הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
NSURL *link = [[NSURL alloc] initWithString:@"https://www.example.com/my-page"];
NSString *dynamicLinksDomainURIPrefix = @"https://example.com/link";
FIRDynamicLinkComponents *linkBuilder = [[FIRDynamicLinkComponents alloc]
                                         initWithLink:link
                                               domainURIPrefix:dynamicLinksDomainURIPrefix];
linkBuilder.iOSParameters = [[FIRDynamicLinkIOSParameters alloc]
                             initWithBundleID:@"com.example.ios"];
linkBuilder.androidParameters = [[FIRDynamicLinkAndroidParameters alloc]
                                 initWithPackageName:@"com.example.android"];

NSLog(@"The long URL is: %@", linkBuilder.url);

כדי ליצור Dynamic Link קצר, יוצרים DynamicLinkComponents באותו אופן ומפעילים את shorten().

כדי ליצור קישור קצר נדרש קריאה לרשת, לכן במקום להחזיר את הקישור ישירות, shorten() מקבל טיפול השלמה (completion handler) שנקרא כשהבקשה מסתיימת. לדוגמה:

Swift

הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
linkBuilder.shorten() { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

Objective-C

הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
[linkBuilder shortenWithCompletion:^(NSURL * _Nullable shortURL,
                                     NSArray<NSString *> * _Nullable warnings,
                                     NSError * _Nullable error) {
  if (error || shortURL == nil) { return; }
  NSLog(@"The short URL is: %@", shortURL);
}];

כברירת מחדל, כתובות Dynamic Links קצרות נוצרות עם סיומת קישורים של 17 תווים, כך שסביר מאוד שלאף אחד לא תהיה אפשרות לנחש Dynamic Link תקין. אם בתרחיש לדוגמה שלכם אין בעיה אם מישהו יזהה קישור קצר, תוכלו להגדיר את המאפיין dynamicLinkComponentsOptions כדי ליצור סיומת באורך הנדרש בלבד כדי שהיא תהיה ייחודית:

Swift

הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
linkBuilder.options = DynamicLinkComponentsOptions()
linkBuilder.options.pathLength = .short
linkBuilder.shorten() { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

Objective-C

הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
linkBuilder.dynamicLinkComponentsOptions = [[FIRDynamicLinkComponentsOptions alloc] init];
linkBuilder.dynamicLinkComponentsOptions.pathLength = FIRShortDynamicLinkPathLengthShort;
[linkBuilder shortenWithCompletion:^(NSURL * _Nullable shortURL,
                                     NSArray<NSString *> * _Nullable warnings,
                                     NSError * _Nullable error) {
  if (error || shortURL == nil) { return; }
  NSLog(@"The short URL is: %@", shortURL);
}];

אפשר להשתמש ב-Dynamic Link Builder API כדי ליצור Dynamic Links עם כל אחד מהפרמטרים הנתמכים. פרטים נוספים זמינים ב הפניית API.

בדוגמה הבאה נוצר Dynamic Link עם כמה פרמטרים נפוצים:

Swift

הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
guard let link = URL(string: "https://www.example.com/my-page") else { return }
let dynamicLinksDomainURIPrefix = "https://example.com/link"
let linkBuilder = DynamicLinkComponents(link: link, domainURIPRefix: dynamicLinksDomainURIPrefix)

linkBuilder.iOSParameters = DynamicLinkIOSParameters(bundleID: "com.example.ios")
linkBuilder.iOSParameters.appStoreID = "123456789"
linkBuilder.iOSParameters.minimumAppVersion = "1.2.3"

linkBuilder.androidParameters = DynamicLinkAndroidParameters(packageName: "com.example.android")
linkBuilder.androidParameters.minimumVersion = 123

linkBuilder.analyticsParameters = DynamicLinkGoogleAnalyticsParameters(source: "orkut",
                                                                       medium: "social",
                                                                       campaign: "example-promo")

linkBuilder.iTunesConnectParameters = DynamicLinkItunesConnectAnalyticsParameters()
linkBuilder.iTunesConnectParameters.providerToken = "123456"
linkBuilder.iTunesConnectParameters.campaignToken = "example-promo"

linkBuilder.socialMetaTagParameters = DynamicLinkSocialMetaTagParameters()
linkBuilder.socialMetaTagParameters.title = "Example of a Dynamic Link"
linkBuilder.socialMetaTagParameters.descriptionText = "This link works whether the app is installed or not!"
linkBuilder.socialMetaTagParameters.imageURL = "https://www.example.com/my-image.jpg"

guard let longDynamicLink = linkBuilder.url else { return }
print("The long URL is: \(longDynamicLink)")

Objective-C

הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
NSURL *link = [[NSURL alloc] initWithString:@"https://www.example.com/my-page"];
NSString *dynamicLinksDomainURIPrefix = @"https://example.com/link";
FIRDynamicLinkComponents *linkBuilder = [[FIRDynamicLinkComponents alloc]
                                         initWithLink:link
                                         domainURIPrefix:dynamicLinksDomainURIPrefix];

linkBuilder.iOSParameters = [[FIRDynamicLinkIOSParameters alloc]
                             initWithBundleID:@"com.example.ios"];
linkBuilder.iOSParameters.appStoreID = @"123456789";
linkBuilder.iOSParameters.minimumAppVersion = @"1.2.3";

linkBuilder.androidParameters = [[FIRDynamicLinkAndroidParameters alloc]
                                 initWithPackageName:@"com.example.android"];
linkBuilder.androidParameters.minimumVersion = 123;

linkBuilder.analyticsParameters = [[FIRDynamicLinkGoogleAnalyticsParameters alloc]
                                   initWithSource:@"orkut"
                                           medium:@"social"
                                         campaign:@"example-promo"];

linkBuilder.iTunesConnectParameters = [[FIRDynamicLinkItunesConnectAnalyticsParameters alloc] init];
linkBuilder.iTunesConnectParameters.providerToken = @"123456";
linkBuilder.iTunesConnectParameters.campaignToken = @"example-promo";

linkBuilder.socialMetaTagParameters = [[FIRDynamicLinkSocialMetaTagParameters alloc] init];
linkBuilder.socialMetaTagParameters.title = @"Example of a Dynamic Link";
linkBuilder.socialMetaTagParameters.descriptionText = @"This link works whether the app is installed or not!";
linkBuilder.socialMetaTagParameters.imageURL = @"https://www.example.com/my-image.jpg";

NSLog(@"The long URL is: %@", linkBuilder.url);

אפשר להגדיר פרמטרים של Dynamic Link באמצעות האובייקטים והמאפיינים הבאים:

DynamicLinkComponents
קישור

הקישור שהאפליקציה תפתח. מציינים כתובת URL שהאפליקציה יכולה לטפל בה. בדרך כלל, זוהי כתובת ה-URL של התוכן או של עומס העבודה (payload) של האפליקציה, שמפעילה לוגיקה ספציפית לאפליקציה (למשל, הקצאת זיכוי למשתמש באמצעות שובר או הצגת מסך קבלת פנים). הקישור הזה חייב להיות כתובת URL בפורמט תקין, עם קידוד כתובת URL תקין, עם HTTP או HTTPS, ולא יכול להיות קישור דינמי אחר.
domainURIPrefix התחילית של כתובת ה-URL ב-Dynamic Link, שאפשר למצוא במסוף Firebase. דומיין Dynamic Link נראה כמו הדוגמאות הבאות: 
https://example.com/link
https://example.page.link
DynamicLinkAndroidParameters
fallbackURL הקישור שייפתח כשהאפליקציה לא מותקנת. מציינים את האפשרות הזו כדי לבצע פעולה אחרת מלהתקין את האפליקציה מחנות Play כשהיא לא מותקנת, למשל לפתוח את גרסת האינטרנט לנייד של התוכן או להציג דף קידום מכירות של האפליקציה.
minimumVersion versionCode של הגרסה המינימלית של האפליקציה שיכולה לפתוח את הקישור. אם האפליקציה המותקנת היא גרסה ישנה יותר, המשתמש מועבר לחנות Play כדי לשדרג את האפליקציה.
DynamicLinkIOSParameters
appStoreID מזהה האפליקציה ב-App Store, שמשמש לשליחת משתמשים ל-App Store כשהאפליקציה לא מותקנת
fallbackURL הקישור שייפתח כשהאפליקציה לא מותקנת. מציינים את האפשרות הזו כדי לבצע פעולה אחרת מלהתקין את האפליקציה מ-App Store כשהיא לא מותקנת, למשל לפתוח את גרסת האינטרנט לנייד של התוכן או להציג דף קידום מכירות של האפליקציה.
customScheme הסכימה של כתובת ה-URL בהתאמה אישית של האפליקציה, אם היא מוגדרת כמשהו אחר מאשר מזהה החבילה של האפליקציה
iPadFallbackURL הקישור שצריך לפתוח ב-iPad כשהאפליקציה לא מותקנת. מציינים את האפשרות הזו כדי לבצע פעולה אחרת מלהתקין את האפליקציה מ-App Store כשהיא לא מותקנת, למשל לפתוח את גרסת האינטרנט של התוכן או להציג דף קידום מכירות של האפליקציה.
iPadBundleID מזהה החבילה של האפליקציה ל-iOS שתשמש לפתוח את הקישור ב-iPad. צריך לחבר את האפליקציה לפרויקט שלכם מהדף Overview במסוף Firebase.
minimumAppVersion מספר הגרסה של הגרסה המינימלית של האפליקציה שיכולה לפתוח את הקישור. הדגל הזה מועבר לאפליקציה כשהיא נפתחת, והאפליקציה צריכה להחליט מה לעשות איתו.
DynamicLinkNavigationInfoParameters
forcedRedirectEnabled אם הערך מוגדר כ-'1', הדף עם התצוגה המקדימה של האפליקציה יודלג כאשר Dynamic Link נפתח, ובמקום זאת תתבצע הפניה אוטומטית לאפליקציה או לחנות. דף התצוגה המקדימה של האפליקציה (מופעל כברירת מחדל) יכול לשלוח משתמשים ליעד המתאים ביותר בצורה מהימנה יותר כשהם פותחים את Dynamic Links באפליקציות. עם זאת, אם אתם מצפים ש-Dynamic Link ייפתח רק באפליקציות שיכולות לפתוח את Dynamic Links בצורה מהימנה בלי הדף הזה, תוכלו להשבית אותו באמצעות הפרמטר הזה. הפרמטר הזה ישפיע על ההתנהגות של Dynamic Link רק ב-iOS.
DynamicLinkSocialMetaTagParameters
כותרת הכותרת שתשמש לשיתוף Dynamic Link בפוסט ברשתות החברתיות.
descriptionText התיאור שישמש כשה-Dynamic Link ישותף בפוסט ברשתות החברתיות.
imageURL כתובת ה-URL של תמונה שקשורה לקישור הזה. התמונה צריכה להיות בגודל 300x200 פיקסלים לפחות, ובגודל של פחות מ-300KB.
DynamicLinkGoogleAnalyticsParameters
source
medium
campaign
term
content		 פרמטרים של ניתוח נתונים ב-Google Play. הפרמטרים האלה (utm_source, ‏ utm_medium,‏ utm_campaign, ‏ utm_term, ‏ utm_content) מועברים לחנות Play ונוספים לעומס הנתונים של הקישור.
DynamicLinkItunesConnectAnalyticsParameters
providerToken
affiliateToken
campaignToken		 פרמטרים של ניתוח נתונים ב-iTunes Connect. הפרמטרים האלה (pt,‏ at, ‏ ct) מועברים ל-App Store.

כדי לקצר Dynamic Link ארוך, מעבירים את Dynamic Link הארוך אל shortenURL(url:options:) יחד עם אובייקט DynamicLinkComponentsOptions אם רוצים ליצור קישור עם סיומת קצרה:

Swift

הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
DynamicLinkComponents.shortenURL(url: longLinkUrl, options: nil) { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

Objective-C

הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
[FIRDynamicLinkComponents shortenURL:longLinkUrl
                             options:nil
                          completion:^(NSURL * _Nullable shortURL,
                                       NSArray<NSString *> * _Nullable warnings,
                                       NSError * _Nullable error) {
  if (error || shortURL == nil) { return; }
  NSLog(@"The short URL is: %@", shortURL);
}];

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

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

  1. כשמגדירים את האפליקציה, חשוב לציין את הסכימה שמוגדרת כברירת מחדל לכתובות ה-URL שבהן האפליקציה תשתמש, לפני שמגדירים את המכונה המשותפת של FirebaseApp:

    Swift

    הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
    func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication
                   .LaunchOptionsKey: Any]?) -> Bool {
  // Set deepLinkURLScheme to the custom URL scheme you defined in your
  // Xcode project.
  FirebaseOptions.defaultOptions()?.deepLinkURLScheme = customURLScheme
  FirebaseApp.configure()

  return true
}

    Objective-C

    הערה: מוצר Firebase הזה לא זמין ביעדים macOS,‏ Mac Catalyst,‏ tvOS או watchOS. 
    - (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // Set deepLinkURLScheme to the custom URL scheme you defined in your
  // Xcode project.
  [FIROptions defaultOptions].deepLinkURLScheme = CUSTOM_URL_SCHEME;
  [FIRApp configure];

  return YES;
}
  2. בכל פעם שיוצרים Dynamic Link, צריך לציין את הסכימה המותאמת אישית של כתובות ה-URL שבה האפליקציה משתמשת. אפשר לעשות זאת דרך מסוף Firebase, להגדיר את customScheme ב-Builder API, לציין את הפרמטר ius בכתובת ה-URL או לשלוח את הפרמטר iosCustomScheme ל-API ל-REST.

השלבים הבאים

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

כדי לקבל את Dynamic Links באפליקציה, אפשר לעיין במסמכים למפתחים של iOS,‏ Android,‏ C++‎ ו-Unity.