יצירת קישורים דינמיים ב-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, כשהפרויקט של האפליקציה פתוח, עוברים אל File > Add Packages (קובץ > הוספת חבילות).
2. כשמוצגת בקשה, מוסיפים את מאגר ה-SDK של Firebase לפלטפורמות של אפל:

  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. שאלות נפוצות על הארגון העדכני של המודולים ב-Google Analytics for Firebase SDK
6. אחרי שתסיימו, פלטפורמת Xcode תתחיל לטפל ביחסי התלות ולהוריד אותם באופן אוטומטי ברקע.

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

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

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

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

   

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

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

1. מייבאים את המודול FirebaseCore אל UIApplicationDelegate, וגם כל מודול Firebase אחר שבו משתמש ה-app delegate. לדוגמה, כדי להשתמש ב-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 ב-method‏ 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, אתם צריכים ליצור נציג של האפליקציה ולצרף אותו ל-struct של App באמצעות UIApplicationDelegateAdaptor או NSApplicationDelegateAdaptor. צריך גם להשבית את ה-swizzling של נציג האפליקציה. מידע נוסף זמין בהוראות של 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() מקבל 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 בהתאמה אישית למטרות אחרות, יכולים להשתמש באותה סכימה גם ל-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.