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

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

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

قبل أن تتمكن من إنشاء روابط ديناميكية في تطبيق Android الخاص بك، يجب عليك تضمين Firebase SDK. إذا تم إعداد تطبيقك لتلقي الروابط الديناميكية، فقد أكملت هذه الخطوات بالفعل ويمكنك تخطي هذا القسم.

  1. إذا لم تكن قد قمت بذلك بالفعل، فأضف Firebase إلى مشروع Android الخاص بك .

    عندما تقوم بتسجيل تطبيقك، حدد مفتاح التوقيع SHA-1 الخاص بك. إذا كنت تستخدم روابط التطبيقات، فحدد أيضًا مفتاح SHA-256 الخاص بك.

  2. في ملف Gradle الخاص بالوحدة النمطية (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle )، قم بإضافة التبعية للارتباطات الديناميكية مكتبة لالروبوت. نوصي باستخدام Firebase Android BoM للتحكم في إصدار المكتبة.

    للحصول على تجربة مثالية مع الروابط الديناميكية، نوصي بتمكين Google Analytics في مشروع Firebase الخاص بك وإضافة Firebase SDK لـ Google Analytics إلى تطبيقك.

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:32.8.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:21.2.0'
        implementation 'com.google.firebase:firebase-analytics:21.6.1'
    }
    
    هل تبحث عن وحدة مكتبة خاصة بـ Kotlin؟ بدءًا من أكتوبر 2023 (Firebase BoM 32.5.0) ، يمكن لمطوري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (لمزيد من التفاصيل، راجع الأسئلة الشائعة حول هذه المبادرة ).
  3. في وحدة تحكم Firebase، افتح قسم الروابط الديناميكية .
  4. إذا لم تكن قد قبلت بالفعل شروط الخدمة وقمت بتعيين مجال للارتباطات الديناميكية الخاصة بك، فقم بذلك عندما يُطلب منك ذلك.

    إذا كان لديك بالفعل مجال الارتباطات الديناميكية، فلاحظ ذلك. يتعين عليك توفير مجال الارتباطات الديناميكية عند إنشاء الارتباطات الديناميكية برمجيًا.

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

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

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

لإنشاء ارتباط ديناميكي، قم بإنشاء كائن DynamicLink جديد باستخدام منشئه، مع تحديد معلمات الارتباط الديناميكي باستخدام أساليب Builder. ثم اتصل بـ buildDynamicLink أو buildShortDynamicLink .

ينشئ المثال البسيط التالي رابطًا ديناميكيًا طويلًا إلى 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();

لإنشاء ارتباط ديناميكي قصير، قم ببناء 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
                    // ...
                }
            }
        });

افتراضيًا، يتم إنشاء الارتباطات الديناميكية القصيرة باستخدام لاحقات ارتباط مكونة من 17 حرفًا، مما يجعل من غير المحتمل جدًا أن يتمكن أي شخص من تخمين الارتباط الديناميكي الصالح. إذا لم يكن هناك أي ضرر، بالنسبة لحالة الاستخدام الخاصة بك، في قيام شخص ما بتخمين رابط قصير بنجاح، فقد تفضل إنشاء لاحقات طالما كانت ضرورية لتكون فريدة، وهو ما يمكنك القيام به عن طريق تمرير 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 لإنشاء روابط ديناميكية باستخدام أي من المعلمات المدعومة. راجع مرجع API للحصول على التفاصيل.

يقوم المثال التالي بإنشاء ارتباط ديناميكي مع مجموعة من المعلمات الشائعة:

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

يمكنك تعيين معلمات الارتباط الديناميكي بالطرق التالية:

معلمات الارتباط الديناميكي
setLink

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

setDomainUriPrefix بادئة عنوان URL للرابط الديناميكي، والتي يمكنك العثور عليها في وحدة تحكم Firebase. يشبه مجال الارتباط الديناميكي الأمثلة التالية:
https://example.com/link
https://example.page.link
معلمات Android
setFallbackUrl الرابط الذي سيتم فتحه عندما لا يكون التطبيق مثبتًا. حدد هذا للقيام بشيء آخر غير تثبيت تطبيقك من متجر Play عندما لا يكون التطبيق مثبتًا، مثل فتح إصدار الويب للجوال من المحتوى، أو عرض صفحة ترويجية لتطبيقك.
setMinimumVersion versionCode الخاص بالإصدار الأدنى لتطبيقك الذي يمكنه فتح الرابط. إذا كان التطبيق المثبت إصدارًا أقدم، فسيتم نقل المستخدم إلى متجر Play لترقية التطبيق.
IosParameters
setAppStoreId معرف متجر التطبيقات الخاص بتطبيقك، والذي يُستخدم لإرسال المستخدمين إلى متجر التطبيقات عندما لا يكون التطبيق مثبتًا
setFallbackUrl الرابط الذي سيتم فتحه عندما لا يكون التطبيق مثبتًا. حدد هذا للقيام بشيء آخر غير تثبيت تطبيقك من App Store عندما لا يكون التطبيق مثبتًا، مثل فتح إصدار الويب للجوال من المحتوى، أو عرض صفحة ترويجية لتطبيقك.
setCustomScheme نظام عنوان URL المخصص لتطبيقك، إذا تم تعريفه على أنه شيء آخر غير معرف حزمة تطبيقك
setIpadFallbackUrl الرابط الذي سيتم فتحه على أجهزة iPad عندما لا يكون التطبيق مثبتًا. حدد هذا للقيام بشيء آخر غير تثبيت تطبيقك من App Store عندما لا يكون التطبيق مثبتًا، مثل فتح إصدار الويب من المحتوى، أو عرض صفحة ترويجية لتطبيقك.
setIpadBundleId معرف حزمة تطبيق iOS المراد استخدامه على أجهزة iPad لفتح الرابط. يجب أن يكون التطبيق متصلاً بمشروعك من صفحة النظرة العامة في وحدة تحكم Firebase.
setMinimumVersion رقم إصدار الحد الأدنى من إصدار تطبيقك الذي يمكنه فتح الرابط. يتم تمرير هذه العلامة إلى تطبيقك عند فتحه، ويجب أن يقرر تطبيقك ما يجب فعله بها.
معلمات معلومات التنقل
setForcedRedirectEnabled إذا تم التعيين على "1"، فتخطى صفحة معاينة التطبيق عند فتح الرابط الديناميكي، وأعد التوجيه بدلاً من ذلك إلى التطبيق أو المتجر. يمكن لصفحة معاينة التطبيق (التي يتم تمكينها افتراضيًا) إرسال المستخدمين بشكل أكثر موثوقية إلى الوجهة الأكثر ملاءمة عند فتح الروابط الديناميكية في التطبيقات؛ ومع ذلك، إذا كنت تتوقع أن يتم فتح الارتباط الديناميكي فقط في التطبيقات التي يمكنها فتح الارتباطات الديناميكية بشكل موثوق بدون هذه الصفحة، فيمكنك تعطيله باستخدام هذه المعلمة. ستؤثر هذه المعلمة على سلوك الارتباط الديناميكي على نظام iOS فقط.
SocialMetaTagParameters
تعيين العنوان العنوان الذي سيتم استخدامه عند مشاركة الارتباط الديناميكي في منشور اجتماعي.
setDescription الوصف الذي سيتم استخدامه عند مشاركة الارتباط الديناميكي في منشور اجتماعي.
setImageUrl عنوان URL للصورة المرتبطة بهذا الرابط. يجب أن تكون الصورة بحجم 300 × 200 بكسل على الأقل، وأقل من 300 كيلو بايت.
معلمات GoogleAnalytics
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 ) إلى متجر التطبيقات.

لتقصير رابط ديناميكي طويل، حدد عنوان URL للارتباط الديناميكي باستخدام 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
                    // ...
                }
            }
        });