تلقّي الروابط الديناميكية على نظام التشغيل iOS

لتلقّي Firebase Dynamic Links الذي أنشأته، يجب تضمين حزمة تطوير البرامج (SDK) لـ Dynamic Links في تطبيقك واستدعاء الطريقتين handleUniversalLink: وdynamicLinkFromCustomSchemeURL: عند تحميل تطبيقك للحصول على البيانات التي تم تمريرها في Dynamic Link.

المتطلبات الأساسية

قبل البدء، تأكَّد من إضافة Firebase إلى مشروعك على iOS.

إعداد Firebase وحزمة تطوير البرامج (SDK) لـ "Dynamic Links"

استخدِم أداة Swift Package Manager لتثبيت تبعيات Firebase وإدارتها.

1. في Xcode، افتح مشروع تطبيقك، ثم انتقِل إلى ملف > إضافة حِزم (File > Add Packages).
2. عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصات Apple في Firebase:

  https://github.com/firebase/firebase-ios-sdk.git

3. اختَر مكتبة "Dynamic Links".
4. أضِف العلامة -ObjC إلى قسم علامات الربط الأخرى (Other Linker Flags) في إعدادات الإنشاء الخاصة بالهدف.
5. للحصول على تجربة مثالية مع Dynamic Links، ننصحك بتفعيل Google Analytics في مشروع Firebase وإضافة Firebase SDK لمنصّة "إحصاءات Google" إلى تطبيقك. يمكنك اختيار المكتبة التي لا تتضمّن جمع معرّف المعلِنين (IDFA) أو التي تتضمّن جمع معرّف المعلِنين (IDFA). يمكنك الاطّلاع على الأسئلة الشائعة حول أحدث تنظيم للوحدات في حزمة تطوير البرامج (SDK) لمنصّة Google Analytics لبرنامج Firebase.
6. بعد الانتهاء، سيبدأ Xcode تلقائيًا في حلّ التبعيات وتنزيلها في الخلفية.

بعد ذلك، نفِّذ بعض خطوات الضبط:

1. في وحدة تحكّم Firebase، افتح قسم Dynamic Links. اقبل بنود الخدمة إذا طُلب منك ذلك.

2. تأكَّد من تحديد معرّف App Store لتطبيقك وبادئة معرّف التطبيق في إعدادات تطبيقك. لعرض إعدادات تطبيقك وتعديلها، انتقِل إلى صفحة الإعدادات في مشروع Firebase واختَر تطبيق iOS.

   يمكنك التأكّد من أنّ مشروع Firebase الخاص بك تم إعداده بشكل صحيح لاستخدام Dynamic Links في تطبيق iOS من خلال فتح عنوان URL التالي:

   https://your_dynamic_links_domain/apple-app-site-association

   إذا كان تطبيقك مرتبطًا، يحتوي ملف apple-app-site-association على مرجع لبادئة معرّف التطبيق ومعرّف الحزمة. على سبيل المثال:

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

   إذا كان حقل details فارغًا، تأكَّد من تحديد بادئة رقم تعريف التطبيق. يُرجى العِلم أنّ بادئة رقم تعريف التطبيق قد لا تكون مماثلة لرقم تعريف الفريق.

3. اختياري: يمكنك إيقاف استخدام حزمة تطوير البرامج (SDK) لـ Dynamic Links للوح اللصق في نظام التشغيل iOS.

   تستخدم حزمة تطوير البرامج (SDK) لـ "Dynamic Links" تلقائيًا لوحة اللصق لتحسين موثوقية الروابط العميقة بعد التثبيت. باستخدام لوحة اللصق، يمكن لـ Dynamic Links التأكّد من أنّه عندما يفتح المستخدم Dynamic Link ولكن يحتاج إلى تثبيت تطبيقك أولاً، يمكنه الانتقال فورًا إلى المحتوى الأصلي المرتبط عند فتح التطبيق للمرة الأولى بعد التثبيت.

   الجانب السلبي لذلك هو أنّ استخدام لوحة اللصق يؤدي إلى ظهور إشعار على نظام التشغيل iOS 14 والإصدارات الأحدث. لذلك، في المرة الأولى التي يفتح فيها المستخدمون تطبيقك، إذا كان لوح اللصق يحتوي على عنوان URL، سيظهر لهم إشعار بأنّ تطبيقك قد وصل إلى لوح اللصق، ما قد يؤدي إلى حدوث ارتباك.

   لإيقاف هذا السلوك، عدِّل ملف Info.plist لمشروع Xcode واضبط مفتاح FirebaseDeepLinkPasteboardRetrievalEnabled على NO.

فتح "Dynamic Links" في تطبيقك

1. في علامة التبويب معلومات ضمن مشروع Xcode الخاص بتطبيقك، أنشئ نوع عنوان URL جديدًا لاستخدامه في Dynamic Links. اضبط حقل المعرّف على قيمة فريدة وحقل مخطّط URL على معرّف الحزمة، وهو مخطّط URL التلقائي الذي يستخدمه Dynamic Links.
2. في علامة التبويب الإمكانات لمشروع Xcode الخاص بتطبيقك، فعِّل "النطاقات المرتبطة" وأضِف ما يلي إلى قائمة النطاقات المرتبطة:

   applinks:your_dynamic_links_domain

3. إذا أردت تلقّي Dynamic Links باستخدام نطاق مخصّص بالكامل، في ملف Info.plist لمشروع Xcode، أنشئ مفتاحًا باسم FirebaseDynamicLinksCustomDomains واضبطه على بادئات عناوين URL Dynamic Links لتطبيقك. على سبيل المثال:

   FirebaseDynamicLinksCustomDomains
   
     https://example.com/promos
     https://example.com/links/share
   

4. استورِد وحدة 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;
   // ...
         

5. اضبط مثيلاً مشتركًا من النوع 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];

6. إذا كنت تستخدم 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()
         }
       }
     }
   }
         

7. بعد ذلك، في طريقة application:continueUserActivity:restorationHandler: ، يمكنك معالجة الروابط التي يتم تلقّيها على أنّها روابط عامة عندما يكون التطبيق مثبّتًا:

   Swift

   ملاحظة: لا يتوفّر هذا المنتج على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS.

   func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
     let handled = DynamicLinks.dynamicLinks()
       .handleUniversalLink(userActivity.webpageURL!) { dynamiclink, error in
         // ...
       }
   
     return handled
   }

   Objective-C

   ملاحظة: لا يتوفّر هذا المنتج على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS.

   - (BOOL)application:(UIApplication *)application
   continueUserActivity:(nonnull NSUserActivity *)userActivity
    restorationHandler:
   #if defined(__IPHONE_12_0) && (__IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_12_0)
   (nonnull void (^)(NSArray<id> *_Nullable))restorationHandler {
   #else
       (nonnull void (^)(NSArray *_Nullable))restorationHandler {
   #endif  // __IPHONE_12_0
     BOOL handled = [[FIRDynamicLinks dynamicLinks] handleUniversalLink:userActivity.webpageURL
                                                             completion:^(FIRDynamicLink * _Nullable dynamicLink,
                                                                          NSError * _Nullable error) {
                                                               // ...
                                                             }];
     return handled;
   }

8. أخيرًا، في application:openURL:options:، يمكنك معالجة الروابط التي يتم تلقّيها من خلال مخطّط URL مخصّص لتطبيقك. يتم استدعاء هذه الطريقة عند فتح تطبيقك لأول مرة بعد التثبيت.

   إذا لم يتم العثور على Dynamic Link عند تشغيل تطبيقك لأول مرة، سيتم استدعاء هذه الطريقة مع ضبط url في DynamicLink على nil، ما يشير إلى أنّ حزمة تطوير البرامج (SDK) لم تنجح في العثور على Dynamic Link معلّق مطابق.

   Swift

   ملاحظة: لا يتوفّر هذا المنتج على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS.

   @available(iOS 9.0, *)
   func application(_ app: UIApplication, open url: URL,
                    options: [UIApplication.OpenURLOptionsKey: Any]) -> Bool {
     return application(app, open: url,
                        sourceApplication: options[UIApplication.OpenURLOptionsKey
                          .sourceApplication] as? String,
                        annotation: "")
   }
   
   func application(_ application: UIApplication, open url: URL, sourceApplication: String?,
                    annotation: Any) -> Bool {
     if let dynamicLink = DynamicLinks.dynamicLinks().dynamicLink(fromCustomSchemeURL: url) {
       // Handle the deep link. For example, show the deep-linked content or
       // apply a promotional offer to the user's account.
       // ...
       return true
     }
     return false
   }

   Objective-C

   ملاحظة: لا يتوفّر هذا المنتج على أهداف macOS أو Mac Catalyst أو tvOS أو watchOS.

   - (BOOL)application:(UIApplication *)app
               openURL:(NSURL *)url
               options:(NSDictionary *)options {
     return [self application:app
                      openURL:url
            sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]
                   annotation:options[UIApplicationOpenURLOptionsAnnotationKey]];
   }
   
   - (BOOL)application:(UIApplication *)application
               openURL:(NSURL *)url
     sourceApplication:(NSString *)sourceApplication
            annotation:(id)annotation {
     FIRDynamicLink *dynamicLink = [[FIRDynamicLinks dynamicLinks] dynamicLinkFromCustomSchemeURL:url];
   
     if (dynamicLink) {
       if (dynamicLink.url) {
         // Handle the deep link. For example, show the deep-linked content,
         // apply a promotional offer to the user's account or show customized onboarding view.
         // ...
       } else {
         // Dynamic link has empty deep link. This situation will happens if
         // Firebase Dynamic Links iOS SDK tried to retrieve pending dynamic link,
         // but pending link is not available for this device/App combination.
         // At this point you may display default onboarding view.
       }
       return YES;
     }
     return NO;
   }