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

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

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

قبل أن تتمكّن من إنشاء Dynamic Links في تطبيق Android، عليك تضمين حزمة تطوير البرامج (SDK) لمنصّة Firebase. إذا تم إعداد تطبيقك لتلقّي 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 وإضافة حزمة تطوير البرامج (SDK) لمنصّة Firebase في "إحصاءات Google" إلى تطبيقك. 

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.6.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:22.1.2'
}
    هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ اعتبارًا من تشرين الأول (أكتوبر) 2023 (Firebase BoM 32.5.0)، يمكن لمطوّري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (للاطّلاع على التفاصيل، راجِع الأسئلة الشائعة حول هذه المبادرة).
  3. في وحدة تحكّم Firebase، افتح قسم Dynamic Links.

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

    إذا كان لديك نطاق Dynamic Links، دوِّنه. عليك تقديم نطاق Dynamic Links عند إنشاء Dynamic Links آليًا.

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

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

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

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

في المثال البسيط التالي، يتم إنشاء سلسلة طويلة من Dynamic Link إلى 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

لإنشاء Dynamic Link قصير، أنشئ 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

يتم تلقائيًا إنشاء Dynamic Links قصيرة باستخدام لاحقات روابط تتألف من 17 حرفًا، ما يجعل من غير المرجّح أن يخمن أحد المستخدمين Dynamic Link صالحًا. إذا كان سيناريو الاستخدام الخاص بك لا يتضمن أي ضرر في تخمين مستخدم رابطًا قصيرًا بنجاح، قد تفضّل إنشاء لاحقات لا تزيد عن الطول اللازم لتكون فريدة، ويمكنك إجراء ذلك من خلال تمرير 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

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

ينشئ المثال التالي Dynamic Link يحتوي على عدة مَعلمات شائعة:

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 باستخدام الطرق التالية:

مَعلمات DynamicLink
setLink

الرابط الذي سيفتحه تطبيقك حدِّد عنوان URL يمكن لتطبيقك التعامل معه، وعادةً ما يكون محتوى التطبيق أو الحمولة، ما يؤدي إلى بدء منطق خاص بالتطبيق (مثل إضافة رصيد قسيمة إلى حساب المستخدم أو عرض شاشة ترحيب). يجب أن يكون هذا الرابط عنوان URL بتنسيق جيد، وأن يكون بترميز عنوان URL صحيح، وأن يستخدم إما HTTP أو HTTPS، ولا يمكن أن يكون رابطًا ديناميكيًا آخر.
setDomainUriPrefix بادئة عنوان URL الخاص بخدمة Dynamic Link، والتي يمكنك العثور عليها في وحدة تحكّم Firebase يشبه نطاق 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.
setMinimumVersion رقم الإصدار الأدنى لتطبيقك الذي يمكنه فتح الرابط يتم تمرير هذا العلامة إلى تطبيقك عند فتحه، وعلى تطبيقك تحديد الإجراء الذي يجب اتّخاذه بشأنها.
NavigationInfoParameters
setForcedRedirectEnabled في حال ضبط القيمة على "1"، سيتم تخطّي صفحة معاينة التطبيق عند فتح Dynamic Link، وسيتم بدلاً من ذلك إعادة التوجيه إلى التطبيق أو المتجر. يمكن لصفحة معاينة التطبيق (المفعّلة تلقائيًا) توجيه المستخدمين بشكل أكثر موثوقية إلى الوجهة الأنسب عند فتح Dynamic Links في التطبيقات. ومع ذلك، إذا كنت تتوقّع أن يتم فتح Dynamic Links فقط في التطبيقات التي يمكنها فتح Dynamic Links بشكل موثوق بدون هذه الصفحة، يمكنك إيقافها باستخدام هذه المَعلمة.Dynamic Link ستؤثّر هذه المَعلمة في سلوك 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 طويل، حدِّد عنوان URL للDynamic Link باستخدام setLongLink بدلاً من ضبط المَعلمات باستخدام methods: أداة الإنشاء الأخرى:

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