إنشاء روابط ديناميكية في تطبيق Flutter

يمكنك إنشاء روابط ديناميكية قصيرة أو طويلة باستخدام واجهة برمجة التطبيقات Firebase Dynamic Links Builder API. تقبل واجهة برمجة التطبيقات هذه رابطًا ديناميكيًا طويلاً أو عنصرًا يحتوي على مَعلمات الرابط الديناميكي، وتُرجع عناوين URL مثل الأمثلة التالية:

https://example.com/link/WXYZ
https://example.page.link/WXYZ

إعداد Firebase وحزمة تطوير البرامج (SDK) لروابط Dynamic Links

قبل أن تتمكّن من إنشاء روابط ديناميكية في تطبيق Android، عليك تضمين حزمة تطوير البرامج (SDK) لمنصّة Firebase. إذا تم إعداد تطبيقك لتلقّي الروابط الديناميكية، يعني ذلك أنّك سبق أن اكتملت هذه الخطوات ويمكنك تخطّي هذا القسم.

ثبِّت حِزم تطوير البرامج (SDK) لمنصّة Firebase لنظام التشغيل Flutter وابدأ إعدادها إذا لم يسبق لك إجراء ذلك.
من الدليل الجذر لمشروع Flutter، شغِّل الرمز التالي لتركيب المكوّن الإضافي "روابط ديناميكية":
```
flutter pub add firebase_dynamic_links
```
إذا كنت بصدد إنشاء تطبيق Android، افتح صفحة إعدادات المشروع في "وحدة تحكّم Firebase" وتأكَّد من تحديد مفتاح التوقيع SHA-1. إذا كنت تستخدم ميزة "روابط التطبيقات"، حدِّد أيضًا مفتاح SHA-256.
في وحدة تحكُّم Firebase، افتح قسم الروابط الديناميكية.
1. إذا لم يسبق لك إعداد نطاق للروابط الديناميكية، انقر على الزر البدء واتّبِع التعليمات.
  
  إذا كان لديك نطاق "روابط ديناميكية"، عليك تدوينه. عليك تقديم نطاق "روابط ديناميكية" عند إنشاء روابط ديناميكية آليًا.
2. إجراء مقترَح: من قائمة "المزيد" (&vellip;)، حدِّد أنماط عناوين URL المسموحة في روابط الصفحات والروابط الاحتياطية. وبهذا الإجراء، تمنع الجهات غير المصرّح لها من إنشاء روابط ديناميكية تعيد توجيهك من نطاقك إلى مواقع إلكترونية لا تملكها. راجِع السماح بأنماط عناوين URL معيّنة.

إنشاء رابط ديناميكي من المَعلمات

لإنشاء رابط ديناميكي، أنشئ عنصرًا جديدًا من النوع DynamicLinkParameters وأرسِله إلى buildLink() أو buildShortLink().

في المثال التالي البسيط، يتم إنشاء رابط ديناميكي طويل يؤدي إلى https://www.example.com/ الذي يتم فتحه باستخدام com.example.app.android على Android والتطبيق com.example.app.ios على iOS:

final dynamicLinkParams = DynamicLinkParameters(
  link: Uri.parse("https://www.example.com/"),
  uriPrefix: "https://example.page.link",
  androidParameters: const AndroidParameters(packageName: "com.example.app.android"),
  iosParameters: const IOSParameters(bundleId: "com.example.app.ios"),
);
final dynamicLink =
    await FirebaseDynamicLinks.instance.buildLink(dynamicLinkParams);

لإنشاء رابط ديناميكي قصير، مرِّر عنصر DynamicLinkParameters إلى buildShortLink(). يتطلب إنشاء الرابط القصير طلب اتصال بالشبكة. على سبيل المثال:

final dynamicLinkParams = DynamicLinkParameters(
  link: Uri.parse("https://www.example.com/"),
  uriPrefix: "https://example.page.link",
  androidParameters: const AndroidParameters(packageName: "com.example.app.android"),
  iosParameters: const IOSParameters(bundleId: "com.example.app.ios"),
);
final dynamicLink =
    await FirebaseDynamicLinks.instance.buildShortLink(dynamicLinkParams);

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

ومع ذلك، إذا كانت الروابط القصيرة تؤدي إلى معلومات خاصة بالمستخدم، يجب إنشاء روابط أطول تحتوي على لاحقات من 17 حرفًا تجعل من غير المرجّح أن يتمكن أحدهم من تخمين رابط ديناميكي صالح. لإجراء ذلك، عليك تمرير ShortDynamicLinkType.unguessable إلى طريقة buildShortLink():

final unguessableDynamicLink = await FirebaseDynamicLinks.instance.buildShortLink(
    dynamicLinkParams,
    shortLinkType: ShortDynamicLinkType.unguessable,
);

مَعلمات الروابط الديناميكية

يمكنك استخدام واجهة برمجة التطبيقات Dynamic Link Builder API لإنشاء روابط ديناميكية باستخدام أيٍّ من المَعلمات المتوافقة. اطّلِع على مرجع واجهة برمجة التطبيقات.

ينشئ المثال التالي رابطًا ديناميكيًا يتضمّن عدة مَعلمات شائعة:

final dynamicLinkParams = DynamicLinkParameters(
  link: Uri.parse("https://www.example.com/"),
  uriPrefix: "https://example.page.link",
  androidParameters: const AndroidParameters(
    packageName: "com.example.app.android",
    minimumVersion: 30,
  ),
  iosParameters: const IOSParameters(
    bundleId: "com.example.app.ios",
    appStoreId: "123456789",
    minimumVersion: "1.0.1",
  ),
  googleAnalyticsParameters: const GoogleAnalyticsParameters(
    source: "twitter",
    medium: "social",
    campaign: "example-promo",
  ),
  socialMetaTagParameters: SocialMetaTagParameters(
    title: "Example of a Dynamic Link",
    imageUrl: Uri.parse("https://example.com/image.png"),
  ),
);
final dynamicLink =
    await FirebaseDynamicLinks.instance.buildShortLink(dynamicLinkParams);

يمكنك ضبط مَعلمات الروابط الديناميكية باستخدام الطريقتَين التاليتَين:

مَعلمات DynamicLink
setLink	الرابط الذي سيفتحه تطبيقك حدِّد عنوان URL يمكن لتطبيقك التعامل معه، وهو عادةً محتوى التطبيق أو الحمولة، ما يؤدي إلى بدء منطق متعلق بالتطبيق (مثل إضافة قسيمة إلى رصيد المستخدم أو عرض شاشة مرحبًا). يجب أن يكون هذا الرابط عنوان URL بتنسيق جيد، ويجب أن يكون مُشفَّرًا بشكل صحيح، ويجب أن يستخدم إما HTTP أو HTTPS، ولا يمكن أن يكون رابطًا ديناميكيًا آخر. عندما يفتح المستخدمون رابطًا ديناميكيًا على متصفّح ويب على كمبيوتر مكتبي، سيتم تحميل عنوان URL هذا (ما لم يتم تحديد المَعلمة ofl). إذا لم يكن لديك محتوى ويب مكافئ للمحتوى المرتبط، ليس بحاجة عنوان URL إلى الإشارة إلى مورد ويب صالح. في هذه الحالة، عليك إعداد عملية إعادة توجيه من عنوان URL هذا إلى صفحتك الرئيسية، على سبيل المثال.
setDomainUriPrefix	بادئة عنوان URL الخاص بـ "الروابط الديناميكية"، والتي يمكنك العثور عليها في وحدة تحكّم Firebase أ يبدو نطاق الروابط الديناميكية مثل الأمثلة التالية: https://example.com/link https://example.page.link

مَعلمات DynamicLink

setLink

الرابط الذي سيفتحه تطبيقك حدِّد عنوان URL يمكن لتطبيقك التعامل معه، وهو عادةً محتوى التطبيق أو الحمولة، ما يؤدي إلى بدء منطق متعلق بالتطبيق (مثل إضافة قسيمة إلى رصيد المستخدم أو عرض شاشة مرحبًا). يجب أن يكون هذا الرابط عنوان URL بتنسيق جيد، ويجب أن يكون مُشفَّرًا بشكل صحيح، ويجب أن يستخدم إما HTTP أو HTTPS، ولا يمكن أن يكون رابطًا ديناميكيًا آخر.

setDomainUriPrefix

بادئة عنوان URL الخاص بـ "الروابط الديناميكية"، والتي يمكنك العثور عليها في وحدة تحكّم Firebase أ يبدو نطاق الروابط الديناميكية مثل الأمثلة التالية:

https://example.com/link
https://example.page.link

AndroidParameters
setFallbackUrl	الرابط الذي يتم فتحه عندما لا يكون التطبيق مثبّتًا حدِّد هذا الخيار لتنفيذ مهمة أخرى غير تثبيت تطبيقك من "متجر Play" عندما يكون التطبيق غير مثبَّت، مثل فتح إصدار الويب المتوافق مع الأجهزة الجوّالة للمحتوى أو عرض صفحة ترويجية لتطبيقك.
setMinimumVersion	رمز الإصدار الخاص بالحد الأدنى لإصدار تطبيقك الذي يمكنه فتح الرابط. إذا كان التطبيق المثبَّت هو إصدار قديم، يتم نقل المستخدم إلى "متجر Play" لترقية التطبيق.

AndroidParameters

setFallbackUrl

الرابط الذي يتم فتحه عندما لا يكون التطبيق مثبّتًا حدِّد هذا الخيار لتنفيذ مهمة أخرى غير تثبيت تطبيقك من "متجر Play" عندما يكون التطبيق غير مثبَّت، مثل فتح إصدار الويب المتوافق مع الأجهزة الجوّالة للمحتوى أو عرض صفحة ترويجية لتطبيقك.

setMinimumVersion

رمز الإصدار الخاص بالحد الأدنى لإصدار تطبيقك الذي يمكنه فتح الرابط. إذا كان التطبيق المثبَّت هو إصدار قديم، يتم نقل المستخدم إلى "متجر Play" لترقية التطبيق.

IosParameters
setAppStoreId	رقم تعريف تطبيقك على "متجر التطبيقات"، والذي يُستخدَم لإرسال المستخدمين إلى "متجر التطبيقات" عندما لا يكون التطبيق مثبّتًا
setFallbackUrl	الرابط الذي يتم فتحه عندما لا يكون التطبيق مثبّتًا حدِّد هذا الخيار لتنفيذ مهمة أخرى غير تثبيت تطبيقك من App Store عندما يكون التطبيق غير مثبّت، مثل فتح إصدار الويب المتوافق مع الأجهزة الجوّالة من المحتوى أو عرض صفحة ترويجية لتطبيقك.
setCustomScheme	مخطّط عنوان URL المخصّص لتطبيقك، إذا تم تحديده ليكون مختلفًا عن معرّف حزمة تطبيقك
setIpadFallbackUrl	الرابط المراد فتحه على أجهزة iPad عندما لا يكون التطبيق مثبّتًا حدِّد هذا الخيار للقيام بإجراء آخر غير تثبيت تطبيقك من App Store عندما يكون التطبيق غير مثبَّت، مثل فتح إصدار الويب من المحتوى أو عرض صفحة ترويجية لتطبيقك.
setIpadBundleId	رقم تعريف حزمة تطبيق iOS المطلوب استخدامه على أجهزة iPad لفتح الرابط يجب ربط التطبيق بمشروعك من صفحة "نظرة عامة" في وحدة تحكّم Firebase.
setMinimumVersion	رقم إصدار الحد الأدنى لإصدار تطبيقك الذي يمكنه فتح الرابط. يتم تمرير هذا العلامة إلى تطبيقك عند فتحه، وعلى تطبيقك تحديد الإجراء الذي يجب اتّخاذه بشأنها.

NavigationInfoParameters
setForcedRedirectEnabled	في حال ضبط القيمة على "1"، سيتم تخطّي صفحة معاينة التطبيق عند فتح الرابط الديناميكي وسيتم بدلاً من ذلك إعادة التوجيه إلى التطبيق أو المتجر. يمكن لصفحة معاينة التطبيق (المفعّلة تلقائيًا) إرسال المستخدمين بشكل أكثر موثوقية إلى الوجهة الأنسب عند فتح الروابط الديناميكية في التطبيقات. ومع ذلك، إذا كنت تتوقّع أن يتم فتح رابط ديناميكي فقط في التطبيقات التي يمكنها فتح الروابط الديناميكية بشكل موثوق بدون هذه الصفحة، يمكنك إيقافها باستخدام هذه المَعلمة ستؤثّر هذه المَعلمة في سلوك الرابط الديناميكي على أجهزة iOS فقط.

NavigationInfoParameters

setForcedRedirectEnabled

في حال ضبط القيمة على "1"، سيتم تخطّي صفحة معاينة التطبيق عند فتح الرابط الديناميكي وسيتم بدلاً من ذلك إعادة التوجيه إلى التطبيق أو المتجر. يمكن لصفحة معاينة التطبيق (المفعّلة تلقائيًا) إرسال المستخدمين بشكل أكثر موثوقية إلى الوجهة الأنسب عند فتح الروابط الديناميكية في التطبيقات. ومع ذلك، إذا كنت تتوقّع أن يتم فتح رابط ديناميكي فقط في التطبيقات التي يمكنها فتح الروابط الديناميكية بشكل موثوق بدون هذه الصفحة، يمكنك إيقافها باستخدام هذه المَعلمة ستؤثّر هذه المَعلمة في سلوك الرابط الديناميكي على أجهزة iOS فقط.

SocialMetaTagParameters
setTitle	العنوان الذي سيتم استخدامه عند مشاركة الرابط الديناميكي في مشاركة على وسائل التواصل الاجتماعي.
setDescription	الوصف الذي سيتم استخدامه عند مشاركة الرابط الديناميكي في مشاركة على وسائل التواصل الاجتماعي.
setImageUrl	عنوان URL لصورة ذات صلة بهذا الرابط يجب أن تكون الصورة بحجم 300 × 200 بكسل على الأقل وبحجم أقل من 300 كيلوبايت.

GoogleAnalyticsParameters
setSource setMedium setCampaign setTerm setContent	مَعلمات إحصاءات Google Play يتمّ نقل هذه المَعلمات (`utm_source` و`utm_medium` و`utm_campaign` و`utm_term` و`utm_content`) إلى "متجر Play" بالإضافة إلى إلحاقها بحمولة الرابط.

ItunesConnectAnalyticsParameters
setProviderToken setAffiliateToken setCampaignToken	مَعلمات إحصاءات iTunes Connect يتم تمرير هذه المَعلمات ("pt"، "at"، "ct") إلى App Store.