Skip to content

Commit 54fe61b

Browse files
kevinthecheungkevinthecheung
authored
docs(dynamic-links): Docs from official site (#8258)
1 parent 131773d commit 54fe61b

File tree

7 files changed

+484
-288
lines changed

7 files changed

+484
-288
lines changed

‎docs/dynamic-links/android-integration.mdx

Lines changed: 0 additions & 31 deletions
This file was deleted.

‎docs/dynamic-links/apple-integration.mdx

Lines changed: 0 additions & 72 deletions
This file was deleted.

‎docs/dynamic-links/create.mdx

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
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" (&vellip;) 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

Comments
 (0)