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

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

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

قبل أن تتمكّن من إنشاء 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.12.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، افتح قسم Dynamic Links.

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

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

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

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

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

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

ينشئ المثال الأدنى التالي رابطًا ديناميكيًا طويلاً يؤدي إلى Dynamic Link to 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

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

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

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

Kotlin

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

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

مَعلمات الروابط الديناميكية
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 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 طويل، حدِّد عنوان 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
    // ...
}

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