إنشاء روابط ديناميكية على 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

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();

لإنشاء 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
    // ...
}

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
                    // ...
                }
            }
        });

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

Kotlin+KTX

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

Java

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

يمكنك استخدام 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!"
    }
}

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()

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

مَعلمات DynamicLink
تعيين الرابط

الرابط الذي سيفتحه تطبيقك عليك تحديد عنوان 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 على أجهزة iOS فقط.
مَعلمات SocialMetaTag
تعيين العنوان العنوان الذي سيتم استخدامه عند مشاركة Dynamic Link في مشاركة على وسائل التواصل الاجتماعي.
setDescription الوصف المستخدم عند نشر Dynamic Link في مشاركة على الشبكات الاجتماعية.
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.

لتقصير Dynamic Link طويل، حدِّد عنوان URL للDynamic Link باستخدام setLongLink بدلاً من ضبط المَعلمات باستخدام 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
    // ...
}

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
                    // ...
                }
            }
        });