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

لتلقي روابط Firebase الديناميكية التي أنشأتها، يجب عليك تضمين حزمة SDK للروابط الديناميكية في تطبيقك وطلب الطريقتين handleUniversalLink: وdynamicLinkFromCustomSchemeURL: عند تحميل تطبيقك للحصول على البيانات التي يتم تمريرها في الرابط الديناميكي.

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

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

إعداد Firebase وحزمة تطوير البرامج (SDK) للروابط الديناميكية

يمكنك استخدام "مدير حزم Swift" لتثبيت اعتماديات Firebase وإدارتها.

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

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

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

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

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

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

   يمكنك التأكّد من إعداد مشروع Firebase بشكل صحيح لاستخدام الروابط الديناميكية في تطبيق 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) للروابط الديناميكية للوحة لصق iOS.

   بشكلٍ تلقائي، تستخدم حزمة تطوير البرامج (SDK) للروابط الديناميكية لوحة اللصق لتحسين موثوقية الروابط لصفحات في التطبيق بعد التثبيت. باستخدام لوحة اللصق، تضمن الروابط الديناميكية إمكانية انتقال المستخدم فورًا إلى المحتوى المرتبط الأصلي عند فتح التطبيق لأول مرة بعد التثبيت، وذلك عندما يفتح المستخدم رابطًا ديناميكيًا ولكنه يحتاج إلى تثبيت تطبيقك أولاً.

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

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

فتح "الروابط الديناميكية" في تطبيقك

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

   applinks:your_dynamic_links_domain

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

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

4. يمكنك استيراد وحدة FirebaseCore في UIApplicationDelegate، بالإضافة إلى أي وحدات Firebase أخرى يستخدمها المستخدم المفوَّض في تطبيقك. على سبيل المثال، لاستخدام Cloud Firestore والمصادقة:

   واجهة المستخدم

   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:) الخاصة بمفوَّض تطبيقك:

   واجهة المستخدم

   // 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.

   واجهة المستخدم

   @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<UIUserActivityRestoring>> *_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 المخصّصة لتطبيقك. ويتم طلب هذه الطريقة عند فتح تطبيقك للمرّة الأولى بعد تثبيته.

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

   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<NSString *, id> *)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;
   }