Context

When your app is opened it can access information about the session from sdk.context. This object provides basic information about the user, the client, and where your app was opened from:

export type FrameContext = {
  user: {
    fid: number;
    username?: string;
    displayName?: string;
    pfpUrl?: string;
  };
  location?: FrameLocationContext;
  client: {
    clientFid: number;
    added: boolean;
    safeAreaInsets?: SafeAreaInsets;
    notificationDetails?: FrameNotificationDetails;
  };
};

Properties

`location`

Contains information about the context from which the Mini App was launched.

export type CastEmbedLocationContext = {
  type: 'cast_embed';
  embed: string;
  cast: {
    fid: number;
    hash: string;
  };
};
 
export type NotificationLocationContext = {
  type: 'notification';
  notification: {
    notificationId: string;
    title: string;
    body: string;
  };
};
 
export type LauncherLocationContext = {
  type: 'launcher';
};
 
export type ChannelLocationContext = {
  type: 'channel';
  channel: {
    /**
     * Channel key identifier
     */
    key: string;
 
    /**
     * Channel name
     */
    name: string;
 
    /**
     * Channel profile image URL
     */
    imageUrl?: string;
  };
};
 
export type LocationContext =
  | CastEmbedLocationContext
  | NotificationLocationContext
  | LauncherLocationContext
  | ChannelLocationContext;

Cast Embed

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

> sdk.context.location
{
  type: "cast_embed",
  cast: {
    fid: 3621,
    hash: "0xa2fbef8c8e4d00d8f84ff45f9763b8bae2c5c544",
  }
}

Notification

Indicates that the Mini App was launched from a notification triggered by the frame.

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

Launcher

Indicates that the Mini App was launched directly by the client app outside of a context, e.g. via some type of catalog or a notification triggered by the client.

> sdk.context.location
{
  type: "launcher"
}

`user`

Details about the calling user which can be used to customize the interface. This should be considered untrusted since it is passed in by the application, and there is no guarantee that it was authorized by the user.

export type AccountLocation = {
  placeId: string;
 
  /**
   * Human-readable string describing the location
   */
  description: string;
};
 
export type UserContext = {
  fid: number;
  username?: string;
  displayName?: string;
 
  /**
   * Profile image URL
   */
  pfpUrl?: string;
  location?: AccountLocation;
};

> sdk.context.user
{
  "fid": 6841,
  "username": "deodad",
  "displayName": "Tony D'Addeo",
  "pfp": "https://i.imgur.com/dMoIan7.jpg",
  "bio": "Building @warpcast and @farcaster, new dad, like making food",
  "location": {
    "placeId": "ChIJLwPMoJm1RIYRetVp1EtGm10",
    "description": "Austin, TX, USA"
  }
}

type User = {
  fid: number;
  username?: string;
  displayName?: string;
  pfp?: string;
  bio?: string;
  location?: {
    placeId: string;
    description: string;
  };
};

client

Details about the Farcaster client running the Mini App. This should be considered untrusted

clientFid: the self-reported FID of the client (e.g. 9152 for Warpcast)
added: whether the user has added the Mini App to the client
safeAreaInsets: insets to avoid areas covered by navigation elements that obscure the view
notificationDetails: in case the user has enabled notifications, includes the url and token for sending notifications

export type SafeAreaInsets = {
  top: number;
  bottom: number;
  left: number;
  right: number;
};
 
export type ClientContext = {
  clientFid: number;
  added: boolean;
  notificationDetails?: FrameNotificationDetails;
  safeAreaInsets?: SafeAreaInsets;
};

> sdk.context.client
{
  clientFid: 9152,
  added: true,
  safeAreaInsets: {
    top: 0,
    bottom: 20,
    left: 0,
    right: 0,
  };
  notificationDetails: {
    url: "https://api.warpcast.com/v1/frame-notifications",
    token: "a05059ef2415c67b08ecceb539201cbc6"
  }
}

type FrameNotificationDetails = {
  url: string;
  token: string;
};
 
type SafeAreaInsets = {
  top: number;
  bottom: number;
  left: number;
  right: number;
};
 
type ClientContext = {
  clientFid: number;
  added: boolean;
  safeAreaInsets?: SafeAreaInsets;
  notificationDetails?: FrameNotificationDetails;
};

Using safeAreaInsets

Mobile devices render navigation elements that obscure the view of an app. Use the safeAreaInsets to render content in the safe area that won't be obstructed.

A basic usage would to wrap your view in a container that adds margin:

<div style={{
  marginTop: context.client.safeAreaInsets.top,
  marginBottom: context.client.safeAreaInsets.bottom,
  marginLeft: context.client.safeAreaInsets.left,
  marginRight: context.client.safeAreaInsets.right,
}}>
  ...your app view
</div>

However, you may want to set these insets on specific elements: for example if you have tab bar at the bottom of your app with a different background, you'd want to set the bottom inset as padding there so it looks attached to the bottom of the view.