Frames Protocol

by

The Frames Protocol, also known Farcaster Frames, is a simple web-based technology used for making applications.

It uses HTML without really using HTML, so that Frames Protocol applications work with clients that don't support the Frames Protocol. The fall-back being OpenGraph.

Really, a Frames Protocol application is mostly made up of images and buttons on the client-side (that are specified using HTML <meta> element) with a back-end that gets HTTP POSTed to, which can return a new "page" with an image and buttons, and so on and so on.

This choice of just being mostly images and buttons actually makes the Frames Protocol simpler to create a viewer from scatch. No need to implement all Web technologies. No need to worry about security and privacy holes that Web technologies introduce.

Although the Frames Protocol could be used outside of Farcaster, at the time of writing, Farcaster clients (such as Warpcast) are the only major (client-side) platform to support it.

(The server-side of the Frames Protocol, which is called a Frame Server, is an just HTTP resource — which some might loosely call an HTTP (or HTTP) URL.)

Farcaster

Before we get into the Frames Protocol let's quickly go over Farcaster — since the Frames Protocol originated with Farcaster.

Farcaster is a decentralized social-media network — and is similar in many ways to other decentralized social-media networks, such as the Fediverse (which includes Mastodon, Pleroma, Pixelfed, PeerTube, Misskey, Lemmy, Kbin, GreatApe, Akkoma, etc), and Bluesky.

And in particular, Farcaster is a micro-blogging social-media network platform.

The most famous micro-blogging social-media network platform is Twitter.. But the Fediverse's Mastodon, Akkoma, Misskey, Pleroma and others are also micro-blogging social-media network platforms. And so too is Bluesky.

All of these (including Farcaster) are similar to Twitter..

HTML

One of the main languages of the Web is HTML.

HTML looks like this: 


The following is <b>bold</b> and <a href="http://example.com/">this</a> is a link.

Although typically, HTML comes as a whole page (rather than a fragment), and thus usually looks more like this: 


<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
    <head>
        <meta charset="utf-8" /<
        <title>An Example</title>
    </head>
    <body>

        <p>
            The following is <b>bold</b> and <a href="http://example.com/">this</a> is a link.
        </p>

    </body>
</html>

The Frames Protocol actually only uses a tiny part of HTML.

HTML <meta> Element

The HTML <meta> element has been around since the 1990s.

If you look at the old HTML 2.0 specification (i.e., IETC RFC-1866 in section 5.2.5.), which was created back in the 1990s, you can see how the HTML <meta> element was defined back then.

When creating a Frames Protocol application, you can effectively ignore almost all of HTML except for one HTML element — the HTML <meta> element.

The Frames Protocol only uses the HTML <meta> element. And it (the Frames Protocol) uses the HTML <meta> element in a very particular way.

OpenGraph

The Frames Protocol usage of the HTML <meta> element takes inspiration from the OpenGraph protocol.

Here is an example of a web-page using the OpenGraph protocol: 


<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
    <head>
        <meta charset="utf-8" /<


	<meta property="og:title" content="Hello world!" />
	<meta property="og:type"  content="article" />
	<meta property="og:image" content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="og:url"   content="http://www.example.com/article/hello-world.xhtml" />


        <title>An Example</title>
    </head>
    <body>

        <p>
            The following is <b>bold</b> and <a href="http://example.com/">this</a> is a link.
        </p>

    </body>
</html>

Since there is a lot of HTML code there, let's just focus on the OpenGraph part of it: 


	<meta property="og:title" content="Hello world!" />
	<meta property="og:type"  content="article" />
	<meta property="og:image" content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="og:url"   content="http://www.example.com/article/hello-world.xhtml" />

It is rather simple. It is just name-value pairs.

The "og" part (in "og:title", "og:type", "og:image", and "og:url") is short for "OpenGraph". And thus all these OpenGraph names are namespaced.

So, what does that actually do‽

Frames <meta>

The Frames Protocol defines its own list of name-value pairs also using the HTML <meta> element, similar to OpenGraph.

When creating a Frames Protocol application, you MUST include these:

  • fc:frame
  • fc:frame:image
  • og:image

(Note that the last required name is from OpenGraph! Where the first two have been created by the Frames Protocol.)

Here is an example of these in HTML <meta> elements: 


	<meta property="fc:frame"       content="vNext" />
	<meta property="fc:frame:image" content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="og:image"       content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />

Or the same in a more full HTML document: 


<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
    <head>
        <meta charset="utf-8" /<


	<meta property="fc:frame"       content="vNext" />
	<meta property="fc:frame:image" content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="og:image"       content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />


        <title>Example Frame Server</title>
    </head>
    <body>

        <p>
		This is an example Frame Server.
        </p>

    </body>
</html>

So, what does that actually do‽

Buttons

We already went over three of the names the Frames Protocol uses with the HTML <meta> element:

  • fc:frame
  • fc:frame:image
  • og:image

But there are other optional names, too. We are going to look at 4 more of them:

  • fc:frame:button:1
  • fc:frame:button:2
  • fc:frame:button:3
  • fc:frame:button:4

These add buttons to a Frames Protocol application.

One Button

For example, this has one button: 


	<meta property="fc:frame"          content="vNext" />
	<meta property="fc:frame:image"    content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="og:image"          content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="fc:frame:button:1" content="the first button" />

Note that this looks exactly the same as the previous example, except one more HTML <meta> element has been added to it: 


	<meta property="fc:frame:button:1" content="the first button" />

Two Buttons

Here is another example that has two buttons: 


	<meta property="fc:frame"          content="vNext" />
	<meta property="fc:frame:image"    content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="og:image"          content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="fc:frame:button:1" content="the first button" />
	<meta property="fc:frame:button:2" content="the second button" />

Again, the focus is on the fc:frame:button:* HTML <meta> elements: 


	<meta property="fc:frame:button:1" content="the first button" />
	<meta property="fc:frame:button:2" content="the second button" />

Three Buttons

This example has three buttons: 


	<meta property="fc:frame"          content="vNext" />
	<meta property="fc:frame:image"    content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="og:image"          content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="fc:frame:button:1" content="the first button" />
	<meta property="fc:frame:button:2" content="the second button" />
	<meta property="fc:frame:button:3" content="the third button" />

Focusing on the fc:frame:button:* HTML <meta> elements: 


	<meta property="fc:frame:button:1" content="the first button" />
	<meta property="fc:frame:button:2" content="the second button" />
	<meta property="fc:frame:button:3" content="the third button" />

Four Buttons

And finally, this example has four buttons: 


	<meta property="fc:frame"          content="vNext" />
	<meta property="fc:frame:image"    content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="og:image"          content="/images/4aigvXF62jMY8iRzFN8x.jpeg" />
	<meta property="fc:frame:button:1" content="the first button" />
	<meta property="fc:frame:button:2" content="the second button" />
	<meta property="fc:frame:button:3" content="the third button" />
	<meta property="fc:frame:button:4" content="the forth button" />

At the time of writing the Frames Protocol does not support more than 4 buttons.

Buttons Presses

So what happens when the user presses a button‽