יצירת קישורים דינמיים ב-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:33.6.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.2'
    }
    מחפשים מודול ספרייה ספציפי ל-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 חדש באמצעות ה-Builder שלו, ולציין את הפרמטרים Dynamic Link באמצעות ה-methods של Builder. לאחר מכן קוראים ל-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 עם כל אחד מהפרמטרים הנתמכים. פרטים נוספים זמינים בהפניית ה-API.

בדוגמה הבאה נוצר 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 בשיטות הבאות:

פרמטרים של DynamicLink
setLink

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