diff --git a/site/components/HighlightLink.tsx b/site/components/HighlightLink.tsx new file mode 100644 index 00000000..929bf3e2 --- /dev/null +++ b/site/components/HighlightLink.tsx @@ -0,0 +1,31 @@ +export function HighlightLink({ + href, + title, +}: { title: string; href: string }) { + return ( + +
+ {title}{' '} + + right arrow + + + +
+ + ) +} diff --git a/site/components/index.ts b/site/components/index.ts new file mode 100644 index 00000000..56401b6b --- /dev/null +++ b/site/components/index.ts @@ -0,0 +1,2 @@ +export * from './Caption.tsx' +export * from './HighlightLink.tsx' diff --git a/site/pages/docs/concepts/embeds.mdx b/site/pages/docs/concepts/embeds.mdx new file mode 100644 index 00000000..a382a291 --- /dev/null +++ b/site/pages/docs/concepts/embeds.mdx @@ -0,0 +1,118 @@ +--- +title: Manifest +description: Permisionlessly publish your Mini App +--- + +import { Caption, HighlightLink } from '../../../components/index.ts'; + +# Manifest + +A Manifest defines global metadata about a Mini App such as who the author is, +what the app is called, and the icon to use for it. This data is used to to +more deeply integrate into Farcaster clients and as well as be listed in Mini +App Stores. + + + + +## Format + +Manifests are JSON files hosted at `/.well-known/farcaster.json` on the [Fully +Qualified Domain +Name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) of the Mini +App. + + +## Schema + +| Property | Type | Required | Description | +|--------------------|--------|----------|--------------------------------------------------| +| accountAssociation | object | Yes | Verifies domain ownership to a Farcaster account | +| frame | object | Yes | Metadata about the Mini App | + +### accountAssociation + +The account association verifies authorship of this domain to a Farcaster +account. + +The value is set to the JSON representation of a [JSON Farcaster +Signature](https://github.com/farcasterxyz/protocol/discussions/208) from the +account's custody address with the following payload: + +```json +{ domain: "" } +``` + +The `domain` value must exactly match the FQDN of where it is hosted. + +#### Schema + +| Property | Type | Required | Description | +|-----------|--------|----------|---------------------------| +| header | string | Yes | base64 encoded JFS header | +| payload | string | Yes | base64 encoded payload | +| signature | string | Yes | base64 encoded signature | + + +#### Example + +```json +{ + "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0", + "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9", + "signature": "MHgwZmJiYWIwODg3YTU2MDFiNDU3MzVkOTQ5MDRjM2Y1NGUxMzVhZTQxOGEzMWQ5ODNhODAzZmZlYWNlZWMyZDYzNWY4ZTFjYWU4M2NhNTAwOTMzM2FmMTc1NDlmMDY2YTVlOWUwNTljNmZiNDUxMzg0Njk1NzBhODNiNjcyZWJjZTFi" +} +``` + +### frame + +Metadata needed to by Hosts to distribute the Mini App. + +import ManifestAppConfigSchema from "../../../snippets/manifestAppConfigSchema.mdx" + + + + +#### Example + +import ManifestAppConfigExample from "../../../snippets/manifestAppConfigExample.mdx" + + + + +## Example + +Example of a valid farcaster.json manifest: + +```json +{ + "accountAssociation": { + "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0", + "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9", + "signature": "MHgwZmJiYWIwODg3YTU2MDFiNDU3MzVkOTQ5MDRjM2Y1NGUxMzVhZTQxOGEzMWQ5ODNhODAzZmZlYWNlZWMyZDYzNWY4ZTFjYWU4M2NhNTAwOTMzM2FmMTc1NDlmMDY2YTVlOWUwNTljNmZiNDUxMzg0Njk1NzBhODNiNjcyZWJjZTFi" + }, + "frame": { + "version": "1", + "name": "Yoink!", + "iconUrl": "https://yoink.party/logo.png", + "homeUrl": "https://yoink.party/framesV2/", + "imageUrl": "https://yoink.party/framesV2/opengraph-image", + "buttonTitle": "🚩 Start", + "splashImageUrl": "https://yoink.party/logo.png", + "splashBackgroundColor": "#f5f0ec", + "webhookUrl": "https://yoink.party/api/webhook" + } +} +``` + +## Versioning + +Manifests will follow a simple versioning scheme where non-breaking +changes can be added to the same version but a breaking change must accompany a +version bump. + + +## Caching + +Farcaster clients may cache the manifest for a Mini App but should provide a +way for refreshing the manifest file. diff --git a/site/pages/docs/concepts/manifest.mdx b/site/pages/docs/concepts/manifest.mdx new file mode 100644 index 00000000..a382a291 --- /dev/null +++ b/site/pages/docs/concepts/manifest.mdx @@ -0,0 +1,118 @@ +--- +title: Manifest +description: Permisionlessly publish your Mini App +--- + +import { Caption, HighlightLink } from '../../../components/index.ts'; + +# Manifest + +A Manifest defines global metadata about a Mini App such as who the author is, +what the app is called, and the icon to use for it. This data is used to to +more deeply integrate into Farcaster clients and as well as be listed in Mini +App Stores. + + + + +## Format + +Manifests are JSON files hosted at `/.well-known/farcaster.json` on the [Fully +Qualified Domain +Name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) of the Mini +App. + + +## Schema + +| Property | Type | Required | Description | +|--------------------|--------|----------|--------------------------------------------------| +| accountAssociation | object | Yes | Verifies domain ownership to a Farcaster account | +| frame | object | Yes | Metadata about the Mini App | + +### accountAssociation + +The account association verifies authorship of this domain to a Farcaster +account. + +The value is set to the JSON representation of a [JSON Farcaster +Signature](https://github.com/farcasterxyz/protocol/discussions/208) from the +account's custody address with the following payload: + +```json +{ domain: "" } +``` + +The `domain` value must exactly match the FQDN of where it is hosted. + +#### Schema + +| Property | Type | Required | Description | +|-----------|--------|----------|---------------------------| +| header | string | Yes | base64 encoded JFS header | +| payload | string | Yes | base64 encoded payload | +| signature | string | Yes | base64 encoded signature | + + +#### Example + +```json +{ + "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0", + "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9", + "signature": "MHgwZmJiYWIwODg3YTU2MDFiNDU3MzVkOTQ5MDRjM2Y1NGUxMzVhZTQxOGEzMWQ5ODNhODAzZmZlYWNlZWMyZDYzNWY4ZTFjYWU4M2NhNTAwOTMzM2FmMTc1NDlmMDY2YTVlOWUwNTljNmZiNDUxMzg0Njk1NzBhODNiNjcyZWJjZTFi" +} +``` + +### frame + +Metadata needed to by Hosts to distribute the Mini App. + +import ManifestAppConfigSchema from "../../../snippets/manifestAppConfigSchema.mdx" + + + + +#### Example + +import ManifestAppConfigExample from "../../../snippets/manifestAppConfigExample.mdx" + + + + +## Example + +Example of a valid farcaster.json manifest: + +```json +{ + "accountAssociation": { + "header": "eyJmaWQiOjM2MjEsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgyY2Q4NWEwOTMyNjFmNTkyNzA4MDRBNkVBNjk3Q2VBNENlQkVjYWZFIn0", + "payload": "eyJkb21haW4iOiJ5b2luay5wYXJ0eSJ9", + "signature": "MHgwZmJiYWIwODg3YTU2MDFiNDU3MzVkOTQ5MDRjM2Y1NGUxMzVhZTQxOGEzMWQ5ODNhODAzZmZlYWNlZWMyZDYzNWY4ZTFjYWU4M2NhNTAwOTMzM2FmMTc1NDlmMDY2YTVlOWUwNTljNmZiNDUxMzg0Njk1NzBhODNiNjcyZWJjZTFi" + }, + "frame": { + "version": "1", + "name": "Yoink!", + "iconUrl": "https://yoink.party/logo.png", + "homeUrl": "https://yoink.party/framesV2/", + "imageUrl": "https://yoink.party/framesV2/opengraph-image", + "buttonTitle": "🚩 Start", + "splashImageUrl": "https://yoink.party/logo.png", + "splashBackgroundColor": "#f5f0ec", + "webhookUrl": "https://yoink.party/api/webhook" + } +} +``` + +## Versioning + +Manifests will follow a simple versioning scheme where non-breaking +changes can be added to the same version but a breaking change must accompany a +version bump. + + +## Caching + +Farcaster clients may cache the manifest for a Mini App but should provide a +way for refreshing the manifest file. diff --git a/site/pages/docs/guides/share-extension.mdx b/site/pages/docs/concepts/share-extensions.mdx similarity index 100% rename from site/pages/docs/guides/share-extension.mdx rename to site/pages/docs/concepts/share-extensions.mdx diff --git a/site/pages/docs/guides/urls.mdx b/site/pages/docs/concepts/universal-links.mdx similarity index 72% rename from site/pages/docs/guides/urls.mdx rename to site/pages/docs/concepts/universal-links.mdx index c3c9cc6d..a0238340 100644 --- a/site/pages/docs/guides/urls.mdx +++ b/site/pages/docs/concepts/universal-links.mdx @@ -1,14 +1,14 @@ --- -title: Mini App URLs -description: How to use Mini App URLs +title: Universal Links +description: Link users into your Mini App from anywhere --- -import { Caption } from '../../../components/Caption.tsx'; +import { Caption } from '../../../components/Caption'; -# Mini App URLs +# 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: +Universal Links give you a single URL that can be shared outside Farcaster in +other social feeds and website that will bring users to your Mini App. `https://farcaster.xyz/miniapps//(/)(?)` @@ -19,19 +19,19 @@ and web sites. The URL format is as follows: The `` and `` 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 Mini App URL and is logged in: +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 Mini App URL +## Where to find the Universal Link On the web [Developers page](https://farcaster.xyz/~/developers), click the top-right kebab menu on one of your Mini App cards and select **"Copy link to mini app"**. This -copies the Mini App URL to your clipboard. +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 Mini App URL to your clipboard. +copy the Universal Link to your clipboard. ![Copy link to mini app](/copy_link_to_miniapp.png) @@ -40,14 +40,14 @@ copy the Mini App URL to your clipboard. -## How to control what is displayed when I share a Mini App URL +## How to control what is displayed when I share a Universal Link -Farcaster automatically generates OpenGraph meta tags for Mini App URLs, ensuring +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 -Mini App URLs (see ["Sharing your app"](/docs/guides/sharing)) and add all relevant fields +Universal Links (see ["Sharing your app"](/docs/guides/sharing)) and add all relevant fields in your [application config](/docs/guides/publishing#define-your-application-configuration), especially `ogTitle`, `ogDescription` and `ogImageUrl`. @@ -58,7 +58,7 @@ Each Mini App defines a `homeUrl` property in its [application config](/docs/gui 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 Mini App URL with a sub-path and/or query parameters, those are appended +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 Mini App @@ -70,14 +70,14 @@ URL is `https://farcaster.xyz/miniapps/12345/example-miniapp/leaderboard?sort=po Not at the moment. -**When copying the link from the Mini App header, it doesn't copy the Mini App URL, why is that?** +**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 Mini App URL. +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 Mini App URL copied from the Mini App header?** +**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 Mini App URL or URL shared in the cast will be copied. +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?** @@ -90,4 +90,4 @@ import { sdk } from '@farcaster/frame-sdk' const url = 'https://farcaster.xyz/miniapps/deoWzfI9kLjH/rewards' await sdk.actions.openUrl(url) -``` \ No newline at end of file +``` diff --git a/site/pages/docs/guides/auth.mdx b/site/pages/docs/guides/auth.mdx index 1048c6ae..9c4df2fd 100644 --- a/site/pages/docs/guides/auth.mdx +++ b/site/pages/docs/guides/auth.mdx @@ -3,7 +3,7 @@ title: Authenticating users description: Authenticating users in your mini app --- -import { Caption } from '../../../components/Caption.tsx'; +import { Caption, HighlightLink } from '../../../components/index.ts'; # Authenticating users @@ -23,8 +23,7 @@ Farcaster](https://docs.farcaster.xyz/developers/siwf/) under the hood to authenticate the user and returns a standard JWT that can be easily verified by your server and used as a session token. -[
Get started with Quick Auth
](/docs/sdk/quick-auth) - + ## Sign In with Farcaster diff --git a/site/pages/docs/guides/sharing.mdx b/site/pages/docs/guides/sharing.mdx index 8529c374..e05c04b0 100644 --- a/site/pages/docs/guides/sharing.mdx +++ b/site/pages/docs/guides/sharing.mdx @@ -118,14 +118,14 @@ const frame = { ``` -## Mini App URLs +## 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//(/)(?)` -Learn how to obtain the Mini App URL and how they work in the [Mini App URLs](/docs/guides/urls) guide. +Learn how to obtain the Universal Links and how they work in the [Mini App URLs](/docs/concepts/universal-links) guide. ## Debugging @@ -159,9 +159,11 @@ that URL gets changed. 5. User sees cast in feed with an embed rendered from the attached metadata. -## Receiving shared casts +## Extending the share sheet -In addition to sharing your Mini App through embeds, your app can also receive casts that users share to it through the system share sheet. Learn more in the [Share Extensions](/docs/guides/share-extension) guide. +In addition to sharing your Mini App through embeds, your app can also receive +casts that users share to it through the system share sheet by setting up a +[Share Extension](/docs/concepts/share-extensions). ## Next steps diff --git a/site/pages/docs/sdk/changelog.mdx b/site/pages/docs/sdk/changelog.mdx index 3c0b32fb..6b0f2507 100644 --- a/site/pages/docs/sdk/changelog.mdx +++ b/site/pages/docs/sdk/changelog.mdx @@ -18,7 +18,8 @@ description: Recent changes to the Mini Apps SDK ## June 6, 2025 (0.0.59) -- Added [`cast_share`](/docs/guides/share-extension) location type for [share extensions](/docs/guides/share-extension), enabling Mini Apps to receive shared casts from the system share sheet +- Added `cast_share` location type for [share +extensions](/docs/concepts/share-extensions), enabling Mini Apps to receive shared casts from the system share sheet - Extended the cast object in `cast_embed` and `cast_share` contexts to include comprehensive metadata (author details, timestamps, mentions, embeds, channel) ## June 4, 2025 (0.0.56) diff --git a/site/vercel.json b/site/vercel.json index 24b32fd1..334556a2 100644 --- a/site/vercel.json +++ b/site/vercel.json @@ -1,5 +1,15 @@ { "redirects": [ + { + "source": "/docs/guides/url", + "destination": "/docs/concepts/universal-links", + "statusCode": 301 + }, + { + "source": "/docs/guides/share-extension", + "destination": "/docs/concepts/share-extensions", + "statusCode": 301 + }, { "source": "/docs/sdk/actions/quick-auth", "destination": "/docs/sdk/quick-auth", diff --git a/site/vocs.config.tsx b/site/vocs.config.tsx index 910d364e..47787a7f 100644 --- a/site/vocs.config.tsx +++ b/site/vocs.config.tsx @@ -36,10 +36,14 @@ export default defineConfig({ '/': OG_BASE_URL + '?title=%title&description=%description&', '/docs/guides': OG_BASE_URL + '?title=%title&description=%description§ion=Guide', + '/docs/concepts': + OG_BASE_URL + '?title=%title&description=%description§ion=Concepts', '/docs/sdk': OG_BASE_URL + '?title=%title&description=%description§ion=SDK', '/docs/sdk/actions': OG_BASE_URL + '?title=%title&description=%description§ion=Action', + '/docs/sdk/quick-auth': + OG_BASE_URL + '?title=%title&description=%description§ion=Quick Auth', }, theme: { accentColor: '#8a63d2', @@ -108,13 +112,26 @@ export default defineConfig({ text: 'Authenticating users', link: '/docs/guides/auth', }, + ], + }, + { + text: 'Concepts', + items: [ + { + text: 'Manifest', + link: '/docs/concepts/manifest', + }, + { + text: 'Embeds', + link: '/docs/concepts/embeds', + }, { - text: 'Mini App URLs', - link: '/docs/guides/urls', + text: 'Universal Links', + link: '/docs/concepts/universal-links', }, { text: 'Share Extensions', - link: '/docs/guides/share-extension', + link: '/docs/concepts/share-extensions', }, ], },