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

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

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

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

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

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

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

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

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.1.2"))

    // 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'
}

    باستخدام أداة إدارة قوائم التشغيل Android في Firebase، سيستخدم تطبيقك دائمًا الإصدارات المتوافقة من مكتبات Android في Firebase.

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

    إذا اخترت عدم استخدام قائمة العناصر في Firebase، يجب تحديد كل إصدار من مكتبة 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:22.0.2'
}
    هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ اعتبارًا من تشرين الأول (أكتوبر) 2023 (الإصدار 32.5.0 من Firebase)، أصبح بإمكان مطوّري لغة Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (لمعرفة التفاصيل، يُرجى الاطّلاع على الأسئلة الشائعة حول هذه المبادرة).
  3. في "وحدة تحكُّم Firebase"، افتح قسم الروابط الديناميكية.

  4. في حال لم تكن قد قبلت بنود الخدمة واخترت نطاقًا للروابط الديناميكية، عليك إجراء ذلك عندما يُطلب منك ذلك.

    إذا كان لديك نطاق "الروابط الديناميكية" من قبل، دوّنه. تحتاج إلى توفير نطاق "الروابط الديناميكية" عند إنشاء "روابط ديناميكية" بشكل آلي.

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

استخدام "وحدة تحكُّم Firebase"

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

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

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

Kotlin+KTX

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

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

Kotlin+KTX

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 حرفًا، ما يجعل من غير المرجّح على الإطلاق أن يتمكّن أحد المستخدمين من تخمين رابط ديناميكي صالح. بالنسبة إلى حالة الاستخدام، لم ينجح أي شخص في تخمين رابط قصير، وقد تفضّل إنشاء لاحقات تكون بالمدة اللازمة فقط لتكون فريدة، ويمكنك إجراء ذلك من خلال تمرير ShortDynamicLink.Suffix.SHORT إلى الطريقة buildShortDynamicLink:

Kotlin+KTX

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

يمكنك استخدام واجهة برمجة تطبيقات إنشاء الروابط الديناميكية لإنشاء روابط ديناميكية باستخدام أي من المعلمات المعتمدة. يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات للحصول على التفاصيل.

ينشئ المثال التالي رابطًا ديناميكيًا به مجموعة من المعلمات الشائعة:

Kotlin+KTX

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
تعيين الرابط

سيفتح التطبيق الرابط. عليك تحديد عنوان URL يمكن لتطبيقك التعامل معه، وعادةً ما يكون محتوى التطبيق أو حمولة البيانات التي تبدأ منطقًا خاصًا بالتطبيق (مثل إضافة قسيمة إلى المستخدم أو عرض شاشة ترحيب). ويجب أن يكون هذا الرابط عنوان URL بتنسيق صحيح، وأن يكون بترميز عنوان URL بشكلٍ صحيح، وأن يستخدم HTTP أو HTTPS، وألا يكون رابطًا ديناميكيًا آخر.
بادئة setDomainUriPrefix بادئة عنوان URL للرابط الديناميكي، والتي يمكنك العثور عليها في وحدة تحكُّم Firebase. يظهر نطاق الرابط الديناميكي على النحو التالي: 
https://example.com/link
https://example.page.link
مَعلمات Android
setFallbackUrl الرابط الذي يتم فتحه عندما لا يكون التطبيق مثبَّتًا. حدِّد هذا الإجراء لتنفيذ إجراء آخر غير تثبيت التطبيق من "متجر Play" إذا كان التطبيق غير مثبَّت، مثل فتح إصدار الويب على الأجهزة الجوّالة من المحتوى أو عرض صفحة ترويجية لتطبيقك.
ضبط الحد الأدنى للإصدار تمثّل هذه السمة versionCode من الحد الأدنى لإصدار التطبيق الذي يمكنه فتح الرابط. إذا كان التطبيق المُثبَّت إصدارًا قديمًا، يتم نقل المستخدم إلى "متجر Play" لترقية التطبيق.
معلَمات Ios
setAppStoreId رقم تعريف تطبيقك على App Store، يُستخدَم لتوجيه المستخدمين إلى App Store عند عدم تثبيت التطبيق
setFallbackUrl الرابط الذي يتم فتحه عندما لا يكون التطبيق مثبَّتًا. حدِّد هذا الإجراء لتنفيذ إجراء آخر غير تثبيت التطبيق من App Store في حال عدم تثبيت التطبيق، مثل فتح إصدار الويب المتوافق مع الأجهزة الجوّالة من المحتوى أو عرض صفحة ترويجية لتطبيقك.
تعيين CustomScheme مخطَّط عنوان URL المخصّص لتطبيقك، إذا تم تحديده على أنّه شيء مختلف عن معرّف حزمة التطبيق
setIpadFallbackUrl الرابط الذي يتم فتحه على أجهزة iPad عندما يكون التطبيق غير مثبَّت. حدِّد هذا الإجراء لتنفيذ إجراء آخر غير تثبيت التطبيق من App Store في حال عدم تثبيت التطبيق، مثل فتح إصدار الويب من المحتوى أو عرض صفحة ترويجية لتطبيقك.
setIpadBundleId رقم تعريف حزمة تطبيق iOS المطلوب استخدامه على أجهزة iPad لفتح الرابط يجب ربط التطبيق بمشروعك من صفحة النظرة العامة في وحدة تحكُّم Firebase.
ضبط الحد الأدنى للإصدار رقم الإصدار من أدنى إصدار من تطبيقك يمكنه فتح الرابط. يتم تمرير هذه العلامة إلى تطبيقك عند فتحه، وعلى التطبيق تحديد الإجراء الذي سيتم اتخاذه بشأنه.
مَعلَمات معلومات التنقّل
setForcedRedirectEnabled في حال الضبط على "1"، يمكنك تخطّي صفحة معاينة التطبيق عند فتح الرابط الديناميكي، وإعادة التوجيه إلى التطبيق أو المتجر بدلاً من ذلك. يمكن لصفحة معاينة التطبيق (المفعَّلة تلقائيًا) أن ترسِل المستخدمين إلى الوجهة الأكثر ملاءمةً عند فتح "الروابط الديناميكية" في التطبيقات، ومع ذلك، إذا كنت تتوقّع أن يتم فتح رابط ديناميكي فقط في التطبيقات التي يمكنها فتح "الروابط الديناميكية" بشكل موثوق بدون هذه الصفحة، يمكنك إيقافها باستخدام هذه المَعلمة. ستؤثّر هذه المَعلمة في سلوك الرابط الديناميكي على نظام التشغيل iOS فقط.
مَعلمات SocialMetaTag
تعيين العنوان العنوان المستخدم عند نشر الرابط الديناميكي في مشاركة اجتماعية.
setDescription الوصف المستخدم عند نشر الرابط الديناميكي في مشاركة اجتماعية.
setImageUrl تمثّل هذه السمة عنوان URL لصورة ذات صلة بهذا الرابط. يجب ألا يقلّ حجم الصورة عن 300 × 200 بكسل وألا يزيد عن 300 كيلوبايت.
مَعلمات Google Analytics
setSource
setMedium
setCampaign
setTerm
setContent		 مَعلمات "إحصاءات Google Play" يتم تمرير هذه المعلمات (utm_source وutm_medium وutm_campaign وutm_term وutm_content) إلى "متجر Play" ويتم إلحاقها بحمولة الروابط.
مَعلمات ItunesConnectAnalytics
setProviderToken
setAffiliateToken
setCampaignToken		 معلَمات إحصاءات iTunes Connect يتم تمرير هذه المعلمات (pt وat وct) إلى App Store.

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

Kotlin+KTX

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