Walse

Posted on Apr 23 • Originally published at apidog.com

Cara Menggunakan Privy API: Dompet Tertanam dan Autentikasi Sosial untuk Web3

Mendaftarkan pengguna ke aplikasi Web3 sering kali membuat banyak orang menyerah di langkah awal. Frasa pemulihan (seed phrase), ekstensi browser, dan biaya gas mengubah pendaftaran sederhana menjadi proses yang rumit. Privy API mengatasi masalah ini dengan memberikan dompet tersemat untuk setiap pengguna baru melalui login email, SMS, Google, Apple, atau dompet eksternal seperti MetaMask. Anda bisa mendapatkan pengguna kripto asli tanpa meminta mereka menginstal ekstensi tambahan.

Coba Apidog hari ini

Privy mendukung dompet untuk Blackbird, Friend.tech, OpenSea, dan ribuan aplikasi lainnya—mencakup Ethereum, Solana, serta rantai EVM lain. Panduan ini berisi langkah-langkah implementasi end-to-end: membuat aplikasi Privy, mengintegrasikan React SDK, verifikasi token di server, penandatanganan transaksi, hingga penggunaan webhook. Jika Anda ingin membandingkan dengan solusi seperti MetaMask developer tools, simpan halaman ini sebagai referensi.

💡Gunakan Apidog untuk memeriksa setiap request HTTPS yang dilakukan SDK Privy. Arahkan aplikasi ke proxy lokal, tangkap payload aktual, dan debug masalah otentikasi dengan cepat.

Singkatnya

Privy menggabungkan dompet tersemat dengan login email, SMS, sosial, dan dompet eksternal dalam satu SDK.
React SDK menyediakan PrivyProvider, useLogin, useWallets, dan usePrivy hooks untuk alur otentikasi dan penandatanganan.
@privy-io/server-auth memverifikasi token akses di backend Anda.
Dompet mendukung Ethereum, Solana, dan rantai EVM lainnya, dengan fitur ekspor dan tanda tangan otorisasi.
Webhook aktif pada pembuatan pengguna, login, dan event dompet—sinkronisasi database tanpa polling.
Policy engine Privy menambahkan MFA, allowlist, dan aturan transaksi tanpa mengubah kode aplikasi Anda.

Apa itu Privy API?

Privy adalah platform otentikasi dan dompet Web3. Fitur utama:

UI login (email, SMS, sosial, dompet).
Dompet tersemat per pengguna, disimpan di enklaf aman (Privy/server Anda tidak mengakses private key).
Endpoint REST untuk pemeriksaan server.
Dukungan ekspor kunci ke dompet self-custody.

Privy mengenakan biaya per dompet aktif bulanan:

Gratis: 1.000 pengguna aktif/bulan
Pro: $149/bulan
Enterprise: SLA khusus

Otentikasi dan Pengaturan

Daftar di privy.io dan buat aplikasi baru.
Catat:
- App ID (clxxxxx...) untuk client SDK
- App Secret untuk server SDK
Atur metode login (email, SMS, Google, Apple, Farcaster, dompet), rantai default, dan domain allowed origins.
Instal React SDK:
```
npm install @privy-io/react-auth
```

Bungkus aplikasi Anda dengan 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 membuat dompet tersemat saat login pertama.
Untuk Solana, gunakan konfigurasi solanaClusters.

Endpoint Inti dan Panggilan SDK

React SDK Privy menangani sebagian besar alur. Namun, server SDK dan webhook menggunakan format token yang sama.

Memicu Login dan Membaca Pengguna

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

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

  if (!ready) return <p>Memuat...</p>;
  if (!authenticated) return <button onClick={login}>Masuk</button>;

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

  return (
    <div>
      <p>Halo {user.email?.address ?? user.id}</p>
      <p>Dompet: {embedded?.address}</p>
      <button onClick={logout}>Keluar</button>
    </div>
  );
}

useWallets mengembalikan semua dompet user.
Cek walletClientType untuk mengetahui dompet Privy.
Pola ini juga bisa Anda gunakan untuk dompet tersemat Privy.

Menandatangani Transaksi

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

Untuk Solana, ganti getEthereumProvider dengan getSolanaProvider dan gunakan transaksi serialized.
Privy mengelola kunci, Alchemy atau RPC lain mengelola koneksi jaringan (lihat contoh Alchemy).

Memverifikasi Token di Server

Instal server SDK:
```
npm install @privy-io/server-auth
```

Verifikasi token JWT dari frontend di backend Anda:

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 adalah Privy user DID
    return Response.json({ userId: claims.userId });
  } catch (err) {
    return new Response('Tidak Diotorisasi', { status: 401 });
  }
}

Anda bisa mengambil data user lengkap dengan privy.getUser(userId).

Mengekspor Dompet Tersemat

Privy memungkinkan user ekspor private key melalui hook berikut:

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

const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>Ekspor kunci pribadi</button>;

Privy menampilkan modal aman—aplikasi Anda tidak menyentuh private key.

Tanda Tangan Otorisasi & Policy Engine

Untuk operasi sensitif (misal transfer besar, login device baru), aktifkan tanda tangan otorisasi dan MFA di dasbor Privy.
Atur policy di dasbor; Privy enforce MFA, allowlist, dan approval server sebelum transaksi.
Lihat detail di panduan authorization key Privy.

Webhook

Privy mengirim event JSON ke endpoint Anda pada setiap perubahan user/wallet:

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" } }
  }'

Verifikasi header svix-signature sebelum menulis ke database.

Kesalahan Umum & Batas Kecepatan

invalid_token: JWT frontend expired. Panggil getAccessToken() dari usePrivy sebelum request.
403 origin_not_allowed: Domain belum ada di allowlist Privy. Tambahkan domain deployment/pratinjau.
wallet_not_ready: useWallets dipanggil sebelum ready. Pastikan akses dompet hanya setelah ready true.
Batas kecepatan: REST API 100 req/s/aplikasi (paket gratis). Batch/caching pada panggilan berat.

Gunakan Apidog untuk replay webhook gagal secara lokal. Tempel payload, edit header signature, dan test server development Anda hingga handler sukses.

Harga Privy

Gratis: Hingga 1.000 dompet aktif/bulan, metode login inti, dompet EVM & Solana.
Pro: $149/bulan, MAW lebih tinggi, webhook lengkap, staging app.
Enterprise: SLA & support khusus, policy engine kustom.

Lihat privy.io/pricing untuk detail terbaru.

Menguji Privy API dengan Apidog

Privy client SDK menyembunyikan request HTTPS, tapi setiap verifikasi token, lookup user, dan webhook tetap REST API biasa. Untuk testing & debugging:

Buat koleksi Privy di Apidog.
Masukkan App ID & Secret sebagai environment variable.
Akses endpoint seperti GET /api/v1/users/{userId} atau POST /api/v1/users/{userId}/wallets langsung dari Apidog.
Rekam payload webhook dari dasbor, simpan sebagai request Apidog, dan replay ke local tunnel.
Buat tes otomatis: JWT valid → user object, JWT expired → 401.
Unduh Apidog gratis, tidak perlu cURL atau Postman. Jika migrasi dari Postman, lihat panduan migrasi workflow.

FAQ

Apa bedanya Privy dengan Web3Auth atau Magic?

Ketiganya menawarkan dompet tersemat. Privy fokus pada otentikasi campuran (email + dompet + sosial) dan policy engine untuk aplikasi besar. Web3Auth lebih pada key MPC; Magic lebih luas di magic-link. Pilih Privy jika Anda ingin onboarding clean dan granular wallet control.
Apakah Privy mendukung Solana?

Ya, dompet tersemat Privy berjalan di mainnet/devnet Solana, dan React SDK expose getSolanaProvider().
Bisakah pengguna membawa dompet mereka sendiri?

Ya. MetaMask, Coinbase Wallet, WalletConnect, Phantom, dll—langsung bisa. Privy treat dompet eksternal sebagai akun terhubung.
Apa yang terjadi jika Privy down?

User tetap bisa akses dompet yang sudah diekspor (private key aman di browser). Untuk produksi, aktifkan fitur ekspor dan dokumentasikan fallback. Lihat panduan perbandingan penyedia identitas.
Apakah Privy mendukung MFA?

Ya. TOTP, SMS, passkey—bisa diaktifkan untuk tindakan tertentu via policy engine.
Kapan kode aplikasi berjalan di server/klien?

Keduanya. SDK client untuk login/sign, SDK server untuk verifikasi token & data user. Jangan pernah expose App Secret ke browser.

DEV Community