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

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

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

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

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

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

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

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

3. اختَر مكتبة Dynamic Links.
4. أضِف العلامة -ObjC إلى قسم علامات الرابط الأخرى في إعدادات الإصدار للهدف.
5. للحصول على أفضل تجربة مع Dynamic Links، ننصحك بتفعيل Google Analytics في مشروع Firebase وإضافة Firebase SDK لخدمة "إحصاءات Google" إلى تطبيقك. يمكنك اختيار المكتبة بدون جمع معرّف المعلِنين (IDFA) أو مع جمع معرّف المعلِنين (IDFA). راجِع الأسئلة الشائعة حول الـ أحدث تنظيم للوحدات في الـ Google Analytics لحزمة تطوير البرامج (SDK) من 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 باستخدام نطاق مخصّص بالكامل، أنشِئ مفتاحًا باسم FirebaseDynamicLinksCustomDomains في ملف Info.plist في مشروع Xcode واضبطه على بادئات عنوان 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;
   }