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