Understanding Mini App Context

Leverage context data to build social-first mini applications that adapt to user entry points and drive viral growth

Context is the environmental data that is automatically provided to your mini app which describes how, where, and by whom your mini app was launched. This guide shows you how to leverage context to create personalized experiences and optimize viral growth.

What is Context?

Context provides three essential data objects that shape your user experience:

User Information

Profile data of the person using your app

Client Details

Information about the host platform and device

Location Context

How the user discovered and launched your app

Context is only available within a Farcaster client such as the Base App, not on the web. If your mini app is accessed via a standard web browser, context data will not be provided. Design your app to gracefully handle the absence of context when running outside the Base App environment.

Why Context Matters

Context enables you to create mini apps that feel native to their social environment and optimize for viral growth:

Use Case	Benefit
Personalized UX	Customize interface based on user identity and entry point
Viral Optimization	Track and optimize discovery paths for growth
Platform Adaptation	Adjust functionality for different host platforms
Social Engagement	Leverage social context for community features

Core Context Structure

User Object

Contains profile information about the person using your mini app:

User Object Structure

{
  "user": {
    "fid": 20390,
    "username": "sohey", 
    "displayName": "Soheybuildson.base",
    "pfpUrl": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/..."
  }
}

User Object Properties

• fid: Unique Farcaster identifier for the user
• username: Handle without @ symbol
• displayName: User’s chosen display name
• pfpUrl: Profile picture URL

Client Object

Information about the host platform and device:

Client Object Structure

{
  "client": {
    "clientFid": 309857,        // Base app identifier
    "added": false,             // App save status
    "platformType": "mobile",   // Device type
    "safeAreaInsets": {
      "top": 0,
      "bottom": 34,
      "left": 0, 
      "right": 0
    }
  }
}

Client Object Properties

• clientFid: Identifies the host app (309857 = Base app)
• added: Whether user has saved your mini app
• platformType: Device type for responsive design
• safeAreaInsets: Safe zones to avoid system UI overlap

Location Object

Describes how the user discovered your mini app - critical for viral optimization:

Launcher Entry

{
  "location": {
    "type": "launcher"
  }
}

User Journey: Returning user opening from saved apps
Strategy: Focus on retention and progression features

Messaging Entry

{
  "location": {
    "type": "messaging"
  }
}

User Journey: Discovery through private messages
Strategy: Encourage broader social sharing

Cast Embed Entry

{
  "location": {
    "type": "cast_embed",
    "embed": "https://frames-v2-demo-lilac.vercel.app/",
    "cast": {
      "author": {
        "fid": 20390,
        "username": "sohey",
        "displayName": "Soheybuildson.base", 
        "pfpUrl": "https://imagedelivery.net/..."
      },
      "fid": 20390,
      "hash": "0x96178d931158cebbdad1b647b6549f0bb05709ed",
      "timestamp": 1755781905000,
      "text": "Check out this mini app!",
      "embeds": ["https://frames-v2-demo-lilac.vercel.app/"]
    }
  }
}

User Journey: Primary viral discovery through social feeds
Strategy: Optimize first-time experience and immediate engagement

Implementation Guide

1. Access Context Data

   Import and use the useMiniKit() hook to access context:

   'use client';
   import { useMiniKit, useIsInMiniApp } from '@coinbase/onchainkit/minikit';
   import { useEffect } from 'react';
   
   function MyMiniApp() {
     const { context, isFrameReady, setFrameReady } = useMiniKit();
   
     const { isInMiniApp } = useIsInMiniApp();
     
     useEffect(() => {
       if (!isFrameReady) {
         setFrameReady();
       }
     }, [setFrameReady, isFrameReady]);
     
     // Always check for context availability
     if (isInMiniApp && !context) {
       return <div>Loading...</div>;
     }
     
     // Access context data
     const user = context.user;
     const client = context.client;
     const location = context.location;
     
     return <AppContent />;
   }
   

   Always check for context availability before accessing its properties to avoid runtime errors.

2. Create Context-Driven Experiences

   Design different experiences based on entry point:

   'use client';
   import { useMiniKit } from '@coinbase/onchainkit/minikit';
   import { useEffect } from 'react';
   
   function ContextAwareApp() {
     const { context, isFrameReady, setFrameReady } = useMiniKit();
     
     useEffect(() => {
       if (!isFrameReady) {
         setFrameReady();
       }
     }, [setFrameReady, isFrameReady]);
     
     if (!context) return <div>Loading...</div>;
     
     switch (context.location?.type) {
       case 'cast_embed':
         return <ViralOnboarding castAuthor={context.location.cast.author} />;
       case 'launcher': 
         return <ReturningUserDashboard />;
       case 'messaging':
         return <PrivateShareExperience />;
       default:
         return <DefaultExperience />;
     }
   }
   

   This approach ensures users get personalized experiences based on how they discovered your app.

3. Implement Safe Area Support

   Ensure your UI doesn’t overlap with system elements:

   'use client';
   import { useMiniKit } from '@coinbase/onchainkit/minikit';
   
   function ResponsiveLayout({ children }) {
     const { context } = useMiniKit();
     const insets = context?.client?.safeAreaInsets;
     
     return (
       <div 
         className="app-container"
         style={{
           paddingTop: insets?.top || 0,
           paddingBottom: insets?.bottom || 0,
           paddingLeft: insets?.left || 0,
           paddingRight: insets?.right || 0,
         }}
       >
         {children}
       </div>
     );
   }
   

   Safe area implementation is crucial for mobile experiences to avoid system UI overlap.

4. Add Social Features

   Leverage cast embed data for social engagement:

   import { useComposeCast, useViewProfile } from '@coinbase/onchainkit/minikit';
   
   function SocialAcknowledgment() {
     const { context } = useMiniKit();
     const { composeCast } = useComposeCast();
     const viewProfile = useViewProfile();
     
     if (context?.location?.type !== 'cast_embed') {
       return null;
     }
     
     const { author, text, timestamp,hash } = context.location.cast;
     
     const handleThankSharer = () => {
       composeCast({
         text: `Thanks @${author.username} for sharing this awesome mini app! 🙏`,
         // Optionally include the original cast as parent
         parent: {
           type: 'cast',
           hash: hash
         }
       });
     };
     
     const handleViewProfile = () => {
       viewProfile(author.fid);
     };
     
     return (
       <div className="social-credit">
         <img src={author.pfpUrl} alt={author.displayName} />
         <div>
           <p><strong>@{author.username}</strong> shared this app</p>
           <p>"{text}"</p>
           <div className="action-buttons">
             <button onClick={handleThankSharer}>
               Thank them! 🙏
             </button>
             <button onClick={handleViewProfile}>
               View Profile
             </button>
           </div>
         </div>
       </div>
     );
   }
   

Analytics and Growth Tracking

Leverage Base.dev provides comprehensive analytics out-of-the-box including user engagement metrics, entry point analysis, and session tracking. Import your mini app to Base.dev to access real-time analytics that complement your context-driven insights.

Viral Attribution

Track how users discover your app to optimize growth:

Analytics Implementation

function trackDiscovery() {
  const { context } = useMiniKit();
  
  const discoveryData = {
    type: context?.location?.type,
    platform: context?.client?.platformType,
    userAdded: context?.client?.added,
  };
  
  if (context?.location?.type === 'cast_embed') {
    discoveryData.sharedBy = context.location.cast.author.username;
    discoveryData.castHash = context.location.cast.hash;
  }
  
  analytics.track('mini_app_launch', discoveryData);
}

Growth Metrics to Monitor

Metric	Context Source	Optimization Goal
Cast Embed Launches	location.type === 'cast_embed'	Maximize viral sharing
Return User Rate	location.type === 'launcher'	Improve retention
Share Attribution	cast.author data	Identify top advocates
Platform Performance	client.platformType	Optimize for mobile/desktop

Next Steps

Understanding and leveraging context is foundational to creating mini apps that feel native to their social environment and drive sustainable viral growth.

Implement Context Access

Add useMiniKit() to your main component and validate context data

Create Entry Point Flows

Design different experiences for each location type

Add Safe Area Support

Implement responsive padding for mobile experiences

Track Viral Metrics

Set up analytics for growth measurement and optimization