ایجاد پیوندهای پویا در Android

بااستفاده از Builder API (میانای برنامه‌سازی کاربردی سازنده) Firebase Dynamic Links می‌توانید Dynamic Links کوتاه یا بلند ایجاد کنید. این میانای برنامه‌سازی کاربردی یا یک Dynamic Link طولانی یا یک شیء حاوی پارامترهای Dynamic Link را می‌پذیرد و نشانی‌های وب را مانند مثال‌های زیر برمی‌گرداند:

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

قبل‌از اینکه بتوانید Dynamic Links را در برنامه Android خود ایجاد کنید، باید کیت توسعه نرم‌افزار 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 خود و افزودن کیت توسعه نرم‌افزار Firebase برای Google Analytics به برنامه خود.

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:35.0.2"))
    
        // 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. توصیه‌شده: الگوهای نشانی وب مجاز در پیوندهای عمیق و پیوندهای بازگشتی را مشخص کنید. با انجام این کار، از ایجاد Dynamic Links توسط طرف‌های غیرمجاز که از دامنه شما به سایت‌هایی که تحت کنترل شما نیستند هدایت می‌کنند جلوگیری می‌کنید. بخش مجاز کردن الگوهای نشانی وب خاص را ببینید.

استفاده از کنسول Firebase

اگر می‌خواهید یک Dynamic Link تکی ایجاد کنید، چه برای اهداف آزمایشی یا برای تیم بازاریابی‌تان تا به‌راحتی پیوندی ایجاد کنند که بتوان از آن در چیزی مثل پست رسانه‌های اجتماعی استفاده کرد، ساده‌ترین راه این است که به کنسول Firebase بروید و با دنبال کردن فرم گام‌به‌گام، یکی را به‌صورت دستی ایجاد کنید.

برای ایجاد Dynamic Link، شیء DynamicLink جدیدی با Builder آن ایجاد کنید و پارامترهای Dynamic Link را با روش‌های Builder مشخص کنید. سپس با 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
                    // ...
                }
            }
        });

به‌طور پیش‌فرض، Dynamic Links کوتاه با پسوند پیوند ۱۷ نویسه‌ای تولید می‌شود که حدس زدن 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
تنظیم پیوند

پیوندی که برنامه‌تان باز خواهد کرد. نشانی وبی را مشخص کنید که برنامه‌تان بتواند آن را مدیریت کند، معمولاً محتوا یا بار مفید برنامه که منطق مختص برنامه را آغاز می‌کند (مثل اعتبار دادن به کاربر با کوپن یا نمایش صفحه خوشامدگویی). این پیوند باید نشانی وب با قالب‌بندی مناسب باشد، به‌درستی کدگذاری نشانی وب شده باشد، از HTTP یا HTTPS استفاده کند، و نمی‌تواند «پیوند پویای» دیگری باشد.

setDomainUriPrefix پیشوند نشانی وب 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 طرح‌واره نشانی وب سفارشی برنامه‌تان، اگر چیزی غیراز شناسه دسته نرم‌افزاری برنامه‌تان تعریف شده باشد
setIpadFallbackUrl پیوندی که وقتی برنامه نصب نشده است در iPad باز می‌شود. این را برای انجام کاری غیراز نصب برنامه‌تان از App Store (وقتی برنامه نصب نشده است) مشخص کنید، مثلاً باز کردن نسخه وب محتوا، یا نمایش صفحه تبلیغاتی برای برنامه‌تان.
setIpadBundleId شناسه دسته نرم‌افزاری برنامه iOS برای استفاده در iPad جهت باز کردن پیوند. برنامه باید از صفحه «نمای کلی» کنسول Firebase به پروژه شما متصل شود.
setMinimumVersion شماره نسخه حداقل نسخه‌ای از برنامه‌تان که می‌تواند پیوند را باز کند. این پرچم هنگام باز شدن برنامه به آن منتقل می‌شود و برنامه شما باید تصمیم بگیرد که با آن چه کند.
NavigationInfoParameters
setForcedRedirectEnabled اگر روی «۱» تنظیم شود، وقتی Dynamic Link باز می‌شود، از صفحه پیش‌نمایش برنامه رد می‌شود و درعوض به برنامه یا فروشگاه هدایت می‌شود. صفحه پیش‌نمایش برنامه (به‌طور پیش‌فرض فعال است) می‌تواند با اطمینان بیشتری کاربران را به مناسب‌ترین مقصد هدایت کند وقتی‌که Dynamic Links را در برنامه‌ها باز می‌کنند؛ بااین‌حال، اگر انتظار دارید Dynamic Link فقط در برنامه‌هایی باز شود که می‌توانند Dynamic Links را بدون این صفحه به‌طور مطمئن باز کنند، می‌توانید آن را با این پارامتر غیرفعال کنید. این پارامتر فقط در iOS بر رفتار Dynamic Link تأثیر می‌گذارد.
SocialMetaTagParameters
تنظیم عنوان عنوانی که هنگام هم‌رسانی Dynamic Link در پست اجتماعی استفاده می‌شود.
setDescription شرحی که هنگام هم‌رسانی Dynamic Link در پست اجتماعی استفاده می‌شود.
setImageUrl نشانی وب تصویر مربوط به این پیوند. تصویر باید حداقل ۳۰۰×۲۰۰ پیکسل و کمتر از ۳۰۰ کیلوبایت باشد.
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 طولانی، نشانی وب 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
                    // ...
                }
            }
        });