إنشاء روابط ديناميكية على 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.2.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، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Android في Firebase.

    (بديل) إضافة اعتماديات مكتبة 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.0'
    }
    هل تبحث عن وحدة مكتبة خاصة بلغة 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 بالطرق التالية:

مَعلمات Dynamic Link
تعيين الرابط

سيفتح التطبيق الرابط. يجب تحديد عنوان URL يمكن لتطبيقك التعامل معه، وعادةً ما يكون محتوى التطبيق. أو الحمولة، التي تبدأ منطقًا خاصًا بالتطبيق (مثل إضافة قسيمة إلى المستخدم) لعرض شاشة ترحيب). ويجب أن يكون هذا الرابط عنوان URL بتنسيق جيد، وترميز عنوان URL بشكل صحيح، ويستخدم إما HTTP أو HTTPS، ولا يمكن أن يكون رابطًا ديناميكيًا آخر.

بادئة setDomainUriPrefix بادئة عنوان URL للسمة Dynamic Link، والتي يمكنك العثور عليها في وحدة التحكّم Firebase. حاسمة يظهر النطاق Dynamic Link على النحو التالي:
https://example.com/link
https://example.page.link
مَعلمات Android
setFallbackUrl الرابط الذي يتم فتحه عندما لا يكون التطبيق مثبَّتًا. حدِّد هذا الإجراء لتنفيذ إجراء آخر غير تثبيت التطبيق من "متجر Play" إذا كان التطبيق غير مثبَّت، مثل فتح إصدار الويب على الأجهزة الجوّالة من المحتوى أو عرض صفحة ترويجية لتطبيقك.
ضبط الحد الأدنى للإصدار تمثّل هذه السمة versionCode من الحد الأدنى لإصدار التطبيق الذي يمكنه فتح الرابط. إذا كان التطبيق المُثبَّت إصدارًا قديمًا، يتم نقل المستخدم إلى "متجر Play" لترقية التطبيق.
معلَمات Ios
setAppStoreId رقم تعريف تطبيقك على App Store، يُستخدَم لتوجيه المستخدمين إلى App Store عند عدم تثبيت التطبيق
setFallbackUrl الرابط الذي يتم فتحه عندما لا يكون التطبيق مثبَّتًا. حدِّد هذا الإجراء لتنفيذ إجراء آخر غير تثبيت التطبيق من App Store في حال عدم تثبيت التطبيق، مثل فتح إصدار الويب المتوافق مع الأجهزة الجوّالة من المحتوى أو عرض صفحة ترويجية لتطبيقك.
تعيين CustomScheme مخطَّط عنوان URL المخصّص لتطبيقك، إذا تم تحديده على أنّه شيء مختلف عن معرّف حزمة التطبيق
setIpadFallbackUrl الرابط الذي يتم فتحه على أجهزة iPad عندما يكون التطبيق غير مثبَّت. حدِّد هذا الإجراء لتنفيذ إجراء آخر غير تثبيت التطبيق من App Store في حال عدم تثبيت التطبيق، مثل فتح إصدار الويب من المحتوى أو عرض صفحة ترويجية لتطبيقك.
setIpadBundleId رقم تعريف الحزمة الخاص بتطبيق iOS والمطلوب استخدامه على أجهزة iPad لفتح الرابط يجب ربط التطبيق بمشروعك من صفحة النظرة العامة في وحدة تحكّم Firebase.
ضبط الحد الأدنى للإصدار رقم الإصدار من أدنى إصدار من تطبيقك يمكنه فتح الرابط. يتم تمرير هذه العلامة إلى تطبيقك عند فتحه، وعلى التطبيق تحديد الإجراء الذي سيتم اتخاذه بشأنه.
مَعلَمات معلومات التنقّل
setForcedRedirectEnabled في حال الضبط على "1"، يمكنك تخطّي صفحة معاينة التطبيق عند فتح "Dynamic Link"، وإعادة التوجيه إلى التطبيق أو المتجر بدلاً من ذلك. يمكن لصفحة معاينة التطبيق (المفعَّلة تلقائيًا) توجيه المستخدمين إلى الوجهة الأكثر ملاءمةً عند فتح Dynamic Links في التطبيقات. ومع ذلك، إذا كنت تتوقع أن يتم فتح Dynamic Link فقط في التطبيقات التي يمكنها فتح 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 بدلاً من ضبط المعلَمات باستخدام أداة الإنشاء الأخرى الطرق:

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