Farcaster 框架：使用 Frog 構建你的第一個框架

07-16

本文為機器翻譯

展示原文

作者：菲戈， IOSG Ventures

Farcaster 是一個Decentralized Social網絡，提供了 Twitter 和 Reddit 等傳統平台的替代方案。用戶可以建立個人資料、發布「演員表」並追蹤其他人，同時保留其帳戶和連結的所有權。這種去中心化的方法允許使用者在不同的應用程式之間移動而不會遺失資料或連接，從而優先考慮使用者的自主權、隱私和互通性。

什麼是框架？

框架是 Farcaster 的一項獨特功能，允許用戶將互動式體驗直接嵌入到他們的 Cast 中。這將靜態貼文變成動態內容，增強用戶體驗。框架可以包括民意調查、即時更新或整個應用程式等元素，為用戶參與提供各種方式。

框架如何運作

從技術角度來看，Farcaster Frames 同時使用鏈上和鏈下功能。它們是嵌入在 Casts 中的輕量級 Web 應用程式。框架規範概述了創建相容框架的技術要求和標準，確保它們在 Farcaster 生態系統中運作。

框架擴展了開放圖譜標準，將靜態嵌入轉變為互動式體驗。開發人員首先選擇開放圖譜圖像，然後添加互動式按鈕。單擊按鈕時，會觸發回調，以新內容或操作更新框架。這種互動由使用者和開發人員管理，從而形成了一種去中心化的方法。

Warpcast 是 Farcaster 的主要客戶之一，支援這些互動式框架，讓用戶在平台上建立動態內容。下圖說明了標準開放圖譜 (OG) 嵌入與 Warpcast 內的框架 OG 之間的差異。

框架範例

Farcaster Frames 的應用是多種多樣的，既能滿足使用者的需求，也能滿足開發者的需求。這裡有些例子：

互動民意調查：用戶可以在他們的演員中嵌入即時民意調查，允許追蹤者投票並查看即時結果。這增強了用戶參與度並促進社區互動。
NFT 展示：開發人員可以創建框架，讓使用者可以直接在他們的 Cast 中鑄造和展示 NFT。這彌合了社交媒體和 NFT 世界之間的差距，實現了新的創意表達形式。
即時來源和畫廊：框架可用於建立即時來源或互動式畫廊，提供一種動態且引人入勝的方式在 Farcaster 上共享內容。

透過實現這些互動體驗，Farcaster Frames 正在改變社群媒體上內容的創建、分享和互動方式。它們為開發人員提供了一個框架來建立與 Farcaster 網路無縫整合的創新應用程序，為內容管理和用戶參與開闢了新的可能性。

什麼以及為什麼青蛙？

Frog由Paradigm和Wevm開發，是一個旨在創建Farcaster框架的框架。它簡化了流程，使開發人員能夠輕鬆建立互動式和高效能的框架。 Frog 包括內建偵錯器、即時重新載入和無縫部署選項。

目前建構 Farcaster 框架的挑戰

在新框架上進行開發可能會帶來以下挑戰：

複雜的狀態管理：有效處理客戶端反應性和狀態。
大小和行為約束：導航框架標籤大小和功能的限制。
安全性問題：確保安全訊息驗證和幀完整性。
效能最佳化：管理負載效能並最大程度地減少不必要的 HTML 內容。

青蛙如何解決這些挑戰

Frog 透過引入簡化框架開發的功能來解決這些問題：

具有即時重新載入功能的本機偵錯器：提供即時回饋，加快開發速度。
簡化的狀態管理：利用狀態匯出輕鬆進行狀態處理。
增強的安全性：提供用於安全框架開發的內建驗證工具。
優化的效能：能夠創建高度優化的框架以實現快速載入。
靈活部署：允許部署到任何 JavaScript 執行時，避免供應商鎖定並提供更大的靈活性。

使用 Frog 不僅可以簡化開發流程，還可以更輕鬆地創建安全、高效和互動的框架，從而增強開發人員的體驗。這為 Farcaster 的創新開啟了無限的可能性。

專案教學：MarketCapOf 框架

我們將建立一個受 MarketCapOf 啟發的 Farcaster 框架。該工具使我們能夠直觀地看到一種加密貨幣 (A) 具有另一種加密貨幣 (B) 的市值時的價格。它是深入了解加密貨幣市場的有用工具。

以下是我們將要創建的內容的快速預覽：

在本教程結束時，您將：

建立一個 Farcaster 框架，能夠根據另一種加密貨幣的市值動態計算並顯示一種加密貨幣的價格。
在 Warpcast 上驗證和測試您的 Frame，確保其在 Farcaster 生態系統中無縫運行。

讓我們開始吧！

先決條件

在我們開始之前，請確保您具備以下條件：

已安裝 npm ：確保您的電腦上安裝了 Node Package Manager (npm)。如果您還沒有，可以從此處下載並安裝。
Farcaster 帳戶：如果您還沒有，請建立 Farcaster 帳戶。您可以在 Farcaster 註冊。

注意：本教學假設您熟悉 JavaScript 並對 JavaScript 有基本的了解。

設定您的項目

首先，打開終端並使用 Frog 初始化項目：

 npm init frog -- -t next

您應該會看到以下設定提示：

按照說明為您的項目命名。

項目初始化後，

導航至專案目錄： cd 專案名稱
我建議在您首選的 IDE 中開啟專案資料夾。例如，如果您使用 VS Code，則可以使用下列命令執行此操作： code 。
現在在專案資料夾中，安裝必要的依賴項： npm install
啟動開發伺服器！ npm 運行開發

伺服器運行後，在瀏覽器中存取 https://localhost:3000/api/dev。

Frog 的最佳功能之一是它配備了內建的框架測試器 UI。該工具提供了一種直觀的方式來直觀地查看程式碼中所做的更改，從而使開發更快、更有效率。

預設模板是一個簡單的演示框架，允許您選擇一個項目並查看您的選擇。雖然這是一個有用的起點，但仍需要一些工作才能將其轉換為我們的 MarketCapOf 框架。

建立我們的應用程式

讓我們深入建立我們的應用程式。首先導覽至app/api/[[...routes]]/route.tsx 。該檔案是我們應用程式的核心，也是幀端點所在的位置。您將看到 Frog 應用程式是透過呼叫 Frog 類別來實例化的。

我們將修改它來設定我們的應用程式。讓我們從新增標題開始：

常量應用程式 = 新青蛙（{
 資產路徑：“/”，
 基本路徑：“/api”，
 title: "Frame Market Cap", // 新增標題
 // 提供一個集線器來啟用幀驗證。
 // hub: neynar({ apiKey: 'NEYNAR_FROG_FM' })
 });

Farcaster 框架由兩個主要 UI 元件組成：一個圖像和一組 Intents。我們可以透過傳回的幀響應的圖像和意圖屬性在 Frog API 中指定這些元件。

在同一個檔案中，您還將看到將圖像返回到 UI 是多麼容易。透過編寫 JSX 程式碼並套用樣式，Frog 會自動將其轉換為圖像。

 app.frame('/', (c) => {
 const { 按鈕值，輸入文本，狀態 } = c
 const 水果 = inputText ||按鈕值
 返回 c.res({
 圖像： （
 <div>
 {/* 這裡的JSX程式碼會自動轉換成圖片 */}
 </div>
 ),
 意圖：[
 …
 ],
 })
 })

設計我們的應用程式流程

我們應用程式的主要思想很簡單。其工作原理如下：

從/ root 開始，第一頁圖像將描述我們的應用程式的功能並提示使用者輸入。
使用者將輸入一對令牌（令牌 A 和令牌 B）。用戶點擊提交。
我們將此輸入傳遞給新的/compare框架，然後從 CoinMarketCap (CMC) API 取得所要求代幣的資料。

Intent屬性將保存一系列可操作的項目。在我們的例子中，我們將只為令牌對（格式為 tokenA、tokenB）保留一個 TextInput 和一個提交按鈕。

我們還需要指定一個操作來確定使用者提交後將被帶到的位置。讓我們讓此操作將使用者定向到/compare端點。

我們也刪除了 return 上面關於c變數的不必要的程式碼。我們很快就會討論更多相關內容。

進行這些更新後，我們將：

 app.frame("/", (c) => {
 返回 c.res({
 動作：“/比較”，
 圖像： （
 <div
 風格={{
 alignItems：“中心”，背景：“黑色”，顯示：“flex”，flexDirection：“列”，
 flexWrap：“nowrap”，高度：“100％”，justifyContent：“中心”，textAlign：“中心”，寬度：“100％”，
 }}
 >
 <div
 風格={{
 顏色：“白色”，字體大小：60，字體樣式：“正常”，空白：“預換行”，
 }}
 >
 {「檢查 A 的價格\n 與 B 的市值！」}
 </div>
 </div>
 ),
 意圖：[<TextInput placeholder="TOKENA,TOKENB" />，<Button value="mine">立即檢查！ </Button>]，
 });
 });

透過這些更改，我們的新根/框架已設定完畢並準備就緒！現在，刷新 Frog UI 以查看包含新描述和輸入欄位的更新框架。

但是，如果您輸入令牌（例如ETH、 BTC ）並按“立即檢查！”，則不會發生任何情況。這是因為我們還沒有創建/compare端點！讓我們現在就開始做吧。

上下文傳遞

在同一個Route.tsx檔案中，我們建立一個新的幀路由。我們可以先複製 / 路線的內容。但是，在進行任何更改之前，讓我們透過記錄 c 參數的值來仔細了解c參數的實際意義。現在，我們可以先刪除這個新框架的動作和意圖屬性。

 app.frame("/比較", (c) => {
 控制台.log({ c })

 返回 c.res({
 圖像： （
 <div
 風格={{
 alignItems：“中心”，背景：“黑色”，顯示：“flex”，flexDirection：“列”，
 flexWrap：“nowrap”，高度：“100％”，justifyContent：“中心”，textAlign：“中心”，寬度：“100％”，
 }}
 >
 <div
 風格={{
 顏色：“白色”，字體大小：60，字體樣式：“正常”，空白：“預換行”，
 }}
 >
 {「檢查 A 的價格\n 與 B 的市值！」}
 </div>
 </div>
 ）
 });
 });

刷新框架 UI，輸入內容，然後按一下「立即檢查！」。讓我們來看看記錄的c值：

從這個日誌中，我們看到c實際上是框架上下文物件。它儲存有用的信息，例如從最後一幀提交的inputText 。此c參數包含有關幀和先前上下文的其他屬性，例如：

幀資料（trustedData/untrustedData）
與之互動的按鈕索引/值或輸入值
匯出和設定狀態的函數
幀的初始/開始路徑
框架的當前 URL
和更多

這就是我們將上下文和使用者輸入從一幀傳遞到下一幀的方式。我們可以使用這個上下文來提取使用者提交的令牌對資訊。現在，我們可以忽略frameData ，因為我們還沒有驗證框架。當我們在後面的部分中設定幀驗證時，將介紹這一點。現在，我們將使用c.inputText來取得使用者輸入的令牌對，並在/compare路由中對其進行相應處理。

設定我們的“/compare”框架

檢索請求的代幣（代幣 A 和代幣 B）後，來自 CoinMarketCap 的必要數據將包括每個代幣的當前價格和完全稀釋估值 (FDV)。現在，讓我們使用靜態模擬資料來設定一個基本結構，並建立一個簡單的 UI 佈局來顯示結果。

這是/compare框架的更新程式碼：

 app.frame("/比較", (c) => {
 const { inputText = "" } = c;

 const tokenA = inputText.split(",")[0].toUpperCase(); //ETH
 const tokenB = inputText.split(",")[1].toUpperCase(); //BTC

 // 令牌 A 和令牌 B 的模擬數據
 常量價格A = 3000；
 常數 marketCapA = 360000000；

 常量價格B = 57000；
 const marketCapB = 1100000000;

 // 如果代幣 A 具有代幣 B 的市值，則計算代幣 A 的價格
 const 乘數 = marketCapB / marketCapA;
 const 計算價格 = 乘數 * 價格A;

 返回 c.res({
 圖像： （
 <div
 風格={{
 alignItems：“中心”，背景：“黑色”，顯示：“flex”，flexDirection：“列”，高度：“100％”，
 justifyContent：“center”，textAlign：“center”，寬度：“100％”，顏色：“白色”，whiteSpace：“預換行”
 }}
 >
 <div
 樣式={{ fontSize: 40, marginBottom: 20 }}
 >
 {`${tokenA}，市值為 ${tokenB}`}
 </div>
 <div
 樣式={{ fontSize: 80, marginBottom: 30 }}
 >
 {`$${calculatedPrice.toFixed(2)} (${multiplier.toFixed(2)}x)`}
 </div>
 <div
 樣式={{ fontSize: 30 }}
 >
 {`${tokenA} 市值：$${marketCapA.toFixed(2)}\n${tokenB} 市值：$${marketCapB.toFixed(2)}`}
 </div>
 </div>
 ),
 });
 });

現在，返回框架 UI 並輸入ETH、 BTC作為輸入進行測試。

極好的！現在我們可以看到公式邏輯有效，而且我們的佈局看起來也不錯。接下來，我們需要設定實際的資料檢索。

建立實用函數

在專案的根目錄中，建立一個新的utils資料夾並初始化該資料夾中的index.tsx檔案。這是我們儲存實用函數的地方。

我們的應用程式依賴檢索動態價格資料的能力。為此，我們將使用 CoinMarketCap API。您可以在此處取得免費的 API 金鑰。

首先，在專案的根目錄中建立一個.env.local檔案。這是我們儲存CMC_API_KEY 的位置。

 // .env.local
 CMC_API_KEY=<您的coin市值 API 金鑰>

您可能需要在終端機中重新啟動程式才能讀取環境檔案。

接下來，將以下程式碼加入utils資料夾中的index.tsx檔案：

匯出 const fetchTokenData = async (tokenSymbols: string) => {
 const 回應 = 等待 fetch(`https://pro-api.coinmarketcap.com/v2/cryptocurrency/quotes/latest?symbol=${tokenSymbols}`, {
 標題：{
 “X-CMC_PRO_API_KEY”：process.env.CMC_API_KEY 作為字串，
 },
 });

 如果（！response.ok）{
 throw new Error(`無法取得資料：${response.statusText}`);
 }

 返回response.json();
 };

匯出 const getTokenPrice = async (tokenSymbol: string) => {
 嘗試 {
 const tokenData = 等待 fetchTokenData(tokenSymbol);
 const tokenArray = tokenData.data[tokenSymbol.toUpperCase()];

 if (!tokenArray || tokenArray.length === 0) {
 拋出新錯誤（`未找到 ${tokenSymbol} 的資料`）；
 }

 const tokenInfo = tokenArray[0];
 const usdQuote = tokenInfo.quote && tokenInfo.quote.USD;

 如果 (!usdQuote) {
 拋出新錯誤（`美元報價不適用於 ${tokenSymbol}`）；
 }

 返回 {
 價格：usdQuote.價格，
 marketCap: usdQuote.market_cap,
 };
 } catch（錯誤：任何）{
 console.error(`取得 ${tokenSymbol} 的代幣價格時出錯:`, error.message);
 返回 {
 價格： 空，
 市值：空，
 錯誤：錯誤訊息，
 };
 }
 };

在同一個檔案中，我們還添加一個formatNumber函數，我們可以使用該函數在整個應用程式中正確格式化數字：

匯出 const formatNumber = (num: number) => {
 讓 formattedNum = num.toFixed(2);
 return formattedNum.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
 };

有了這些實用函數，我們現在可以從 CoinMarketCap 取得代幣資料並格式化數字以供顯示。

完成“/比較”

現在讓我們用我們寫的實用函數來更新/compare框架。由於獲取代幣價格需要時間，因此請記住將wait添加到函數的開頭，並將函數聲明設為async 。

首先，更新/compare框架以使用實用函數：

從 './utils' 導入 { getTokenPrice, formatNumber };

 app.frame("/compare", async (c) => {
 const { inputText = "" } = c;

 const tokenA = inputText.split(",")[0].toUpperCase();
 const tokenB = inputText.split(",")[1].toUpperCase();

 const { 價格：priceA，marketCap：marketCapA，錯誤：errorA } =等待 getTokenPrice（tokenA）;
 const { 價格：priceB，marketCap：marketCapB，錯誤：errorB } =等待 getTokenPrice（tokenB）;

 // ...
 });

接下來，新增一個按鈕以允許使用者返回根框架並輸入另一對。為此，我們只需添加一個帶有導航回/ 的操作的按鈕。

返回 c.res({
 行動： ”/”，
 圖像： （
 // ...
 ),
 意圖：[<Button>嘗試另一對</Button>]，
 });

最後，讓我們添加一些錯誤處理並完成/compare框架準備就緒！

 app.frame("/compare", async (c) => {
 const { inputText = "" } = c;

 嘗試 {
 const tokens = inputText.split(",");
 if (tokens.length < 2) {
 throw new Error("輸入無效。請提供兩個標記，以逗號分隔。");
 }

 const tokenA = tokens[0].toUpperCase();
 const tokenB = tokens[1].toUpperCase();

 const { 價格：priceA，marketCap：marketCapA，錯誤：errorA } =等待 getTokenPrice（tokenA）;
 const { 價格：priceB，marketCap：marketCapB，錯誤：errorB } =等待 getTokenPrice（tokenB）;

 if (錯誤A || 錯誤B) {
 拋出新的錯誤（錯誤A || 錯誤B）；
 }

 const 乘數 = marketCapB / marketCapA;
 const 計算價格 = 乘數 * 價格A;

 返回 c.res({
 行動： ”/”，
 圖像： （
 <div
 風格={{
 alignItems：“中心”，背景：“黑色”，顯示：“flex”，flexDirection：“列”，高度：“100％”，
 justifyContent：“center”，textAlign：“center”，寬度：“100％”，顏色：“白色”，whiteSpace：“預換行”
 }}
 >
 <div
 樣式={{ fontSize: 40, marginBottom: 20 }}
 >
 {`${tokenA}，市值為 ${tokenB}`}
 </div>
 <div
 樣式={{ fontSize: 80, marginBottom: 30 }}
 >
 {`$${formatNumber(calculatedPrice)} (${formatNumber(multiplier)}x)`}
 </div>
 <div
 樣式={{ fontSize: 30 }}
 >
 {`${tokenA} 市值：$${formatNumber(marketCapA)}\n${tokenB} 市值：$${formatNumber(marketCapB)}`}
 </div>
 </div>
 ),
 意圖：[<Button action="/">嘗試另一對</Button>]，
 });
 } catch（錯誤：任何）{
 console.error("發生錯誤：", error.message);
 返回 c.res({
 行動： ”/”，
 圖像： （
 <div
 風格={{
 alignItems：“中心”，背景：“黑色”，顯示：“flex”，flexDirection：“列”，高度：“100％”，
 justifyContent：“center”，textAlign：“center”，寬度：“100％”，顏色：“白色”，whiteSpace：“預換行”
 }}
 >
 <div
 樣式={{ fontSize: 40, marginBottom: 20 }}
 >
 {`發生錯誤:(`}
 </div>
 </div>
 ),
 意圖：[<Button action="/">返回並重試</Button>]，
 });
 }
 });

試一試！您的應用程式現在應該能夠從 CoinMarketCap 檢索動態價格資料並在 UI 中顯示格式正確的計算。我們的應用程式完成了！ 🎉

驗證和測試

幀驗證

在將框架投入生產之前，驗證和驗證框架至關重要。如果沒有驗證，輸入可能會被欺騙，從而損害資料完整性。我們希望用戶透過 Warpcast 用戶端進行驗證並登入 Farcaster，確保與框架的互動是真實的。

對於收集選票或其他關鍵互動等用例，驗證至關重要。但是，對於更簡單的應用程式（例如我們當前的範例），它可能並不那麼重要。

Frog 透過啟用集線器讓驗證過程變得簡單。兩個最常用的集線器是 Neynar 和 Pinata。在我們的程式碼範本中，我們可以取消 Neynar 程式碼的註釋，以啟用對我們的框架的驗證。

啟用內納爾的方法如下：

 // 其他進口..
從「青蛙/集線器」導入{ neynar }；

常量應用程式 = 新青蛙（{
 資產路徑：“/”，
 基本路徑：“/api”，
 標題：“框架市值”，
 集線器： neynar({ apiKey: "NEYNAR_FROG_FM" }),
 });

啟用後，您的框架現在將需要驗證。但是，這表示在 localhost 上執行應用程式將導致無效簽章錯誤，因為 localhost 未登入 Farcaster。

現在，我們需要探索在連接到 Farcaster 用戶端的線上設定中測試框架的方法。

線上測試

要正確測試您的 Farcaster 框架，您需要登入 Farcaster 帳戶。這可以透過兩種方式完成：

透過 Frog Test UI 登入：點擊 Frog Test UI 右上角的登入按鈕進行登入。
Warpcast 框架驗證器：使用 Warpcast 框架驗證器。

對於第二種方法，您需要使本機主機可以存取網際網路。我強烈推薦使用 ngrok。如果您使用的是Mac，則可以透過在終端機中執行brew install ngrok/ngrok/ngrok來安裝它。安裝後，只需輸入ngrok http 3000即可透過公用 URL 存取您的本機主機。

然後，前往 Warpcast 幀驗證器並輸入您的 ngrok URL。例如： https://7a32-193-142-202-2.ngrok-free.app/api

不過，我個人更喜歡第一種方法，因為它更快、更容易。您只需掃描登入二維碼，不到一分鐘即可連線！

登入後，讓我們嘗試在/compare端點再次查看c的值：

我們可以看到已驗證的欄位現在顯示為true 。有了這個，我們現在還可以從frameData中獲取inputText ，這更安全，因為它已經過驗證。

更新您的/compare框架以使用frameData提取inputText ：

 app.frame("/compare", async (c) => {
 控制台.log({ c });

 // const { inputText = "" } = c;

 // 啟用驗證時使用它
 const { 幀數據，已驗證 } = c
 const { inputText = ""} =frameData || {}

 // ...
 });

透過確保您的框架經過驗證，您可以增強安全性和信任，確保使用者互動合法且受到保護。

獎勵：部署！

作為獎勵，您還可以使用 Vercel CLI 將應用程式部署到 Vercel。這將允許您與其他人共享您的 Farcaster 框架並在網路上即時查看它。要部署，只需執行以下步驟：

安裝 Vercel CLI： npm install -g vercel
登入 Vercel： vercel 登入
要部署您的應用程序，請從專案的根目錄執行： npm run deploy

有關更詳細的說明，您可以參閱有關部署到 Vercel 的 Frog 文件。

下一步

恭喜建立您的第一個 Farcaster 框架！現在您已經掌握瞭如何使用 Frog 輕鬆建立和測試框架的基礎知識。借助 Frames，您將步入 Farcaster 上充滿互動可能性的世界。這只是個開始;在這個令人興奮的創新空間中還有很多東西值得探索和創造。創造力和參與的潛力是無限的。

您可以考慮的一些方向是探索更高級的框架交互，例如：

交易框架：發展與智慧合約互動的框架，直接在 Farcaster 內實現鏈上交易。
社交整合框架：利用 Farcaster 的本地社交資料創建豐富的社交感知應用程式。
進階互動：設計框架引導使用者完成詳細流程以增強參與度。

要進一步探索 Frames，請查看我們的測試版IOSG 開發人員中心網站，您可以在其中找到本教學和未來部落格、學習材料、活動和其他以開發人員為中心的資源的 GitHub 儲存庫。您也可以加入我們在 Telegram 上的IOSG 開發者社區，獲取所有技術方面的支持和討論！

如果您覺得本教學有幫助，請分享並按讚。再次感謝，請繼續關注更多！繼續探索和建設！

資源

Farcaster 框架： https://docs.farcaster.xyz/learn/what-is-farcaster/frames
青蛙： https://www.paradigm.xyz/2024/02/frames

Farcaster 框架：使用 Frog 建立您的第一個框架最初發表在IOSG Ventures 的Medium 上，人們透過突出顯示和回應這個故事來繼續對話。