Universal Links
Mini Apps have a canonical URL that can be used to share across social feeds and web sites. The URL format is as follows:
https://farcaster.xyz/miniapps/<app-id>/<app-slug>(/<sub-path>)(?<query-params>)
- The
<app-id>
is a unique identifier assigned to the Mini App when it is published. - The
<app-slug>
is a kebab-case version of the Mini App name, used to create a more readable URL. - The
<sub-path>
is an optional path appended to the Mini App’shomeURL
when it is opened. - The
<query-params>
are optional parameters added to thehomeURL
as a query string when the Mini App is opened.
The <sub-path>
and <query-params>
are optional and can be used to navigate to a specific page in the Mini App or pass data to the Mini App.
When a user clicks a Universal Link and is logged in:
- On web: the Mini App opens in the mini app drawer.
- On mobile: the browser deep links to the Farcaster app and opens the Mini App.
Where to find the Universal Link
On the web Developers page, click the top-right kebab menu on one of your Mini App cards and select "Copy link to mini app". This copies the Universal Link to your clipboard.
When the Mini App is open, tap on the top-right kebab menu and select "Copy link" to copy the Universal Link to your clipboard.
Copy link to mini app on the Developers page or the Mini App screen.
How to control what is displayed when I share a Universal Link
Farcaster automatically generates OpenGraph meta tags for Universal Links, ensuring they render correctly when shared on social platforms or web apps that support embedded link previews, such as X.
To make sure your Mini App displays as intended, include the fc:frame
meta tag on all
Universal Links (see "Sharing your app") and add all relevant fields
in your application config,
especially ogTitle
, ogDescription
and ogImageUrl
.
How Universal Link sub-paths and query params work
Each Mini App defines a homeUrl
property in its application config.
When a user clicks on a Mini App in the Farcaster client's Mini App explorer, a
WebView (on mobile) or iframe (on web) pointing to the homeUrl
is opened.
If you share a Universal Link with a sub-path and/or query parameters, those are appended
to the homeUrl
's path and query string.
For example, if the homeUrl
is https://example.com/miniapp/v1
and the Universal
Link is https://farcaster.xyz/miniapps/12345/example-miniapp/leaderboard?sort=points
, the WebView or iframe will load https://example.com/miniapp/v1/leaderboard?sort=points
.
FAQ
Is there another way to get a Mini App's id?Not at the moment.
How can I map a Mini App Universal Link to a domain?The domain is provided in the fc:miniapp:domain
meta tag.
Any URL with a valid fc:frame
meta tag shared in a cast will be treated as a Mini App.
Copying the link from these Mini Apps will copy the original URL shared in the cast, not the canonical Universal Link.
Not at the moment. Only the canonical Universal Link or URL shared in the cast will be copied.
Can I open a Mini App from another Mini App?Yes, you can open a Mini App from another Mini App by using the openMiniApp
action.
This will prompt the user to open the new app. Note that this closes the current app when the new app is opened and there is no way to navigate back.