|
| 1 | +--- |
| 2 | +title: Create Dynamic Links in a Flutter app |
| 3 | +sidebar_label: Create Links In-App |
| 4 | +--- |
| 5 | + |
| 6 | +You can create short or long Dynamic Links with the Firebase Dynamic Links Builder API. |
| 7 | +This API accepts either a long Dynamic Link or an object containing Dynamic Link |
| 8 | +parameters, and returns URLs like the following examples: |
| 9 | + |
| 10 | +``` |
| 11 | +https://example.com/link/WXYZ |
| 12 | +https://example.page.link/WXYZ |
| 13 | +``` |
| 14 | + |
| 15 | +## Set up Firebase and the Dynamic Links SDK |
| 16 | + |
| 17 | +Before you can create Dynamic Links in your Android app, you must include the |
| 18 | +Firebase SDK. If your app is set up to receive Dynamic Links, you have already |
| 19 | +completed these steps and you can skip this section. |
| 20 | + |
| 21 | +1. [Install and initialize the Firebase SDKs for Flutter](../overview) if you |
| 22 | + haven't already done so. |
| 23 | + |
| 24 | +1. From the root direcctory of your Flutter project, run the following |
| 25 | + command to install the Dynamic Links plugin: |
| 26 | + |
| 27 | + ``` |
| 28 | + flutter pub add firebase_dynamic_links |
| 29 | + ``` |
| 30 | + |
| 31 | +1. If you're building an Android app, open the [Project settings](https://console.firebase.google.com/project/_/settings/general/) |
| 32 | + page of the Firebase console and make sure you've specified your SHA-1 |
| 33 | + signing key. If you use App Links, also specify your SHA-256 key. |
| 34 | + |
| 35 | +1. In the Firebase console, open the [Dynamic Links](https://console.firebase.google.com/project/_/durablelinks) |
| 36 | + section. |
| 37 | + |
| 38 | + 1. If you have not already set up a domain for your Dynamic Links, click the |
| 39 | + **Get Started** button and follow the prompts. |
| 40 | + |
| 41 | + If you already have a Dynamic Links domain, take note of it. You need to |
| 42 | + provide a Dynamic Links domain when you programmatically create Dynamic Links. |
| 43 | + <img src="https://firebase.google.com/docs/dynamic-links/images/dynamic-links-domain.png"></img> |
| 44 | + |
| 45 | + 1. **Recommended**: From the "More" (⋮) menu, specify the URL |
| 46 | + patterns allowed in your deep links and fallback links. By doing so, |
| 47 | + you prevent unauthorized parties from creating Dynamic Links that redirect |
| 48 | + from your domain to sites you don't control. |
| 49 | + |
| 50 | + See <a href="https://support.google.com/firebase/answer/9021429">Allow specific URL patterns</a>. |
| 51 | + |
| 52 | + |
| 53 | +## Create a Dynamic Link from parameters |
| 54 | + |
| 55 | +To create a Dynamic Link, create a new `DynamicLinkParameters` object and pass it to |
| 56 | +`buildLink()` or `buildShortLink()`. |
| 57 | + |
| 58 | +The following minimal example creates a long Dynamic Link to |
| 59 | +`https://www.example.com/` that opens with `com.example.app.android` on Android |
| 60 | +and the app `com.example.app.ios` on iOS: |
| 61 | + |
| 62 | +```dart |
| 63 | +final dynamicLinkParams = DynamicLinkParameters( |
| 64 | + link: Uri.parse("https://www.example.com/"), |
| 65 | + uriPrefix: "https://example.page.link", |
| 66 | + androidParameters: const AndroidParameters(packageName: "com.example.app.android"), |
| 67 | + iosParameters: const IOSParameters(bundleId: "com.example.app.ios"), |
| 68 | +); |
| 69 | +final dynamicLink = |
| 70 | + await FirebaseDynamicLinks.instance.buildLink(dynamicLinkParams); |
| 71 | +``` |
| 72 | + |
| 73 | +To create a short Dynamic Link, pass the `DynamicLinkParameters` object to |
| 74 | +`buildShortLink()`. Building the short link requires a network call. |
| 75 | +For example: |
| 76 | + |
| 77 | +```dart |
| 78 | +final dynamicLinkParams = DynamicLinkParameters( |
| 79 | + link: Uri.parse("https://www.example.com/"), |
| 80 | + uriPrefix: "https://example.page.link", |
| 81 | + androidParameters: const AndroidParameters(packageName: "com.example.app.android"), |
| 82 | + iosParameters: const IOSParameters(bundleId: "com.example.app.ios"), |
| 83 | +); |
| 84 | +final dynamicLink = |
| 85 | + await FirebaseDynamicLinks.instance.buildShortLink(dynamicLinkParams); |
| 86 | +``` |
| 87 | + |
| 88 | +By default, short Dynamic Links are generated with suffixes that are only a few |
| 89 | +characters long. Although this makes links more compact, it also introduces |
| 90 | +the possibility that someone could guess a valid short link. Often, there's no |
| 91 | +harm if someone does so, because the link leads to public information. |
| 92 | + |
| 93 | +However, if your short links lead to user-specific information, you should |
| 94 | +create longer links with 17-character suffixes that make it very unlikely that |
| 95 | +someone can guess a valid Dynamic Link. To do so, pass `ShortDynamicLinkType.unguessable` |
| 96 | +to the `buildShortLink()` method: |
| 97 | + |
| 98 | +```dart |
| 99 | +final unguessableDynamicLink = await FirebaseDynamicLinks.instance.buildShortLink( |
| 100 | + dynamicLinkParams, |
| 101 | + shortLinkType: ShortDynamicLinkType.unguessable, |
| 102 | +); |
| 103 | +``` |
| 104 | + |
| 105 | +<h3>Dynamic Link parameters</h3> |
| 106 | + |
| 107 | +You can use the Dynamic Link Builder API to create Dynamic Links with any of the |
| 108 | +supported parameters. See the [API reference](https://pub.dev/documentation/firebase_dynamic_links_platform_interface/latest/firebase_dynamic_links_platform_interface/DynamicLinkParameters-class.html). |
| 109 | + |
| 110 | +The following example creates a Dynamic Link with several common parameters |
| 111 | +set: |
| 112 | + |
| 113 | +```dart |
| 114 | +final dynamicLinkParams = DynamicLinkParameters( |
| 115 | + link: Uri.parse("https://www.example.com/"), |
| 116 | + uriPrefix: "https://example.page.link", |
| 117 | + androidParameters: const AndroidParameters( |
| 118 | + packageName: "com.example.app.android", |
| 119 | + minimumVersion: 30, |
| 120 | + ), |
| 121 | + iosParameters: const IOSParameters( |
| 122 | + bundleId: "com.example.app.ios", |
| 123 | + appStoreId: "123456789", |
| 124 | + minimumVersion: "1.0.1", |
| 125 | + ), |
| 126 | + googleAnalyticsParameters: const GoogleAnalyticsParameters( |
| 127 | + source: "twitter", |
| 128 | + medium: "social", |
| 129 | + campaign: "example-promo", |
| 130 | + ), |
| 131 | + socialMetaTagParameters: SocialMetaTagParameters( |
| 132 | + title: "Example of a Dynamic Link", |
| 133 | + imageUrl: Uri.parse("https://example.com/image.png"), |
| 134 | + ), |
| 135 | +); |
| 136 | +final dynamicLink = |
| 137 | + await FirebaseDynamicLinks.instance.buildShortLink(dynamicLinkParams); |
| 138 | +``` |
| 139 | + |
| 140 | +You can set Dynamic Link parameters with the following methods: |
| 141 | + |
| 142 | +<table> |
| 143 | + <tr><th colspan="2" id="general-params">DynamicLink parameters</th></tr> |
| 144 | + <tr> |
| 145 | + <td>setLink</td> |
| 146 | + <td>The link your app will open. Specify a URL that your app can handle, |
| 147 | + typically the app's content or payload, which initiates app-specific |
| 148 | + logic (such as crediting the user with a coupon or displaying a |
| 149 | + welcome screen). This link must be a well-formatted URL, be properly |
| 150 | + URL-encoded, use either HTTP or HTTPS, and cannot be another Dynamic |
| 151 | + Link. |
| 152 | + <aside>When users open a Dynamic Link on a desktop web browser, they |
| 153 | + will load this URL (unless the ofl parameter is specified). If you |
| 154 | + don't have a web equivalent to the linked content, the URL doesn't |
| 155 | + need to point to a valid web resource. In this situation, you |
| 156 | + should set up a redirect from this URL to, for example, your home |
| 157 | + page. |
| 158 | + </aside> |
| 159 | + </td> |
| 160 | + </tr> |
| 161 | + <tr> |
| 162 | + <td>setDomainUriPrefix</td> |
| 163 | + <td>Your Dynamic Link URL prefix, which you can find in the Firebase console. A |
| 164 | + Dynamic Link domain looks like the following examples: |
| 165 | + <pre> |
| 166 | +https://example.com/link |
| 167 | +https://example.page.link |
| 168 | +</pre> |
| 169 | + </td> |
| 170 | + </tr> |
| 171 | +</table> |
| 172 | + |
| 173 | +<table id="android-params"> |
| 174 | + <tr><th colspan="2">AndroidParameters</th></tr> |
| 175 | + <tr> |
| 176 | + <td>setFallbackUrl</td> |
| 177 | + <td>The link to open when the app isn't installed. Specify this to do |
| 178 | + something other than install your app from the Play Store when the app |
| 179 | + isn't installed, such as open the mobile web version of the content, or |
| 180 | + display a promotional page for your app.</td> |
| 181 | + </tr> |
| 182 | + <tr> |
| 183 | + <td>setMinimumVersion</td> |
| 184 | + <td>The versionCode of the minimum version of your app that can open the |
| 185 | + link. If the installed app is an older version, the user is taken to |
| 186 | + the Play Store to upgrade the app.</td> |
| 187 | + </tr> |
| 188 | +</table> |
| 189 | + |
| 190 | +<table id="ios-params"> |
| 191 | + <tr><th colspan="2">IosParameters</th></tr> |
| 192 | + <tr> |
| 193 | + <td>setAppStoreId</td> |
| 194 | + <td>Your app's App Store ID, used to send users to the App Store when the |
| 195 | + app isn't installed</td> |
| 196 | + </tr> |
| 197 | + <tr> |
| 198 | + <td>setFallbackUrl</td> |
| 199 | + <td>The link to open when the app isn't installed. Specify this to do |
| 200 | + something other than install your app from the App Store when the app |
| 201 | + isn't installed, such as open the mobile web version of the content, or |
| 202 | + display a promotional page for your app.</td> |
| 203 | + </tr> |
| 204 | + <tr> |
| 205 | + <td>setCustomScheme</td> |
| 206 | + <td>Your app's custom URL scheme, if defined to be something other than |
| 207 | + your app's bundle ID</td> |
| 208 | + </tr> |
| 209 | + <tr> |
| 210 | + <td>setIpadFallbackUrl</td> |
| 211 | + <td>The link to open on iPads when the app isn't installed. Specify this to |
| 212 | + do something other than install your app from the App Store when the |
| 213 | + app isn't installed, such as open the web version of the content, or |
| 214 | + display a promotional page for your app.</td> |
| 215 | + </tr> |
| 216 | + <tr> |
| 217 | + <td>setIpadBundleId</td> |
| 218 | + <td>The bundle ID of the iOS app to use on iPads to open the link. The app |
| 219 | + must be connected to your project from the Overview page of the |
| 220 | + Firebase console.</td> |
| 221 | + </tr> |
| 222 | + <tr> |
| 223 | + <td>setMinimumVersion</td> |
| 224 | + <td>The version number of the minimum version of your app that can open the |
| 225 | + link. This flag is passed to your app when it is opened, and your app |
| 226 | + must decide what to do with it.</td> |
| 227 | + </tr> |
| 228 | +</table> |
| 229 | + |
| 230 | +<table> |
| 231 | + <tr><th colspan="2">NavigationInfoParameters</th></tr> |
| 232 | + <tr> |
| 233 | + <td>setForcedRedirectEnabled</td> |
| 234 | + <td>If set to '1', skip the app preview page when the Dynamic Link is |
| 235 | + opened, and instead redirect to the app or store. The app preview page |
| 236 | + (enabled by default) can more reliably send users to the most |
| 237 | + appropriate destination when they open Dynamic Links in apps; however, |
| 238 | + if you expect a Dynamic Link to be opened only in apps that can open |
| 239 | + Dynamic Links reliably without this page, you can disable it with this |
| 240 | + parameter. This parameter will affect the behavior of the Dynamic Link |
| 241 | + only on iOS.</td> |
| 242 | + </tr> |
| 243 | +</table> |
| 244 | + |
| 245 | +<table id="social-params"> |
| 246 | + <tr><th colspan="2">SocialMetaTagParameters</th></tr> |
| 247 | + <tr> |
| 248 | + <td>setTitle</td> |
| 249 | + <td>The title to use when the Dynamic Link is shared in a social post.</td> |
| 250 | + </tr> |
| 251 | + <tr> |
| 252 | + <td>setDescription</td> |
| 253 | + <td>The description to use when the Dynamic Link is shared in a social post.</td> |
| 254 | + </tr> |
| 255 | + <tr> |
| 256 | + <td>setImageUrl</td> |
| 257 | + <td>The URL to an image related to this link. The image should be at least |
| 258 | + 300x200 px, and less than 300 KB.</td> |
| 259 | + </tr> |
| 260 | +</table> |
| 261 | + |
| 262 | +<table id="google-analytics-params"> |
| 263 | + <tr><th colspan="2">GoogleAnalyticsParameters</th></tr> |
| 264 | + <tr> |
| 265 | + <td>setSource<br/>setMedium<br/>setCampaign<br/>setTerm<br/>setContent</td> |
| 266 | + <td>Google Play analytics parameters. These parameters |
| 267 | + (`utm_source`, `utm_medium`, |
| 268 | + `utm_campaign`, `utm_term`, `utm_content`) |
| 269 | + are passed on to the Play Store as well as appended to the link payload. |
| 270 | + </td> |
| 271 | + </tr> |
| 272 | +</table> |
| 273 | + |
| 274 | +<table id="itunes-analytics-params"> |
| 275 | + <tr><th colspan="2">ItunesConnectAnalyticsParameters</th></tr> |
| 276 | + <tr> |
| 277 | + <td>setProviderToken<br/>setAffiliateToken<br/>setCampaignToken</td> |
| 278 | + <td>iTunes Connect analytics parameters. These parameters (`pt`, |
| 279 | + `at`, `ct`) are passed to the App Store.</td> |
| 280 | + </tr> |
| 281 | +</table> |
0 commit comments