יצירת קישורים דינמיים ב-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.

הגדרת Firebase ו-Dynamic Links SDK

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

1. ב-Xcode, כשפרויקט האפליקציה פתוח, עוברים אל קובץ > הוספת חבילות.
2. כשמופיעה בקשה, מוסיפים את המאגר של Firebase SDK לפלטפורמות של Apple:

  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 מפרמטרים

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

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

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

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) שנקרא כשהבקשה מסתיימת. לדוגמה:

linkBuilder.shorten() { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

[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 כדי ליצור סיומת באורך הנדרש בלבד כדי שהיא תהיה ייחודית:

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

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

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

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

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

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 באמצעות האובייקטים והמאפיינים הבאים:

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

קיצור סרטון Dynamic Link ארוך

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

DynamicLinkComponents.shortenURL(url: longLinkUrl, options: nil) { url, warnings, error in
  guard let url = url, error != nil else { return }
  print("The short URL is: \(url)")
}

[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);
}];

ציון סכימה מותאמת אישית של כתובת URL עבור Dynamic Links

כברירת מחדל, 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.