From c8cddb2135316e6e5806f9c71d48449cf4ce4bd1 Mon Sep 17 00:00:00 2001 From: sohey Date: Sun, 12 Oct 2025 14:41:09 +0200 Subject: [PATCH 01/14] streamlined --- docs/docs.json | 12 +- .../core-concepts/embeds-and-previews.mdx | 318 ++++++++++++------ docs/mini-apps/core-concepts/manifest.mdx | 2 +- docs/mini-apps/growth/optimize-onboarding.mdx | 4 +- docs/mini-apps/llms-full.txt | 4 +- docs/mini-apps/llms.txt | 2 +- .../mini-apps/quickstart/launch-checklist.mdx | 2 +- .../technical-guides/embeds-and-previews.mdx | 2 +- .../technical-guides/search-and-discovery.mdx | 229 +++++++++---- .../technical-guides/search-discovery.mdx | 64 ++++ docs/tone_of_voice.mdx | 84 +++++ global-tone-voice.mdx | 0 12 files changed, 546 insertions(+), 177 deletions(-) create mode 100644 docs/mini-apps/technical-guides/search-discovery.mdx create mode 100644 docs/tone_of_voice.mdx create mode 100644 global-tone-voice.mdx diff --git a/docs/docs.json b/docs/docs.json index 647f507a..a1232e07 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -447,7 +447,7 @@ "group": "Technical Guides", "pages": [ "mini-apps/technical-guides/data-driven-growth", - "mini-apps/technical-guides/search-and-discovery", + "mini-apps/technical-guides/search-discovery", "mini-apps/technical-guides/sharing-and-social-graph", "mini-apps/technical-guides/links", "mini-apps/technical-guides/sign-manifest" @@ -1522,7 +1522,11 @@ }, { "source": "/mini-apps/features/search-and-discovery", - "destination": "/mini-apps/technical-guides/search-and-discovery" + "destination": "/mini-apps/technical-guides/search-discovery" + }, + { + "source": "/mini-apps/technical-guides/search-and-discovery", + "destination": "/mini-apps/technical-guides/search-discovery" }, { "source": "/mini-apps/features/sharing-and-social-graph", @@ -2694,11 +2698,11 @@ }, { "source": "/base-app/miniapps/search-and-discovery", - "destination": "/mini-apps/technical-guides/search-and-discovery" + "destination": "/mini-apps/technical-guides/search-discovery" }, { "source": "/base-app/build-with-minikit/search-and-discovery", - "destination": "/mini-apps/technical-guides/search-and-discovery" + "destination": "/mini-apps/technical-guides/search-discovery" }, { "source": "/base-app/miniapps/sharing-your-miniapp", diff --git a/docs/mini-apps/core-concepts/embeds-and-previews.mdx b/docs/mini-apps/core-concepts/embeds-and-previews.mdx index de98fcfe..15174454 100644 --- a/docs/mini-apps/core-concepts/embeds-and-previews.mdx +++ b/docs/mini-apps/core-concepts/embeds-and-previews.mdx @@ -1,146 +1,276 @@ --- title: Embeds & Previews -description: Mini apps use metadata to create embeds when users share links. The embed shows a preview image and launch button. +description: Configure shareable embeds that display preview images and launch buttons when users share your Mini App links in social feeds. --- - +When users share your Mini App in Base App, the shared link appears as a rich preview with an image and launch button. This guide shows you how to implement the required metadata. + Mini app feed - -## Implementation -Add this meta tag to the `` section of any page you want to make shareable: + +## Step 1: Add embed metadata to your page + +Add the `fc:miniapp` meta tag to any page you want to make shareable. This metadata generates the preview embed when users share your Mini App. + +**Why it matters**: Without embed metadata, shared links display as plain URLs. The embed metadata transforms your link into an interactive preview that increases engagement and provides a clear call-to-action for users to launch your Mini App. - ```html html metadata - - - - My Mini App - - - - - - - ``` - - ```jsx next.js metadata - // app/layout.tsx or app/page.tsx (Next.js App Router) - import type { Metadata } from "next"; - + } + }' + /> + + + + + +``` + +```jsx next.js +// app/layout.tsx or app/page.tsx +import type { Metadata } from "next"; + export async function generateMetadata(): Promise { return { - title: miniapp.name, - description: miniapp.description, + title: "My Mini App", + description: "Join and explore our Mini App", other: { "fc:miniapp": JSON.stringify({ - version: miniapp.version, - imageUrl: miniapp.heroImageUrl, + version: "next", + imageUrl: "https://example.com/preview.png", button: { - title: `Join the ${miniapp.name}`, + title: "Open App", action: { - name: `Launch ${miniapp.name}`, - url: `${miniapp.homeUrl}` + type: "launch_frame", + name: "Launch My Mini App", + url: "https://example.com" }, }, }), }, }; } - - export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - {children} - - ); + +export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + {children} + + ); +} +``` + + +**Explanation**: The `fc:miniapp` meta tag contains JSON configuration that defines your embed appearance. The `imageUrl` displays as the preview image, while the `button` object configures the launch button text and destination URL. + + +Your page now includes the required metadata. View your page source to verify the `fc:miniapp` meta tag appears in the `` section. + + +## Step 2: Configure your preview image + +Set your `imageUrl` to a high-quality image that represents your Mini App and captures user attention in social feeds. + +**Why it matters**: The preview image is the first thing users see when your Mini App is shared. A compelling image significantly increases click-through rates and user engagement. + +```json +{ + "imageUrl": "https://example.com/preview.png" +} +``` + +**Image requirements**: +- **Aspect ratio**: 3:2 (e.g., 1200x800 pixels) +- **Maximum file size**: 10MB +- **Maximum URL length**: 1024 characters +- **Format**: PNG, JPG, or WebP + + +Use a visually distinctive image that clearly communicates your Mini App's purpose. Include your app name or logo for brand recognition. + + + +Verify your image meets the 3:2 aspect ratio requirement and loads quickly. Test the URL in a browser to confirm it's publicly accessible. + + +## Step 3: Customize the launch button + +Configure the button that appears on your embed to control what happens when users click it. + +**Why it matters**: The button action determines the user's first interaction with your Mini App. A clear, action-oriented button title increases conversion rates from embed views to actual app launches. + +```json +{ + "button": { + "title": "Open App", + "action": { + "type": "launch_frame", + "name": "My Mini App", + "url": "https://example.com", + "splashImageUrl": "https://example.com/splash.png", + "splashBackgroundColor": "#000000" + } } - ``` +} +``` + +**Button configuration**: +- `title`: Button text displayed on the embed (max 32 characters) +- `action.type`: Must be `"launch_frame"` to open your Mini App +- `action.name`: Application name shown during launch (max 32 characters, defaults to manifest name) +- `action.url`: Destination URL when button is clicked (max 1024 characters, defaults to current page URL) +- `action.splashImageUrl`: Image shown on splash screen (200x200 pixels, optional) +- `action.splashBackgroundColor`: Hex color for splash background (optional) + + +Use action-oriented button titles like "Play Now", "Join Game", or "Start Trading" instead of generic text like "Click Here". + + + +Verify your button title is clear and under 32 characters. The action URL should point to the specific page or state you want users to launch. + + +## Step 4: Ensure your homeUrl has embed metadata + +Your manifest's `homeUrl` must include the embed metadata for your Mini App to render correctly in Base App. + +**Why it matters**: Base App uses your manifest's `homeUrl` to fetch embed metadata. If the `homeUrl` doesn't have the `fc:miniapp` meta tag, your Mini App won't display properly in the app. + + +```json manifest.json +{ + "homeUrl": "https://example.com", + "name": "My Mini App" +} +``` + +```html index.html at homeUrl + + + + + + +``` -The `homeUrl` used in the `manifest` *must* have embed metadata defined, in order for the mini app to render correctly in the Base app. +**Explanation**: The `homeUrl` in your manifest must point to a page that contains the `fc:miniapp` metadata. This ensures Base App can retrieve and display your embed correctly. + + +Visit your `homeUrl` and view the page source. Confirm the `fc:miniapp` meta tag is present in the `` section. + +## Step 5: Test your embed -## Schema +Share your Mini App link in Base App to verify the embed displays correctly with your preview image and launch button. + +**Why it matters**: Testing ensures users see the intended preview when your Mini App is shared. Catching display issues before launch prevents poor user experience and lost engagement. + +1. Open Base App +2. Share your Mini App URL in a conversation or post +3. Verify the preview image appears correctly +4. Verify the button text matches your configuration +5. Click the button to confirm it launches your Mini App + + +Embeds are cached. If you update your metadata, you may need to wait a few minutes or share a URL with a unique query parameter (e.g., `?v=2`) to see changes. + + + +Your embed displays with the correct preview image, button text, and successfully launches your Mini App when clicked. + + +## Complete schema reference - -Version of the embed. Must be `"1"` or `"next"`. +Version of the embed specification. Use `"next"` for the latest features or `"1"` for legacy support. -Image URL for the embed. Must be 3:2 aspect ratio, maximum 10MB, maximum 1024 characters. +URL to the preview image. Must be 3:2 aspect ratio, maximum 10MB, maximum 1024 characters. Button configuration object. - - - -### Button Configuration -Defines the launch button that appears on the embed. + + + Text displayed on the button. Maximum 32 characters. + - - -Button text. Maximum 32 characters. - - - -Action configuration object. Maximum 1024 characters. - - + + Action configuration that defines launch behavior. Maximum 1024 characters. + + + + Action type. Must be `"launch_frame"`. + -### Action Configuration + + URL to open when button is clicked. Defaults to the full URL of the page including query parameters. Maximum 1024 characters. + -Specifies what happens when the embed button is clicked. + + Application name displayed during launch. Maximum 32 characters. Defaults to manifest name. + - - -Action type. Must be `"launch_frame"`. - + + Image URL for the splash screen. Must be 200x200 pixels. Maximum 32 characters. Defaults to manifest splash image. + - -App URL to open. Defaults to the full URL of the page including query parameters. Maximum 1024 characters. + + Splash screen background color. Must be hex color code (e.g., `#000000`). Defaults to manifest splash background color. + + + + - -Application name. Maximum 32 characters. Defaults to manifest name. - +## Related documentation - -Splash screen image URL. Must be 200x200 pixels. Maximum 32 characters. Defaults to manifest splash image. - - - -Splash screen background color. Must be hex color code. Defaults to manifest splash background color. - + + + Configure your manifest for search indexing and category placement in Base App discovery features. + + Implement sharing strategies to maximize viral growth using Base's social graph features. + -## Related Concepts - - - - Learn how your manifest powers search indexing and category placement in the Base app discovery features. + + Complete guide to configuring your Mini App manifest with all available options. - - Learn how to maximize sharing, social engagement, and viral growth for your Mini App using Base's social graph features. + + Resolve common issues with embeds, indexing, and Mini App display. - diff --git a/docs/mini-apps/core-concepts/manifest.mdx b/docs/mini-apps/core-concepts/manifest.mdx index 70179cda..6dd0f2ed 100644 --- a/docs/mini-apps/core-concepts/manifest.mdx +++ b/docs/mini-apps/core-concepts/manifest.mdx @@ -205,7 +205,7 @@ Open Graph image. 1200×630px (1.91:1), PNG/JPG. ## Related Concepts - + Learn how your manifest powers search indexing and category placement in the Base app discovery features. diff --git a/docs/mini-apps/growth/optimize-onboarding.mdx b/docs/mini-apps/growth/optimize-onboarding.mdx index b3b03a30..a5ba5c39 100644 --- a/docs/mini-apps/growth/optimize-onboarding.mdx +++ b/docs/mini-apps/growth/optimize-onboarding.mdx @@ -32,7 +32,7 @@ Deliver value instantly and avoid blocking actions. - After success, prompt social actions via [SDK actions](/mini-apps/features/links) and [Sharing & Social Graph](/mini-apps/features/sharing-and-social-graph) -- Offer next step: save, follow, or share — optimize with [Search & Discovery](/mini-apps/features/search-and-discovery) +- Offer next step: save, follow, or share — optimize with [Search & Discovery](/mini-apps/technical-guides/search-discovery) @@ -103,7 +103,7 @@ Learn how to implement them with [SDK actions](/mini-apps/features/links). - + diff --git a/docs/mini-apps/llms-full.txt b/docs/mini-apps/llms-full.txt index 07ac91d2..5c07cafe 100644 --- a/docs/mini-apps/llms-full.txt +++ b/docs/mini-apps/llms-full.txt @@ -49,7 +49,7 @@ export function Providers(props: { children: React.ReactNode }) { - [Manifest](https://docs.base.org/mini-apps/features/manifest.md) — Manifest - [Authentication](https://docs.base.org/mini-apps/features/Authentication.md) — Auth - [Embeds & Previews](https://docs.base.org/mini-apps/features/embeds-and-previews.md) — Embeds -- [Search & Discovery](https://docs.base.org/mini-apps/features/search-and-discovery.md) — Discovery +- [Search & Discovery](https://docs.base.org/mini-apps/technical-guides/search-discovery.md) — Discovery - [Sharing & Social Graph](https://docs.base.org/mini-apps/features/sharing-and-social-graph.md) — Sharing - [Notifications](https://docs.base.org/mini-apps/features/notifications.md) — Notifications - [Links](https://docs.base.org/mini-apps/features/links.md) — Links @@ -94,7 +94,7 @@ Source: `https://docs.base.org/mini-apps/overview.md` - Onboarding: Reduce steps; defer heavy auth until value is shown; prefill from client context. - Source: `https://docs.base.org/mini-apps/growth/optimize-onboarding.md` - Discovery: Optimize for search and featuring by following guidelines. - - Source: `https://docs.base.org/mini-apps/features/search-and-discovery.md` + - Source: `https://docs.base.org/mini-apps/technical-guides/search-discovery.md` ## Authentication Best Practices (excerpts) diff --git a/docs/mini-apps/llms.txt b/docs/mini-apps/llms.txt index 852e4b4d..7d662a1c 100644 --- a/docs/mini-apps/llms.txt +++ b/docs/mini-apps/llms.txt @@ -33,7 +33,7 @@ - [Hooks: useMiniKit](https://docs.base.org/mini-apps/technical-reference/minikit/hooks/useMiniKit.md) — Access frame context and client features ## Optional -- [Search & Discovery](https://docs.base.org/mini-apps/features/search-and-discovery.md) — Indexing and ranking signals in Base App +- [Search & Discovery](https://docs.base.org/mini-apps/technical-guides/search-discovery.md) — Indexing and ranking signals in Base App - [Sharing & Social Graph](https://docs.base.org/mini-apps/features/sharing-and-social-graph.md) — Viral distribution patterns diff --git a/docs/mini-apps/quickstart/launch-checklist.mdx b/docs/mini-apps/quickstart/launch-checklist.mdx index 16ce270b..727d4e77 100644 --- a/docs/mini-apps/quickstart/launch-checklist.mdx +++ b/docs/mini-apps/quickstart/launch-checklist.mdx @@ -34,7 +34,7 @@ Distribution starts in the feed: compelling previews with a clear image and laun Be found across surfaces: set a primary category, share once to trigger indexing, and keep assets valid to appear in search and categories. - + ## Sharing & Social Graph diff --git a/docs/mini-apps/technical-guides/embeds-and-previews.mdx b/docs/mini-apps/technical-guides/embeds-and-previews.mdx index 1faa9908..0c90b5cf 100644 --- a/docs/mini-apps/technical-guides/embeds-and-previews.mdx +++ b/docs/mini-apps/technical-guides/embeds-and-previews.mdx @@ -265,7 +265,7 @@ Set `Cache-Control` carefully: long enough for performance (300–600s), short e Continue with: -- [Search and Discovery](/mini-apps/technical-guides/search-and-discovery) +- [Search and Discovery](/mini-apps/technical-guides/search-discovery) - [Manifest](/mini-apps/core-concepts/manifest) diff --git a/docs/mini-apps/technical-guides/search-and-discovery.mdx b/docs/mini-apps/technical-guides/search-and-discovery.mdx index fcb82dce..0c477bcd 100644 --- a/docs/mini-apps/technical-guides/search-and-discovery.mdx +++ b/docs/mini-apps/technical-guides/search-and-discovery.mdx @@ -1,111 +1,198 @@ --- title: Search & Discovery -description: Learn how users discover and access Mini Apps in the Base ecosystem, including discovery surfaces, ranking systems, and optimization strategies for maximum visibility. +description: How Base App indexes Mini Apps and surfaces them in search results and category rankings. --- -> **What you’ll learn** -> By the end of this guide, you’ll be able to: -> - Get your Mini App indexed in Base App search and understand how indexing works. -> - Choose the right categories and implement strategies to improve visibility across discovery surfaces. -> - Apply best practices to increase discoverability across Base App surfaces. +Base App indexes your Mini App when someone shares it. Once indexed, users discover it through search queries and category browsing. This guide explains how the search system works and how to troubleshoot visibility issues. -## Search - -### How Search Works -Users discover Mini Apps through direct search queries in Base App. - - + search bar in base app -Your Mini App will only appear in search results after it has been indexed. To ensure indexing, share your Mini App at least once in Base App. Indexing typically takes ~10 minutes after the first share. +## How search works -### Managing Search Indexing +### The search algorithm -Development Environment: add `"noindex": true` to prevent dev/staging from appearing in search. Remove or set false for production. +Base App searches your Mini App's `name` field when users type a query. -**Removing from Search:** -To remove your Mini App from search results, invalidate your manifest (removes from all discovery). +**Matching behavior**: +- Case-insensitive matching +- Partial matches supported (searching "chess" matches "Chess Arena") +- Exact matches rank higher than partial matches - -If your Mini App does not show in search please follow the debugging guide [here](/mini-apps/troubleshooting/common-issues#1-app-discovery--indexing-issues) - +**Example ranking**: +``` +User searches: "chess" -## Discovery Surfaces +Results (in order): +1. name: "Chess" (exact match) +2. name: "Chess Arena" (starts with query) +3. name: "Ultimate Chess Master" (contains query) +``` +### How indexing triggers -### Saved Apps -Personal launcher and quick access hub +Your Mini App enters the search index through a specific sequence: - -saved apps - + + +Set up `/.well-known/farcaster.json` with required fields: `name`, `homeUrl`, `iconUrl`, `primaryCategory`, and `tags`. See [manifest documentation](/mini-apps/core-concepts/manifest). + -Appears here: -- User's saved Mini Apps -- Recently used applications + +Add the `fc:miniapp` meta tag to your `homeUrl`. This validates your Mini App is properly configured. See [embeds documentation](/mini-apps/core-concepts/embeds-and-previews). + -Prompt users to save via the Add Frame flow at key value moments. + +When someone shares your URL in Base App for the first time: +- Base App fetches your manifest from `/.well-known/farcaster.json` +- Validates the manifest structure and required fields +- Fetches your `homeUrl` and confirms embed metadata exists +- Extracts your Mini App `name` for search indexing +- Creates search index entry +- Initializes category ranking based on `primaryCategory` -### App Categories -Browsable directory organized by interest +Indexing completes in approximately 10 minutes. + + - -app categories - +**Why sharing triggers indexing**: Base App uses on-demand indexing rather than crawling. Only Mini Apps that are actively shared get indexed. This keeps the search index focused on active, user-validated apps. - -Choose your primaryCategory carefully as it determines where your app appears in Base App's category browsing. - + +Share your Mini App, wait 10 minutes, then search for its exact name. If it appears, indexing succeeded. + - -app categories +## Category rankings + +Beyond search, Base App surfaces Mini Apps through category browsing with dynamic rankings. + + +category rankings - The Base app uses aggregated data (7-day rolling window) to generate dynamic category rankings. +**How rankings work**: +- Based on 7-day rolling window of engagement data +- Engagement includes: launches, return visits, saves, shares, session duration +- Recent activity weighted higher than older activity +- Your `primaryCategory` determines which ranking list you appear in +- Each category has independent rankings + +**New app behavior**: Apps with zero engagement appear at the bottom of their category. First launches and shares quickly improve initial ranking. + +## Controlling search visibility + +### Remove from search with noindex + +Set `"noindex": true` in your manifest to exclude from search and discovery: + +```json Development environment +{ + "miniapp": { + "name": "My App (Dev)", + "noindex": true + } +} +``` + +Use `noindex` for development and staging environments to prevent duplicate entries in search results. + +### Force reindexing + +After changing your manifest, trigger reindexing by sharing your URL again. Changes appear in search after ~10 minutes. + +## Troubleshooting + +### Mini App doesn't appear in search + +Run these checks in order: + + + +Test in browser: `https://yourdomain.com/.well-known/farcaster.json` + +If 404 or error: Fix manifest deployment and location. + + + +Copy manifest response into a JSON validator. + +If syntax errors: Fix JSON formatting (common: trailing commas, missing quotes). + + + +Confirm manifest includes: `name`, `homeUrl`, `iconUrl`, `splashImageUrl`, `splashBackgroundColor`, `primaryCategory`, `tags`, and `accountAssociation`. + +If missing fields: Add required fields. See [manifest documentation](/mini-apps/core-concepts/manifest). + + + +Visit your `homeUrl` and view page source. Search for `fc:miniapp`. + +If missing: Add embed metadata to `homeUrl`. See [embeds documentation](/mini-apps/core-concepts/embeds-and-previews). + + + +Confirm `noindex` is `false` or omitted in production manifest. + +If `true`: Change to `false` or remove the field. + + + +Share your Mini App URL in Base App, wait 10 minutes, then search again. + +If still missing: See [complete debugging guide](/mini-apps/troubleshooting/common-issues#1-app-discovery--indexing-issues). + + + +### Search shows outdated information -## Visual Specifications +**Cause**: Manifest changes require reindexing. -For detailed visual mapping of how metadata translates to UI elements, see the [Figma specification file](https://www.figma.com/design/4wx6s24NB0KLgprQAyMT8R/TBA-Mini-App-Specs). +**Solution**: Share your URL again to trigger reindexing, wait 10 minutes for cache refresh. -## Optimization Strategies +### Mini App appears in wrong category +**Cause**: Invalid or incorrect `primaryCategory` value. +**Solution**: Update `primaryCategory` to a valid category (`games`, `social`, `finance`, `utility`, `productivity`, `health-fitness`, `news-media`, `music`, `shopping`, `education`, `developer-tools`, `entertainment`, `art-creativity`), then share URL to reindex. -### Category Optimization -- **Choose primaryCategory strategically** based on your target audience and competition -- **Monitor category rankings** and adjust strategy based on performance -- **Consider seasonal trends** that might affect category popularity +### Mini App disappeared from search -### Metadata Best Practices -- **High-quality icon** (1024×1024, clear and recognizable at small sizes) -- **Compelling description** under 130 characters that clearly communicates value -- **Relevant tags** that match user search behavior -- **OG image optimized** for social sharing (1200×630) with clear visual hierarchy +**Common causes**: +- Recent deployment broke manifest (404 error) +- Accidentally set `noindex: true` +- Manifest syntax error -## Build for Discovery: Checklist +**Solution**: Load your manifest URL in browser to verify accessibility, check for errors, then share URL to reindex. -- [ ] High-quality icon (1024×1024, clear at small sizes) -- [ ] Compelling description under 130 characters -- [ ] Relevant category selection for your target audience -- [ ] OG image optimized for social sharing (1200×630) -- [ ] Test metadata rendering across different clients -- [ ] Implement proper manifest files with correct categorization -- [ ] Choose relevant categories (primaryCategory) -- [ ] Create shareable moments that naturally encourage shares -- [ ] Design compelling embeds with clear CTAs -- [ ] Encourage saves for easy return access +## Quick reference -## Complete Implementation Guide +**Indexing checklist**: +- [ ] Manifest loads at `/.well-known/farcaster.json` +- [ ] Manifest has valid JSON syntax +- [ ] All required fields present +- [ ] `homeUrl` has `fc:miniapp` meta tag +- [ ] `noindex` is `false` or omitted for production +- [ ] Mini App URL shared at least once +- [ ] Waited 10 minutes after sharing -For step-by-step implementation including code examples, see: -- [Manifest Configuration](/mini-apps/core-concepts/manifest) -- [Embed Implementation](/mini-apps/core-concepts/embeds-and-previews) +**After manifest changes**: +- [ ] Share URL again to trigger reindexing +- [ ] Wait 10 minutes for changes to appear -Further reading: +## Related documentation -- [Sharing & Embeds](/mini-apps/core-concepts/embeds-and-previews) -- [Manifest](/mini-apps/core-concepts/manifest) + + + Configure your Mini App name and metadata for indexing and discovery. + + + Add required embed metadata for indexing validation. + + + Complete debugging guide for indexing and discovery issues. + + diff --git a/docs/mini-apps/technical-guides/search-discovery.mdx b/docs/mini-apps/technical-guides/search-discovery.mdx new file mode 100644 index 00000000..35293ff3 --- /dev/null +++ b/docs/mini-apps/technical-guides/search-discovery.mdx @@ -0,0 +1,64 @@ +--- +title: Search & Discovery +description: How Base App indexes Mini Apps and surfaces them in search results and category rankings. +--- + + + +## How search works + +Base App uses on-demand indexing to make Mini Apps discoverable. When you share your Mini App URL, Base App indexes it for search and category rankings. +The search algorithm matches user queries against your Mini App's `name` field. Indexing completes in 10 minutes. + + +Your manifest must be properly configured and validated for indexing to work. See [manifest documentation](/mini-apps/core-concepts/manifest) for required fields and validation. + + +search bar in base app + + +## Category rankings +Rankings use 7-day engagement such as shares. Your `primaryCategory` determines your category list. + + +category rankings + + +## Control search visibility + +Set `noindex: true` to exclude from search during development: + +```json +{ + "miniapp": { + "name": "My App (Dev)", + "noindex": true + } +} +``` + +Reindex after changes: Share your URL again. Updates appear in 10 minutes. + +## Troubleshooting + +**Outdated information:** Share your URL to reindex. Wait 10 minutes. + +**Wrong category:** Update `primaryCategory` to valid value, then share to reindex. + +**Disappeared from search:** Load your manifest URL in browser. Common causes: 404 error, `noindex: true`, syntax error. + + +## Related + + + + Configure name and metadata for indexing. + + + Add required embed metadata. + + + Complete debugging guide. + + + diff --git a/docs/tone_of_voice.mdx b/docs/tone_of_voice.mdx new file mode 100644 index 00000000..589dfb7f --- /dev/null +++ b/docs/tone_of_voice.mdx @@ -0,0 +1,84 @@ + You are an expert technical documentation specialist with deep expertise in developer documentation, technical writing best practices, and the Mintlify documentation platform. Your role is to create clear, consistent, and developer-focused content that helps engineers accomplish their goals quickly and successfully. +You have mastery in: +Technical writing principles (clarity, concision, active voice) +Developer psychology and information needs +Mintlify component usage and best practices +Identifying and eliminating the curse of knowledge +Writing for both human developers and AI comprehension + + +## Voice +Professional and direct - No preamble. State facts clearly. +Active voice - Identify who does what. +❌ The data is processed by the function + ✅ The function processes data +Conversational brevity - Use "you" but cut excess words. +❌ You should configure the environment variables + ✅ Configure your environment variables +Data over description - Show metrics, not marketing. +❌ incredibly fast → ✅ completes in < 100ms + + + + + +## Structure + +**Strong verbs** - Choose precise action verbs over weak ones (is, are, occurs, happens). + +**Concise sentences** - One idea per sentence. Target 15-20 words, maximum 30. + +**Direct constructions** - Start with the subject. Eliminate "There is/There are" and filler phrases (~~at this point in time~~ → now, ~~is able to~~ → can). + +**Progressive disclosure** - Essential info first, then standard workflows, then error cases, finally advanced topics. + +## Terminology + +**Consistent** - One term per concept throughout all documentation (parameter OR argument, method OR function). + +**Precise** - Use explicit names: ❌ "the auth file" → ✅ "`authentication.js`" + +**Clear** - Define abbreviations on first use: "Application Programming Interface (API)" → then use "API" + +## Organization + +**Focused paragraphs** - One topic per paragraph with a clear topic sentence. + +**Strategic lists** - Numbered for sequential steps, bulleted for unordered items. Maintain parallel structure. + +**Clear instructions** - Start steps with imperative verbs (Install, Configure, Initialize). + +## Code + +Write complete, runnable examples with error handling, expected outputs, and realistic values (use environment variables, not placeholders). + +```javascript +const apiKey = process.env.API_KEY; + +try { + const result = calculateTotal([10, 20, 30]); + console.log(result); // Output: 60 +} catch (error) { + console.error(`Calculation failed: ${error.message}`); +} +``` + + + + +Never use: emojis, placeholder values (YOUR_API_KEY), weak verbs (is, are, occurs), "There is/There are", marketing language, mixed terminology, vague link text ("click here"), unexplained concepts, passive voice without justification. + + + +Page structure requires YAML frontmatter with title and description. Use `` for procedures, `` for platform variations, `` for multi-language examples, callouts for context (``, ``, ``), `` for images, and field components for API docs. + + + +Before output: sentences under 30 words with strong verbs and active voice, terms defined and consistent, no emojis, code examples complete with error handling, proper frontmatter and components used. + + + +**Before:** "There is a configuration file that is used for setting up the API client. The file should be located in the root directory and it needs to have the API key and endpoint URL." + +**After:** "The `config.json` file configures your API client. Place it in your project's root directory. Required fields: `apiKey` and `endpointUrl`. Missing files trigger initialization errors." + diff --git a/global-tone-voice.mdx b/global-tone-voice.mdx new file mode 100644 index 00000000..e69de29b From 4fc43cf8e062e32c231178d5de552dd1e46c5402 Mon Sep 17 00:00:00 2001 From: sohey Date: Mon, 13 Oct 2025 18:43:45 +0200 Subject: [PATCH 02/14] added direct messging as a surface --- .../technical-guides/search-discovery.mdx | 51 ++++++++++--------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/docs/mini-apps/technical-guides/search-discovery.mdx b/docs/mini-apps/technical-guides/search-discovery.mdx index 35293ff3..d757949a 100644 --- a/docs/mini-apps/technical-guides/search-discovery.mdx +++ b/docs/mini-apps/technical-guides/search-discovery.mdx @@ -3,41 +3,46 @@ title: Search & Discovery description: How Base App indexes Mini Apps and surfaces them in search results and category rankings. --- - - -## How search works - -Base App uses on-demand indexing to make Mini Apps discoverable. When you share your Mini App URL, Base App indexes it for search and category rankings. -The search algorithm matches user queries against your Mini App's `name` field. Indexing completes in 10 minutes. +Base App makes your Mini App discoverable through automated indexing. Unlike traditional app stores with manual submission, sharing your Mini App URL triggers Base App to crawl your manifest and add your app to the searchable catalog no review process required. Your manifest must be properly configured and validated for indexing to work. See [manifest documentation](/mini-apps/core-concepts/manifest) for required fields and validation. - -search bar in base app + + +## Discovery surfaces + +Your Mini App appears in three places in Base App: + +### Search results +Users find your app by searching your Mini App's `name`. Both exact and partial matches appear in results. + + +search bar in base app + + +### Category browsing +Your app appears in the category specified by `primaryCategory` in your manifest. Users browse categories to discover apps by interest. + + +app categories ## Category rankings Rankings use 7-day engagement such as shares. Your `primaryCategory` determines your category list. - -category rankings - -## Control search visibility +### Saved Apps +When users save your Mini App, it appears in their personal saved options for quick access. Prompt users to save at key moments. -Set `noindex: true` to exclude from search during development: + +saved apps + + +### Direct Messaging -```json -{ - "miniapp": { - "name": "My App (Dev)", - "noindex": true - } -} -``` +When users share your Mini App URL in a direct message, it displays as an interactive embed. Recipients can preview and open your app directly from the conversation, with `context.location` set to `messaging` so you can customize the experience for shared discovery. -Reindex after changes: Share your URL again. Updates appear in 10 minutes. ## Troubleshooting @@ -45,8 +50,6 @@ Reindex after changes: Share your URL again. Updates appear in 10 minutes. **Wrong category:** Update `primaryCategory` to valid value, then share to reindex. -**Disappeared from search:** Load your manifest URL in browser. Common causes: 404 error, `noindex: true`, syntax error. - ## Related From aec761de8acba7960f974b162636912e35de0994 Mon Sep 17 00:00:00 2001 From: sohey Date: Mon, 13 Oct 2025 18:44:46 +0200 Subject: [PATCH 03/14] added direct messging as a surface --- .../technical-guides/search-and-discovery.mdx | 198 ------------------ 1 file changed, 198 deletions(-) delete mode 100644 docs/mini-apps/technical-guides/search-and-discovery.mdx diff --git a/docs/mini-apps/technical-guides/search-and-discovery.mdx b/docs/mini-apps/technical-guides/search-and-discovery.mdx deleted file mode 100644 index 0c477bcd..00000000 --- a/docs/mini-apps/technical-guides/search-and-discovery.mdx +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: Search & Discovery -description: How Base App indexes Mini Apps and surfaces them in search results and category rankings. ---- - -Base App indexes your Mini App when someone shares it. Once indexed, users discover it through search queries and category browsing. This guide explains how the search system works and how to troubleshoot visibility issues. - - -search bar in base app - - -## How search works - -### The search algorithm - -Base App searches your Mini App's `name` field when users type a query. - -**Matching behavior**: -- Case-insensitive matching -- Partial matches supported (searching "chess" matches "Chess Arena") -- Exact matches rank higher than partial matches - -**Example ranking**: -``` -User searches: "chess" - -Results (in order): -1. name: "Chess" (exact match) -2. name: "Chess Arena" (starts with query) -3. name: "Ultimate Chess Master" (contains query) -``` - -### How indexing triggers - -Your Mini App enters the search index through a specific sequence: - - - -Set up `/.well-known/farcaster.json` with required fields: `name`, `homeUrl`, `iconUrl`, `primaryCategory`, and `tags`. See [manifest documentation](/mini-apps/core-concepts/manifest). - - - -Add the `fc:miniapp` meta tag to your `homeUrl`. This validates your Mini App is properly configured. See [embeds documentation](/mini-apps/core-concepts/embeds-and-previews). - - - -When someone shares your URL in Base App for the first time: -- Base App fetches your manifest from `/.well-known/farcaster.json` -- Validates the manifest structure and required fields -- Fetches your `homeUrl` and confirms embed metadata exists -- Extracts your Mini App `name` for search indexing -- Creates search index entry -- Initializes category ranking based on `primaryCategory` - -Indexing completes in approximately 10 minutes. - - - -**Why sharing triggers indexing**: Base App uses on-demand indexing rather than crawling. Only Mini Apps that are actively shared get indexed. This keeps the search index focused on active, user-validated apps. - - -Share your Mini App, wait 10 minutes, then search for its exact name. If it appears, indexing succeeded. - - -## Category rankings - -Beyond search, Base App surfaces Mini Apps through category browsing with dynamic rankings. - - -category rankings - - -**How rankings work**: -- Based on 7-day rolling window of engagement data -- Engagement includes: launches, return visits, saves, shares, session duration -- Recent activity weighted higher than older activity -- Your `primaryCategory` determines which ranking list you appear in -- Each category has independent rankings - -**New app behavior**: Apps with zero engagement appear at the bottom of their category. First launches and shares quickly improve initial ranking. - -## Controlling search visibility - -### Remove from search with noindex - -Set `"noindex": true` in your manifest to exclude from search and discovery: - -```json Development environment -{ - "miniapp": { - "name": "My App (Dev)", - "noindex": true - } -} -``` - -Use `noindex` for development and staging environments to prevent duplicate entries in search results. - -### Force reindexing - -After changing your manifest, trigger reindexing by sharing your URL again. Changes appear in search after ~10 minutes. - -## Troubleshooting - -### Mini App doesn't appear in search - -Run these checks in order: - - - -Test in browser: `https://yourdomain.com/.well-known/farcaster.json` - -If 404 or error: Fix manifest deployment and location. - - - -Copy manifest response into a JSON validator. - -If syntax errors: Fix JSON formatting (common: trailing commas, missing quotes). - - - -Confirm manifest includes: `name`, `homeUrl`, `iconUrl`, `splashImageUrl`, `splashBackgroundColor`, `primaryCategory`, `tags`, and `accountAssociation`. - -If missing fields: Add required fields. See [manifest documentation](/mini-apps/core-concepts/manifest). - - - -Visit your `homeUrl` and view page source. Search for `fc:miniapp`. - -If missing: Add embed metadata to `homeUrl`. See [embeds documentation](/mini-apps/core-concepts/embeds-and-previews). - - - -Confirm `noindex` is `false` or omitted in production manifest. - -If `true`: Change to `false` or remove the field. - - - -Share your Mini App URL in Base App, wait 10 minutes, then search again. - -If still missing: See [complete debugging guide](/mini-apps/troubleshooting/common-issues#1-app-discovery--indexing-issues). - - - -### Search shows outdated information - -**Cause**: Manifest changes require reindexing. - -**Solution**: Share your URL again to trigger reindexing, wait 10 minutes for cache refresh. - -### Mini App appears in wrong category - -**Cause**: Invalid or incorrect `primaryCategory` value. - -**Solution**: Update `primaryCategory` to a valid category (`games`, `social`, `finance`, `utility`, `productivity`, `health-fitness`, `news-media`, `music`, `shopping`, `education`, `developer-tools`, `entertainment`, `art-creativity`), then share URL to reindex. - -### Mini App disappeared from search - -**Common causes**: -- Recent deployment broke manifest (404 error) -- Accidentally set `noindex: true` -- Manifest syntax error - -**Solution**: Load your manifest URL in browser to verify accessibility, check for errors, then share URL to reindex. - -## Quick reference - -**Indexing checklist**: -- [ ] Manifest loads at `/.well-known/farcaster.json` -- [ ] Manifest has valid JSON syntax -- [ ] All required fields present -- [ ] `homeUrl` has `fc:miniapp` meta tag -- [ ] `noindex` is `false` or omitted for production -- [ ] Mini App URL shared at least once -- [ ] Waited 10 minutes after sharing - -**After manifest changes**: -- [ ] Share URL again to trigger reindexing -- [ ] Wait 10 minutes for changes to appear - -## Related documentation - - - - Configure your Mini App name and metadata for indexing and discovery. - - - - Add required embed metadata for indexing validation. - - - - Complete debugging guide for indexing and discovery issues. - - - From 7923c65d0a76abe4a2663ea3fd54d9484e9a3213 Mon Sep 17 00:00:00 2001 From: sohey Date: Mon, 13 Oct 2025 19:12:42 +0200 Subject: [PATCH 04/14] added search section --- .../technical-guides/search-discovery.mdx | 55 +++++++++++-------- 1 file changed, 33 insertions(+), 22 deletions(-) diff --git a/docs/mini-apps/technical-guides/search-discovery.mdx b/docs/mini-apps/technical-guides/search-discovery.mdx index d757949a..df66fdf0 100644 --- a/docs/mini-apps/technical-guides/search-discovery.mdx +++ b/docs/mini-apps/technical-guides/search-discovery.mdx @@ -3,54 +3,65 @@ title: Search & Discovery description: How Base App indexes Mini Apps and surfaces them in search results and category rankings. --- -Base App makes your Mini App discoverable through automated indexing. Unlike traditional app stores with manual submission, sharing your Mini App URL triggers Base App to crawl your manifest and add your app to the searchable catalog no review process required. +Indexing is how Base App adds your Mini App to its catalog, making it discoverable through search and browsing. +Unlike traditional app stores with manual submission, you control when indexing happens. Share your Mini App URL to the social feed, and indexing starts automatically—no review process required. + +## How indexing works + + + + Share your URL to the feed. + + + Base App fetches and validates your manifest file. + + Invalid or unreachable manifests will fail indexing. + + + + Your Mini App is recorded and becomes searchable within 10 minutes. + + Your manifest must be properly configured and validated for indexing to work. See [manifest documentation](/mini-apps/core-concepts/manifest) for required fields and validation. - -## Discovery surfaces - -Your Mini App appears in three places in Base App: - -### Search results -Users find your app by searching your Mini App's `name`. Both exact and partial matches appear in results. +## How search works +Base App search queries your Mini App's `name` field from the catalog. Both exact and partial matches appear in results. Search displays your Mini App based on information you provided in your manifest. search bar in base app + +When making changes to your manifest, you will need to share your URL to reindex. + + +## Discovery surfaces + ### Category browsing Your app appears in the category specified by `primaryCategory` in your manifest. Users browse categories to discover apps by interest. -app categories +app categories -## Category rankings -Rankings use 7-day engagement such as shares. Your `primaryCategory` determines your category list. - + +**Category rankings**: Rankings use 7-day engagement metrics such as shares. + ### Saved Apps When users save your Mini App, it appears in their personal saved options for quick access. Prompt users to save at key moments. -saved apps +saved apps -### Direct Messaging +### Direct Messages When users share your Mini App URL in a direct message, it displays as an interactive embed. Recipients can preview and open your app directly from the conversation, with `context.location` set to `messaging` so you can customize the experience for shared discovery. - -## Troubleshooting - -**Outdated information:** Share your URL to reindex. Wait 10 minutes. - -**Wrong category:** Update `primaryCategory` to valid value, then share to reindex. - - ## Related From b0ba69e0e0c6fd2d05de1b96306b8fd109a2f925 Mon Sep 17 00:00:00 2001 From: sohey Date: Mon, 13 Oct 2025 19:15:58 +0200 Subject: [PATCH 05/14] added search section --- .../mini-apps/technical-guides/search-discovery.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/mini-apps/technical-guides/search-discovery.mdx b/docs/mini-apps/technical-guides/search-discovery.mdx index df66fdf0..0fc8b438 100644 --- a/docs/mini-apps/technical-guides/search-discovery.mdx +++ b/docs/mini-apps/technical-guides/search-discovery.mdx @@ -8,6 +8,10 @@ Unlike traditional app stores with manual submission, you control when indexing ## How indexing works + +Your manifest must be properly configured and validated for indexing to work. See [manifest documentation](/mini-apps/core-concepts/manifest) for required fields and validation. + + Share your URL to the feed. @@ -23,12 +27,9 @@ Unlike traditional app stores with manual submission, you control when indexing - -Your manifest must be properly configured and validated for indexing to work. See [manifest documentation](/mini-apps/core-concepts/manifest) for required fields and validation. - ## How search works -Base App search queries your Mini App's `name` field from the catalog. Both exact and partial matches appear in results. Search displays your Mini App based on information you provided in your manifest. +Base App's search queries your Mini App's `name` field from the catalog. Both exact and partial matches appear in results. Search displays your Mini App based on information you provided in your manifest. search bar in base app @@ -51,14 +52,14 @@ Your app appears in the category specified by `primaryCategory` in your manifest **Category rankings**: Rankings use 7-day engagement metrics such as shares. -### Saved Apps +### Saved apps When users save your Mini App, it appears in their personal saved options for quick access. Prompt users to save at key moments. saved apps -### Direct Messages +### Direct messages When users share your Mini App URL in a direct message, it displays as an interactive embed. Recipients can preview and open your app directly from the conversation, with `context.location` set to `messaging` so you can customize the experience for shared discovery. From a39025d1d8f7270c5f8202ca0559c3eb7afb48f5 Mon Sep 17 00:00:00 2001 From: sohey Date: Tue, 14 Oct 2025 11:30:33 +0200 Subject: [PATCH 06/14] undid embed changes --- .../core-concepts/embeds-and-previews.mdx | 317 +++++------------- 1 file changed, 93 insertions(+), 224 deletions(-) diff --git a/docs/mini-apps/core-concepts/embeds-and-previews.mdx b/docs/mini-apps/core-concepts/embeds-and-previews.mdx index 15174454..f5c7b601 100644 --- a/docs/mini-apps/core-concepts/embeds-and-previews.mdx +++ b/docs/mini-apps/core-concepts/embeds-and-previews.mdx @@ -1,276 +1,145 @@ --- title: Embeds & Previews -description: Configure shareable embeds that display preview images and launch buttons when users share your Mini App links in social feeds. +description: Mini apps use metadata to create embeds when users share links. The embed shows a preview image and launch button. --- -When users share your Mini App in Base App, the shared link appears as a rich preview with an image and launch button. This guide shows you how to implement the required metadata. - + Mini app feed - -## Step 1: Add embed metadata to your page - -Add the `fc:miniapp` meta tag to any page you want to make shareable. This metadata generates the preview embed when users share your Mini App. - -**Why it matters**: Without embed metadata, shared links display as plain URLs. The embed metadata transforms your link into an interactive preview that increases engagement and provides a clear call-to-action for users to launch your Mini App. + +## Implementation +Add this meta tag to the `` section of any page you want to make shareable: -```html html - - - - My Mini App - - - - - - -``` - -```jsx next.js -// app/layout.tsx or app/page.tsx -import type { Metadata } from "next"; - + }' + /> + + + + + + ``` + + ```jsx next.js metadata + // app/layout.tsx or app/page.tsx (Next.js App Router) + import type { Metadata } from "next"; + export async function generateMetadata(): Promise { return { - title: "My Mini App", - description: "Join and explore our Mini App", + title: miniapp.name, + description: miniapp.description, other: { "fc:miniapp": JSON.stringify({ - version: "next", - imageUrl: "https://example.com/preview.png", + version: miniapp.version, + imageUrl: miniapp.heroImageUrl, button: { - title: "Open App", + title: `Join the ${miniapp.name}`, action: { - type: "launch_frame", - name: "Launch My Mini App", - url: "https://example.com" + name: `Launch ${miniapp.name}`, + url: `${miniapp.homeUrl}` }, }, }), }, }; } - -export default function RootLayout({ children }: { children: React.ReactNode }) { - return ( - - {children} - - ); -} -``` - - -**Explanation**: The `fc:miniapp` meta tag contains JSON configuration that defines your embed appearance. The `imageUrl` displays as the preview image, while the `button` object configures the launch button text and destination URL. - - -Your page now includes the required metadata. View your page source to verify the `fc:miniapp` meta tag appears in the `` section. - - -## Step 2: Configure your preview image - -Set your `imageUrl` to a high-quality image that represents your Mini App and captures user attention in social feeds. - -**Why it matters**: The preview image is the first thing users see when your Mini App is shared. A compelling image significantly increases click-through rates and user engagement. - -```json -{ - "imageUrl": "https://example.com/preview.png" -} -``` - -**Image requirements**: -- **Aspect ratio**: 3:2 (e.g., 1200x800 pixels) -- **Maximum file size**: 10MB -- **Maximum URL length**: 1024 characters -- **Format**: PNG, JPG, or WebP - - -Use a visually distinctive image that clearly communicates your Mini App's purpose. Include your app name or logo for brand recognition. - - - -Verify your image meets the 3:2 aspect ratio requirement and loads quickly. Test the URL in a browser to confirm it's publicly accessible. - - -## Step 3: Customize the launch button - -Configure the button that appears on your embed to control what happens when users click it. - -**Why it matters**: The button action determines the user's first interaction with your Mini App. A clear, action-oriented button title increases conversion rates from embed views to actual app launches. - -```json -{ - "button": { - "title": "Open App", - "action": { - "type": "launch_frame", - "name": "My Mini App", - "url": "https://example.com", - "splashImageUrl": "https://example.com/splash.png", - "splashBackgroundColor": "#000000" - } + + export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + {children} + + ); } -} -``` - -**Button configuration**: -- `title`: Button text displayed on the embed (max 32 characters) -- `action.type`: Must be `"launch_frame"` to open your Mini App -- `action.name`: Application name shown during launch (max 32 characters, defaults to manifest name) -- `action.url`: Destination URL when button is clicked (max 1024 characters, defaults to current page URL) -- `action.splashImageUrl`: Image shown on splash screen (200x200 pixels, optional) -- `action.splashBackgroundColor`: Hex color for splash background (optional) - - -Use action-oriented button titles like "Play Now", "Join Game", or "Start Trading" instead of generic text like "Click Here". - - - -Verify your button title is clear and under 32 characters. The action URL should point to the specific page or state you want users to launch. - - -## Step 4: Ensure your homeUrl has embed metadata - -Your manifest's `homeUrl` must include the embed metadata for your Mini App to render correctly in Base App. - -**Why it matters**: Base App uses your manifest's `homeUrl` to fetch embed metadata. If the `homeUrl` doesn't have the `fc:miniapp` meta tag, your Mini App won't display properly in the app. - - -```json manifest.json -{ - "homeUrl": "https://example.com", - "name": "My Mini App" -} -``` - -```html index.html at homeUrl - - - - - - -``` + ``` +The `homeUrl` used in the `manifest` *must* have embed metadata defined, in order for the mini app to render correctly in the Base app. -**Explanation**: The `homeUrl` in your manifest must point to a page that contains the `fc:miniapp` metadata. This ensures Base App can retrieve and display your embed correctly. - - -Visit your `homeUrl` and view the page source. Confirm the `fc:miniapp` meta tag is present in the `` section. - -## Step 5: Test your embed -Share your Mini App link in Base App to verify the embed displays correctly with your preview image and launch button. - -**Why it matters**: Testing ensures users see the intended preview when your Mini App is shared. Catching display issues before launch prevents poor user experience and lost engagement. - -1. Open Base App -2. Share your Mini App URL in a conversation or post -3. Verify the preview image appears correctly -4. Verify the button text matches your configuration -5. Click the button to confirm it launches your Mini App - - -Embeds are cached. If you update your metadata, you may need to wait a few minutes or share a URL with a unique query parameter (e.g., `?v=2`) to see changes. - - - -Your embed displays with the correct preview image, button text, and successfully launches your Mini App when clicked. - - -## Complete schema reference +## Schema + -Version of the embed specification. Use `"next"` for the latest features or `"1"` for legacy support. +Version of the embed. Must be `"1"` or `"next"`. -URL to the preview image. Must be 3:2 aspect ratio, maximum 10MB, maximum 1024 characters. +Image URL for the embed. Must be 3:2 aspect ratio, maximum 10MB, maximum 1024 characters. Button configuration object. + + - - - Text displayed on the button. Maximum 32 characters. - +### Button Configuration - - Action configuration that defines launch behavior. Maximum 1024 characters. - - - - Action type. Must be `"launch_frame"`. - +Defines the launch button that appears on the embed. + + + +Button text. Maximum 32 characters. + - - URL to open when button is clicked. Defaults to the full URL of the page including query parameters. Maximum 1024 characters. - + +Action configuration object. Maximum 1024 characters. + + - - Application name displayed during launch. Maximum 32 characters. Defaults to manifest name. - +### Action Configuration - - Image URL for the splash screen. Must be 200x200 pixels. Maximum 32 characters. Defaults to manifest splash image. - +Specifies what happens when the embed button is clicked. - - Splash screen background color. Must be hex color code (e.g., `#000000`). Defaults to manifest splash background color. - - - - + + +Action type. Must be `"launch_frame"`. -## Related documentation + +App URL to open. Defaults to the full URL of the page including query parameters. Maximum 1024 characters. + - - - Configure your manifest for search indexing and category placement in Base App discovery features. - + +Application name. Maximum 32 characters. Defaults to manifest name. + + + +Splash screen image URL. Must be 200x200 pixels. Maximum 32 characters. Defaults to manifest splash image. + - - Implement sharing strategies to maximize viral growth using Base's social graph features. + +Splash screen background color. Must be hex color code. Defaults to manifest splash background color. + - - Complete guide to configuring your Mini App manifest with all available options. + +## Related Concepts + + + + Learn how your manifest powers search indexing and category placement in the Base app discovery features. - - Resolve common issues with embeds, indexing, and Mini App display. + + Learn how to maximize sharing, social engagement, and viral growth for your Mini App using Base's social graph features. From 51cd77c0a769c0cd9b18b4bd50f5eb95b35751fe Mon Sep 17 00:00:00 2001 From: sohey Date: Tue, 14 Oct 2025 11:52:44 +0200 Subject: [PATCH 07/14] rechanged title --- .../technical-guides/search-discovery.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/mini-apps/technical-guides/search-discovery.mdx b/docs/mini-apps/technical-guides/search-discovery.mdx index 0fc8b438..c29b10fd 100644 --- a/docs/mini-apps/technical-guides/search-discovery.mdx +++ b/docs/mini-apps/technical-guides/search-discovery.mdx @@ -1,9 +1,9 @@ --- title: Search & Discovery -description: How Base App indexes Mini Apps and surfaces them in search results and category rankings. +description: How The Base app indexes Mini Apps and surfaces them in search results and category rankings. --- -Indexing is how Base App adds your Mini App to its catalog, making it discoverable through search and browsing. +Indexing is how The Base app adds your Mini App to its catalog, making it discoverable through search and browsing. Unlike traditional app stores with manual submission, you control when indexing happens. Share your Mini App URL to the social feed, and indexing starts automatically—no review process required. ## How indexing works @@ -16,8 +16,8 @@ Your manifest must be properly configured and validated for indexing to work. Se Share your URL to the feed. - - Base App fetches and validates your manifest file. + + The Base app fetches and validates your manifest file. Invalid or unreachable manifests will fail indexing. @@ -29,10 +29,10 @@ Your manifest must be properly configured and validated for indexing to work. Se ## How search works -Base App's search queries your Mini App's `name` field from the catalog. Both exact and partial matches appear in results. Search displays your Mini App based on information you provided in your manifest. +The Base app's search queries your Mini App's `name` field from the catalog. Both exact and partial matches appear in results. Search displays your Mini App based on information you provided in your manifest. - -search bar in base app + +search bar in the Base app From 1cdf7424f55fb8465c1f65ae310da21f6beb3d09 Mon Sep 17 00:00:00 2001 From: sohey Date: Fri, 17 Oct 2025 10:49:56 +0200 Subject: [PATCH 08/14] moved search and discovery from technical to troubleshooting --- docs/docs.json | 8 ++++++-- .../search-discovery.mdx | 5 +++-- 2 files changed, 9 insertions(+), 4 deletions(-) rename docs/mini-apps/{technical-guides => troubleshooting}/search-discovery.mdx (92%) diff --git a/docs/docs.json b/docs/docs.json index 0f1a3a12..8f5f018b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -454,7 +454,6 @@ "group": "Technical Guides", "pages": [ "mini-apps/technical-guides/data-driven-growth", - "mini-apps/technical-guides/search-discovery", "mini-apps/technical-guides/sharing-and-social-graph", "mini-apps/technical-guides/sign-manifest", "mini-apps/technical-guides/neynar-notifications" @@ -483,7 +482,8 @@ "group": "Troubleshooting", "pages": [ "mini-apps/troubleshooting/common-issues", - "mini-apps/troubleshooting/base-app-compatibility" + "mini-apps/troubleshooting/base-app-compatibility", + "mini-apps/troubleshooting/search-discovery" ] }, { @@ -1506,6 +1506,10 @@ ] }, "redirects": [ + { + "source": "/mini-apps/technical-guides/search-discovery", + "destination": "/mini-apps/troubleshooting/search-discovery" + }, { "source": "/mini-apps/overview", "destination": "/mini-apps/quickstart/create-new-miniapp" diff --git a/docs/mini-apps/technical-guides/search-discovery.mdx b/docs/mini-apps/troubleshooting/search-discovery.mdx similarity index 92% rename from docs/mini-apps/technical-guides/search-discovery.mdx rename to docs/mini-apps/troubleshooting/search-discovery.mdx index c29b10fd..26e8834f 100644 --- a/docs/mini-apps/technical-guides/search-discovery.mdx +++ b/docs/mini-apps/troubleshooting/search-discovery.mdx @@ -1,13 +1,14 @@ --- title: Search & Discovery -description: How The Base app indexes Mini Apps and surfaces them in search results and category rankings. +description: If your Mini App isn't appearing in The Base app, this guide explains how indexing and search work so you can identify and fix the issue. --- - Indexing is how The Base app adds your Mini App to its catalog, making it discoverable through search and browsing. Unlike traditional app stores with manual submission, you control when indexing happens. Share your Mini App URL to the social feed, and indexing starts automatically—no review process required. ## How indexing works +Understanding the indexing process helps you diagnose why your Mini App may not be appearing. + Your manifest must be properly configured and validated for indexing to work. See [manifest documentation](/mini-apps/core-concepts/manifest) for required fields and validation. From 7beb4608e525618e40a6529c267ce749fec76e51 Mon Sep 17 00:00:00 2001 From: sohey Date: Fri, 17 Oct 2025 10:52:11 +0200 Subject: [PATCH 09/14] moved search and discovery from technical to troubleshooting updated docs.json --- docs/docs.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 8f5f018b..2a02f229 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -2712,11 +2712,11 @@ }, { "source": "/base-app/miniapps/search-and-discovery", - "destination": "/mini-apps/technical-guides/search-discovery" + "destination": "/mini-apps/troubleshooting/search-discovery" }, { "source": "/base-app/build-with-minikit/search-and-discovery", - "destination": "/mini-apps/technical-guides/search-discovery" + "destination": "/mini-apps/troubleshooting/search-discovery" }, { "source": "/base-app/miniapps/sharing-your-miniapp", From a5c8ca850ebb3876fb0213114a547725c7772ad2 Mon Sep 17 00:00:00 2001 From: sohey Date: Fri, 17 Oct 2025 10:54:22 +0200 Subject: [PATCH 10/14] moved search and discovery from technical to troubleshooting updated docs.json --- docs/docs.json | 4 ++-- docs/mini-apps/core-concepts/manifest.mdx | 2 +- docs/mini-apps/growth/optimize-onboarding.mdx | 2 +- docs/mini-apps/quickstart/build-checklist.mdx | 2 +- docs/mini-apps/technical-guides/embeds-and-previews.mdx | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 2a02f229..7f922295 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1536,11 +1536,11 @@ }, { "source": "/mini-apps/features/search-and-discovery", - "destination": "/mini-apps/technical-guides/search-discovery" + "destination": "/mini-apps/troubleshooting/search-discovery" }, { "source": "/mini-apps/technical-guides/search-and-discovery", - "destination": "/mini-apps/technical-guides/search-discovery" + "destination": "/mini-apps/troubleshooting/search-discovery" }, { "source": "/mini-apps/features/sharing-and-social-graph", diff --git a/docs/mini-apps/core-concepts/manifest.mdx b/docs/mini-apps/core-concepts/manifest.mdx index 6dd0f2ed..d7ef18b2 100644 --- a/docs/mini-apps/core-concepts/manifest.mdx +++ b/docs/mini-apps/core-concepts/manifest.mdx @@ -205,7 +205,7 @@ Open Graph image. 1200×630px (1.91:1), PNG/JPG. ## Related Concepts - + Learn how your manifest powers search indexing and category placement in the Base app discovery features. diff --git a/docs/mini-apps/growth/optimize-onboarding.mdx b/docs/mini-apps/growth/optimize-onboarding.mdx index a5ba5c39..1529ea53 100644 --- a/docs/mini-apps/growth/optimize-onboarding.mdx +++ b/docs/mini-apps/growth/optimize-onboarding.mdx @@ -32,7 +32,7 @@ Deliver value instantly and avoid blocking actions. - After success, prompt social actions via [SDK actions](/mini-apps/features/links) and [Sharing & Social Graph](/mini-apps/features/sharing-and-social-graph) -- Offer next step: save, follow, or share — optimize with [Search & Discovery](/mini-apps/technical-guides/search-discovery) +- Offer next step: save, follow, or share — optimize with [Search & Discovery](/mini-apps/troubleshooting/search-discovery) diff --git a/docs/mini-apps/quickstart/build-checklist.mdx b/docs/mini-apps/quickstart/build-checklist.mdx index c3aa300b..b4848b02 100644 --- a/docs/mini-apps/quickstart/build-checklist.mdx +++ b/docs/mini-apps/quickstart/build-checklist.mdx @@ -33,7 +33,7 @@ Distribution starts in the feed: compelling previews with a clear image and laun Be found across surfaces: set a primary category, share once to trigger indexing, and keep assets valid to appear in search and categories. - + ## Sharing & Social Graph diff --git a/docs/mini-apps/technical-guides/embeds-and-previews.mdx b/docs/mini-apps/technical-guides/embeds-and-previews.mdx index 0c90b5cf..f2350fcd 100644 --- a/docs/mini-apps/technical-guides/embeds-and-previews.mdx +++ b/docs/mini-apps/technical-guides/embeds-and-previews.mdx @@ -265,7 +265,7 @@ Set `Cache-Control` carefully: long enough for performance (300–600s), short e Continue with: -- [Search and Discovery](/mini-apps/technical-guides/search-discovery) +- [Search and Discovery](/mini-apps/troubleshooting/search-discovery) - [Manifest](/mini-apps/core-concepts/manifest) From f2d4d8cb5f305006a18117e09cfac5266acd2161 Mon Sep 17 00:00:00 2001 From: sohey Date: Fri, 17 Oct 2025 10:58:50 +0200 Subject: [PATCH 11/14] moved search and discovery from technical to troubleshooting updated docs.json --- docs/docs.json | 12 ++++++------ docs/mini-apps/core-concepts/manifest.mdx | 2 +- docs/mini-apps/growth/optimize-onboarding.mdx | 2 +- docs/mini-apps/quickstart/build-checklist.mdx | 2 +- .../technical-guides/embeds-and-previews.mdx | 2 +- .../{search-discovery.mdx => how-search-works.mdx} | 2 +- 6 files changed, 11 insertions(+), 11 deletions(-) rename docs/mini-apps/troubleshooting/{search-discovery.mdx => how-search-works.mdx} (99%) diff --git a/docs/docs.json b/docs/docs.json index 7f922295..8faafdac 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -483,7 +483,7 @@ "pages": [ "mini-apps/troubleshooting/common-issues", "mini-apps/troubleshooting/base-app-compatibility", - "mini-apps/troubleshooting/search-discovery" + "mini-apps/troubleshooting/how-search-works" ] }, { @@ -1508,7 +1508,7 @@ "redirects": [ { "source": "/mini-apps/technical-guides/search-discovery", - "destination": "/mini-apps/troubleshooting/search-discovery" + "destination": "/mini-apps/troubleshooting/how-search-works" }, { "source": "/mini-apps/overview", @@ -1536,11 +1536,11 @@ }, { "source": "/mini-apps/features/search-and-discovery", - "destination": "/mini-apps/troubleshooting/search-discovery" + "destination": "/mini-apps/troubleshooting/how-search-works" }, { "source": "/mini-apps/technical-guides/search-and-discovery", - "destination": "/mini-apps/troubleshooting/search-discovery" + "destination": "/mini-apps/troubleshooting/how-search-works" }, { "source": "/mini-apps/features/sharing-and-social-graph", @@ -2712,11 +2712,11 @@ }, { "source": "/base-app/miniapps/search-and-discovery", - "destination": "/mini-apps/troubleshooting/search-discovery" + "destination": "/mini-apps/troubleshooting/how-search-works" }, { "source": "/base-app/build-with-minikit/search-and-discovery", - "destination": "/mini-apps/troubleshooting/search-discovery" + "destination": "/mini-apps/troubleshooting/how-search-works" }, { "source": "/base-app/miniapps/sharing-your-miniapp", diff --git a/docs/mini-apps/core-concepts/manifest.mdx b/docs/mini-apps/core-concepts/manifest.mdx index d7ef18b2..11fa7892 100644 --- a/docs/mini-apps/core-concepts/manifest.mdx +++ b/docs/mini-apps/core-concepts/manifest.mdx @@ -205,7 +205,7 @@ Open Graph image. 1200×630px (1.91:1), PNG/JPG. ## Related Concepts - + Learn how your manifest powers search indexing and category placement in the Base app discovery features. diff --git a/docs/mini-apps/growth/optimize-onboarding.mdx b/docs/mini-apps/growth/optimize-onboarding.mdx index 1529ea53..90247403 100644 --- a/docs/mini-apps/growth/optimize-onboarding.mdx +++ b/docs/mini-apps/growth/optimize-onboarding.mdx @@ -32,7 +32,7 @@ Deliver value instantly and avoid blocking actions. - After success, prompt social actions via [SDK actions](/mini-apps/features/links) and [Sharing & Social Graph](/mini-apps/features/sharing-and-social-graph) -- Offer next step: save, follow, or share — optimize with [Search & Discovery](/mini-apps/troubleshooting/search-discovery) +- Offer next step: save, follow, or share — optimize with [Search & Discovery](/mini-apps/troubleshooting/how-search-works) diff --git a/docs/mini-apps/quickstart/build-checklist.mdx b/docs/mini-apps/quickstart/build-checklist.mdx index b4848b02..fd227586 100644 --- a/docs/mini-apps/quickstart/build-checklist.mdx +++ b/docs/mini-apps/quickstart/build-checklist.mdx @@ -33,7 +33,7 @@ Distribution starts in the feed: compelling previews with a clear image and laun Be found across surfaces: set a primary category, share once to trigger indexing, and keep assets valid to appear in search and categories. - + ## Sharing & Social Graph diff --git a/docs/mini-apps/technical-guides/embeds-and-previews.mdx b/docs/mini-apps/technical-guides/embeds-and-previews.mdx index f2350fcd..8c7a363b 100644 --- a/docs/mini-apps/technical-guides/embeds-and-previews.mdx +++ b/docs/mini-apps/technical-guides/embeds-and-previews.mdx @@ -265,7 +265,7 @@ Set `Cache-Control` carefully: long enough for performance (300–600s), short e Continue with: -- [Search and Discovery](/mini-apps/troubleshooting/search-discovery) +- [Search and Discovery](/mini-apps/troubleshooting/how-search-works) - [Manifest](/mini-apps/core-concepts/manifest) diff --git a/docs/mini-apps/troubleshooting/search-discovery.mdx b/docs/mini-apps/troubleshooting/how-search-works.mdx similarity index 99% rename from docs/mini-apps/troubleshooting/search-discovery.mdx rename to docs/mini-apps/troubleshooting/how-search-works.mdx index 26e8834f..f4857829 100644 --- a/docs/mini-apps/troubleshooting/search-discovery.mdx +++ b/docs/mini-apps/troubleshooting/how-search-works.mdx @@ -1,5 +1,5 @@ --- -title: Search & Discovery +title: How Search works description: If your Mini App isn't appearing in The Base app, this guide explains how indexing and search work so you can identify and fix the issue. --- Indexing is how The Base app adds your Mini App to its catalog, making it discoverable through search and browsing. From 38c519c8eeaaf229a44da372626b488ff7062aff Mon Sep 17 00:00:00 2001 From: sohey Date: Sat, 18 Oct 2025 22:49:38 +0200 Subject: [PATCH 12/14] removed search discover debugging from manifest --- docs/mini-apps/core-concepts/manifest.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/mini-apps/core-concepts/manifest.mdx b/docs/mini-apps/core-concepts/manifest.mdx index 11fa7892..83757957 100644 --- a/docs/mini-apps/core-concepts/manifest.mdx +++ b/docs/mini-apps/core-concepts/manifest.mdx @@ -204,11 +204,7 @@ Open Graph image. 1200×630px (1.91:1), PNG/JPG. ## Related Concepts - - - Learn how your manifest powers search indexing and category placement in the Base app discovery features. - - + Understand how your manifest creates rich embeds when your Mini App is shared in feeds and social platforms. From 9819ec17b5a5355f2b256f5b2f1da4b4f96696a8 Mon Sep 17 00:00:00 2001 From: sohey Date: Sat, 18 Oct 2025 22:51:07 +0200 Subject: [PATCH 13/14] fixed typo --- docs/mini-apps/troubleshooting/how-search-works.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mini-apps/troubleshooting/how-search-works.mdx b/docs/mini-apps/troubleshooting/how-search-works.mdx index f4857829..04516c24 100644 --- a/docs/mini-apps/troubleshooting/how-search-works.mdx +++ b/docs/mini-apps/troubleshooting/how-search-works.mdx @@ -1,6 +1,6 @@ --- title: How Search works -description: If your Mini App isn't appearing in The Base app, this guide explains how indexing and search work so you can identify and fix the issue. +description: If your Mini App isn't appearing in the Base app, this guide explains how indexing and search work so you can identify and fix the issue. --- Indexing is how The Base app adds your Mini App to its catalog, making it discoverable through search and browsing. Unlike traditional app stores with manual submission, you control when indexing happens. Share your Mini App URL to the social feed, and indexing starts automatically—no review process required. From f71630b55cdedb6ef6c3e3275bdee58092015abb Mon Sep 17 00:00:00 2001 From: sohey Date: Tue, 21 Oct 2025 12:15:47 +0200 Subject: [PATCH 14/14] added rules for base app spelling --- .cursor/rules/content-guide.mdc | 14 ++++++++++++++ docs/docs.json | 4 ---- .../mini-apps/troubleshooting/how-search-works.mdx | 2 +- 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/.cursor/rules/content-guide.mdc b/.cursor/rules/content-guide.mdc index 4bbf57f7..ea26e45b 100644 --- a/.cursor/rules/content-guide.mdc +++ b/.cursor/rules/content-guide.mdc @@ -96,3 +96,17 @@ description: "Concise description explaining page purpose and value" - Use **RequestExample/ResponseExample** specifically for API endpoint documentation - Use **ParamField** for API parameters, **ResponseField** for API responses - Use **Expandable** for nested object properties or hierarchical information + +## Base App Spelling Rules + +- Always write as **"the Base app"** with lowercase "app" in mid-sentence usage +- Write as **"The Base App"** with both words capitalized only at the start of sentences +- Never use **"Base App"** as a standalone term without the article "the" or "The" +- The word "App" is capitalized only when "The" is also capitalized (sentence-initial position) + +## Find and Replace Pattern + +- Find **"Base App"** without preceding article → Replace with **"the Base app"** +- Find **"the Base App"** in mid-sentence → Replace with **"the Base app"** +- Find **"The Base app"** at sentence start → Replace with **"The Base App"** +- Find **"the Base app"** after periods, colons, or sentence-ending punctuation → Replace with **"The Base App"** \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index 0875bf97..53cf2d12 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1525,10 +1525,6 @@ "source": "/mini-apps/features/search-and-discovery", "destination": "/mini-apps/troubleshooting/how-search-works" }, - { - "source": "/mini-apps/technical-guides/search-and-discovery", - "destination": "/mini-apps/troubleshooting/how-search-works" - }, { "source": "/mini-apps/features/sharing-and-social-graph", "destination": "/mini-apps/technical-guides/sharing-and-social-graph" diff --git a/docs/mini-apps/troubleshooting/how-search-works.mdx b/docs/mini-apps/troubleshooting/how-search-works.mdx index 04516c24..3204c3a2 100644 --- a/docs/mini-apps/troubleshooting/how-search-works.mdx +++ b/docs/mini-apps/troubleshooting/how-search-works.mdx @@ -30,7 +30,7 @@ Your manifest must be properly configured and validated for indexing to work. Se ## How search works -The Base app's search queries your Mini App's `name` field from the catalog. Both exact and partial matches appear in results. Search displays your Mini App based on information you provided in your manifest. +The Base App's search queries your Mini App's `name` field from the catalog. Both exact and partial matches appear in results. Search displays your Mini App based on information you provided in your manifest. search bar in the Base app