FIP: Frames v2 #205

varunsrin · 2024-11-20T04:59:58Z

varunsrin
Nov 20, 2024
Maintainer

Problem

Developers want users to discover and use their onchain apps. Farcaster was great for discovery but not so much for usage. If you found an app in your feed, you had to click the link, load a page and connect it to a wallet. It was navigable on desktop, but nearly impossible on mobile even for advanced users.

Frames launched in Jan 2024 and make this a bit better. When a user clicked on a frame, the developer knew the identity of the user and their wallet address. They could send things to the users wallet and the user could take actions through a limited set of interactions. This was neat and we saw a lot of apps built, but there were some limitations that caused their usage to peter out:

Frames were small and interactions were limited, which made many apps impossible to build.
Frames had to be rendered as images which were slow to generate.
Frames were ephemeral and users couldn't get back to them.

A new frame standard that allows interactive applications, onchain transactions and user notifications would enable many new kinds of social applications.

Specification

A frame is full-screen application that renders inside a Farcaster app.

It can be embedded in feeds in a compact form which includes an image and a button which opens the frame. When the button is clicked the frame URL is rendered in an in-app browser. Developers can build anything that renders in a browser and can use a JavaScript SDK to trigger actions like saving the frame or requesting an onchain transaction.

Frames will have access to :

Context: information about the user's Farcaster account and where the frame was called from
Actions: APIs to request the parent app to do certain things on the frame's behalf
Wallet: an Ethereum provider to request transactions and signatures from the connected wallet

Here's an example of a frame using a wallet to complete a transaction:

Frame URL Specifications

A URL is considered a valid frame if it includes an embed tag in its HTML <head> and a manifest file at a well known location at the root of the domain.

Versioning

Frames will follow semantic versioning and frames must declare the version that they support. Apps will choose to render frames based on the versions they can support.

Frame Embed Metatags

A frame URL must have a FrameEmbed in a serialized form in the fc:frame meta tag in the HTML <head>. When this URL is rendered in a cast, the image is displayed in a 3:2 ratio with a button underneath. Clicking the button will open an app frame to the provided action url and use the splash page to animate the transition.

<meta name="fc:frame" content="<stringified FrameEmbed JSON>" />

type FrameEmbed = {
  // Frame spec version. Required.
  // Example: "next"
  version: 'next';

  // Frame image.
  // Max 512 characters.
  // Image must be 3:2 aspect ratio and less than 10 MB.
  // Example: "https://yoink.party/img/start.png"
  imageUrl: string;

  // Button attributes
  button: {
    // Button text.
    // Max length of 32 characters.
    // Example: "Yoink Flag"
    title: string;

    // Action attributes
    action: {
      // Action type. Must be "launch_frame".
      type: 'launch_frame';

      // App name
      // Max length of 32 characters.
      // Example: "Yoink!"
      name: string;

      // Frame launch URL.
      // Max 512 characters.
      // Example: "https://yoink.party/"
      url: string;

      // Splash image URL.
      // Max 512 characters.
      // Image must be 200x200px and less than 1MB.
      // Example: "https://yoink.party/img/splash.png"
      splashImageUrl: string;

      // Hex color code.
      // Example: "#eeeee4"
      splashBackgroundColor: string;
    };
  };
};

Frame Manifest

The manifest file declares the metadata that is applied to the frame application served from this domain. It also defines triggers that indicate which actions it supports from trigger points like casts and the composer.

Frame servers must provide a JSON manifest file on their domain at the well known URI /.well-known/farcaster.json.

type FarcasterManifest = {
  // Metadata associating the domain with a Farcaster account
  accountAssociation: {
    // base64url encoded JFS header.
    // See FIP: JSON Farcaster Signatures for details on this format.
    header: string;

    // base64url encoded payload containing a single property `domain`
    payload: string;

    // base64url encoded signature bytes
    signature: string;
  };

  // Frame configuration
  frame: FrameConfig;

  // Trigger configuration
  triggers?: TriggerConfig[];
};

Domain Account Association

The account association links the domain to a Farcaster account. The signature must be a signed JSON Farcaster Signature from the account's custody address with the following payload:

{
  domain: string;
}

The domain in the signed object must match the domain the manifest is served from.

Frame Config

type FrameConfig = {
  // Manifest version. Required.
  version: '1';

  // App name. Required.
  // Max length of 32 characters.
  // Example: "Yoink!"
  name: string;

  // Default launch URL. Required.
  // Max 512 characters.
  // Example: "https://yoink.party/"
  homeUrl: string;

  // Frame application icon URL.
  // Max 512 characters.
  // Image must be 200x200px and less than 1MB.
  // Example: "https://yoink.party/img/icon.png"
  iconUrl: string;

  // Default image to show when frame is rendered in a feed.
  // Max 512 characters.
  // Image must have a 3:2 ratio.
  // Example: "https://yoink.party/framesV2/opengraph-image"
  imageUrl: string;

  // Default button title to use when frame is rendered in a feed.
  // Max 32 characters.
  // Example: "🚩 Start"
  buttonTitle: string;

  // Splash image URL.
  // Max 512 characters.
  // Image must be 200x200px and less than 1MB.
  // Example: "https://yoink.party/img/splash.png"
  splashImageUrl?: string;

  // Hex color code.
  // Example: "#eeeee4"
  splashBackgroundColor?: string;

  // URL to which clients will POST events.
  // Max 512 characters.
  // Required if the frame application uses notifications.
  // Example: "https://yoink.party/webhook"
  webhookUrl?: string;
};

Frame Invocation

Frames may be invoked in the following ways. When invoked, the frame application may receive additional information about the context in which it was launched.

Type	Description	Context
global	Called when the app is invoked from the app launcher or any other unspecified context. Loads the `homeUrl` defined in the frame application manifest.	None
embed	Called when the frame is invoked from an embed in a feed or direct cast. Loads the `url` specified in the FrameEmbed metadata.	Cast hash, embed URL, embed type (feed or direct cast), see below
notification	Called when a user taps/clicks a frame notification. Loads the `targetUrl` specified in the notification payload.	Notification ID, see below

Triggers

Triggers allow a user to launch into your frame application from different places in a Farcaster client application. These will eventually replace "cast actions" and "composer actions." See Feature: Triggers in the Appendix for further details.

type TriggerConfig =
  | {
      // Type of trigger, either cast or composer. Required.
      type: 'cast';

      // Unique ID. Required. Reported to the frame.
      // Example: "yoink-score"
      id: string;

      // Handler URL. Required.
      // Example: "https://yoink.party/triggers/cast"
      url: string;

      // Name override. Optional, defaults to FrameConfig.name
      // Example: "View Yoink Score"
      name?: string;
    }
  | {
      type: 'composer';
      id: string;
      url: string;
      name?: string;
    };

The frame receives the trigger type and id as context data.

Frame manifest caching

Farcaster clients may cache the frame manifest when scraping embeds, but should provide a mechanism for refreshing the manifest file.

Frame UI Specifications

Header

Clients should render a header above the frame that includes the name and author specified in the manifest. Clients should show the header whenever the app frame is launched.

Splash Screen

Clients should show a splash screen as soon as the app is launched. The icon and background must be specified in the frame manifest or embed meta tags. The frame can hide the splash screen once loading is complete.

Size & Orientation

A frame should be rendered in a vertical modal. Mobile frame sizes will be dictated by device dimensions while web frame sizes will be set to 424x695px.

Client SDK API

Frame applications must include a frame SDK JavaScript package to communicate with the parent app. Frames may include it as a bundled package or using a <script> tag.

The frame SDK manages frame-client communication over a window.postMessage channel. Since the parent app cannot inject arbitrary JavaScript in a browser context, frame applications must include the SDK in their app to establish a communication channel.

The sdk.context variable provides information about the context within which the frame is running:

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

context.location

Contains information about the context from which the frame was launched.

export type FrameLocationContextCastEmbed = {
  type: 'cast_embed';
  cast: {
    fid: number;
    hash: string;
  };
};

export type FrameLocationContextNotification = {
  type: 'notification';
  notification: {
    notificationId: string;
    title: string;
    body: string;
  };
};

export type FrameLocationContextLauncher = {
  type: 'launcher';
};

export type FrameLocationContext =
  | FrameLocationContextCastEmbed
  | FrameLocationContextNotification
  | FrameLocationContextLauncher;

Cast Embed

Indicates that the frame 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 frame 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 frame 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"
}

context.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.

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

context.client

Details about the Farcaster client running the frame. 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 frame 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

> 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 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 a frame. 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 frame 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 frame 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.

actions.ready

Indicates that the application is fully loaded and ready to displayed to users. Once this is called the loading screen will be hidden. Frame applications MUST call ready() to display their app.

> await sdk.actions.ready();

type Ready = (
  options: Partial<{
    /**
     * Disable native gestures. Use this option if your frame uses gestures
     * that conflict with native gestures.
     */
    disableNativeGestures: boolean;
  }>
) => Promise<void>;

actions.openUrl

Request the client app to direct the user to an external URL via deep link or web browser.

> await sdk.actions.openUrl({ url: "<https://yoink.today/>" });

type OpenExternalUrl = (options: {
  url: string;
  close?: boolean;
}) => Promise<void>;

actions.close

Close the app frame and display an optional toast.

> await sdk.actions.close({ toast: {
    message: "You yoinked the flag from @deodad."
  }
});

type Close = (options: {
  toast?: {
    message: string;
  };
}) => Promise<void>;

wallet.ethProvider

An EIP-1193 Ethereum Provider for interacting with the user’s connected wallet. App Frames can interact with this provider using familiar tools like wagmi to:

get the user’s connected Ethereum addresses (eth_requestAccounts)
request a transaction (eth_sendTransaction)
request a wallet signature (eth_signTypedData_v4)

> await sdk.wallet.ethProvider.request({
  method: 'eth_requestAccounts'
});
["0xf17e02c56D8c86767c12332571C91BB29ae302f3"]

Rationale

FAQ

What about older frame types / cast actions / composer actions / mini-apps?

Older frame types will be fully supported for now until we develop a thorough transition plan. We will give developers at least 3 months notice before deprecating anything.

Release Plan

Schedule

Nov 22nd: new draft of spec, mobile playground
Nov 27th: v0.0.0 of frames on mobile
Dec 6th+: v0.1.0 of frames on mobile and web (scope tbd, but likely includes auth, add frame, notifications)
Jan/Feb: stable release of v1.0.0

Changelog

Date	Version	Changes
Dec 2	0.0.1	Copy edits, update release plan

Appendix

Feature: Auth

Allow users to sign into frames using their Farcaster identity.

actions.signIn

Initiates a Sign In with Farcaster flow for the user. The Frame host must set
the domain value of the SIWF message to the domain of the frame and the uri
value of the url of the Frame. When validating this message the domain must
be checked.

> await sdk.actions.signIn({ nonce });
{ message: "yoink.party wants you to sign in...", signature: "0xabcd..." }

export type SignInOptions = {
  /**
   * A random string used to prevent replay attacks.
   */
  nonce: string;

  /**
   * Start time at which the signature becomes valid.
   * ISO 8601 datetime.
   */
  notBefore?: string;

  /**
   * Expiration time at which the signature is no longer valid.
   * ISO 8601 datetime.
   */
  expirationTime?: string;
};

export type SignInResult = {
  signature: string;
  message: string;
};

export type SignIn = (options: SignInOptions) => Promise<SignInResult>;

Feature: Add frame

The user can add a frame to their Farcaster app, either through an SDK action or directly (from a deep link, catalog page, etc). The Farcaster app should make it easy to find this saved frame in their UI and accept notifications from the app developer and deliver them to the user. For example, a frame which monitors onchain prices could notify users when the price of something exceeds a certain threshold.

Request add frame

Asks the user to add the frame to the Farcaster app, which allows the user to invoke the frame from a cast, composer or other locations in the app. Also allows the app to send notifications to the user.

actions.addFrame

Request the user to add the frame, which adds it to the user's favorites list and allows the frame server to send in-app notifications to the user. The Farcaster client is expected to prompt the user for confirmation. Per session, only a single prompt should be shown (repeated calls to addFrame() should immediately result in a. rejected_by_user error). When the client supports notifications, returns a notificationDetails object with a notification callback URL and token.

> await sdk.actions.addFrame();
{
  "type": "success",
  "notificationDetails": {
    "url": "https://api.warpcast.com/v1/frame-notifications",
    "token": "a05059ef2415c67b08ecceb539201cbc6"
  }
}

type FrameNotificationDetails = {
  url: string;
  token: string;
};

export type AddFrameRejectedReason =
  | 'invalid_domain_manifest'
  | 'rejected_by_user';

export type AddFrameResult =
  | {
      added: true;
      notificationDetails?: FrameNotificationDetails;
    }
  | {
      added: false;
      reason: AddFrameRejectedReason;
    };

export type AddFrame = () => Promise<AddFrameResult>;

There are 2 expected failure conditions which the frame should gracefully handle:

invalid_domain_manifest: The frame domain manifest is invalid. The frame developer should use the developer tools to validate and fix their manifest.
rejected_by_user: Returned when the user rejects/dismisses the prompt asking them to add the frame, or the frame has triggered addFrame() more than once per session.

Feature: Server Events

The Farcaster client server POSTs 4 types of events to the frame server at the webhookUrl specified in its frame manifest:

frame_added
frame_removed
notifications_enabled
notifications_disabled

The body looks like this:

Events use the JSON Farcaster Signature format and are signed with the app key of the user. The final format is:

{
  header: string;
  payload: string;
  signature: string;
}

All 3 values are base64url encoded. The payload and header can be decoded to JSON, where the payload is different per event.

`frame_added`: frame added to a client

This event may happen when an open frame calls actions.addFrame to prompt the user to favorite it, or when the frame is closed and the user adds the frame elsewhere in the client application (e.g. from a catalog).

Adding a frame includes enabling notifications.

The Farcaster app server generates a unique notificationToken and sends it together with the notificationUrl that the frame must call, to both the Farcaster app client and the frame server. Client apps must generate unique tokens for each user.

The app client then resolves the actions.addFrame promise so the frame can react immediately (without having to check its server).

This is the flow for an open frame:

This is the flow when the frame is not open; only the backend part runs:

Webhook payload:

{
  "event": "frame-added",
  "notificationDetails": {
    "url": "https://api.warpcast.com/v1/frame-notifications",
    "token": "a05059ef2415c67b08ecceb539201cbc6"
  }
}

type EventFrameAddedPayload = {
  event: 'frame_added';
  notificationDetails?: FrameNotificationDetails;
};

`frame_removed`: user removed frame from client

A user can remove a frame, which means that any notification tokens for that fid and client app (based on signer requester) should be considered invalid:

Webhook payload:

{
  "event": "frame-removed"
}

`notifications_disabled`: user disabled notifications

A user can disable frame notifications from e.g. a settings panel in the client app. Any notification tokens for that fid and client app (based on signer requester) should be considered invalid:

Webhook payload:

{
  "event": "notifications_disabled"
}

`notifications_enabled`: user enabled notifications

A user can enable frame notifications (e.g. after disabling them). The client backend again sends a notificationUrl and a token, with a backend-only flow:

Webhook payload:

{
  "event": "notifications-enabled",
  "notificationDetails": {
    "url": "https://api.warpcast.com/v1/frame-notifications",
    "token": "a05059ef2415c67b08ecceb539201cbc6"
  }
}

type EventNotificationsEnabledPayload = {
  event: 'notifications_enabled';
  notificationDetails: FrameNotificationDetails;
};

Feature: Frame Events

Farcaster clients emit events to your frame, while it is open, to let you know of actions the user takes.

To listen to events, you have to use sdk.on to register callbacks (see full example).

sdk.on('frameAdded', ({ notificationDetails }) => {
  setLastEvent(
    `frameAdded${!!notificationDetails ? ', notifications enabled' : ''}`
  );

  setAdded(true);
  if (notificationDetails) {
    setNotificationDetails(notificationDetails);
  }
});

Ensure that on unmount/close, all the listeners are removed via sdk.removeAllListeners().

Here are the callback definitions:

export type EventMap = {
  frameAdded: ({
    notificationDetails,
  }: {
    notificationDetails?: FrameNotificationDetails;
  }) => void;
  frameAddRejected: ({ reason }: { reason: AddFrameRejectedReason }) => void;
  frameRemoved: () => void;
  notificationsEnabled: ({
    notificationDetails,
  }: {
    notificationDetails: FrameNotificationDetails;
  }) => void;
  notificationsDisabled: () => void;
};

The emitted events are:

frameAdded, same as the frame_added webhook
frameAddRejected, frontend-only, emitted when the frame has triggered the addFrame action and the frame was not added. Reason is the same as in the return value of addFrame.
frameRemoved, same as the frame_removed webhook
notificationsEnabled, same as the notifications_enabled webhook
notificationsDisabled, same as the notifications_disabled webhook

Feature: Notifications API

A frame server can send notifications to one or more users who have enabled them.

The frame server is given an authentication token and a URL which they can use to push a notification to the specific Farcaster app that invoked the frame. This is private and must be done separately for each Farcaster app that a user may use.

The frame server calls the notificationUrl with:

notificationId: a string (max size 128) that servers as an idempotency key and will be passed back to the frame via context. A Farcaster client should deliver only one notification per user per notificationId, even if called multiple times.
title: title of the notification, max length of 32 characters
body: body of the notification
targetUrl: the target frame URL to open when a user clicks the notification. It must match the domain for which the notification token was issued.
tokens: an array of tokens (for that notificationUrl) to send the notification to. Client servers may impose a limit here, e.g. max 10000 tokens.

Client servers may also impose a rate limit per token, e.g. 5 sends per 5 minutes.

The response from the client server must be an HTTP 200 OK, with the following 3 arrays:

successTokens: tokens for which the notification succeeded
invalidTokens: tokens which are no longer valid and should never be used again. This could happen if the user disabled notifications but for some reason the frame server has no record of it.
rateLimitedTokens: tokens for which the rate limit was exceeded. Frame server can try later.

Once a user has been notified, when clicking the notification the client app will:

Open targetUrl
Set the context to the notification, see NotificationLaunchContext

Farcaster apps should:

Display a list of added frames somewhere in their UI, allowing the user to enable/disable notifications.
Show notifications from added frames along with other in-app notifications.

Feature: Triggers

Contexts

A frame can be launched from different contexts like a cast or direct message. In each case, the frame app receives a context object that contains information about how the frame was triggered. The context may also define what SDK functions are available. For example, a "translate" frame launched from the composer context will have a method that allows it to update the cast being written, while one triggered from a cast context in the feed will only get the contents of the cast.

Contexts unify cast actions, composer actions, frames and mini-apps into a single standard, instead of having custom flows for each of these features.

A single frame may expose multiple cast and composer triggers via the TriggerConfig in its frame application manifest. When invoked, the context will include the ID of the trigger that was activated.

We intend to introduce additional triggers in the future, replacing "cast actions" and "composer actions" and introducing new launch contexts:

Trigger	Description	Context
cast	Called when the app is invoked from a cast. (aka “cast action”)	Cast hash, cast content, author ID, trigger ID
composer	Called when invoked from the cast composer. (aka “composer action”)	Cast parent, text, embeds, trigger ID
channel	Called when invoked from a channel profile	Channel key
user	Called when invoked from a user profile	User ID

Context types

type CastLaunchContext = {
  type: 'cast';
  triggerId: string; // comes from TriggerConfig
  cast: Cast;
};

type ComposerLaunchContext = {
  type: 'composer';
  triggerId: string; // comes from TriggerConfig
  cast: {
    parent?: string;
    text?: string;
    embeds?: string[];
  };
};

type ChannelLaunchContext = {
  type: 'channel';
  channel: {
    key: string;
    name: string;
    imageUrl: string;
  };
};

type UserLaunchContext = {
  type: 'user';
  profile: User;
};

type LinkLaunchContext = {
  type: 'link';
  url: string;
};

type DirectCastEmbedLaunchContext = {
  type: 'direct_cast_embed';
};

> sdk.context.location
{
  type: "cast_embed",
  cast: {
    fid: 3621,
    hash: "0xa2fbef8c8e4d00d8f84ff45f9763b8bae2c5c544",
    text: "New Yoink just dropped:",
    embeds: ["https://yoink.party/frames"]
  }
}

Feature: Primary Button

actions.setPrimaryButton

Action Button

A native action button may be rendered via an SDK call which provides a clear and consistent call to action for the user. The app frame can specify the text, color mode and callback function. This is optional and frames may choose to implement their own user interface using UI components inside the web view.

Set the Primary Button.

> await sdk.actions.setPrimaryButton({ text: "Yoink!" });

type SetPrimaryButton = (options: {
  text: string;
  enabled?: boolean;
  hidden?: boolean;
}) => Promise<void>;

An app frame should subscribe to the primaryButtonClicked event to respond to interactions.

primaryButtonClick (Event)

Emitted when user clicks the Primary Button.

> Farcaster.events.on("primaryButtonClick", () => {
    console.log("clicked!") }
);

benadamsky · 2024-11-21T06:16:31Z

benadamsky
Nov 21, 2024

When this URL is rendered in a cast, the image is displayed in a 1.9:1 ratio with a button underneath.

Is 1.91:1 being confirmed as the official ratio for the initial frame image? Or is this just being marked as an example?

Overall super excited for these changes, lots to unpack here!

4 replies

deodad Nov 22, 2024
Maintainer

Right now the plan is to start with only this aspect ratio (same as standard open graph). What we found with 1:1 is that take up a lot of feed space and artists who were the biggest users of 1:1 originally ended up attaching their artwork as separate attachment anyway.

Can always add but never take away :)

benadamsky Nov 22, 2024

Got it @deodad thanks for clarity here, we'll go with 1.91:1 for the time being then

What I will say is the majority of our users have strongly preferred the 1:1 ratio on our polls, expressed in both our TG group + DCs and polls like this one:
https://www.weponder.io/polls/6157

This sentiment could shift with v2 since it's a different form function than v1, but still worth calling out

varunsrin Nov 22, 2024
Maintainer Author

most apps i think will benefit from frames v2.

the two kinds of apps for whom it is not yet clear is nft mints and polls, which rely on the bigger image sizes and 1-shot actions to complete without having to pop open a window. for now, it might be best to keep using frames v1 while we find a good transition path to frames v2.

benadamsky Nov 24, 2024

@varunsrin we're keeping polls on frames v1 for the time being, pending a better way to interact with them in Farcaster on v2

We're planning on releasing an entirely new iteration of polls we've been experimenting with that uses frames v2, so the aspect ratio set to 1.91:1 on the initial frame is relevant only on that case

davidfurlong · 2024-11-21T13:14:29Z

davidfurlong
Nov 21, 2024

I would like to be able to opt out of notifications separately, without unfavoriting.

The name change suggests this is replacing the old the frames entirely and warpcast will stop supporting them, correct?

2 replies

depatchedmode Nov 21, 2024

+1 to a separate notifications option

deodad Nov 22, 2024
Maintainer

agreed on opting out of notifications w/o removing

no frames v1 will continue to be supported. it might make sense to stop supporting if usage is low or we fold more of the their functionality into the v2 spec

dalechyn · 2024-11-21T14:33:02Z

dalechyn
Nov 21, 2024

Can we get more details on the launchHooks property in the manifest?

Not particularly sure what launcher means there, as well as user.

1 reply

horsefacts Nov 22, 2024
Maintainer

Added a couple tables describing hooks under "Frame Manifest" and in the appendix. We will probably only launch with a notification hook, so the ones in the appendix are probably more interesting.

cast and composer replace "cast actions" and "composer actions" and there are potential new ones like user for user profile and channel for channel profile.

davidfurlong · 2024-11-22T13:07:23Z

davidfurlong
Nov 22, 2024

Some open questions or thoughts I have:

The interface between the Frame and the client is currently spec'd to be very limited. I think there is an opportunity to open this interface up to also providing "developer legos" by allowing the Frames in v2 to call an action that opens a limited version of Frames v1 (frames v1 without the "POST" action, so it's only 1 step frames). This allows third party programmability at this permissions layer between Frames and Client, enabling Frames to interact with eachother. As it stands, Frames v2 have no way to interface with each other, or any of the existing developer legos via a trusted context. The trickiest part of implementing Frames v1 for clients was the complexity and performance of state transitions between frames. By limiting Frames v1 to "one step Frames", you get the safe composability without adding much complexity.
are favorited frames something per client or across clients? If only in one client this feels like it will just add to the reinforcing of a monoclient lock in. I'm assuming they are, as the notification callback url needs to be a specific clients'.
Would be helpful if the manifest included the category of the frame, which can be a set of 10. Whilst building a client it's a lot of work to manually categorize miniapps. Much easier to add now than later.
A Max size on manifest images; icon and splash; would be nice - we saw a lot of very big frame images that then became a bit annoying to try to optimize as a client for speed.
Would be nice if DirectCastEmbedLaunchContext had some sort of unique conversational identifier. I understand that you may not want to do this whilst DCs are not in protocol.
I think hooks might be an unnecessarily ambigious word as most devs are using React, and may lead to unnecessary confusion. Perhaps trigger is better?

How can we make it as easy as possible for frame apps to verify context data? Ideally we avoid the round trip to hubs required by frames v1

Agree this would be nice. Perhaps a hub can sign certain data or the signed TLS packaged can be passed on from the hub to the miniapp here, so the Mini-app doesn't need to trust the client, but still get the preloaded hub data?

Should we include client information in the context?

I think this might be helpful especially with the way frames v1 went where many of the changes were not backwards compatible with clients. Many clients had incomplete or outdated implementations. Passing along the context may help solve this, as Frames would be able to feature detect clients compatibility rather than breaking, although perhaps a frames version passed into the context is a better solution.

Should clients provide additional user data?

Passing along the Accept-Language header (if web) would be valuable. The additional data would be nice, as it'll help speed up frames.

I think this is very exciting direction for Frames, but I think suggestion (1) above is essential for allowing open developer legos to emerge in v2 like it did in v1

5 replies

horsefacts Nov 22, 2024
Maintainer

are favorited frames something per client or across clients? If only in one client this feels like it will just add to the reinforcing of a monoclient lock in. I'm assuming they are, as the notification callback url needs to be a specific clients'.

Per-client in the current design. That doesn't preclude adding some mechanism to sync a user's favorited frames. But the hunch is that most users will want to see app notifications once in their primary client rather than duplicated across every client they use. If you do, you can opt in to notifications in other apps by adding them there, too. Or install a totally different set of frames in a different client context. (Maybe you use Supercast for the brand account and Warpcast for your personal).

I don't see a reason to restrict the notification callback URL to the client domain, so it would be possible for frames to use third party notification APIs too. (For example, Neynar could provide a notifications API consumed by multiple client apps)

horsefacts Nov 22, 2024
Maintainer

Would be helpful if the manifest included the category of the frame, which can be a set of 10. Whilst building a client it's a lot of work to manually categorize miniapps. Much easier to add now than later.

Yeah, agree on this.

horsefacts Nov 22, 2024
Maintainer

A Max size on manifest images; icon and splash; would be nice - we saw a lot of very big frame images that then became a bit annoying to try to optimize as a client for speed.

+1

varunsrin Nov 22, 2024
Maintainer Author

I'm still wrapping my head around this. Whats something you would build if this was available that isn't possible otherwise?
Per client for now because we dont have a simple way to make this x-client but private. I don't think people expect the list of apps they have installed to be publicly visible. Its a very very minor lock in concern - browser extensions don't sync but most people pretty easily set up new extensions when switching between Chrome and Brave.
+1 , but maybe we keep it open ended to give people more freedom to self-categorize
+1
What would you want to do with this identifier?
will think on this

davidfurlong Nov 25, 2024

I'm still wrapping my head around this. Whats something you would build if this was available that isn't possible otherwise?

Some examples:

rsvp to an event on @event from within another Frame v2 by pulling up the Frame v1 event frame
use a credit card checkout to buy a product using percz from a Frame via their v1 Frame
follow someone's newsletter on paragraph from any other Frame
save a link to a social bookmarking service from within another Frame

We've been building on something enabling read/write to github, farcaster & twitter for devs via frame v1 as permissions/middleware that if (1) was implemented could still be work. Users connect their credentials once via our app and can then give granular case by case permission to use these credentials via a Frames v1. We intended for this to be used in Frames v1s as frame middleware, but this could also be leveraged by Frames v2. Retweet on twitter within a Frames v2 app becomes just pressing a Frames v1 button for the user

What would you want to do with this identifier?

Personalize a Frame based on the context; for example a Frame that let's me start a group wallet should be able to display (read only) the balance of the shared wallet by default. Only works when the Frame is aware of some sort of unique identifier for the context

porenes · 2024-11-22T13:59:28Z

porenes
Nov 22, 2024

V1 frames are like enhanced OpenGraph tags with a bit of interactivity, perfect for sharing content. Developers have pushed them to do more complex things, which isn’t their intended purpose. This has made V1 frames underused, but the real issue is a lack of support and tools.

Problems:

No plugins for major CMS platforms.
Few websites use frames for links, so most frames are standalone instead of enhancing shared links.
Developers made frames too complex and slow, missing simple use cases that could appeal to a wider audience.
Moving to V2 frames might make things harder. A simple frame with minor interactivity would now require building modules for features like multiple CTAs. This could discourage use.

tl;dr: V1 frames are great for simple, interactive content sharing. They’re just underutilized, not bad. Don’t throw them out—they deserve better tools and promotion.

0 replies

netnose · 2024-11-22T17:31:39Z

netnose
Nov 22, 2024

Looks cool, especially for static apps!
These are the first questions that come into my mind:

the fc:frame content will be read straight out of the http response or the page will be rendered? I mean js can change it before it will be read?
target _blank links will trigger the openExternalUrl method?
can setPrimaryButton be called before hideSplashScreen?

2 replies

netnose Nov 22, 2024

Also, is there a way to statically define the frame and open the shared link into it instead of specifying the url for each frame? It would be useful for client side web app.

varunsrin Nov 22, 2024
Maintainer Author

the fc:frame content will be read straight out of the http response or the page will be rendered? I mean js can change it before it will be read?

it will be read first

target _blank links will trigger the openExternalUrl method?

you should plan on calling it explicitly for now

can setPrimaryButton be called before hideSplashScreen?

yes, we will allow this.

andrei0x309 · 2024-11-22T18:34:06Z

andrei0x309
Nov 22, 2024

This looks good because, de facto, frames v2 will inherit in fact what was mini-apps, and make them permissionless.

This is something that was mentioned and requested many many times on Farcaster.

IMO Iframes proved already that are superior, as I said, even before v1 was in spec design.

It is still overall a client-only feature, and Farcaster being a protocol it seems confusing that this is categorized as an FIP.

As is just a client spec, not an FIP, might be a technicality but I think is important, to not overmarket it.

3 replies

vrypan Nov 22, 2024

I don't agree. The protocol does not consist of the protobuf specifications only. Everything that describes a standard and commonly agreed way of interacting with the ecosystem should be an FIP.

(In the same way that ERC-721 did not affect the EVM, but it is part of what makes Ethereum, Ethereum.)

varunsrin Nov 22, 2024
Maintainer Author

It is still overall a client-only feature, and Farcaster being a protocol it seems confusing that this is categorized as an FIP.

we actually kept frames v1 outside of the fip scope, but developers were annoyed that there was no canonical way to find all the farcaster related things.

andrei0x309 Nov 23, 2024

I don't agree. The protocol does not consist of the protobuf specifications only. Everything that describes a standard and commonly agreed way of interacting with the ecosystem should be an FIP.

(In the same way that ERC-721 did not affect the EVM, but it is part of what makes Ethereum, Ethereum.)

I mean at the end of the day is a client spec because is not enforceable, I don't have a strong opinion if is an FIP or not, I just see the technical part.

In my view, there's a big difference between FIPs that do changes at the protocol level and those that are not at the protocol level, and I think that distinction being clearly made is a net positive. ( even with a label could be helpful)

Protocol changes will always have an enforcement component that can lead to disagreement forks etc, but a client spec is more of a recommendation as enforceability does not exist.

And this is something very clear with all protocols, if someone builds any client the first question is always what the protocol dictates in the first place, and then will look at recommendations.

dalechyn · 2024-11-23T15:58:32Z

dalechyn
Nov 23, 2024

What are the caching policies of properties related to images in the manifest?
Specifically icon and splashImage. I suppose they are immutable?
FrameEmbed.action's splashImage and splashBackgroundColor are most likely gonna be copies of such from Frame Manifest. Does it make sense to define them there? Isn't manifest gonna be pre-fetched or fetched on button click and retrieve the same values?
I believe that FrameManifest.triggers.notification should be notifications instead, and accept an array of notifications – consider the case of Moxie, where there are lots of frames and different features with different CTAs for every other notification.

1 reply

varunsrin Nov 23, 2024
Maintainer Author

Cached until explicitly invalidated by using a developer tool.
Duplicate definition is for performance - we can load the initial frame without an additional network request to the manifest and then cache the manifest later.
Will flag this one to the team

CryptoRabble · 2024-11-24T20:43:40Z

CryptoRabble
Nov 24, 2024

I'm struggling to understand the difference between this and mini apps that already exist.

Feel like there is a lot of overlap and will shut out amateur coders who were able to learn the simplicity of coding a frame, but can't code a full web app.

Also, think there is something to be said for keeping the user interaction in-feed, having stuff pop up over the full screen is less user friendly (why mini apps have struggled to take off so far)

1 reply

tantodefi Nov 24, 2024

I think frames v1 were like static apps. (like metatags)
Think like a slideshow where buttons toggled through slides. Some buttons could prompt transactions and user could input some data into a input field but for the most part the functionality was limited and deterministic. These v1 frames and their associated 'user journeys' needed for the most part to be created and known before hand.

I think frames v2 upgrades the spec to be more 'dynamic' - you can use the associated context like user fid and with javascript 'await' to fetch data from user and then render a different 'user-journey' for different users based on onchain activity, balances, or client interactions.

that is at least my current understanding (if I'm wrong please correct me).

One of the hopeful outcomes of this improvement is more general frames with more features and less one-time use frames.

Also there are A LOT of no-code frame builder tools for frames v1 and possibly eventually will be for frames v2 to help developers who cant write full async javascript code.

compusophy · 2024-11-25T09:11:43Z

compusophy
Nov 25, 2024

should be context.user.pfpUrl instead of context.user.pfp right?

0 replies

michalkvasnicak · 2024-11-26T08:46:02Z

michalkvasnicak
Nov 26, 2024

Should it be FrameEmbed.button.title or FrameEmbed.button.text? The table says text but type definition has title.

1 reply

deodad Nov 26, 2024
Maintainer

good call will reconcile there two

netnose · 2024-11-30T12:53:30Z

netnose
Nov 30, 2024

I find the Farcaster object in this documentation very confusing. When the documentation instructs you to call:

await Farcaster.actions.ready()

you include it in your code, only to discover that it doesn’t work.

It should be made very clear that this object is not part of the final implementation and that you need to use a library to access it.

Additionally, why isn’t it a real object? Why do we need to rely on another library to use it?

3 replies

netnose Nov 30, 2024

One last thing, I promise.
I find using the meta tag not idiomatic, it is not very usual to deliver json in this way.
You can understand is at soon as you need to escape the quotes in it’s value.

A good solution could be the script tag, like schema.org does, with the application/ld+json type.
Here is an example from their documentation:
<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "CreativeWork", "author": "Sony", "contentRating": "Mature", "image": "videogame.jpg", "name": "Resistance 3: Fall of Man" } </script>

deodad Dec 2, 2024
Maintainer

Additionally, why isn’t it a real object? Why do we need to rely on another library to use it?

Frames get rendered in cross domain iFrames in web and web views on mobile devices—there's no way to inject a full object. The SDK abstracts the communication over postMessage on web and shimmed postMessage channel in mobile contexts.

netnose Dec 2, 2024

Thank you for your response, I totally get it now. I was thinking in a native app mindset and I miss it.

At this point, purely for the sake of optimization, will you release documentation on the messages protocol?

payton · 2024-12-03T20:09:33Z

payton
Dec 3, 2024

Assuming that sdk.actions.requestAuthToken is called on the Frame App, it's important to include an optional challenge field that is produced by the relying party (Frame Server). The Frame App can be expected to get the challenge from the Frame Server.

> await sdk.actions.requestAuthToken({challenge: "unique-one-time-cryptographic-challenge-abc-123"});
"0xabcd...1234"

This follows the same principals as webauthn where presence of a challenge is meant to prevent replay attacks.

type RequestAuthToken = (
  options: Partial<{
    /**
     * When this token should be considered invalid.
     * @default 15 minutes from now
     */
    exp?: number;
    /**
     * A cryptographic challenge produced by the relying party
     * to prevent replay attacks.
     */
    challenge?: string;
  }>
) => Promise<string>;

@varunsrin is this a reasonable addition or are there other factors that may make this difficult?

0 replies

vrypan · 2024-12-05T18:31:50Z

vrypan
Dec 5, 2024

Re: Notifications.

Users will be able to mute at the app level. But does the frame know that it has been muted? I think this would be an important piece of info that Frames could use. Some ideas:

If the user has muted the Frame, the request to send a notification could return some kind or error or status.
Provide a standard endpoint for the user (the app) to notify the Frame that the user wants to stop notifications.

3 replies

varunsrin Dec 8, 2024
Maintainer Author

Good suggestion, will consider whether to add in initial release or in a later one.

YogiAnwar Dec 13, 2024

Banger

vrypan Dec 19, 2024

Following up on notifications:

I think that some kind of TTL in the notification payload would be useful.

If a user does not check their notifications often, the client can safely discard them.
In some cases, a Frame server may want to push frequent notifications without worrying that they will become spammy. A price alert frame, or a calendar frame. A "live stream starts in 10 minutes" notification could be safely discarded after the event is started (or it's over).

You could also consider adding a notificationId, that can be used to update a notification: Event starts in one hour, in 10 minutes, in 1 minute -Ideally, it should be one event that gets updated. (Reading more carefully the updated specs: There is a notificationId, but it's used in the opposite way. I see why, but I think it's something to maybe reconsider in the future.)

nyusternie · 2024-12-05T22:41:05Z

nyusternie
Dec 5, 2024

following up on what other have already stated:

V1 frames are like enhanced OpenGraph tags with a bit of interactivity
@porenes

will shut out amateur coders who were able to learn the simplicity of coding a frame, but can't code a full web app
@CryptoRabble

imo, v1 satisfies different use-cases than what is planned for v2 (which seems more like a web app than a "simple" frame)

my first frame project is almost complete, and I've committed to make use of both v1 and v2; to benefit from their respective strengths, while avoiding their weaknesses.

tl;dr -- calling a (pre-authenticated) v2 app from a v1 (in-feed) frame would seem to me like the best of both worlds

0 replies

FIP: Frames v2 #205

varunsrin Nov 20, 2024 Maintainer

Problem

Specification

Frame URL Specifications

Versioning

Frame Embed Metatags

Frame Manifest

Frame UI Specifications

Client SDK API

context.location

context.user

context.client

Using safeAreaInsets

actions.ready

actions.openUrl

actions.close

wallet.ethProvider

Rationale

FAQ

Release Plan

Schedule

Changelog

Appendix

Feature: Auth

actions.signIn

Feature: Add frame

actions.addFrame

Feature: Server Events

frame_added: frame added to a client

frame_removed: user removed frame from client

notifications_disabled: user disabled notifications

notifications_enabled: user enabled notifications

Feature: Frame Events

Feature: Notifications API

Feature: Triggers

Contexts

Feature: Primary Button

actions.setPrimaryButton

primaryButtonClick (Event)

Replies: 15 comments · 26 replies

deodad Nov 22, 2024 Maintainer

varunsrin Nov 22, 2024 Maintainer Author

deodad Nov 22, 2024 Maintainer

horsefacts Nov 22, 2024 Maintainer

horsefacts Nov 22, 2024 Maintainer

horsefacts Nov 22, 2024 Maintainer

horsefacts Nov 22, 2024 Maintainer

varunsrin Nov 22, 2024 Maintainer Author

varunsrin Nov 22, 2024 Maintainer Author

varunsrin Nov 22, 2024 Maintainer Author

varunsrin Nov 23, 2024 Maintainer Author

deodad Nov 26, 2024 Maintainer

deodad Dec 2, 2024 Maintainer

varunsrin Dec 8, 2024 Maintainer Author

varunsrin
Nov 20, 2024
Maintainer

`frame_added`: frame added to a client

`frame_removed`: user removed frame from client

`notifications_disabled`: user disabled notifications

`notifications_enabled`: user enabled notifications

Replies: 15 comments 26 replies

deodad Nov 22, 2024
Maintainer

varunsrin Nov 22, 2024
Maintainer Author

deodad Nov 22, 2024
Maintainer

horsefacts Nov 22, 2024
Maintainer

horsefacts Nov 22, 2024
Maintainer

horsefacts Nov 22, 2024
Maintainer

horsefacts Nov 22, 2024
Maintainer

varunsrin Nov 22, 2024
Maintainer Author

varunsrin Nov 22, 2024
Maintainer Author

varunsrin Nov 22, 2024
Maintainer Author

varunsrin Nov 23, 2024
Maintainer Author

deodad Nov 26, 2024
Maintainer

deodad Dec 2, 2024
Maintainer

varunsrin Dec 8, 2024
Maintainer Author