إنشاء روابط ديناميكية على 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) الخاصة بخدمة "إحصاءات Google" لبرنامج Firebase إلى تطبيقك. 

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.0.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متعدّدة في تطبيقك، ننصحك بشدة باستخدام 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.0.0'
}
  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

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

لإنشاء فيديو Shorts 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
    // ...
}
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

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

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 A كما في الأمثلة التالية: 
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 console.
setMinimumVersion رقم الإصدار لأدنى إصدار من تطبيقك يمكنه فتح الرابط يتم تمرير هذا العلامة إلى تطبيقك عند فتحه، ويجب أن يحدّد تطبيقك الإجراء الذي يجب اتّخاذه بشأنها.
NavigationInfoParameters
setForcedRedirectEnabled في حال ضبط القيمة على "1"، سيتم تخطّي صفحة معاينة التطبيق عند فتح Dynamic Link، وسيتم بدلاً من ذلك إعادة التوجيه إلى التطبيق أو المتجر. يمكن أن ترسل صفحة معاينة التطبيق (المفعّلة تلقائيًا) المستخدمين بشكل أكثر موثوقية إلى الوجهة الأنسب عند فتح Dynamic Links في التطبيقات. ومع ذلك، إذا كنت تتوقّع فتح Dynamic Link في التطبيقات التي يمكنها فتح Dynamic Links بشكل موثوق بدون هذه الصفحة فقط، يمكنك إيقافها باستخدام هذه المَعلمة. سيؤثر هذا المَعلمة في سلوك Dynamic Link على أجهزة iOS فقط.
SocialMetaTagParameters
setTitle تمثّل هذه السمة العنوان المطلوب استخدامه عند مشاركة Dynamic Link في منشور على وسائل التواصل الاجتماعي.
setDescription الوصف الذي سيتم استخدامه عند مشاركة Dynamic Link في منشور على وسائل التواصل الاجتماعي
setImageUrl تمثّل هذه السمة عنوان URL لصورة ذات صلة بهذا الرابط. يجب أن يكون حجم الصورة 300x200 بكسل على الأقل، وأقل من 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
    // ...
}
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