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

  3. في موقع Apple Developer الإلكتروني، أنشِئ ملفًا شخصيًا لإدارة الحسابات لتطبيقك مع تفعيل إمكانية "النطاق المرتبط".

  4. في Xcode، نفِّذ ما يلي:

    1. افتح تطبيقك أسفل العنوان TARGETS.

    2. في صفحة "التوقيع والإمكانات"، تأكّد من تسجيل فريقك وضبط ملفك الشخصي لإدارة الحسابات.

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

      applinks:example.page.link

    4. في صفحة المعلومات، أضف نوع عنوان URL إلى مشروعك. اضبط حقل مخططات عناوين URL على معرّف حزمة التطبيق. (يمكن أن يكون المعرّف 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. اختياري: أوقِف استخدام "حزمة تطوير البرامج للروابط الديناميكية" للوحة اللصق لنظام التشغيل iOS.

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

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

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