Miniapps/existing apps breakdown #298
Conversation
🟡 Heimdall Review Status
|
|
|
||
| Mini Apps provide many benefits, including access to a users social graph, native distribution channels (e.g Base app or any Farcaster client) and ability to be launched without approval . [Learn more about why mini apps](https://docs.base.org/mini-apps/overview). | ||
|
|
||
| ### Key Differences from Regular Web Apps |
There was a problem hiding this comment.
I'd question if we should have this section at all here, but if you feel strongly we can keep it. Generally I think of the quickstart as only the essential information to get started and not supporting context like this. But its a weakly held opinion in this specific case
|
|
||
| The application manifest serves as your Mini App's identity card. Host clients use this file to identify your app, display its metadata, and verify domain ownership. | ||
|
|
||
| ## Why You Need a Manifest |
There was a problem hiding this comment.
The description, first 2 sentences, and the "Why You Need a Manifest" section feel duplicative. Can we simplify this down to be more concise while still conveying the same information?
| - Must be accessible at `https://yourdomain.com/.well-known/farcaster.json` | ||
| - Must return valid JSON with `Content-Type: application/json` | ||
| - Must be publicly accessible (no authentication required) | ||
| - Must include both `accountAssociation` and `frame`/`miniapp` objects |
There was a problem hiding this comment.
We should make sure all of our manifest examples call it the miniapp object and have a callout that it can be called frame to support legacy apps, but best practice is to call it miniapp
| - Must include both `accountAssociation` and `frame`/`miniapp` objects | ||
| </Warning> | ||
|
|
||
| ## Complete Manifest Structure |
There was a problem hiding this comment.
udner the H2 and before the code block lets add a line that links to the manifest feature page:
|
|
||
| ## Framework-Specific Implementation | ||
|
|
||
| Choose the approach that matches your technology stack: |
There was a problem hiding this comment.
nit but shorten technology to tech.
Would this be a good place to use a "group" component? Might be slightly cleaner. Just a suggestion
|
|
||
| ## Generate Your Account Association | ||
|
|
||
| 1. Visit the [Mini App Manifest Tool](https://farcaster.xyz/~/developers/new) |
There was a problem hiding this comment.
When does our base.dev manifest tool go live? Today?
There was a problem hiding this comment.
+1 I'd reference Base.dev Preview tool here
|
|
||
| ## Next Steps | ||
|
|
||
| <CardGroup cols={2}> |
There was a problem hiding this comment.
The overview card was the previous step...
I think we remove these cards on all pages other than the Overview page. We generally want them to go straight through the pages instead of jumping around and the cards create some extra noise. For devs who explicitly want to jump around they can use the sidebar
|
|
||
| ## Implementation by Framework | ||
|
|
||
| **Next.js** |
There was a problem hiding this comment.
What does the implementation look like for vite?
Could we use a group component here so that builders can select what code blocks they see?
There was a problem hiding this comment.
Would it make sense to have a helmet example for those using vite plus react?
| ## Implementation by Framework | ||
|
|
||
| **Next.js** | ||
| ```typescript |
There was a problem hiding this comment.
Lets use the mintlify structuring for naming code blocks instead of having it as a comment. This applies everywhere, in case I missed it elsewhere
| **HTML-based Applications** | ||
| ```html | ||
| <!-- Add to <head> section --> | ||
| <meta name="fc:frame" content='{"version":"next","imageUrl":"https://yourapp.com/preview.png","button":{"title":"Launch App","action":{"type":"launch_frame","url":"https://yourapp.com"}}}' /> |
There was a problem hiding this comment.
lets switch the example code to use "fc:miniapp" given that the frame language is basically supporting legacy
|
|
||
| ## Next Steps | ||
|
|
||
| <CardGroup cols={2}> |
There was a problem hiding this comment.
Remove cards, per other comment on manifest setup page
| description: Enable rich social sharing and discovery by configuring embed metadata for your Mini App. | ||
| --- | ||
|
|
||
| Embed metadata transforms your Mini App URLs into rich, interactive previews when shared in social feeds. Instead of plain text links, users will see preview images and launch buttons. |
There was a problem hiding this comment.
We should add an image of an embed to help land the concept
| @@ -0,0 +1,124 @@ | |||
| --- | |||
There was a problem hiding this comment.
For title maybe: "Mini App SDK Integration"? Drop the "Configuration" from the title
There was a problem hiding this comment.
Actually think we should not call it SDK at all
We are showing them how to integrate mini app specific features
Maybe its: "Add Mini App Features" or simply "Mini App Features"
Then we introduce the concepts either without any specific implementation details and we rely entirely on the install guides OR we partially introduce by using the Tabs component (i've been calling it groups elsewhere, I mean tabs) to show parts of the implementation code to help show how simple its is
Then at the end of this article, we provide cards that allow them to navigate to the right full implementation guide.
|
|
||
| ## Integrate Context and User Data | ||
|
|
||
| The [Mini App SDK](https://miniapps.farcaster.xyz/docs/getting-started) provides access to user's social context and enables app-specific functionality like notifications and cast composition. |
There was a problem hiding this comment.
do we think "Cast composition" is clear enough? Or should we use more layman's terms like "... notifications and posting directly to the feed"
| ### Why Context Integration Is Essential | ||
|
|
||
| Context integration allows your app to: | ||
| - **Access User Data**: Get the user's Farcaster profile, FID, and connected wallet |
There was a problem hiding this comment.
should we reposition as value focused instead of tech focused?
e.g. (this is rough, should think and polish)
-Instantly Personalize: Access the user's profile and other key user data to make them feel at home
-Re-engage users with Notifications: Notify...
-Improve Share-ability: ...
We are talking to devs, so tech first isn't bad necessarily, but may be helpful to explicitly convey the why before the how here
| Follow the [MiniKit integration guide](https://docs.base.org/mini-apps/quickstart/existing-apps/install) for React-specific hooks and onchain components. | ||
|
|
||
| **For All Other Frameworks** | ||
| Follow the [Farcaster Mini Apps Getting Started Guide](https://miniapps.farcaster.xyz/docs/getting-started) to integrate the core SDK. |
There was a problem hiding this comment.
Pretty strong opinion we should add the steps directly within our own docs. This is a key step in the developer journey and don't want to be sending users to a different docs site.
Ack this adds some maintenance overhead but think its best for reducing dev churn in the "time-to-deployment" metric we generally should keep track of
There was a problem hiding this comment.
Also this feels like a branching point where developers need to ask themselves:
Do I keep reading the docs in the Quickstart? Or do I switch to one of these documents. Ideally we don't have that branching point in the quickstart and its a clear end to end flow.
Looking at this SDK Integration doc, I think we probably should remove this branching point. And instead continue with introducing the key concepts to the builders. So cutting the "Choose your integration path" subsection entirely
| Follow the [Farcaster Mini Apps Getting Started Guide](https://miniapps.farcaster.xyz/docs/getting-started) to integrate the core SDK. | ||
|
|
||
| <Tip> | ||
| MiniKit is built on top of the Mini App SDK and provides additional React hooks and onchain components for easier integration in React applications. |
There was a problem hiding this comment.
Lets explicitly call out that its part of OCK and provide an internal link to that docs page
| } | ||
| ``` | ||
|
|
||
| ## Implementation Checklist |
There was a problem hiding this comment.
Checklist shouldn't be in this page. We should keep this page focused solely on integrating the sdk
There was a problem hiding this comment.
Maybe we just ensure this is part of the launch checklist
| --- | ||
|
|
||
| ## Next Steps | ||
|
|
There was a problem hiding this comment.
remove as noted otherwhere
| 3. Generate your `accountAssociation` object. | ||
| 4. Copy the generated values into your manifest. | ||
|
|
||
| ## Verify Your Setup |
There was a problem hiding this comment.
Let's keep pointing users to Base Build's Preview tool
There was a problem hiding this comment.
yes that be goal just waiting for the tool to be live
| <Note> | ||
| Both `fc:frame` and `fc:miniapp` meta tags are accepted by clients. | ||
| </Note> | ||
|
|
There was a problem hiding this comment.
Two pieces of information that would do well on this page would be
- A link to metadata specification. I will port this over today.
- A tooltip (at a minimum) that prompts the user to use the metadata feature in the Preview Tool
| description: Integrate context APIs, configure ready state handling, and set up notifications for your Mini App. | ||
| --- | ||
|
|
||
| ## Integrate Context and User Data |
There was a problem hiding this comment.
I think the content here is solid, but it feels a bit too detailed for a QS step. For someone just getting started, the key takeaway should be how to add the MiniKit provider and call ready() in their app entry point. This moves them closer to having a working mini app.
The extra details (like adding context, etc.) are valuable, but they’d be better placed in a separate guide (e.g. “Adding/Using Context”), which you can link out to.
There was a problem hiding this comment.
The point of this page in particular is to give an exact breakdown of the components that are required to build a mini app. That way developers can read and have a framework agnostic view, hence the details. The actual implementation is in the instructions guide section
| ### Implementation Examples | ||
|
|
||
| Choose the guide that matches your setup: | ||
|
|
There was a problem hiding this comment.
We should put implementation examples inline directly or not show examples at this point at all. We could use groups component to have one group per implementation path and then inline the code
| - **Mini App SDK**: [Ready Action Documentation](https://miniapps.farcaster.xyz/docs/sdk/actions/ready) | ||
| - **MiniKit**: [Frame Readiness Documentation](https://docs.base.org/mini-apps/technical-reference/minikit/hooks/useMiniKit#frame-readiness) | ||
|
|
||
| ## Understanding Notification Requirements |
There was a problem hiding this comment.
I think we should just call this header "Notifications"
| ### Why Notifications Need a Backend | ||
|
|
||
| Notifications require server-side handling because: | ||
| - **Security**: Notification tokens must be stored securely in a database |
There was a problem hiding this comment.
We say "notification tokens" without introducing that concept first. Thats confusing for new devs
|
|
||
| Notifications enhance user engagement but require server-side infrastructure. If your app is frontend-only, you have several options to add notification capabilities. | ||
|
|
||
| ### Why Notifications Need a Backend |
There was a problem hiding this comment.
Seems like this should only be in a flow for builders who know they don't have a backend.
This is the notifications setup part of the quickstart. There are several different potential tech stacks trying to set up notifs. Only one of those are stacks without a backend. We should let readers self select (either via a group component within the doc or in an install guide
|
|
||
| ### Webhook Configuration | ||
|
|
||
| If implementing notifications, add the webhook URL to your manifest: |
There was a problem hiding this comment.
This feels incomplete. How is this webhook implemented? What exactly does this webhook do?
| "mini-apps/quickstart/existing-apps/test-and-deploy", | ||
| "mini-apps/quickstart/launch-checklist", | ||
| { | ||
| "group": "Install Guides", |
There was a problem hiding this comment.
We should put. Install Guides after what we currently call the SDK Integration guide and before the Test and Deploy doc. That would be the natural dev progression:
- Learn about the concepts
- follow the full integration guide
- test and deploy
| - Use Vercel Serverless Functions to generate OG tags dynamically | ||
| - Use [Vercel Satori](https://github.com/vercel/satori) to render HTML/SVG to images for social embeds | ||
|
|
||
| ## Notifications |
There was a problem hiding this comment.
Probably worth in a different sub page so its easy to find for builders once its live? Given that this page is called "Add Frame Metadata"
|
|
||
| Frontend-only applications cannot implement notifications without backend infrastructure. | ||
|
|
||
| ## Run Your Mini App |
There was a problem hiding this comment.
Part of a test & deploy page? Or just integrate this into the already existing test and deploy page?
What changed? Why?
Notes to reviewers
How has it been tested?