יצירת קישורים דינמיים ב-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:34.0.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:22.1.0'
    implementation 'com.google.firebase:firebase-analytics:23.0.0'
}
  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 באמצעות שיטות ה-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
MainActivity.kt

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();
MainActivity.java

כדי ליצור סרטון Shorts 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
    // ...
}
MainActivity.kt

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

כברירת מחדל, קישורי Dynamic Links נוצרים עם סיומות של 17 תווים, כך שמאוד לא סביר שמישהו יוכל לנחש Dynamic Link תקין. אם בתרחיש לדוגמה שלכם אין נזק אם מישהו מנחש בהצלחה קישור קצר, יכול להיות שתעדיפו ליצור סיומות באורך שנדרש כדי להיות ייחודיות. כדי לעשות זאת, מעבירים את ShortDynamicLink.Suffix.SHORT לשיטה buildShortDynamicLink:

Kotlin

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

Java

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

אפשר להשתמש ב-Dynamic Link Builder API כדי ליצור 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!"
    }
}
MainActivity.kt

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()
MainActivity.java

אפשר להגדיר פרמטרים של Dynamic Link בשיטות הבאות:

פרמטרים של DynamicLink
setLink

הקישור שהאפליקציה תפתח. מציינים כתובת 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 הקישור לפתיחה באייפדים כשהאפליקציה לא מותקנת. אפשר לציין פעולה אחרת במקום התקנת האפליקציה מ-App Store אם האפליקציה לא מותקנת, כמו פתיחת גרסת האינטרנט של התוכן או הצגת דף קידום מכירות של האפליקציה.
setIpadBundleId מזהה החבילה של אפליקציית iOS שבה רוצים להשתמש באייפדים כדי לפתוח את הקישור. האפליקציה צריכה להיות מקושרת לפרויקט שלכם בדף 'סקירה כללית' בFirebaseמסוף.
setMinimumVersion מספר הגרסה של הגרסה המינימלית של האפליקציה שבה אפשר לפתוח את הקישור. הדגל הזה מועבר לאפליקציה כשפותחים אותה, והאפליקציה צריכה להחליט מה לעשות איתו.
NavigationInfoParameters
setForcedRedirectEnabled אם הערך מוגדר כ-1, כשפותחים את Dynamic Link, המערכת מדלגת על דף התצוגה המקדימה של האפליקציה ומפנה את המשתמש לאפליקציה או לחנות. דף התצוגה המקדימה של האפליקציה (מופעל כברירת מחדל) יכול לשלוח משתמשים בצורה מהימנה יותר ליעד המתאים ביותר כשהם פותחים Dynamic Links באפליקציות. עם זאת, אם אתם מצפים ש-Dynamic Links ייפתח רק באפליקציות שיכולות לפתוח Dynamic Links בצורה מהימנה בלי הדף הזה, אתם יכולים להשבית אותו באמצעות הפרמטר הזה.Dynamic Link הפרמטר הזה ישפיע על ההתנהגות של 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 במקום להגדיר פרמטרים באמצעות שיטות אחרות של הכלי ליצירת כתובות URL:

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
    // ...
}
MainActivity.kt

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