วิธีใช้ Privy API: Embedded Wallets และ Social Auth สำหรับ Web3

การเริ่มต้นใช้งานแอป Web3 ยังคงทำให้ผู้ใช้ส่วนใหญ่ถอยห่างตั้งแต่ขั้นตอนแรก วลี Seed phrase, ส่วนขยายเบราว์เซอร์ และค่าธรรมเนียม gas เปลี่ยนการลงทะเบียนที่ใช้เพียงสองครั้งเป็นการต่อสู้ยาวนานสิบนาที Privy API แก้ไขปัญหานี้โดยมอบกระเป๋าเงินแบบฝัง (embedded wallet) ให้ผู้ใช้ใหม่ทุกคนผ่านการเข้าสู่ระบบที่คุ้นเคย เช่น อีเมล, SMS, Google, Apple หรือกระเป๋าเงินที่มีอยู่แล้วอย่าง MetaMask คุณจะได้รับผู้ใช้ที่เป็น native crypto โดยไม่ต้องขอให้ใครติดตั้งส่วนขยายเบราว์เซอร์

ปัจจุบัน Privy รองรับกระเป๋าเงินสำหรับ Blackbird, Friend.tech, OpenSea และแอปพลิเคชันอื่น ๆ อีกมากมายนับพัน และผลิตภัณฑ์นี้รองรับ Ethereum, Solana และเชน EVM ใดๆ คู่มือนี้จะนำเสนอขั้นตอนการทำงานของนักพัฒนาอย่างครบถ้วน: การสร้างแอป Privy, การเชื่อมต่อ React SDK, การยืนยันโทเค็นบนเซิร์ฟเวอร์, การลงนามธุรกรรมด้วยกระเป๋าเงินแบบฝัง และการจัดส่ง webhook หากคุณต้องการเปรียบเทียบตัวเลือกอื่น ๆ เช่น ชุดเครื่องมือสำหรับนักพัฒนาของ MetaMask ให้เปิดหน้านี้ไว้และสลับไปมาได้

💡

ก่อนที่คุณจะอ่านโค้ด มีข้อควรรู้เกี่ยวกับเครื่องมือหนึ่ง Apidog คือวิธีที่คุณควรใช้ตรวจสอบทุกคำขอ HTTPS ที่ SDK ของ Privy สร้างขึ้นเบื้องหลัง ชี้แอปของคุณไปยังพร็อกซีท้องถิ่น, ดักจับ payload จริง และแก้ไขข้อผิดพลาดในการตรวจสอบสิทธิ์ได้ในไม่กี่วินาที แทนที่จะต้องมานั่งไล่ดู log

ปุ่ม

สรุปโดยย่อ (TL;DR)

Privy ผนวกรวมกระเป๋าเงินแบบฝังเข้ากับการเข้าสู่ระบบด้วยอีเมล, SMS, โซเชียล และกระเป๋าเงินภายนอก ภายใต้ SDK เดียว
React SDK มี PrivyProvider, useLogin, useWallets และ usePrivy hooks เพื่อรองรับขั้นตอนการยืนยันตัวตนและการลงนามทั้งหมด
@privy-io/server-auth ตรวจสอบ access token บนแบ็กเอนด์ของคุณ เพื่อให้คุณเชื่อถือ user ID ในทุกคำขอได้
กระเป๋าเงินรองรับ Ethereum, Solana และเชน EVM อื่นๆ พร้อมตัวเลือกการส่งออก (exportability) และลายเซ็นการอนุญาตสำหรับธุรกรรมสำคัญ
Webhook จะทำงานเมื่อมีการสร้างผู้ใช้, การเข้าสู่ระบบ และกิจกรรมเกี่ยวกับกระเป๋าเงิน ทำให้ฐานข้อมูลของคุณซิงค์อยู่เสมอโดยไม่ต้อง polling
Policy engine ของ Privy เพิ่ม MFA, allowlist และกฎธุรกรรมโดยไม่ต้องแก้ไขโค้ดแอปของคุณ

Privy API คืออะไร?

Privy คือแพลตฟอร์มโครงสร้างพื้นฐานสำหรับการยืนยันตัวตนและกระเป๋าเงิน มันมอบสามสิ่งให้กับแอปของคุณ: UI การเข้าสู่ระบบ, กระเป๋าเงินแบบฝังที่จัดเตรียมไว้ให้ผู้ใช้แต่ละคน และชุด REST endpoint สำหรับการตรวจสอบฝั่งเซิร์ฟเวอร์ กระเป๋าเงินแบบฝังจะอยู่ในพื้นที่ปลอดภัย (secure enclave) ดังนั้น Privy จะไม่เห็น private key และแบ็กเอนด์ของคุณก็เช่นกัน ผู้ใช้สามารถส่งออกคีย์ของตนได้ในภายหลังหากต้องการย้ายไปยังกระเป๋าเงินที่ดูแลเอง (self-custody wallet); ความยืดหยุ่นนี้เป็นส่วนสำคัญของการนำเสนอ

แพลตฟอร์มนี้คิดค่าบริการต่อกระเป๋าเงินที่ใช้งานรายเดือน ซึ่งหมายความว่าคุณสามารถเปิดตัวโปรโตไทป์ได้ฟรีและปรับราคาเพิ่มขึ้นตามการเติบโตของการใช้งาน แพ็กเกจฟรีรองรับผู้ใช้ที่ใช้งานรายเดือน 1,000 คน, แพ็กเกจ Pro เริ่มต้นที่ 149 ดอลลาร์ต่อเดือน และแพ็กเกจ Enterprise มีการจัดการ SLA แบบกำหนดเอง

การยืนยันตัวตนและการตั้งค่า

เริ่มต้นที่ privy.io และสร้างแอปใหม่จากแดชบอร์ด คุณจะได้รับสองค่าที่สำคัญ:

App ID (clxxxxx...) สำหรับ client SDK
App secret สำหรับ server SDK

ตั้งค่าวิธีการเข้าสู่ระบบที่อนุญาต (อีเมล, SMS, Google, Apple, Farcaster, กระเป๋าเงิน), เลือกเชนเริ่มต้นของคุณ และเพิ่มโดเมนของคุณลงในรายการต้นทางที่อนุญาต สำหรับ React ให้ติดตั้ง SDK:

npm install @privy-io/react-auth

ครอบแอปของคุณด้วย PrivyProvider:

import { PrivyProvider } from '@privy-io/react-auth';

export default function App({ Component, pageProps }) {
  return (
    <PrivyProvider
      appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
      config={{
        loginMethods: ['email', 'wallet', 'google'],
        embeddedWallets: { createOnLogin: 'users-without-wallets' },
        defaultChain: { id: 8453 }, // Base
        supportedChains: [{ id: 1 }, { id: 8453 }, { id: 137 }],
      }}
    >
      <Component {...pageProps} />
    </PrivyProvider>
  );
}

แฟล็ก createOnLogin จะจัดเตรียมกระเป๋าเงินแบบฝังให้ในครั้งแรกที่ผู้ใช้เข้าสู่ระบบโดยไม่มีกระเป๋าเงิน คุณสามารถควบคุมเชนที่รองรับได้; Solana มีการกำหนดค่า solanaClusters แยกต่างหาก

Core endpoint และการเรียกใช้ SDK

React SDK ของ Privy จัดการขั้นตอนส่วนใหญ่ ทำให้คุณไม่ค่อยต้องเรียกใช้ REST ดิบๆ อย่างไรก็ตาม server SDK และ webhook payloads ใช้รูปแบบโทเค็นเดียวกัน ดังนั้นการรู้ API พื้นฐานจะช่วยได้เมื่อเกิดปัญหา

การเรียกใช้การเข้าสู่ระบบและการอ่านข้อมูลผู้ใช้

import { usePrivy, useWallets } from '@privy-io/react-auth';

function LoginButton() {
  const { ready, authenticated, login, logout, user } = usePrivy();
  const { wallets } = useWallets();

  if (!ready) return <p>Loading...</p>;
  if (!authenticated) return <button onClick={login}>Sign in</button>;

  const embedded = wallets.find((w) => w.walletClientType === 'privy');

  return (
    <div>
      <p>Hi {user.email?.address ?? user.id}</p>
      <p>Wallet: {embedded?.address}</p>
      <button onClick={logout}>Log out</button>
    </div>
  );
}

useWallets จะคืนค่ากระเป๋าเงินทั้งหมดที่ผู้ใช้ได้เชื่อมโยงไว้ และฟิลด์ walletClientType จะบอกคุณว่า Privy สร้างกระเป๋าเงินใด นี่คือรูปแบบที่คุณใช้สำหรับ กระเป๋าเงินแบบฝังของ Privy

การลงนามธุรกรรม

const { wallets } = useWallets();
const wallet = wallets.find((w) => w.walletClientType === 'privy');

async function sendTx() {
  const provider = await wallet.getEthereumProvider();
  const hash = await provider.request({
    method: 'eth_sendTransaction',
    params: [{
      to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2',
      value: '0x38d7ea4c68000', // 0.001 ETH
    }],
  });
  console.log('tx hash', hash);
}

สำหรับ Solana ให้เปลี่ยน getEthereumProvider เป็น getSolanaProvider และส่งผ่านธุรกรรมที่ถูก serialize หากคุณต้องการจำลองรูปแบบการเข้าถึงข้อมูลจากผู้ให้บริการอย่าง Alchemy, Privy ทำงานร่วมกับพวกเขาได้เป็นอย่างดี; Privy จัดการคีย์, Alchemy จัดการ RPC

การตรวจสอบโทเค็นบนเซิร์ฟเวอร์

ติดตั้ง server SDK:

npm install @privy-io/server-auth

ทุกคำขอที่ยืนยันตัวตนจากส่วนหน้าของคุณจะส่ง Privy access token (JWT) มาด้วย ตรวจสอบบนเซิร์ฟเวอร์ก่อนที่คุณจะเชื่อถือ user ID ใดๆ:

import { PrivyClient } from '@privy-io/server-auth';

const privy = new PrivyClient(
  process.env.PRIVY_APP_ID,
  process.env.PRIVY_APP_SECRET
);

export async function GET(req) {
  const auth = req.headers.get('authorization')?.replace('Bearer ', '');
  try {
    const claims = await privy.verifyAuthToken(auth);
    // claims.userId is the Privy user DID
    return Response.json({ userId: claims.userId });
  } catch (err) {
    return new Response('Unauthorized', { status: 401 });
  }
}

คุณยังสามารถดึงออบเจกต์ผู้ใช้ทั้งหมด (`privy.getUser(userId)`) เพื่อตรวจสอบบัญชีที่เชื่อมโยง, ที่อยู่กระเป๋าเงิน และ metadata ที่กำหนดเองได้

การส่งออกกระเป๋าเงินแบบฝัง

Privy อนุญาตให้ผู้ใช้ส่งออก private key ได้ทุกเมื่อ ประสบการณ์ผู้ใช้เป็น hook เดียว:

import { useExportWallet } from '@privy-io/react-auth';

const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>Export private key</button>;

Privy จะแสดง modal แบบ iframe ที่ปลอดภัย; แอปของคุณจะไม่แตะต้องข้อมูลคีย์เลย

ลายเซ็นการอนุญาตและ Policy engine

สำหรับการดำเนินการที่ละเอียดอ่อน (การโอนจำนวนมาก, การเข้าสู่ระบบด้วยอุปกรณ์ใหม่), Privy รองรับ ลายเซ็นการอนุญาต (authorization signatures) คุณกำหนดนโยบายในแดชบอร์ด, แนบเข้ากับแอปของคุณ และ Privy จะบังคับใช้ MFA, allowlist หรือการอนุมัติที่ลงนามโดยเซิร์ฟเวอร์ก่อนที่ธุรกรรมจะดำเนินไป รายละเอียดอยู่ใน คู่มือ Privy authorization key เมื่อรวมกับตัวเลือก MFA (TOTP, SMS, passkey) จะช่วยลดช่องโหว่ส่วนใหญ่ของการเข้ายึดบัญชีที่กระเป๋าเงินธรรมดาเปิดทิ้งไว้

Webhooks

Privy จะโพสต์เหตุการณ์ JSON ไปยัง endpoint ของคุณเมื่อมีการเปลี่ยนแปลงวงจรชีวิตของผู้ใช้และกระเป๋าเงิน:

curl -X POST https://yourapp.com/webhooks/privy \
  -H "Content-Type: application/json" \
  -H "svix-id: msg_..." \
  -H "svix-signature: v1,..." \
  -d '{
    "type": "user.created",
    "user": { "id": "did:privy:...", "email": { "address": "a@b.com" } }
  }'

ตรวจสอบส่วนหัว svix-signature ด้วย webhook secret จากแดชบอร์ดก่อนที่คุณจะเขียนอะไรลงในฐานข้อมูลของคุณ

ข้อผิดพลาดทั่วไปและข้อจำกัดอัตรา (Rate Limits)

มีข้อผิดพลาดบางอย่างที่เกิดขึ้นบ่อยครั้ง:

invalid_token: JWT ของ frontend หมดอายุแล้ว เรียกใช้ getAccessToken() จาก usePrivy ก่อนที่คุณจะทำการ fetch; โทเค็นมีอายุหนึ่งชั่วโมง
403 origin_not_allowed: URL ที่คุณใช้งานไม่ได้อยู่ใน allowlist ของแดชบอร์ด Privy เพิ่ม https://yourapp.com และโดเมนสำหรับพรีวิวใดๆ
wallet_not_ready: คุณอ่าน useWallets ก่อนที่ ready จะเป็น true กำหนดให้การเรียกใช้ wallet ทั้งหมดขึ้นอยู่กับแฟล็ก ready
ข้อจำกัดอัตรา (Rate limits): REST endpoint อนุญาตให้ 100 คำขอต่อวินาทีต่อแอปในแพ็กเกจฟรี แอปส่วนใหญ่ไม่เคยถึงขีดจำกัดนี้; หากคุณถึง ให้รวมการเรียก getUser หรือแคชด้วย user ID

ใช้ Apidog เพื่อทดสอบ webhook ที่ล้มเหลวในเครื่อง วาง payload ดิบลงในคำขอ, แก้ไขส่วนหัว signature และเรียกใช้ dev server ของคุณซ้ำๆ จนกว่า handler จะทำงานผ่าน

ราคาของ Privy

ฟรี: รองรับกระเป๋าเงินที่ใช้งานรายเดือนสูงสุด 1,000 ใบ, วิธีการเข้าสู่ระบบหลัก, กระเป๋าเงินแบบฝังบน EVM + Solana
Pro: 149 ดอลลาร์ต่อเดือน, ขีดจำกัด MAW ที่สูงขึ้น, ชุด webhook เต็มรูปแบบ, staging app
Enterprise: SLA แบบกำหนดเอง, การสนับสนุนเฉพาะ, วิศวกรพร้อมให้บริการ, กฎ policy engine แบบกำหนดเอง

ตรวจสอบ privy.io/pricing สำหรับตัวเลขปัจจุบัน; ระดับราคาจะเปลี่ยนแปลงไปตามการเติบโตของผลิตภัณฑ์

การทดสอบ Privy API ด้วย Apidog

Client SDK ของ Privy จะซ่อนการเรียกใช้ HTTPS แต่การตรวจสอบโทเค็น, การค้นหาผู้ใช้ และ webhook ทุกรายการที่แบ็กเอนด์ของคุณจัดการเป็นคำขอ REST ปกติ นั่นคือสิ่งที่ Apidog มีประโยชน์ สร้าง Privy collection ใน Apidog, ใส่ app ID และ secret ของคุณเป็นตัวแปรสภาพแวดล้อม และเรียกใช้ endpoint เช่น GET /api/v1/users/{userId} หรือ POST /api/v1/users/{userId}/wallets โดยไม่ต้องออกจากเครื่องมือ

คุณยังสามารถบันทึก webhook payloads จากแดชบอร์ด, บันทึกเป็นคำขอ Apidog และเล่นซ้ำกับ local tunnel ได้ ตั้งค่าการทดสอบอัตโนมัติที่ตรวจสอบว่า JWT ที่ถูกต้องคืนค่าออบเจกต์ผู้ใช้ และ JWT ที่หมดอายุคืนค่า 401; รันการทดสอบเหล่านี้ทุกครั้งที่ deploy ดาวน์โหลด Apidog ฟรี และไม่ต้องวุ่นวายกับการใช้ cURL หากคุณย้ายจาก Postman แล้ว, คู่มือเวิร์กโฟลว์แบบเคียงข้างกันครอบคลุมการย้ายทั้งหมด

ปุ่ม

คำถามที่พบบ่อย

Privy แตกต่างจาก Web3Auth หรือ Magic อย่างไร?ทั้งสามมีกระเป๋าเงินแบบฝัง แต่ Privy เน้นหนักไปที่การยืนยันตัวตนแบบผสม (อีเมล + กระเป๋าเงิน + โซเชียล) และ policy engine ที่แอปขนาดใหญ่ต้องการ Web3Auth มุ่งเน้นไปที่การแบ่งคีย์ MPC; Magic นำเสนอผลิตภัณฑ์ magic-link ที่กว้างกว่า เลือก Privy เมื่อคุณต้องการทั้ง UI การเริ่มต้นใช้งานที่สะอาดตาและการควบคุมอย่างละเอียดว่ากระเป๋าเงินทำอะไรได้บ้าง

Privy รองรับ Solana หรือไม่?ใช่ กระเป๋าเงินแบบฝังทำงานบน Solana mainnet และ devnet และ React SDK จะเปิดเผย getSolanaProvider() สำหรับการลงนามและส่งธุรกรรม คุณสามารถกำหนดค่าทั้ง EVM และ Solana ในแอปเดียวกันได้

ผู้ใช้สามารถนำกระเป๋าเงินของตนเองมาใช้ได้หรือไม่?ใช่ MetaMask, Coinbase Wallet, WalletConnect, Phantom และอื่นๆ อีกมากมายหลายสิบตัวใช้งานได้ทันที Privy ถือว่ากระเป๋าเงินภายนอกเป็นบัญชีที่เชื่อมโยง ดังนั้น user DID เดียวกันจึงเป็นเจ้าของทั้งคีย์แบบฝังและคีย์ภายนอก

จะเกิดอะไรขึ้นหาก Privy ไม่สามารถใช้งานได้?ผู้ใช้ยังคงเข้าถึงกระเป๋าเงินที่ส่งออกได้ เนื่องจากคีย์อยู่ในพื้นที่ปลอดภัยของเบราว์เซอร์ของผู้ใช้ สำหรับแอปพลิเคชันที่ใช้งานจริง, เปิดใช้งานการส่งออกกระเป๋าเงินและจัดทำเอกสารเส้นทางสำรอง ดู คู่มือการเปรียบเทียบผู้ให้บริการข้อมูลประจำตัว สำหรับข้อมูลเพิ่มเติมเกี่ยวกับรูปแบบความเสี่ยงของผู้ขาย

Privy รองรับ MFA หรือไม่?ใช่ TOTP, SMS และ passkey มีมาให้ในตัวทั้งหมด และคุณสามารถกำหนดให้ต้องใช้ MFA สำหรับการดำเนินการเฉพาะ (เช่น การส่งโทเค็น, การส่งออกกระเป๋าเงิน) ผ่าน policy engine ได้

โค้ดของแอปฉันทำงานฝั่งเซิร์ฟเวอร์หรือฝั่งไคลเอ็นต์?ทั้งสองอย่าง Client SDK จัดการ UI การเข้าสู่ระบบและการลงนาม; server SDK ตรวจสอบโทเค็นและดึงข้อมูลผู้ใช้ ห้ามส่ง app secret ของคุณไปยังเบราว์เซอร์เด็ดขาด