Skip to content

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’s homeURL when it is opened.
  • The <query-params> are optional parameters added to the homeURL 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

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.

When copying the link from the Mini App header, it doesn't copy the Universal Link, why is that?

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.

Can I add a sub-path or query params to the Universal Link copied from the Mini App header?

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.