> ## Documentation Index
> Fetch the complete documentation index at: https://base-a060aa97-eb-mini-app-ia-overhaul.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sharing Your Mini App

> Turn every user action into organic growth with shareable, metadata-powered embeds that drive engagement and discovery.

> **What you'll learn**\
> By the end of this guide, you'll be able to:
>
> * Understand how embeds and metadata work together to create rich social previews
> * Choose between static and dynamic embeds for different use cases
> * Debug and optimize embeds for maximum performance and engagement

## Why Sharing Matters

Sharing is one of the fastest and most cost-effective ways to grow your Mini App user base.

When a user shares your app into a feed (such as Base App or Farcaster), the platform generates a **rich embed** — a visual preview complete with your branding, imagery, and call-to-action button that appears directly in social feeds.

Every share:

* **Increases reach** — friends and followers see your app instantly
* **Drives engagement** — visually compelling embeds get more clicks than plain links
* **Improves ranking** — shared apps are more likely to appear in "Trending" and category leaderboards
* **Creates viral loops** — great experiences encourage users to share with their networks

## Metadata and Embeds

Understanding how metadata creates embeds is fundamental to implementing effective sharing for your Mini App.

### How Metadata Creates Embeds

When someone shares your Mini App link, platforms like Base App don't just show a plain URL. Instead, they fetch **metadata** from your page and use it to generate a rich **embed** — a visual preview card with your image, title, and call-to-action button.

The metadata acts as instructions that tell the platform exactly how to display your Mini App in feeds.

<Frame caption="How metadata transforms into embeds">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/base-a060aa97-eb-mini-app-ia-overhaul/images/minikit/Diagram.png" alt="How embed data is rendered" />
</Frame>

**The complete metadata-to-embed process:**

<Steps>
  <Step title="User shares your link">
    User clicks share or pastes your Mini App URL into a social feed (Base App, Farcaster).
  </Step>

  <Step title="Platform fetches metadata">
    The platform makes a request to your URL and reads the `<meta>` tags in your HTML to understand how to display your app.
  </Step>

  <Step title="Metadata becomes embed">
    Platform transforms your metadata into a rich visual embed with image, title, description, and interactive button.
  </Step>

  <Step title="Embed appears in feed">
    Your Mini App appears as an attractive, clickable card that users can launch directly from their feed.
  </Step>
</Steps>

### Metadata Structure

Your metadata consists of specific HTML meta tags that define each part of the embed:

```html
<meta name="fc:frame" content='{
  "version":"next",
  "imageUrl":"https://your-app.com/embed-image",
  "button":{
    "title":"Play Now",
    "action":{
      "type":"launch_frame",
      "name":"Your App Name",
      "url":"https://your-app.com"
    }
  }
}' />
```

Each piece of metadata directly corresponds to a visual element in the embed:

* **`imageUrl`** → The main visual that appears in the embed
* **`button.title`** → Text on the call-to-action button
* **`action.name`** → App name displayed in the embed
* **`action.url`** → Where users go when they click the embed

### Embed Appearance in Feeds

Here's how your metadata appears as a rich embed in social feeds:

<Frame caption="Mini App embed in social feed">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/base-a060aa97-eb-mini-app-ia-overhaul/images/minikit/feed_mini.jpg" alt="Mini app feed" className="h-[220px] w-auto" />
</Frame>

### Manifest vs Embed Metadata

Your Mini App uses two types of metadata:

#### Manifest file

**Purpose:** App registration and discovery

Located at `/.well-known/farcaster.json`, this file contains your app's basic information for Base App's directory.

```json
{
  "name": "Your App Name",
  "description": "App description",
  "iconUrl": "https://your-app.com/icon.png",
  "url": "https://your-app.com"
}
```

<Warning>
  Mini Apps require a complete manifest. Read the [manifest requirements](/base-app/miniapps/how-manifest-work#example-manifest).
</Warning>

#### Embed metadata

**Purpose:** Embed generation when shared

Located in your HTML `<head>` tags, this metadata creates the rich embeds when users share your app.

```html
<meta name="fc:frame" content='{
  "version":"next",
  "imageUrl":"https://your-app.com/embed-image",
  "button":{
    "title":"Play Now",
    "action":{
      "type":"launch_frame",
      "name":"Your App Name",
      "url":"https://your-app.com"
    }
  }
}' />
```

This controls how your embeds appear in social feeds.

### Best Practices for Metadata

* **Image optimization:** Use 3:2 aspect ratio for optimal display across platforms
* **Clear value proposition:** Make your button text and description immediately compelling
* **Visual consistency:** Ensure your embed image reflects your app's actual interface
* **Fast loading:** Optimize images and ensure metadata endpoints respond quickly
* **Test thoroughly:** Validate embeds across different platforms before launch

## Sharing

### Adding Share Functionality

Prompt users to share during key accomplishment moments in your app using composeCast from the MiniKit SDK

<Frame caption="CTA for a user to share the Mini App">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/base-a060aa97-eb-mini-app-ia-overhaul/images/minikit/share_cta.jpeg" alt="Share button in a Mini App" className="h-[320px] w-auto" />
</Frame>

```ts
import { useComposeCast } from '@coinbase/onchainkit/minikit';

export default function ComposeCastButton() {
  const { composeCast } = useComposeCast();

  const handleCompose = () => {
    composeCast({
      text: 'Just minted an awesome NFT using @coinbase OnchainKit! ',
    });
  };

// 
  const handleComposeWithEmbed = () => {
    composeCast({
      text: 'Check out this amazing Mini App!',
      embeds: ['https://your-mini-app-url.com'],
    });
  };

  return (
    <div>
      <button onClick={handleCompose}>Share Achievement</button>
      <button onClick={handleComposeWithEmbed}>Share Frame</button>
    </div>
  );
}
```

<Tip>
  **Strategic sharing moments:**

  * After completing a quiz ("I'm Blossom!")
  * After minting an NFT ("Just minted my first collectible!")
  * After completing a challenge ("Finished today's puzzle in 2 minutes!")
  * After reaching a milestone ("Hit level 10!")
</Tip>

### From the Base App UI

Users can also share directly from your app's detail view in the Base app through the built-in share functionality.

<Frame caption="Share button in the Base app UI">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/base-a060aa97-eb-mini-app-ia-overhaul/images/minikit/share-button-ui.jpg" alt="Share button in Base app" className="h-[220px] w-auto" />
</Frame>

## Embed Types

### Choosing Between Static and Dynamic Embeds

#### Static embeds

<Frame caption="Static embed example - every user shares the same embed">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/base-a060aa97-eb-mini-app-ia-overhaul/images/minikit/static_embed.jpeg" alt="Static OG embed" className="h-[220px] w-auto" />
</Frame>

**Use case:** Simple, consistent branding across all shares

A single, unchanging image and text for all shares of your Mini App.

**Pros:**

* Easy to set up and maintain
* Consistent branding across all shares
* Fast loading with no server processing

**Cons:**

* Less personalized user experience
* No real-time data reflection

**Best for:** Brand awareness campaigns, simple apps without user-specific content

#### Dynamic embeds

<Frame caption="Dynamic embed example based user outcome">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/base-a060aa97-eb-mini-app-ia-overhaul/images/minikit/dynamic_embed.jpeg" alt="Dynamic OG embed" className="h-[220px] w-auto" />
</Frame>

**Use case:** Live, user-specific, or time-sensitive data

Metadata is generated in real-time when a share happens, perfect for displaying current user stats or live information.

**Example:** Trading dashboard showing user's current portfolio:

```
/user/portfolio/123
```

Your backend fetches the latest stats and generates an OG image dynamically.

**Benefits:**

* Highly personalized experience
* Reflects real-time data
* Drives re-shares when state changes
* Creates FOMO and urgency

**Best for:** Trading apps, social stats, live leaderboards, time-sensitive content

<Warning>
  Real-time generation can be slower — ensure your endpoint responds within 3–5 seconds to avoid timeouts.
</Warning>

### Dynamic Metadata Request Flow

<Steps>
  <Step title="User initiates share">
    User shares your Mini App link containing dynamic parameters (e.g., `/result/user/123`).
  </Step>

  <Step title="Platform requests metadata">
    The social platform makes a server request to fetch your page's metadata.
  </Step>

  <Step title="Server processes parameters">
    Your route handler extracts parameters and fetches relevant data (user stats, quiz results, etc.).
  </Step>

  <Step title="Generate metadata">
    Server generates customized OG metadata including personalized image and text content.
  </Step>

  <Step title="Embed renders">
    Platform receives the metadata and renders the personalized embed in the user's feed.
  </Step>
</Steps>

<Tip>
  Use [Vercel OG Image Generation](https://vercel.com/docs/functions/og-image-generation) for fast, serverless image rendering that scales automatically.
</Tip>

## Implementation

### How MiniKit works with Embeds

If you're building with MiniKit, metadata setup is handled automatically in your `layout.tsx` or `layout.ts` file:

```ts layout.tsx
export async function generateMetadata(): Promise<Metadata> {
  const URL = process.env.NEXT_PUBLIC_URL;
  
  return {
    title: process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME,
    description: "Your Mini App description here",
    other: {
      "fc:frame": JSON.stringify({
        version: "next",
        imageUrl: process.env.NEXT_PUBLIC_APP_HERO_IMAGE,
        button: {
          title: `Launch ${process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME}`,
          action: {
            type: "launch_frame",
            name: process.env.NEXT_PUBLIC_ONCHAINKIT_PROJECT_NAME,
            url: URL,
            splashImageUrl: process.env.NEXT_PUBLIC_SPLASH_IMAGE,
            splashBackgroundColor: process.env.NEXT_PUBLIC_SPLASH_BACKGROUND_COLOR,
          },
        },
      }),
    },
  };
}
```

**Customizing for different pages:**

You can create page-specific metadata by implementing `generateMetadata` in individual page components:

```ts page.tsx
// Dynamic metadata for user-specific results using minikit
export async function generateMetadata({ params }: { params: { userId: string } }): Promise<Metadata> {
  const userData = await fetchUserData(params.userId);
  
  return {
    title: `${userData.name}'s Quiz Result`,
    other: {
      "fc:frame": JSON.stringify({
        version: "next",
        imageUrl: `https://your-app.com/api/og/user/${params.userId}`,
        button: {
          title: "Take the Quiz",
          action: {
            type: "launch_frame",
            name: "Personality Quiz",
            url: process.env.NEXT_PUBLIC_URL,
          },
        },
      }),
    },
  };
}
```

if not using minikit

```html
<meta name="fc:frame" content='{
  "version":"next",
  "imageUrl":"https://your-app.com/embed-image",
  "button":{
    "title":"Play Now",
    "action":{
      "type":"launch_frame",
      "name":"Your App Name",
      "url":"https://your-app.com"
    }
  }
}' />
```

## Debugging

### Debugging Tools

Use these tools to test and validate your embeds before going live:

<CardGroup cols={1}>
  <Card title="Farcaster Embed Debugger" icon="bug" href="https://farcaster.xyz/~/developers/mini-apps/debug">
    Test your Mini App metadata and preview how embeds will appear in Base App feeds.
  </Card>
</CardGroup>

### Common Issues and Solutions

<AccordionGroup>
  <Accordion title="Embed not showing or displaying incorrectly">
    **Possible causes:**

    * Incorrect image dimensions (should be 3:2 aspect ratio)
    * Missing required `fc:frame` meta tags
    * Invalid JSON in frame metadata
    * Image URL not accessible or returning errors

    **Solutions:**

    * Verify image dimensions and accessibility
    * Validate JSON structure in metadata
    * Test metadata with debugging tools
  </Accordion>

  <Accordion title="Embeds not updating after changes">
    **Possible causes:**

    * Aggressive cache headers preventing updates
    * Make sure to repost the mini app to update any metadata

    **Solutions:**

    * Set appropriate `Cache-Control` headers (max-age=300 for dynamic content)
    * Use cache-busting parameters in image URLs
    * Wait 10-15 minutes for platform caches to refresh
  </Accordion>

  <Accordion title="Slow embed generation affecting user experience">
    **Possible causes:**

    * Heavy server processing for dynamic images
    * Database queries blocking metadata generation
    * Large image file sizes

    **Solutions:**

    * Optimize image generation process
    * Pre-generate common embed variations
    * Use serverless functions for scaling
    * Compress images without quality loss
  </Accordion>
</AccordionGroup>

<Info>
  Check out our debugging section that covers embed issues [here](/base-app/miniapps/debugging)
</Info>

<Warning>
  Set `Cache-Control` headers carefully: long enough for performance (300-600 seconds), short enough to allow metadata updates to appear quickly.
</Warning>

## Next Steps

Ready to implement sharing in your Mini App? Follow this implementation checklist:

<Steps>
  <Step title="Choose your embed strategy">
    Decide between static, predetermined dynamic, or real-time dynamic embeds based on your app's functionality and user experience goals.
  </Step>

  <Step title="Implement metadata generation">
    Add `fc:frame` metadata to your.
  </Step>

  <Step title="Add strategic share points">
    Integrate sharing prompts into key moments: achievements, completions, milestones, and other celebration-worthy events.
  </Step>

  <Step title="Test and optimize">
    Use debugging tools to validate your embeds, test across platforms, and optimize for performance before launching.
  </Step>
</Steps>

Continue building your Mini App with these resources:

* [Search and Discovery](/base-app/miniapps/search-and-discovery): Learn how users find your Mini App
* [MiniKit Overview](/base-app/miniapps/overview): Complete MiniKit integration guide