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 CaseBenefit
Personalized UXCustomize interface based on user identity and entry point
Viral OptimizationTrack and optimize discovery paths for growth
Platform AdaptationAdjust functionality for different host platforms
Social EngagementLeverage 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/..."
  }
}

​
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
    }
  }
}

​
Location Object

Describes how the user discovered your mini app - critical for viral optimization: 
{
  "location": {
    "type": "launcher"
  }
}
User Journey: Returning user opening from saved apps
Strategy: Focus on retention and progression features

​
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 } = 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: context.location.cast.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

MetricContext SourceOptimization Goal
Cast Embed Launcheslocation.type === 'cast_embed'Maximize viral sharing
Return User Ratelocation.type === 'launcher'Improve retention
Share Attributioncast.author dataIdentify top advocates
Platform Performanceclient.platformTypeOptimize 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