Privy API Kullanımı: Web3 için Gömülü Cüzdanlar ve Sosyal Giriş

Bir Web3 uygulamasına kullanıcıları dahil etmek hala çoğu insanı ilk adımda uzaklaştırıyor. Gizli anahtarlar (seed phrase'ler), tarayıcı eklentileri ve işlem ücretleri, iki dokunuşluk bir kaydolma işlemini on dakikalık bir mücadeleye dönüştürüyor. Privy API, her yeni kullanıcıya tanıdık bir giriş yönteminin (e-posta, SMS, Google, Apple veya MetaMask gibi mevcut bir cüzdan) arkasında gömülü bir cüzdan sunarak bu boşluğu gideriyor. Kimseye bir tarayıcı eklentisi kurmasını istemeden kripto-yerel bir kullanıcı elde edersiniz.

Apidog'u hemen deneyin

Privy artık Blackbird, Friend.tech, OpenSea ve binlerce başka uygulama için cüzdanları destekliyor ve ürün Ethereum, Solana ve tüm EVM zincirlerini kapsıyor. Bu rehberde, Privy ile entegrasyonu adım adım nasıl kuracağınızı, React SDK'sını nasıl entegre edeceğinizi, sunucuda token doğrulamayı, gömülü cüzdanlarla işlem imzalamayı ve webhook yönetimini uygulamalı olarak bulacaksınız. MetaMask'ın geliştirici araç seti gibi alternatiflerle karşılaştırma yapmak isteyenler için ilgili bağlantılar da mevcut.

💡

Kodu okumadan önce kısa bir araç notu. Privy'nin SDK'larının perde arkasında yaptığı her HTTPS isteğini Apidog ile incelemelisiniz. Uygulamanızı yerel bir proxy'ye yönlendirin, gerçek yükü yakalayın ve logları takip etmek yerine kimlik doğrulama hatalarını saniyeler içinde ayıklayın.

ÖZET

• Privy, gömülü cüzdanları e-posta, SMS, sosyal medya ve harici cüzdan girişini tek bir SDK altında birleştirir.
• React SDK ile hızlı entegrasyon için PrivyProvider, useLogin, useWallets, usePrivy kancalarını kullanabilirsiniz.
• @privy-io/server-auth ile sunucunuzda erişim tokenlarını doğrulayabilir ve güvenli istekler oluşturabilirsiniz.
• Cüzdanlar, dışa aktarılabilirlik ve kritik işlemler için yetkilendirme imzalarını destekler. Ethereum, Solana ve diğer EVM zincirleriyle uyumlu çalışır.
• Webhook'lar sayesinde kullanıcı oluşturma, giriş ve cüzdan olaylarını gerçek zamanlı olarak tetikleyebilirsiniz.
• Privy politika motoru ile MFA, izin listeleri ve işlem kurallarını kodunuzu dallandırmadan uygulayabilirsiniz.

Privy API nedir?

Privy, uygulamanıza kullanıcı girişi, gömülü cüzdan ve REST tabanlı sunucu kontrolleri sağlayan bir kimlik doğrulama ve cüzdan altyapısı platformudur. Gömülü cüzdanlar, güvenli bir ortamda tutulur; Privy ve backend'iniz özel anahtarlara erişemez. Kullanıcılar, isterlerse kendi anahtarlarını dışa aktararak self-custody'ye geçebilirler.

Fiyatlandırma aylık aktif cüzdan başına olur. Ücretsiz katmanda 1.000 kullanıcıya kadar destek var, Pro paketi aylık 149$'dan başlıyor. En güncel detaylar için privy.io/pricing adresini kontrol edin.

Kimlik doğrulama ve kurulum

1. privy.io üzerinden yeni bir uygulama oluşturun.
2. Uygulama Kimliği (clxxxxx...) ve Uygulama Gizli Anahtarı'nı alın.
3. Giriş yöntemlerini (e-posta, SMS, Google, Apple, Farcaster, cüzdan) seçin ve izin verilen alan adlarını ekleyin.
4. React SDK'yı yükleyin:

npm install @privy-io/react-auth

1. Uygulamanızı PrivyProvider ile sarın:

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, cüzdanı olmayan kullanıcıya otomatik olarak gömülü cüzdan oluşturur.
• Desteklenen zincirler tamamen sizin kontrolünüzde. Solana için ayrıca solanaClusters yapılandırmasını kullanın.

Temel uç noktalar ve SDK çağrıları

Genellikle React SDK yeterli olur ancak hata ayıklama veya özel ihtiyaçlar için temel REST uç noktalarını bilmek işinizi kolaylaştırır.

Giriş tetikleme ve kullanıcıyı okuma

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

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

  if (!ready) return <p>Yükleniyor...</p>;
  if (!authenticated) return <button onClick={login}>Giriş Yap</button>;

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

  return (
    <div>
      <p>Merhaba {user.email?.address ?? user.id}</p>
      <p>Cüzdan: {embedded?.address}</p>
      <button onClick={logout}>Çıkış Yap</button>
    </div>
  );
}

• useWallets ile kullanıcıya ait tüm cüzdanları, walletClientType ile de gömülü cüzdanları ayırt edebilirsiniz.
• Daha fazla detay için Privy gömülü cüzdanları makalesine göz atın.

Bir işlemi imzalama

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 için getSolanaProvider kullanın ve işlemi serileştirip gönderin.
• Alchemy gibi RPC sağlayıcılarıyla uyumlu çalışır.

Tokenları sunucuda doğrulama

Sunucu SDK'sını yükleyin:

npm install @privy-io/server-auth

Ve erişim tokenını doğrulayın:

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('Yetkisiz', { status: 401 });
  }
}

• Kullanıcı nesnesinin tamamını almak için privy.getUser(userId) fonksiyonunu kullanabilirsiniz.

Gömülü bir cüzdanı dışa aktarma

Kullanıcılar istedikleri zaman cüzdanlarını dışa aktarabilir:

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

const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>Özel anahtarı dışa aktar</button>;

• Güvenli bir iframe modalı açılır, uygulamanız anahtar materyaline erişmez.

Yetkilendirme imzaları ve politika motoru

Kritik işlemler için yetkilendirme imzalarını etkinleştirin. Kontrol panelinden politika tanımlar, uygulamanıza uygular ve MFA veya yetki gerektiren işlemleri güvenli hale getirirsiniz. Ayrıntılar için Privy yetkilendirme anahtarı kılavuzu kısmını inceleyin.

Webhook'lar

Kullanıcı ve cüzdan olaylarını backend'inize otomatik iletmek için webhook uç noktası kurun:

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": "[e-mail]" } }
  }'

• Veritabanına yazmadan önce svix-signature başlığını kontrol panelinde bulduğunuz gizli anahtarla doğrulayın.

Yaygın hatalar ve hız limitleri

Sık görülen hata ve çözümleri:

• invalid_token: JWT süresi dolmuş olabilir. Her veri çekiş öncesi usePrivy ile getAccessToken() çağırın.
• 403 origin_not_allowed: Uygulamanızın domaini Privy panelinde izinli değil. Tüm dağıtım ve önizleme alan adlarını ekleyin.
• wallet_not_ready: ready true olmadan cüzdanlara erişmeye çalıştınız. Tüm cüzdan işlemlerini bu bayrağa göre yönetin.
• Hız limitleri: Ücretsiz katmanda saniyede 100 istek sınırını aşarsanız, getUser çağrılarını toplu yapın veya kimlik bazlı önbellek kullanın.

Başarısız webhook'ları yerel olarak tekrar oynatmak için Apidog'u kullanabilirsiniz. Ham yükü yapıştırın, imzayı düzenleyin, handler başarılı olana kadar test edin.

Privy fiyatlandırması

• Ücretsiz: 1.000 aylık aktif cüzdan, temel giriş yöntemleri, EVM + Solana desteği.
• Pro: Ayda 149$, daha yüksek MAW limiti, tam webhook desteği, staging uygulaması.
• Enterprise: SLA, özel destek, politika motoru özelleştirmesi.

Güncel planlar için privy.io/pricing adresine bakabilirsiniz.

Privy API'yi Apidog ile test etme

Privy istemci SDK'sı çoğu şeyi soyutlar, ancak backend token doğrulama, kullanıcı sorgusu ve webhook işlemleri için REST API'leri kullanılır. Apidog ile şu şekilde test edebilirsiniz:

1. Apidog'da bir Privy koleksiyonu oluşturun.
2. Uygulama kimliği ve gizli anahtarınızı ortam değişkeni olarak ekleyin.
3. GET /api/v1/users/{userId} veya POST /api/v1/users/{userId}/wallets gibi uç noktalara doğrudan istek gönderin.
4. Webhook yüklerini kaydedin, Apidog ile tekrar oynatın ve imza başlığını test edin.
5. JWT ile giriş yapan bir kullanıcının başarılı döndüğünü ve süresi dolmuş tokenların 401 aldığından emin olmak için otomatik testler oluşturun.
6. Apidog'u ücretsiz indirin ve cURL ya da Postman'a alternatif olarak hızlıca testlerinizi çalıştırın.
7. Eğer geçiş yapmak istiyorsanız, iş akışı kılavuzu ile süreci kolayca takip edebilirsiniz.

Sıkça Sorulan Sorular

Privy, Web3Auth veya Magic'ten nasıl farklıdır?

Üçü de gömülü cüzdan sunar, fakat Privy karma kimlik doğrulama (e-posta + cüzdan + sosyal) ve politika motoruna daha fazla odaklanır. Web3Auth, MPC anahtar bölmeye; Magic ise "magic-link" akışına ağırlık verir. Hem kullanıcı arayüzü hem de cüzdan işlevselliği üzerinde hassas kontrol istiyorsanız Privy öne çıkar.

Privy Solana'yı destekliyor mu?

Evet, Solana ana ağında ve geliştirme ortamında gömülü cüzdan desteği var. React SDK ile getSolanaProvider() üzerinden işlem imzalayabilirsiniz. Aynı uygulamada hem EVM hem de Solana'yı yönetebilirsiniz.

Kullanıcılar kendi cüzdanlarını getirebilir mi?

Evet. MetaMask, Coinbase Wallet, WalletConnect, Phantom ve birçok cüzdan doğrudan desteklenir. Privy, harici cüzdanları bağlı hesap olarak ekler; kullanıcı aynı anda gömülü ve harici anahtarları yönetebilir.

Privy çökerse ne olur?

Kullanıcılar dışa aktardıkları cüzdanlara erişmeye devam edebilir; anahtarlar tarayıcı enclave'inde saklanır. Üretim uygulamalarında dışa aktarılabilirliği etkinleştirin ve yedekleme yolunu dokümante edin. Satıcı riskleri için karşılaştırma kılavuzuna bakın.

Privy MFA'yı destekliyor mu?

Evet. TOTP, SMS ve geçiş anahtarları yerleşik ve politika motoru ile kritik işlemler için MFA zorunlu kılınabilir.

Uygulamamın kodu sunucu tarafında mı yoksa istemci tarafında mı çalışıyor?

Her ikisinde de çalışabilir. İstemci SDK'sı giriş ve imzalama işlemlerini, sunucu SDK'sı ise token doğrulama ve veri sorgusunu yönetir. Gizli anahtarınızı asla istemciye göndermeyin.