إنشاء روابط ديناميكية على Android

ملاحظة: تم إيقاف ميزة "روابط Firebase الديناميكية" نهائيًا، ويجب عدم استخدامها في المشاريع الجديدة. سيتم إيقاف الخدمة قريبًا. يُرجى اتّباع دليل نقل البيانات والاطّلاع على الأسئلة الشائعة حول إيقاف ميزة "روابط Firebase الديناميكية" نهائيًا لمزيد من المعلومات.

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

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

إعداد Firebase وDynamic Links SDK

قبل أن تتمكّنوا من إنشاء Dynamic Links في تطبيق Android، يجب تضمين Firebase SDK. إذا كان تطبيقكم معدًا لتلقّي Dynamic Links، فقد أكملتم هذه الخطوات بالفعل ويمكنكم تخطّي هذا القسم.

1. أضِفوا Firebase إلى مشروع Android الخاص بكم، في حال لم يسبق لكم إجراء ذلك، .

   عند تسجيل تطبيقكم، حدِّدوا مفتاح توقيع SHA-1. إذا كنتم تستخدمون روابط التطبيقات، حدِّدوا أيضًا مفتاح SHA-256.

2. في ملف Gradle الخاص بالوحدة (على مستوى التطبيق) (عادةً ما يكون <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضيفوا التبعية لمكتبة Dynamic Links لنظام Android. ننصحكم باستخدام Firebase Android BoM للتحكّم في تحديد إصدار المكتبة.

   للحصول على أفضل تجربة مع Dynamic Links، ننصحكم بتفعيل Google Analytics في مشروع Firebase وإضافة Firebase SDK لخدمة "إحصاءات Google" إلى تطبيقكم.

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:34.13.0"))
   
       // Add the dependencies for the Dynamic Links and Analytics libraries
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation 'com.google.firebase:firebase-dynamic-links'
       implementation 'com.google.firebase:firebase-analytics'
   }

   باستخدام Firebase Android BoM, سيستخدم تطبيقكم دائمًا إصدارات متوافقة من مكتبات Firebase Android.

   (بديل)  إضافة تبعيات مكتبة Firebase بدون استخدام BoM

   إذا اخترتم عدم استخدام Firebase BoM، يجب تحديد إصدار كل مكتبة من مكتبات Firebase في سطر التبعية الخاص بها.

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

   dependencies {
       // Add the dependencies for the Dynamic Links and Analytics libraries
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation 'com.google.firebase:firebase-dynamic-links:22.1.0'
       implementation 'com.google.firebase:firebase-analytics:23.2.0'
   }

3. في Firebase Console، افتحوا قسم Dynamic Links.

4. إذا لم يسبق لكم قبول بنود الخدمة وتعيين نطاق لـ Dynamic Links، يُرجى إجراء ذلك عندما يُطلب منكم ذلك.

   إذا كان لديكم نطاق Dynamic Links، يُرجى تدوينه. عليك تقديم نطاق Dynamic Links عند إنشاء Dynamic Links آليًا.

   

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

استخدام Firebase Console

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

إنشاء Dynamic Link من المَعلمات

لإنشاء Dynamic Link، أنشئوا عنصر DynamicLink جديدًا باستخدام أداة الإنشاء، مع تحديد مَعلمات Dynamic Link باستخدام طرق أداة الإنشاء. بعد ذلك، استدعوا buildDynamicLink أو buildShortDynamicLink.

ينشئ المثال الأدنى التالي رابطًا ديناميكيًا طويلاً Dynamic Link إلى https://www.example.com/ ويفتح مع تطبيق Android على Android والتطبيق com.example.ios على iOS:

Kotlin

val dynamicLink = Firebase.dynamicLinks.dynamicLink {
    link = Uri.parse("https://www.example.com/")
    domainUriPrefix = "https://example.page.link"
    // Open links with this app on Android
    androidParameters { }
    // Open links with com.example.ios on iOS
    iosParameters("com.example.ios") { }
}

val dynamicLinkUri = dynamicLink.uri
MainActivity.kt

Java

DynamicLink dynamicLink = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLink(Uri.parse("https://www.example.com/"))
        .setDomainUriPrefix("https://example.page.link")
        // Open links with this app on Android
        .setAndroidParameters(new DynamicLink.AndroidParameters.Builder().build())
        // Open links with com.example.ios on iOS
        .setIosParameters(new DynamicLink.IosParameters.Builder("com.example.ios").build())
        .buildDynamicLink();

Uri dynamicLinkUri = dynamicLink.getUri();
MainActivity.java

لإنشاء Dynamic Link قصير، أنشئوا DynamicLink بالطريقة نفسها، و ثم استدعوا buildShortDynamicLink. يتطلّب إنشاء رابط قصير إجراء طلب على الشبكة، لذا بدلاً من عرض الرابط مباشرةً، buildShortDynamicLink تعرض Task يتيح الرابط القصير عند اكتمال الطلب. على سبيل المثال:

Kotlin

val shortLinkTask = Firebase.dynamicLinks.shortLinkAsync {
    link = Uri.parse("https://www.example.com/")
    domainUriPrefix = "https://example.page.link"
    // Set parameters
    // ...
}.addOnSuccessListener { (shortLink, flowchartLink) ->
    // You'll need to import com.google.firebase.dynamiclinks.component1 and
    // com.google.firebase.dynamiclinks.component2

    // Short link created
    processShortLink(shortLink, flowchartLink)
}.addOnFailureListener {
    // Error
    // ...
}
MainActivity.kt

Java

Task<ShortDynamicLink> shortLinkTask = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLink(Uri.parse("https://www.example.com/"))
        .setDomainUriPrefix("https://example.page.link")
        // Set parameters
        // ...
        .buildShortDynamicLink()
        .addOnCompleteListener(this, new OnCompleteListener<ShortDynamicLink>() {
            @Override
            public void onComplete(@NonNull Task<ShortDynamicLink> task) {
                if (task.isSuccessful()) {
                    // Short link created
                    Uri shortLink = task.getResult().getShortLink();
                    Uri flowchartLink = task.getResult().getPreviewLink();
                } else {
                    // Error
                    // ...
                }
            }
        });
MainActivity.java

تتم تلقائيًا إضافة لاحقات روابط مكوّنة من 17 حرفًا إلى الروابط الديناميكية القصيرة، ما يجعل من غير المرجّح على الإطلاق أن يتمكّن أحد المستخدمين من تخمين رابط ديناميكي صالح.Dynamic LinksDynamic Link إذا لم يكن هناك أي ضرر في أن يتمكّن أحد المستخدمين من تخمين رابط قصير بنجاح في حالة الاستخدام الخاصة بكم، قد تفضّلون إنشاء لاحقات لا تكون أطول من اللازم لتكون فريدة، ويمكنكم إجراء ذلك من خلال تمرير ShortDynamicLink.Suffix.SHORT إلى طريقة buildShortDynamicLink

Kotlin

val shortLinkTask = Firebase.dynamicLinks.shortLinkAsync(ShortDynamicLink.Suffix.SHORT) {
    // Set parameters
    // ...
}
MainActivity.kt

Java

Task<ShortDynamicLink> shortLinkTask = FirebaseDynamicLinks.getInstance().createDynamicLink()
        // ...
        .buildShortDynamicLink(ShortDynamicLink.Suffix.SHORT);
        // ...
MainActivity.java

مَعلمات Dynamic Link

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

ينشئ المثال التالي Dynamic Link تم ضبط عدة مَعلمات شائعة له:

Kotlin

val dynamicLink = Firebase.dynamicLinks.dynamicLink { // or Firebase.dynamicLinks.shortLinkAsync
    link = Uri.parse("https://www.example.com/")
    domainUriPrefix = "https://example.page.link"
    androidParameters("com.example.android") {
        minimumVersion = 125
    }
    iosParameters("com.example.ios") {
        appStoreId = "123456789"
        minimumVersion = "1.0.1"
    }
    googleAnalyticsParameters {
        source = "orkut"
        medium = "social"
        campaign = "example-promo"
    }
    itunesConnectAnalyticsParameters {
        providerToken = "123456"
        campaignToken = "example-promo"
    }
    socialMetaTagParameters {
        title = "Example of a Dynamic Link"
        description = "This link works whether the app is installed or not!"
    }
}
MainActivity.kt

Java

DynamicLink dynamicLink = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLink(Uri.parse("https://www.example.com/"))
        .setDomainUriPrefix("https://example.page.link")
        .setAndroidParameters(
                new DynamicLink.AndroidParameters.Builder("com.example.android")
                        .setMinimumVersion(125)
                        .build())
        .setIosParameters(
                new DynamicLink.IosParameters.Builder("com.example.ios")
                        .setAppStoreId("123456789")
                        .setMinimumVersion("1.0.1")
                        .build())
        .setGoogleAnalyticsParameters(
                new DynamicLink.GoogleAnalyticsParameters.Builder()
                        .setSource("orkut")
                        .setMedium("social")
                        .setCampaign("example-promo")
                        .build())
        .setItunesConnectAnalyticsParameters(
                new DynamicLink.ItunesConnectAnalyticsParameters.Builder()
                        .setProviderToken("123456")
                        .setCampaignToken("example-promo")
                        .build())
        .setSocialMetaTagParameters(
                new DynamicLink.SocialMetaTagParameters.Builder()
                        .setTitle("Example of a Dynamic Link")
                        .setDescription("This link works whether the app is installed or not!")
                        .build())
        .buildDynamicLink();  // Or buildShortDynamicLink()
MainActivity.java

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

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

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

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

NavigationInfoParameters

setForcedRedirectEnabled

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

SocialMetaTagParameters
setTitle	العنوان الذي سيتم استخدامه عند مشاركة Dynamic Link في منشور على وسائل التواصل الاجتماعي
setDescription	الوصف الذي سيتم استخدامه عند مشاركة Dynamic Link في منشور على وسائل التواصل الاجتماعي
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.

تقصير رابط طويل Dynamic Link

لتقصير رابط ديناميكي طويل Dynamic Link، حدِّدوا عنوان URL للرابط الديناميكي Dynamic Link باستخدام setLongLink بدلاً من ضبط المَعلمات باستخدام طرق أداة الإنشاء الأخرى:

Kotlin

val shortLinkTask = Firebase.dynamicLinks.shortLinkAsync {
    longLink = Uri.parse(
        "https://example.page.link/?link=" +
            "https://www.example.com/&apn=com.example.android&ibn=com.example.ios",
    )
}.addOnSuccessListener { (shortLink, flowChartLink) ->
    // You'll need to import com.google.firebase.dynamiclinks.component1 and
    // com.google.firebase.dynamiclinks.component2

    // Short link created
    processShortLink(shortLink, flowChartLink)
}.addOnFailureListener {
    // Error
    // ...
}
MainActivity.kt

Java

Task<ShortDynamicLink> shortLinkTask = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLongLink(Uri.parse("https://example.page.link/?link=https://www.example.com/&apn=com.example.android&ibn=com.example.ios"))
        .buildShortDynamicLink()
        .addOnCompleteListener(this, new OnCompleteListener<ShortDynamicLink>() {
            @Override
            public void onComplete(@NonNull Task<ShortDynamicLink> task) {
                if (task.isSuccessful()) {
                    // Short link created
                    Uri shortLink = task.getResult().getShortLink();
                    Uri flowchartLink = task.getResult().getPreviewLink();
                } else {
                    // Error
                    // ...
                }
            }
        });
MainActivity.java