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

لتلقّي روابط Firebase الديناميكية التي أنشأتها، يجب تضمين حزمة تطوير البرامج (SDK) لـ "الروابط الديناميكية" في تطبيقك واستدعاء الطريقة FirebaseDynamicLinks.getDynamicLink() عند تحميل تطبيقك للحصول على البيانات التي تم تمريرها في الرابط الديناميكي.

  1. ثبِّت حِزم تطوير البرامج (SDK) لمنصة Firebase الخاصة بـ Flutter وابدأ إعدادها إذا لم يسبق لك إجراء ذلك.

  2. من دليل الجذر لمشروع Flutter، نفِّذ الأمر التالي لتثبيت المكوّن الإضافي "روابط ديناميكية":

    flutter pub add firebase_dynamic_links

  3. إذا كنت بصدد إنشاء تطبيق Android، افتح صفحة إعدادات المشروع في "وحدة تحكّم Firebase" وتأكَّد من أنّك حدّدت مفتاح التوقيع SHA-1. إذا كنت تستخدم روابط التطبيقات، حدِّد أيضًا مفتاح SHA-256.

شريك التكامل

أكمِل خطوات دمج المنصات التالية للمنصات التي تنشئ تطبيقك لها.

Android

على نظام التشغيل Android، عليك إضافة intent filter جديد لتلقّي الروابط المؤدية إلى صفحات معيّنة في نطاقك، لأنّ الرابط الديناميكي سيعيد التوجيه إلى نطاقك إذا كان تطبيقك مثبّتًا. ويجب توفُّر هذا الإذن لكي يتلقّى تطبيقك بيانات Dynamic Link بعد تثبيته أو تحديثه من "متجر Play" والنقر على الزر "متابعة". في AndroidManifest.xml:

<intent-filter>
    <action android:name="android.intent.action.VIEW"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE"/>
    <data
        android:host="example.com"
        android:scheme="https"/>
</intent-filter>

عندما يفتح المستخدمون رابطًا ديناميكيًا يتضمّن رابطًا لصفحة معيّنة في المخطط والمضيف اللذين تحدّدهما، سيبدأ تطبيقك النشاط باستخدام intent filter هذا للتعامل مع الرابط.

الخطوة التالية هي التأكّد من تسجيل الملف المرجعي لشهادة SHA-256 في وحدة تحكّم Firebase للتطبيق. يمكنك العثور على مزيد من التفاصيل حول كيفية استرداد الملف المرجعي لشهادة SHA-256 في صفحة مصادقة العميل.

منصات Apple

  1. أنشئ حساب مطوّر على Apple إذا لم يكن لديك حساب.

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

  3. على موقع Apple Developer الإلكتروني، أنشئ ملفًا تعريفيًا للتزويد لتطبيقك مع تفعيل إمكانية "النطاقات المرتبطة".

  4. في Xcode، اتّبِع الخطوات التالية:

    1. افتح تطبيقك ضمن العنوان الاستهدافات.

    2. في صفحة "التوقيع والإمكانات" (Signing & Capabilities)، تأكَّد من تسجيل فريقك وضبط ملف الإعداد (Provisioning Profile).

    3. في صفحة Signing & Capabilities، فعِّل النطاقات المرتبطة (Associated Domains) وأضِف ما يلي إلى قائمة النطاقات المرتبطة (Associated Domains) (استبدِل example بنطاقك):

      applinks:example.page.link

    4. في صفحة "المعلومات"، أضِف "نوع عنوان URL" إلى مشروعك. اضبط حقل "مخططات عناوين URL" (URL Schemes) على معرّف حزمة تطبيقك. (يمكن أن يكون المعرّف Bundle ID أو أي قيمة أخرى تريدها).

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

      <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>FirebaseDynamicLinksCustomDomains</key>
<array>
    <string>https://custom.domain.io/path1</string>
    <string>https://custom.domain.io/path2</string>
</array>

...other settings

</dict>
</plist>

    6. اختياري: أوقِف استخدام حزمة تطوير البرامج (SDK) لخدمة Dynamic Links في لوحة النسخ واللصق على أجهزة iOS.

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

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

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

للتعامل مع "رابط ديناميكي" في تطبيقك، يجب تنفيذ سيناريوهَين.

الحالة "تم إنهاؤه"

اضبط الطرق التالية:

  1. ‫FirebaseDynamicLinks.getInitialLink - تعرض Future<PendingDynamicLinkData?>
  2. ‫FirebaseDynamicLinks.onLink: معالج أحداث يعرض Stream يحتوي على PendingDynamicLinkData?

سيتلقّى Android الرابط دائمًا من خلال FirebaseDynamicLinks.getInitialLink من حالة إنهاء، ولكن لا يمكن ضمان ذلك على iOS. لذلك، ننصحك بإعداد كليهما بالترتيب التالي لضمان تلقّي تطبيقك للرابط:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseConfig.platformOptions);

  // Check if you received the link via `getInitialLink` first
  final PendingDynamicLinkData? initialLink = await FirebaseDynamicLinks.instance.getInitialLink();

  if (initialLink != null) {
    final Uri deepLink = initialLink.link;
    // Example of using the dynamic link to push the user to a different screen
    Navigator.pushNamed(context, deepLink.path);
  }

  FirebaseDynamicLinks.instance.onLink.listen(
        (pendingDynamicLinkData) {
          // Set up the `onLink` event listener next as it may be received here
          if (pendingDynamicLinkData != null) {
            final Uri deepLink = pendingDynamicLinkData.link;
            // Example of using the dynamic link to push the user to a different screen
            Navigator.pushNamed(context, deepLink.path);
          }
        },
      );

  runApp(MyApp(initialLink));
}

يمكنك بعد ذلك التحقّق مما إذا تمت معالجة رابط وتنفيذ إجراء معيّن، على سبيل المثال:

if (initialLink != null) {
  final Uri deepLink = initialLink.link;
  // Example of using the dynamic link to push the user to a different screen
  Navigator.pushNamed(context, deepLink.path);
}

حالة التطبيق في الخلفية أو المقدّمة

أثناء فتح التطبيق أو تشغيله في الخلفية، استخدِم FirebaseDynamicLinks.onLink getter:

FirebaseDynamicLinks.instance.onLink.listen((dynamicLinkData) {
  Navigator.pushNamed(context, dynamicLinkData.link.path);
}).onError((error) {
  // Handle errors
});

بدلاً من ذلك، إذا أردت تحديد ما إذا تم استخدام رابط ديناميكي مطابق لفتح التطبيق، يمكنك تمريره إلى الطريقة getDynamicLink بدلاً من ذلك:

String link = 'https://dynamic-link-domain/ke2Qa';

final PendingDynamicLinkData? initialLink = await FirebaseDynamicLinks.instance.getDynamicLink(Uri.parse(link));

لاختبار رابط ديناميكي على iOS، يجب استخدام جهاز فعلي. عليك أيضًا تشغيل التطبيق في وضع الإصدار (أي flutter run --release.)، إذا كنت تختبر رابطًا ديناميكيًا من حالة تطبيق تم إنهاؤها (أي تم إغلاق التطبيق عن طريق التمرير سريعًا).