How to Use Farcaster Frame Analytics

We’ve been busy at Pinata making tools and guides for Farcaster, and we’re truly excited about our newest feature: Frame Analytics. If you have been keeping up with our blog, you might have seen several of our tutorials and posts on Frames, including How to Build a Frame that Mints NFTs, as well as our Frame Development Kit. This newest feature uses both the FDK and the Pinata App to provide developers precision metrics on how their frames are doing. With that said, let’s get right into it and show you how it works!

Farcaster Integration

The first thing you’ll need to do is connect your Farcaster account to your Pinata account. If you haven’t already, you can create a Pinata account for free and start using Frame Analytics right away! Once signed in, click on the profile button in the top right, then select “Integrations.”

Once on the Integrations page, click “Sign In” for the Farcaster integration. Once you do this, it will open a QR code you can scan with your phone. You will need Warpcast installed on your mobile device and logged into a Farcaster account.

FDK Setup

The other half of getting Frame Analytics setup is building your frame with the Pinata FDK. We have done previous tutorials on how to build this, so we will only do a brief recap, but if you want a full tutorial, check out this blog post. While still inside the Pinata App, you will want to make an API Key and grab the domain for your Dedicated Gateway. Then, inside your JavaScript framework of choice, you will want to initialize the FDK with the following code.

import { PinataFDK } from "pinata-fdk";
const fdk = new PinataFDK({
    pinata_jwt: "YOUR_PINATA_JWT",
    pinata_gateway: "YOUR_PINATA_GATEWAY"}, 
    //do not include https:// in your gateway url
);

Once you have initialized it, you can call frame analytics anytime you’d like by passing in a frame_id (your choice what to name it) and the raw payload from the Frame action (typically acquired through something like const body = await req.json()).

// This should be the raw payload from the frame action
const frame_data = {
  untrustedData: {
    fid: 2,
    url: "https://fcpolls.com/polls/1",
    messageHash: "0xd2b1ddc6c88e865a33cb1a565e0058d757042974",
    timestamp: 1706243218,
    network: 1,
    buttonIndex: 2,
    inputText: "hello world", // "" if requested and no input, undefined if input not requested
    castId: {
      fid: 226,
      hash: "0xa48dd46161d8e57725f5e26e34ec19c13ff7f3b9",
    },
  },
  trustedData: {
    messageBytes: "d2b1ddc6c88e865a33cb1a565e0058d757042974...",
  },
};
const frame_id = "my-unique-frame-name"

await fdk.sendAnalytics(frame_id, frame_data)

Here’s an example from our previous tutorial on How to Build a Frame that Mints NFTs where we call fdk.sendAnalytics whenever someone clicked on a button.

import { NextRequest, NextResponse } from "next/server";
import { PinataFDK } from "pinata-fdk";

const fdk = new PinataFDK({
  pinata_jwt: process.env.PINATA_JWT as string,
  pinata_gateway: process.env.GATEWAY_URL as string,
});

export async function POST(req: NextRequest, res: NextResponse) {
  const body = await req.json();
  const buttonId = body.untrustedData.buttonIndex;
  const { isValid, message } = await fdk.validateFrameMessage(body);
  if (buttonId === 1) {
    try {
      if (isValid) {
        await fdk.sendAnalytics("frame-mint-tutorial-blog", body);
      }
      return NextResponse.redirect(
        "https://www.pinata.cloud/blog/how-to-build-a-farcaster-frame-that-mints-nfts",
        { status: 302 },
      );
    } catch (error) {
      console.log(error);
      return NextResponse.json({ error: error });
    }
  } else {
    try {
      if (isValid) {
        await fdk.sendAnalytics("frame-mint-tutorial-video", body);
      }
      return NextResponse.redirect("https://youtu.be/5VVOMolm-TA", {
        status: 302,
      });
    } catch (error) {
      console.log(error);
      return NextResponse.json({ error: error });
    }
  }
}

This is built in Next.js and functions as a /redirect route where, depending what button the user clicks on, we send analytics and return the redirect response. As you can see, we can use two different frame_id  based on what the user presses, which will feed back into our Frame Analytics Dashboard.

Frame Analytics Dashboard

If you sign back into the Pinata App, you can navigate to the Frame Analytics Dashboard by clicking on Frame Analytics on the side bar. Once there, you can view all the interactions, as well as unique users over time. As you can see below, we added our new endpoints for mint, blog, and video to see the distinction!

Wrapping Up

This is only the beginning of our new Frame Analytics tool, and we would love your feedback as to what you would find helpful as a developer! Be sure to join /pinata on Farcaster to stay up to date with all the features, tutorials, and ideas we are shipping. Also check out our new Docs that feature a page just for Farcaster and give you an API reference for the Pinata Hub!

Happy Pinning!

‍