יצירת קישורים דינמיים ב-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. כשמוצגת בקשה, מוסיפים את מאגר Firebase Apple platforms SDK:
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. בוחרים את הספרייה Dynamic Links.
  4. מוסיפים את הדגל -ObjC לקטע Other Linker Flags בהגדרות הבנייה של היעד.
  5. כדי ליהנות מחוויה אופטימלית עם Dynamic Links, מומלץ להפעיל את Google Analytics בפרויקט Firebase ולהוסיף את Firebase SDK for Google Analytics לאפליקציה. אפשר לבחור בספרייה ללא איסוף של IDFA או עם איסוף של IDFA. אפשר לעיין בשאלות הנפוצות בנושא הארגון העדכני של מודולים ב-Google Analytics עבור Firebase SDK.
  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 מהדומיין הבסיסי (root) וגם מספריית המשנה .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 אחרים שמשמשים את נציג האפליקציה. לדוגמה, כדי להשתמש ב-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);

כדי ליצור סרטון Shorts 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 הקישור לפתיחה באייפדים כשהאפליקציה לא מותקנת. אפשר לציין פעולה אחרת במקום התקנת האפליקציה מ-App Store אם האפליקציה לא מותקנת, כמו פתיחת גרסת האינטרנט של התוכן או הצגת דף קידום מכירות של האפליקציה.
iPadBundleID מזהה החבילה של אפליקציית iOS שבה רוצים להשתמש באייפדים כדי לפתוח את הקישור. האפליקציה צריכה להיות מקושרת לפרויקט שלכם בדף 'סקירה כללית' בFirebaseמסוף.
minimumAppVersion מספר הגרסה של הגרסה המינימלית של האפליקציה שבה אפשר לפתוח את הקישור. הדגל הזה מועבר לאפליקציה כשפותחים אותה, והאפליקציה צריכה להחליט מה לעשות איתו.
DynamicLinkNavigationInfoParameters
forcedRedirectEnabled אם הערך מוגדר כ-1, כשפותחים את Dynamic Link, המערכת מדלגת על דף התצוגה המקדימה של האפליקציה ומפנה את המשתמש לאפליקציה או לחנות. דף התצוגה המקדימה של האפליקציה (מופעל כברירת מחדל) יכול לשלוח משתמשים בצורה מהימנה יותר ליעד המתאים ביותר כשהם פותחים Dynamic Links באפליקציות. עם זאת, אם אתם מצפים ש-Dynamic Links ייפתח רק באפליקציות שיכולות לפתוח Dynamic Links בצורה מהימנה בלי הדף הזה, אתם יכולים להשבית אותו באמצעות הפרמטר הזה.Dynamic Link הפרמטר הזה ישפיע על ההתנהגות של 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 מותאמת אישית למטרות אחרות, יכולים להשתמש באותה סכמת כתובות 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 ל-REST API.

השלבים הבאים

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

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