יצירת קישורים דינמיים ב-Android

אפשר ליצור Dynamic Links קצרים או ארוכים באמצעות Firebase Dynamic Links Builder API. ה-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 ולהוסיף לאפליקציה את Firebase SDK for Google Analytics.

    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 שמותר להשתמש בהן בקישורי העומק ובקישורי ה-fallback. כך אפשר למנוע מגורמים לא מורשים ליצור Dynamic Links שמפנים מהדומיין שלך לאתרים שאין לך שליטה עליהם. אפשר לעיין במאמר אישור של תבניות URL ספציפיות.

שימוש במסוף 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 קצרות נוצרות עם סיומות קישור באורך 17 תווים, כך שאין כמעט סיכוי שמישהו יצליח לנחש Dynamic Link חוקית. אם בתרחיש לדוגמה שלכם אין נזק בכך שמישהו ינחש בהצלחה קישור קצר, יכול להיות שתעדיפו ליצור סיומות באורך המינימלי שנדרש כדי שהן יהיו ייחודיות. אפשר לעשות זאת על ידי העברת ShortDynamicLink.Suffix.SHORT ל-method‏ buildShortDynamicLink:

Kotlin

val shortLinkTask = Firebase.dynamicLinks.shortLinkAsync(ShortDynamicLink.Suffix.SHORT) {
    // Set parameters
    // ...
}

Java

Task<ShortDynamicLink> shortLinkTask = FirebaseDynamicLinks.getInstance().createDynamicLink()
        // ...
        .buildShortDynamicLink(ShortDynamicLink.Suffix.SHORT);
        // ...

אתם יכולים להשתמש ב-API של Dynamic Link Builder כדי ליצור Dynamic Links עם כל אחד מהפרמטרים הנתמכים. למידע נוסף, קראו את מאמרי העזרה של ה-API.

בדוגמה הבאה נוצר 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 שהאפליקציה יכולה לטפל בה, בדרך כלל התוכן או המטען הייעודי (payload) של האפליקציה, שמפעילים לוגיקה ספציפית לאפליקציה (כמו זיכוי המשתמש בשובר או הצגת מסך פתיחה). הקישור הזה חייב להיות כתובת URL בפורמט תקין, מקודד כראוי, להשתמש ב-HTTP או ב-HTTPS, ולא יכול להיות קישור דינמי אחר.

setDomainUriPrefix הקידומת של כתובת ה-URL של 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 סכמת ה-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 של תמונה שקשורה לקישור הזה. התמונה צריכה להיות בגודל של לפחות 300x200 פיקסלים, ופחות מ-300KB.
GoogleAnalyticsParameters
setSource
setMedium
setCampaign
setTerm
setContent
פרמטרים של ניתוח נתונים ב-Google Play. הפרמטרים האלה (utm_source, utm_medium, utm_campaign, utm_term, utm_content) מועברים לחנות Play וגם מצורפים למטען הייעודי (payload) של הקישור.
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
    // ...
}

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