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

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:35.0.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'
}

    باستخدام 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:24.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

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

By default, short Dynamic Links are generated with 17-character link suffixes that make it extremely unlikely that someone can guess a valid Dynamic 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 بالطرق التالية:

مَعلمات DynamicLink
setLink

الرابط الذي سيفتحه تطبيقك حدِّد عنوان URL يمكن لتطبيقك التعامل معه، ويكون عادةً محتوى التطبيق أو حمولته، والذي يبدأ منطقًا خاصًا بالتطبيق (مثل منح المستخدم قسيمة أو عرض شاشة ترحيب). يجب أن يكون هذا الرابط عنوان URL منسَّقًا بشكل جيد، وأن يكون بترميز عنوان URL بشكل صحيح، وأن يستخدم إما HTTP أو HTTPS، ولا يمكن أن يكون رابطًا ديناميكيًا آخر.
setDomainUriPrefix بادئة عنوان URL في Dynamic Link، والتي يمكنك العثور عليها في وحدة تحكّم Firebase يبدو نطاق Dynamic Link مثل الأمثلة التالية: 
https://example.com/link
https://example.page.link
AndroidParameters
setFallbackUrl الرابط الذي يتم فتحه في حال عدم تثبيت التطبيق حدِّد هذا الإجراء لتنفيذ إجراء آخر غير تثبيت تطبيقك من "متجر Google Play" عندما لا يكون التطبيق مثبَّتًا، مثل فتح إصدار الويب على الأجهزة الجوّالة للمحتوى أو عرض صفحة ترويجية لتطبيقك.
setMinimumVersion ‫versionCode للحد الأدنى من إصدار تطبيقك الذي يمكنه فتح الرابط إذا كان التطبيق المثبّت إصدارًا قديمًا، يتم توجيه المستخدم إلى "متجر Google Play" لترقية التطبيق.
IosParameters
setAppStoreId معرّف متجر التطبيقات لتطبيقك، ويُستخدَم لإرسال المستخدمين إلى متجر التطبيقات عندما لا يكون التطبيق مثبَّتًا
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) إلى "متجر Google Play"، بالإضافة إلى إلحاقها بحمولة الرابط.
ItunesConnectAnalyticsParameters
setProviderToken
setAffiliateToken
setCampaignToken		 مَعلمات إحصاءات iTunes Connect يتم تمرير هذه المَعلمات (pt وat وct) إلى متجر التطبيقات.

لاختصار 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
                    // ...
                }
            }
        });