تلقّي "روابط 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، عليك إضافة فلتر أهداف جديد لتلقّي الروابط المؤدية إلى صفحات معيّنة في نطاقك، لأنّ الرابط الديناميكي سيعيد التوجيه إلى نطاقك إذا كان تطبيقك مثبّتًا. ويجب توفُّر هذا الإعداد لكي يتلقّى تطبيقك بيانات 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>

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

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

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

      أما الجانب السلبي لذلك، فهو أنّ استخدام الحافظة يؤدي إلى ظهور إشعار على نظام التشغيل 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.)، إذا كنت تختبر رابطًا ديناميكيًا من حالة تطبيق تم إنهاؤها (أي تم إغلاق التطبيق عن طريق التمرير السريع).