Extend Mini App Metadata

[gabrielayuso]

The metadata specified for a mini app on the manifest (farcaster.json) is very minimal, clients don't have much to work with.

For example, Warpcast can't feature any mini app on the mini apps tab because we don't have a tagline and 1:91.1 hero image for all mini apps. We can't split top mini apps by category. When we add search, we'll only have the name and domain to work with. Etc. etc.

The table below is a comprehensive list of fields and their purpose aiming to provide a rich experience across client experiences.

We'll keep backwards compatibility in mind so new field absence doesn't break clients. However, their absense means that mini apps missing certain fields won't be eligible for experiences that require the field. For example, mini apps that are missing a tagline or heroImageUrl won't be featured.

Experience	Field	Purpose	Limitations	Design Guidelines
Mini App Store Listing	iconUrl	Main icon	1024x1024 px PNG, no alpha	Use a bold, recognizable logo. No text. Avoid photos or screenshots.
	name	Display name of the app	30 characters, no emojis or special characters	Use brandable, unique names. Avoid generic terms. No emojis or trademark symbols.
	subtitle	Short description under the app name	30 characters, no emojis or special characters	Should clarify what your app does in a catchy way. Avoid repeating the title.
Mini App Store Page	description	Promotional message displayed on Mini App Page	170 characters, no emojis or special characters	Use short paragraphs, headings, and bullet points. Focus on value, not features. Include social proof if possible. Avoid jargon.
	screenshotUrls	Visual previews of the app, max 3 screens	Portrait, 1284 x 2778	Focus on showing the core value or magic moment of the app in the first 2–3 shots. Use device frames and short captions.
Search & Discovery	primaryCategory	Primary category of app	One of the pre-defined categories: games, social, finance, utility, productivity, health-fitness, news-media, music, shopping, education, developer-tools, entertainment, art-creativity	Games, Social, Finance, Utility, Productivity, Health & Fitness, News & Media, Music, Shopping, Education, Developer Tools, Entertainment, Art & Creativity
	tags	Descriptive tags for filtering/search	up to 5 tags	Use 3–5 high-volume terms; no spaces, no repeats, no brand names. Use singular form.
Mini App Promotional Asset	heroImageUrl	Promotional display image on top of the mini app store	1200 x 630px (1.91:1)
	tagline	Marketing tagline should be punchy and descriptive	30 characters	Use for time-sensitive promos or CTAs. Keep copy active (e.g., “Grow, Raid & Rise in Stoke Fire”).
Sharing Experience	ogTitle		30 characters	Use your app name + short tag (e.g., “AppName – Local News Fast”). Title case, no emojis.
	ogDescription	100 characters		Summarize core benefit in 1–2 lines. Avoid repeating OG title.
	ogImageUrl	Promotional image (same as app hero image)	1200 x 630px (1.91:1)	1200x630 px JPG or PNG. Should show your brand clearly. No excessive text. Logo + tagline + UI is a good combo.

Example:

{
  "accountAssociation": {
    "header": "eyJmaWQiOjkxNTIsInR5cGUiOiJjdXN0b2R5Iiwia2V5IjoiMHgwMmVmNzkwRGQ3OTkzQTM1ZkQ4NDdDMDUzRURkQUU5NDBEMDU1NTk2In0",
    "payload": "eyJkb21haW4iOiJyZXdhcmRzLndhcnBjYXN0LmNvbSJ9",
    "signature": "MHgxMGQwZGU4ZGYwZDUwZTdmMGIxN2YxMTU2NDI1MjRmZTY0MTUyZGU4ZGU1MWU0MThiYjU4ZjVmZmQxYjRjNDBiNGVlZTRhNDcwNmVmNjhlMzQ0ZGQ5MDBkYmQyMmNlMmVlZGY5ZGQ0N2JlNWRmNzMwYzUxNjE4OWVjZDJjY2Y0MDFj"
  },
  "frame": {
    "version": "1",
    "name": "Rewards",
    "iconUrl": "https://rewards.warpcast.com/app.png",
    "splashImageUrl": "https://rewards.warpcast.com/logo.png",
    "splashBackgroundColor": "#000000",
    "homeUrl": "https://rewards.warpcast.com",
    "webhookUrl": "https://client.warpcast.com/v1/creator-rewards-notifs-webhook",
    "subtitle": "Top Warpcast creators",
    "description": "Climb the leaderboard and earn rewards by being active on Warpcast.",
    "screenshotUrls": [
      "https://rewards.warpcast.com/screenshot1.png",
      "https://rewards.warpcast.com/screenshot2.png",
      "https://rewards.warpcast.com/screenshot3.png"
    ],
    "primaryCategory": "social",
    "tags": [
      "rewards",
      "leaderboard",
      "warpcast",
      "earn"
    ],
    "heroImageUrl": "https://rewards.warpcast.com/og.png",
    "tagline": "Top Warpcast creators",
    "ogTitle": "Rewards",
    "ogDescription": "Climb the leaderboard and earn rewards by being active on Warpcast.",
    "ogImageUrl": "https://rewards.warpcast.com/og.png"
  }
}

[vrypan]

Is there a good reason for choosing the 1200x628 format? It feels like we introduce one more image size a dev has to produce. Facebook and Linkedin use 1200x630, can we stick to it?

https://www.ogimage.gallery/libary/the-ultimate-guide-to-og-image-dimensions-2024-update

[gabrielayuso]

makes sense - will switch to that

[andrei0x309]

This is a great addition, it has been requested a few times, at least 3-4 times that I saw.

It will allow better discovery by enabling the creation of a directory and search.

[geovgy]

Although some of these fields are very much needed, I think there are others that are also redundant. For example, the og fields ogTitle, ogDescription and ogImageUrl don't seem necessary since they can just be fetched from the meta tags in the website header. Plus, there are already fields name, description and imageUrl in this manifest.

I think the tags field overlaps with the keywords meta tag in website headers, but there could be justifications for having different values in tags than in keywords to optimize for search/discoverability in both Farcaster clients and popular search engines (Google, etc.). So I wouldn't say it's entirely redundant.

As for some of the other new fields, I really like them and think they could be even better:

• For clarity, I think heroImageUrl and tagline should be named promoImageUrl and promoSubtitle (or something else that makes it more explicit they are promotional asset fields). Current field names will likely get easily confused with imageUrl and subtitle.
• Thoughts on the pre-defined categories having numeric code identifiers or being lowercase with "-" or "_" instead of spaces?

Overall, I love this direction and hope this feedback helps :) I've been looking forward to some of these additions. There are a few others I didn't even consider and yet excited about like screenshotUrls and the promo fields.

[vrypan]

Also, OG fields would allow links to the Mini App Store page of the app (there should be one! :-) to be presented nicely in other sites.

[gabrielayuso]

Right we have the launch URL https://warpcast.com/~/mini-apps/launch?domain=rewards.warpcast.com
but we have plans to improve this.

[geovgy]

Although some of these fields are very much needed, I think there are others that are also redundant. For example, the og fields ogTitle, ogDescription and ogImageUrl don't seem necessary since they can just be fetched from the meta tags in the website header. Plus, there are already fields name, description and imageUrl in this manifest.

IMO we should deprecate imageUrl in favor of ogImageUrl (Warpcast doesn't really make use of imageUrl and the og prefix makes its purpose clearer). There are benefits of having og fields defined here. These serve as the canonical OG fields that represent the Mini App itself as opposed to a specific URL under the Mini App. This way clients can just rely on farcaster.json to know how to represent a Mini App without having to deal with meta tags. Same logic applies to tags vs keywords meta tag, even though Mini Apps are websites under the hood, farcaster.json is a manifest that represents the entire app, homeUrl being the equivalent to the main function.

Ok I can understand that logic. I figured the homeUrl would determine where to fetch the canonical og fields but I see the convenience just grabbing them directly from farcaster.json. Replacing imageUrl with ogImageUrl does provide more clarity name-wise and I support the tags field. Though I'm unsure if ogTitle and ogDescription will be used by clients since there are also name, subtitle and description which feel like they serve the same purpose.

For clarity, I think heroImageUrl and tagline should be named promoImageUrl and promoSubtitle (or something else that makes it more explicit they are promotional asset fields). Current field names will likely get easily confused with imageUrl and subtitle.

Although. heroImageUrl and tagline aren't necessarily limited to promo use case, it makes sense to add the prefix for clarity.

Yeah I'm curious how else these two fields will be utilized. I'm sure they can be useful for marketing campaigns/tools beyond just to be featured on Warpcast.

Thoughts on the pre-defined categories having numeric code identifiers or being lowercase with "-" or "_" instead of spaces?

Yes, these will be kebab case. I'll update the proposal for clarity.

👌👌

[artlu99]

DX request: please consider using .jsonc format with a $schema to
enable JSON Schema validation and code completion. Can support .json for backwards compatibility. Marking fields as required vs optional will help us all tremendously

[gabrielayuso]

Thanks for the suggestion @artlu99 . We currently use Zod for validation, you can find the definition here.

No plans to change that atm.

[dylsteck]

This looks great! The extra metadata is going to be really helpful for other clients to have enough info to prominently feature mini apps. Excited to see this land(hopefully soon)!

[thecompez]

This is incredible! It’s like having a super app store!

[zacharytyhacz]

GM friends, is there a timeline for this on when we should update our json and/or metadata html?

[andrei0x309]

It's already live, on Warpcast, so you should probably add that.
It's a client thing, so any client could adopt this or discard it anytime, but many proposals are getting implemented right away, a tag like implemented in Warpcast would be useful.

[Barabazs]

Any file type restrictions for the screenshotUrls?