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

يمكنك إنشاء روابط ديناميكية قصيرة أو طويلة باستخدام واجهة برمجة التطبيقات Firebase Dynamic Links Builder API. تقبل واجهة برمجة التطبيقات هذه إما رابطًا ديناميكيًا طويلاً أو كائنًا يحتوي على معلمات رابط ديناميكي، وتعرض عناوين 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. ننصحك باستخدام برنامج Firebase Android BoM للتحكّم في إصدارات المكتبة.

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

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

    // 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 BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات 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 ( Firebase BoM 32.5.0)، أصبح بإمكان مطوّري لغتَي 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

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

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

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

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

معلمات الرابط الديناميكي
ضبط الرابط

الرابط الذي سيفتحه تطبيقك حدِّد عنوان 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 عندما لا يكون التطبيق مثبتًا، مثل فتح إصدار ويب من المحتوى على الأجهزة الجوّالة، أو عرض صفحة ترويجية لتطبيقك.
أمر setCustomScheme مخطط عنوان URL المخصص لتطبيقك، إذا تم تحديده ليكون مختلفًا عن معرّف حزمة التطبيق
setIpadFallbackUrl الرابط الذي يتم فتحه على أجهزة iPad عندما يكون التطبيق غير مثبَّت. حدِّد ذلك لتنفيذ إجراء آخر غير تثبيت تطبيقك من App Store عندما لا يكون التطبيق مثبتًا، مثل فتح إصدار الويب من المحتوى أو عرض صفحة ترويجية لتطبيقك.
معرِّف setIpadBundle معرِّف حزمة تطبيق iOS لاستخدامه على أجهزة iPad لفتح الرابط. يجب أن يكون التطبيق مرتبطًا بمشروعك من صفحة "نظرة عامة" في وحدة تحكُّم Firebase.
تعيين الحد الأدنى رقم إصدار الحد الأدنى من تطبيقك الذي يمكنه فتح الرابط. يتم تمرير هذه العلامة إلى تطبيقك عند فتحه، ويجب أن يحدّد تطبيقك ما يجب فعله باستخدامها.
تفاصيل التنقل
setForcedredirectEnabled وفي حال ضبط السياسة على "1"، يمكنك تخطي صفحة معاينة التطبيق عند فتح الرابط الديناميكي، وإعادة التوجيه إلى التطبيق أو المتجر بدلاً من ذلك. يمكن لصفحة معاينة التطبيق (المفعّلة تلقائيًا) توجيه المستخدمين إلى الوجهة الأكثر ملاءمة بشكل أكثر موثوقية عند فتح "الروابط الديناميكية" في التطبيقات، ولكن إذا كنت تتوقع أن يتم فتح الرابط الديناميكي في التطبيقات التي يمكنها فتح "الروابط الديناميكية" بشكل موثوق بدون هذه الصفحة، يمكنك إيقافه باستخدام هذه المعلَمة. ستؤثر هذه المعلمة في سلوك الرابط الديناميكي على نظام التشغيل iOS فقط.
مَعلمات SocialMetaTag
setTitle العنوان الذي سيتم استخدامه عند مشاركة الرابط الديناميكي في مشاركة على الشبكات الاجتماعية.
setDescription الوصف الذي سيتم استخدامه عند مشاركة الرابط الديناميكي في مشاركة على الشبكات الاجتماعية.
setImageUrl تمثّل هذه السمة عنوان URL لصورة ذات صلة بهذا الرابط. يجب ألا يقل حجم الصورة عن 300×200 بكسل، وأقل من 300 كيلوبايت.
معلَمات "إحصاءات Google"
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