تلقّي الروابط الديناميكية على نظام التشغيل 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) لمنصّات Apple من Firebase عندما يُطلب منك ذلك:

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

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

   تستخدِم حزمة Dynamic Links SDK تلقائيًا لوحة اللصق لتحسين موثوقية الروابط لصفحات معيّنة في التطبيق بعد التثبيت. باستخدام لوحة اللصق، 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 وضبطه على إعدادات Dynamic Links بادئات عناوين URL على سبيل المثال:

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

   إذا لم يتم العثور على 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<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;
   }