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

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

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

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

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

  1. في Xcode، بعد فتح مشروع تطبيقك، انتقِل إلى ملف > إضافة حِزم.
  2. عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصة Firebase على أجهزة Apple:
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. اختَر مكتبة Dynamic Links.
  4. أضِف العلامة -ObjC إلى قسم علامات الربط الأخرى في إعدادات الإصدار الخاص بالكائن المستهدَف.
  5. للحصول على أفضل تجربة مع Dynamic Links، ننصحك بتفعيل Google Analytics في مشروعك على Firebase وإضافة حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" على Firebase إلى تطبيقك. يمكنك اختيار المكتبة بدون جمع معرّف المعلِن أو مع جمع معرّف المعلِن. اطّلِع على الأسئلة الشائعة حول أحدث تنظيم للوحدات في 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.

  1. في علامة التبويب المعلومات (Info) الخاصة بمشروع 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;
}