Mini App Context

Improve user experience by instantly displaying user profile data and customizing user flows based on where your mini app was opened

When your app is opened as a mini app, sdk.context provides 4 data objects:

• user: User profile data
• location: Where the mini app was opened
• client: Host platform (e.g. the Base app or another Farcaster client) and device data
• features: Availability and state of features in the current client

Implementation

1. Install and import @farcaster/miniapp-sdk
2. Check if opened as a mini app using sdk.isInMiniApp();
3. If in a mini app, load the context object using sdk.context

In the example below we detect if the app was opened as a mini app, and if so, we return the user’s username, fid, display name, and profile image.

app/profile/page.tsx

"use client";
import { sdk } from "@farcaster/miniapp-sdk";
import { useEffect, useState } from "react";

export default function Profile() {
  const [user, setUser] = useState(null);
  const [isInMiniApp, setIsInMiniApp] = useState(false); 

  useEffect(() => {
    const loadUserData = async () => {
      try {
        // Check if we're in a Mini App
        const miniAppStatus = await sdk.isInMiniApp();
        setIsInMiniApp(miniAppStatus);

        if (miniAppStatus) {
          // Get context and extract user info
          const context = await sdk.context;
          setUser(context.user);
        }
      } catch (error) {
        console.error("Error loading user data:", error);
      }
    };

    loadUserData();
  }, []);

  // Show message if not in Mini App
  if (!isInMiniApp) {
    return (
      <div>
        <p>Please open this app in a Farcaster or Base client to see your profile.</p>
      </div>
    );
  }

  // Show user information
  if (user) {
    return (
      <div>
        <h2>Welcome, {user.displayName || user.username}!</h2>
        <p>FID: {user.fid}</p>
        <p>Username: @{user.username}</p>
        {user.pfpUrl && (
          <img 
            src={user.pfpUrl} 
            alt="Profile" 
            width={64} 
            height={64} 
            style={{ borderRadius: '50%' }}
          />
        )}
      </div>
    );
  }

  return <div>Loading user profile...</div>;
}

Schema

User Object

Contains the user’s profile information. This data shouldn’t be used for authentication or sensitive actions because its passed by the application.

fid · number · required

Unique Farcaster identifier for the user.

username · string

Handle without @ symbol.

displayName · string

User’s chosen display name.

pfpUrl · string

Profile picture URL.

bio · string

User’s biography text.

location · object

User’s location information.

location.placeId · string

Google Places ID.

location.description · string

Human-readable location description.

user.json

{
  "fid": 6841,
  "username": "deodad",
  "displayName": "Tony D'Addeo",
  "pfpUrl": "https://i.imgur.com/dMoIan7.jpg",
  "bio": "Building @warpcast and @farcaster",
  "location": {
    "placeId": "ChIJLwPMoJm1RIYRetVp1EtGm10",
    "description": "Austin, TX, USA"
  }
}

Location Object

Contains information about the context from which the Mini App was launched. This helps you understand how users discovered and accessed your app.

Location Types:

• cast_embed: Launched from a cast where your app is embedded
• cast_share: Launched when a user shared a cast to your app
• notification: Launched from a notification triggered by your app
• launcher: Launched directly from the client app catalog
• channel: Launched from within a specific Farcaster channel
• open_miniapp: Launched from another Mini App

CastEmbedLocationContext

type · 'cast_embed' · required

Indicates the Mini App was launched from a cast where it is an embed.

embed · string · required

The embed URL.

cast · MiniAppCast · required

Cast information containing the embed.

cast_embed.json

{
  "type": "cast_embed",
  "embed": "https://myapp.example.com",
  "cast": {
    "author": {
      "fid": 3621,
      "username": "alice",
      "displayName": "Alice",
      "pfpUrl": "https://example.com/alice.jpg"
    },
    "hash": "0xa2fbef8c8e4d00d8f84ff45f9763b8bae2c5c544",
    "timestamp": 1749160866000,
    "text": "Check out this awesome mini app!",
    "embeds": ["https://myapp.example.com"],
    "channelKey": "farcaster"
  }
}

CastShareLocationContext

type · 'cast_share' · required

Indicates the Mini App was launched when a user shared a cast to your app.

cast · MiniAppCast · required

The cast that was shared to your app.

NotificationLocationContext

type · 'notification' · required

Indicates the Mini App was launched from a notification.

notification · object · required

Notification details.

notification.notificationId · string · required

Unique notification identifier.

notification.title · string · required

Notification title.

notification.body · string · required

Notification body text.

notification.json

{
  "type": "notification",
  "notification": {
    "notificationId": "f7e9ebaf-92f0-43b9-a410-ad8c24f3333b",
    "title": "Yoinked!",
    "body": "horsefacts captured the flag from you."
  }
}

LauncherLocationContext

type · 'launcher' · required

Indicates the Mini App was launched directly by the client app outside of a context.

ChannelLocationContext

type · 'channel' · required

Indicates the Mini App was launched from within a specific Farcaster channel.

channel · object · required

Channel details.

channel.key · string · required

Channel key identifier.

channel.name · string · required

Channel name.

channel.imageUrl · string

Channel profile image URL.

OpenMiniAppLocationContext

type · 'open_miniapp' · required

Indicates the Mini App was launched from another Mini App.

referrerDomain · string · required

The domain of the Mini App that opened the current app.

Client Object

Contains details about the Farcaster client running your Mini App. This data should be considered untrusted.

ClientContext

platformType · 'web' | 'mobile'

Platform where the app is running.

clientFid · number · required

Self-reported FID of the client (e.g., 9152 for Farcaster).

added · boolean · required

Whether the user has added your Mini App to their client.

safeAreaInsets · object

Screen insets to avoid navigation elements that obscure the view.

Show properties

top · number · required

Top safe area inset in pixels.

bottom · number · required

Bottom safe area inset in pixels.

left · number · required

Left safe area inset in pixels.

right · number · required

Right safe area inset in pixels.

notificationDetails · object

Notification configuration if enabled.

Show properties

url · string · required

Endpoint for sending notifications.

token · string · required

Authentication token for notifications.

client.json

{
  "platformType": "mobile",
  "clientFid": 9152,
  "added": true,
  "safeAreaInsets": {
    "top": 0,
    "bottom": 20,
    "left": 0,
    "right": 0
  },
  "notificationDetails": {
    "url": "https://api.farcaster.xyz/v1/frame-notifications",
    "token": "a05059ef2415c67b08ecceb539201cbc6"
  }
}

Features Object

Indicates which platform features are available and their current state in the client.

haptics · boolean · required

Whether haptic feedback is supported on the current platform.

cameraAndMicrophoneAccess · boolean

Whether camera and microphone permissions have been granted and stored for this mini app.

features.json

{
  "haptics": true,
  "cameraAndMicrophoneAccess": true
}

For more detailed capability detection, use the sdk.getCapabilities() method which returns specific SDK methods supported by the host.