Firebase Dynamic Links: ما هو، إنشاء الروابط والدمج

ما هي Firebase Dynamic Links

Firebase Dynamic Links هي تقنية من Google تنشئ رابطاً واحداً يؤدي إلى المحتوى المطلوب في تطبيق جوال أو موقع ويب، مع تكييف السلوك حسب المنصة وحالة التثبيت. يتحقق الرابط مما إذا كان التطبيق مثبتاً على الجهاز: إذا كان كذلك — يفتحه مع تمرير المعلمات، إذا لم يكن — يوجه إلى Google Play أو App Store للتثبيت، وبعد التثبيت يعيد التوجيه إلى الشاشة المستهدفة.

الميزة الرئيسية: Deferred Deep Linking

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

حالات الاستخدام

تُستخدم Dynamic Links في برامج الإحالة لجذب مستخدمين جدد مع إسناد إلى حساب الداعي. الحملات التسويقية ذات الانتقالات من النشرات البريدية والشبكات الاجتماعية تستخدم Dynamic Links لقياس التحويل بدقة. في سيناريوهات الإعداد الأولي، يقود الرابط المستخدم الجديد إلى شاشة ترحيب بمحتوى مخصص. في التجارة الإلكترونية، تحافظ روابط المنتجات على السياق وتقود إلى بطاقة المنتج حتى عند التشغيل الأول بعد التثبيت.

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

آلية العمل لـ Dynamic Links تتكون من عدة مراحل، يمكن أن تختلف كل منها حسب حالة التطبيق. عندما ينقر المستخدم على رابط ديناميكي، يرسل المتصفح طلباً إلى خادم Firebase. يتحقق Firebase مما إذا كان التطبيق مثبتاً باستخدام التحقق من intent-filter أو universal link. إذا كان التطبيق مثبتاً، يفتحه Firebase مع تمرير الرابط العميق. إذا لم يكن — يعيد التوجيه إلى صفحة المتجر أو الإصدار الويب.

تشريح الرابط الديناميكي

يتكون Dynamic Link القياسي من URL أساسي ومعلمات الرابط وعلامات تسويقية اختيارية. URL الأساسي هو نطاق مثل your-app.page.link مسجل في Firebase Console. يتم تعيين معلمات الرابط العميق عبر معلمات الاستعلام: link (URL الهدف داخل التطبيق)، apn (اسم حزمة أندرويد)، ibi (معرّف حزمة iOS)، st و sd (العنوان والوصف للمعاينة الاجتماعية). يتم تمرير العلامات التسويقية utm_source و utm_medium و utm_campaign إلى Google Analytics للتتبع.

إنشاء الروابط عبر Firebase Console وAPI

Firebase Console توفر واجهة مرئية لإنشاء Dynamic Links في قسم Engage > Dynamic Links. في لوحة التحكم، يمكنك تعيين جميع معلمات الرابط، بما في ذلك الرابط العميق والسلوك في الويب والبيانات الوصفية الاجتماعية وعلامات UTM. بعد إنشاء الرابط، توفر لوحة التحكم URL جاهزاً للاستخدام، بالإضافة إلى إحصائيات النقرات والانتقالات. للإنشاء الجماعي للروابط، يتم استخدام REST API لـ Firebase Dynamic Links مع مصادقة OAuth 2.0.

إنشاء رابط عبر REST API

للإنشاء البرمجي لـ Dynamic Links، يتم تقديم طلب POST إلى API Firebase Dynamic Links. جسم الطلب يحتوي على dynamicLinkInfo مع معلمات الرابط العميق وإعدادات المنصة والبيانات الوصفية الاجتماعية. يُرجع API URL جاهزاً للاستخدام مثل https://your-app.page.link/abc123. للروابط طويلة العمر، يُستخدم suffix.option = UNIQUE — روابط قصيرة بلاحقة فريدة. للروابط المؤقتة — SHORT، مع احتمالية التصادم.

const axios = require("axios")

const apiUrl = "https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=API_KEY"

const data = {
    dynamicLinkInfo: {
        domainUriPrefix: "https://yourapp.page.link",
        link: "https://yourapp.com/promo/summer",
        androidInfo: { androidPackageName: "com.example.myapp" },
        iosInfo: { iosBundleId: "com.example.myapp.ios" },
        socialMetaTagInfo: {
            socialTitle: "عرض الصيف",
            socialDescription: "خصم يصل إلى 50% حتى نهاية الشهر"
        }
    },
    suffix: { option: "UNIQUE" }
}

axios.post(apiUrl, data)
    .then(res => console.log(res.data.shortLink))
    .catch(err => console.error(err))

الروابط القصيرة وعلامات UTM

تنشئ Dynamic Links تلقائياً URLs قصيرة بطول 6–8 أحرف بعد النطاق، مما يجعلها مناسبة للاستخدام في الرسائل النصية القصيرة والشبكات الاجتماعية. معلمات UTM تُضاف عبر حقل utmParameters أو مباشرة في معلمة link. يربط Firebase تلقائياً النقرات على Dynamic Links مع Google Analytics لـ Firebase، مما يتيح تتبع حركة الإحالة وإسناد الحملات.

دمج Dynamic Links في أندرويد

إعداد Dynamic Links في أندرويد يتضمن إضافة Firebase SDK، وتكوين intent-filter للنشاط الذي يستقبل الروابط العميقة، ومعالجة الروابط عبر Firebase Dynamic Links SDK. بعد تثبيت SDK وإضافة google-services.json، تحتاج إلى تسجيل النشاط في AndroidManifest.xml مع intent-filter لمعالجة الروابط من نطاق تطبيقك.

إعداد intent-filter في AndroidManifest

النشاط الذي يعالج Dynamic Links يجب أن يكون لديه intent-filter لإجراء VIEW وفئتي DEFAULT و BROWSABLE. AndroidManifest.xml يتضمن علامة data مع android:scheme و android:host و android:pathPrefix المطابقة لرابطك العميق. لمعالجة الروابط من نطاق page.link، تتم إضافة intent-filter مع مخطط https ومضيف نطاق Dynamic Links الخاص بك.

<!-- AndroidManifest.xml -->
<activity android:name=".MainActivity">
    <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:scheme="https"
            android:host="yourapp.com"
            android:pathPrefix="/promo" />
    </intent-filter>
</activity>

معالجة الرابط في الكود

بعد إعداد intent-filter، تحتاج إلى معالجة Dynamic Link الوارد في كود النشاط. API FirebaseDynamicLinks تستقبل الرابط من intent وتعيد كائن PendingDynamicLinkData مع المعلمات المستخرجة. تُعيد طريقة getLink الرابط العميق الهدف، الذي يمكن تحليله واستخدامه للتنقل. من المهم معالجة الرابط سواء عند بدء التشغيل البارد (عبر getIntent في onCreate) أو عند بدء التشغيل الساخن (عبر onNewIntent).

دمج Dynamic Links في iOS

إعداد Dynamic Links في iOS يتطلب تكويناً على جانبي Firebase ومشروع Xcode. تحتاج إلى تحميل مفتاح APNs إلى Firebase Console، وإضافة Firebase SDK عبر Swift Package Manager أو CocoaPods، وتكوين App Delegate لمعالجة Universal Links. تستخدم Dynamic Links في iOS Universal Links للانتقال السلس بين المتصفح والتطبيق دون صفحة وسيطة.

إعداد Universal Links

Universal Links هي تقنية من Apple تربط نطاقك بتطبيق الجوال. ملف apple-app-site-association (AASA) يُرفع على الخادم على https://your-app.page.link/apple-app-site-association. ينشئ Firebase ويحافظ تلقائياً على هذا الملف لنطاق Dynamic Links الخاص بك. في Xcode، تحتاج إلى تمكين Associated Domains وتحديد applinks:your-app.page.link في قدرات المشروع.

معالجة الرابط عبر Firebase SDK

لـ iOS، تتم معالجة Dynamic Links عبر Firebase SDK في App Delegate أو Scene Delegate. طريقة application:continueUserActivity: تعترض Universal Link الوارد وتمرره إلى API Firebase Dynamic Links، الذي يستخرج الرابط الهدف والمعلمات. يعالج Firebase SDK تلقائياً Deferred Deep Links عن طريق طلب بيانات التثبيت عبر مخزن Firebase Installation API قصير الأجل.

import FirebaseDynamicLinks

class AppDelegate: UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping
            ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        return DynamicLinks.dynamicLinks()
            .handleUniversalLink(userActivity.webpageURL!) {
                dynamicLink, error in
                if let link = dynamicLink?.url {
                    self.handleDeepLink(link)
                }
            }
    }
}

مثال تنفيذ في Kotlin

دعنا نلقي نظرة على مثال كامل لمعالجة Dynamic Link في تطبيق أندرويد باستخدام Kotlin. MainActivity تقرأ Dynamic Link الوارد عند بدء التشغيل البارد والساخن للتطبيق. يتم تحليل الرابط إلى معلمات تُستخدم للتنقل إلى الشاشة المطلوبة مع تمرير الوسائط. يوضح المثال معالجة رابط لصفحة عرض ترويجي مع معرّف حملة ترويجية.

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        handleDynamicLink(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handleDynamicLink(intent)
    }

    private fun handleDynamicLink(intent: Intent) {
        FirebaseDynamicLinks.getInstance()
            .getDynamicLink(intent)
            .addOnSuccessListener { data ->
                val deepLink = data?.link ?: return@addOnSuccessListener
                val promoId = deepLink
                    .getQueryParameter("promoId") ?: ""
                if (promoId.isNotEmpty()) {
                    navigateToPromoScreen(promoId)
                }
            }
            .addOnFailureListener { e ->
                Log.e("DL", "خطأ في معالجة الرابط", e)
            }
    }
}

اختبار Dynamic Links

لاختبار Dynamic Links، يُستخدم Firebase Console، حيث يمكنك إنشاء رابط اختبار وإرساله إلى جهاز عبر تطبيق مراسلة أو بريد إلكتروني. مصحح أخطاء Firebase Dynamic Links متاح على https://your-app.page.link/?d=1 ويعرض معلومات تفصيلية عن سلوك الرابط. عند اختبار Deferred Deep Links، تحتاج إلى التأكد من إلغاء تثبيت التطبيق، وبعد التثبيت يقود الرابط إلى الشاشة الصحيحة مع المعلمات المُمررة.