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.
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 kılavuz, tam geliştirici iş akışını adım adım açıklıyor: bir Privy uygulaması oluşturma, React SDK'sını entegre etme, sunucuda tokenları doğrulama, gömülü cüzdanlarla işlem imzalama ve webhook'ları gönderme. Eğer MetaMask'ın geliştirici araç seti gibi seçenekleri de karşılaştırmak isterseniz, bu sayfayı açık tutun ve ileri geri gidip gelebilirsiniz.
Ö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, tam kimlik doğrulama ve imzalama akışını kapsayan
PrivyProvider,useLogin,useWalletsveusePrivykancalarını (hook'larını) sunar. @privy-io/server-auth, arka ucunuzdaki erişim tokenlarını doğrulayarak her istekte kullanıcı kimliğine güvenmenizi sağlar.- Cüzdanlar, isteğe bağlı dışa aktarılabilirlik ve önemli işlemler için yetkilendirme imzaları ile Ethereum, Solana ve diğer EVM zincirlerini destekler.
- Web kancaları (webhook'lar) kullanıcı oluşturma, giriş ve cüzdan olaylarında tetiklenir, böylece veritabanınız sorgulama yapmadan senkronize kalır.
- Privy ilke motoru, uygulamanızın kodunu dallandırmadan çok faktörlü kimlik doğrulama (MFA), izin listeleri ve işlem kuralları ekler.
Privy API nedir?
Privy bir kimlik doğrulama ve cüzdan altyapısı platformudur. Uygulamanıza üç şey sağlar: bir giriş kullanıcı arayüzü, her kullanıcı için sağlanan gömülü bir cüzdan ve sunucu tarafı kontrolleri için bir dizi REST uç noktası. Gömülü cüzdan güvenli bir bölgede bulunur, bu nedenle Privy özel anahtarı asla görmez ve arka ucunuz da görmez. Kullanıcılar, kendi kendine saklama cüzdanına geçmek isterlerse anahtarlarını daha sonra dışa aktarabilirler; bu isteğe bağlılık teklifin büyük bir parçasıdır.
Platform, aylık aktif cüzdan başına ücret alır, bu da ücretsiz bir prototip yayınlayabileceğiniz ve ilgi arttıkça fiyatlandırmayı ölçeklendirebileceğiniz anlamına gelir. Ücretsiz katman 1.000 aylık aktif kullanıcıyı kapsar, Pro ayda 149 dolardan başlar ve Kurumsal (Enterprise) özel SLA'ları yönetir.
Kimlik doğrulama ve kurulum
privy.io adresinden başlayın ve kontrol panelinden yeni bir uygulama oluşturun. İlgilendiğiniz iki değer elde edersiniz:
- Uygulama Kimliği (`clxxxxx...`) (istemci SDK'sı için)
- Uygulama gizli anahtarı (sunucu SDK'sı için)
İzin verilen giriş yöntemlerini (e-posta, SMS, Google, Apple, Farcaster, cüzdan) ayarlayın, varsayılan zincirinizi seçin ve alan adınızı izin verilen kaynaklar listesine ekleyin. React için SDK'yı yükleyin:
npm install @privy-io/react-auth
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` bayrağı, bir kullanıcı cüzdanı olmadan ilk kez giriş yaptığında gömülü bir cüzdan sağlar. Desteklenen zincirleri siz kontrol edersiniz; Solana ayrı bir `solanaClusters` yapılandırması altında bulunur.
Temel uç noktalar ve SDK çağrıları
Privy'nin React SDK'sı çoğu akışı yönetir, bu nedenle nadiren ham REST çağrıları yaparsınız. Yine de, sunucu SDK'sı ve webhook yükleri aynı token formatını kullanır, bu nedenle temel API'yi bilmek işler ters gittiğinde yardımcı olur.
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`, kullanıcının bağladığı her cüzdanı döndürür ve `walletClientType` alanı Privy'nin hangisini oluşturduğunu gösterir. Bu, Privy gömülü cüzdanları için takip ettiğiniz desendir.
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, `getEthereumProvider` yerine `getSolanaProvider` kullanın ve serileştirilmiş bir işlem geçirin. Alchemy gibi sağlayıcılardan veri erişim desenlerini yansıtmak isterseniz, Privy onlarla iyi bir uyum içinde çalışır; Privy anahtarı yönetir, Alchemy ise RPC'yi yönetir.
Tokenları sunucuda doğrulama
Sunucu SDK'sını yükleyin:
npm install @privy-io/server-auth
Ön ucunuzdan gelen her kimliği doğrulanmış istek bir Privy erişim tokenı (JWT) taşır. Herhangi bir kullanıcı kimliğine güvenmeden önce onu sunucuda 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 });
}
}
Bağlı hesapları, cüzdan adreslerini ve özel meta verileri kontrol etmek için tam kullanıcı nesnesini (`privy.getUser(userId)`) de alabilirsiniz.
Gömülü bir cüzdanı dışa aktarma
Privy, kullanıcıların özel anahtarlarını istedikleri zaman dışa aktarmalarına olanak tanır. Kullanıcı deneyimi tek bir kanca (hook) şeklindedir:
import { useExportWallet } from '@privy-io/react-auth';
const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>Özel anahtarı dışa aktar</button>;
Privy güvenli bir iframe modal penceresi gösterir; uygulamanız anahtar materyaline asla dokunmaz.
Yetkilendirme imzaları ve politika motoru
Hassas işlemler (büyük transferler, yeni cihaz girişleri) için Privy, **yetkilendirme imzalarını** destekler. Kontrol panelinde bir politika tanımlar, uygulamanıza ekler ve Privy, bir işlem gerçekleşmeden önce MFA, izin listeleri veya sunucu tarafından imzalanmış onayları uygular. Detaylar Privy yetkilendirme anahtarı kılavuzunda yer almaktadır. MFA seçenekleriyle (TOTP, SMS, geçiş anahtarı) birleştiğinde, bu, basit cüzdanların açık bıraktığı çoğu hesap ele geçirme yüzeyini kapatır.
Webhook'lar
Privy, kullanıcı ve cüzdan yaşam döngüsü değişikliklerinde JSON olaylarını uç noktanıza gönderir:
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" } }
}'
Veritabanınıza herhangi bir şey yazmadan önce `svix-signature` başlığını kontrol panelindeki webhook gizli anahtarı ile doğrulayın.
Yaygın hatalar ve hız limitleri
Birkaç hata tekrar tekrar ortaya çıkar:
- `invalid_token`: ön uç JWT'si süresi dolmuş. Veri çekmeden hemen önce `usePrivy`'den `getAccessToken()` çağırın; tokenlar bir saat yaşar.
- `403 origin_not_allowed`: dağıtım URL'niz Privy kontrol paneli izin listesinde değil. `https://yourapp.com` ve tüm önizleme alan adlarını ekleyin.
- `wallet_not_ready`: `ready` true olmadan önce `useWallets` okudunuz. Tüm cüzdan çağrılarını `ready` bayrağına göre geçitlendirin.
- Hız limitleri: REST uç noktaları, ücretsiz katmanda uygulama başına saniyede 100 isteğe izin verir. Çoğu uygulama bu limite asla ulaşmaz; ulaşırsanız, `getUser` çağrılarını gruplandırın veya kullanıcı kimliğine göre önbelleğe alın.
Başarısız bir webhook'u yerel olarak tekrar oynatmak için Apidog'u kullanın. Ham yükü bir isteğe yapıştırın, imza başlığını düzenleyin ve işleyici geçene kadar geliştirme sunucunuza art arda istek gönderin.
Privy fiyatlandırması
- Ücretsiz: 1.000'e kadar aylık aktif cüzdan, temel giriş yöntemleri, EVM + Solana üzerinde gömülü cüzdanlar.
- Pro: Ayda 149 dolar, daha yüksek MAW limitleri, tam webhook paketi, hazırlık (staging) uygulaması.
- Kurumsal (Enterprise): özel SLA, özel destek, çağrı üzerine mühendislik, özel politika motoru kuralları.
Güncel sayılar için privy.io/pricing adresini kontrol edin; ürün büyüdükçe katmanlar değişir.
Privy API'yi Apidog ile test etme
Privy'nin istemci SDK'sı HTTPS çağrılarını gizler, ancak arka ucunuzun yönettiği her token doğrulama, kullanıcı arama ve webhook düzenli bir REST isteğidir. Apidog'un değerini gösterdiği yer burasıdır. Apidog'da bir Privy koleksiyonu oluşturun, uygulama kimliğinizi ve gizli anahtarınızı ortam değişkenleri olarak ekleyin ve araçtan çıkmadan `GET /api/v1/users/{userId}` veya `POST /api/v1/users/{userId}/wallets` gibi uç noktalara istek gönderin.
Kontrol panelinden webhook yüklerini kaydedebilir, bunları Apidog istekleri olarak kaydedebilir ve yerel bir tünele karşı tekrar oynatabilirsiniz. Geçerli bir JWT'nin bir kullanıcı nesnesi döndürdüğünü ve süresi dolmuş bir JWT'nin 401 döndürdüğünü doğrulayan otomatik testler kurun; bunları her dağıtımda çalıştırın. Apidog'u ücretsiz indirin ve cURL egzersizlerini atlayın. Postman'dan zaten geçtiyseniz, yan yana iş akışı kılavuzu tam geçişi kapsar.
Sıkça Sorulan Sorular
Privy, Web3Auth veya Magic'ten nasıl farklıdır?
Üçü de gömülü cüzdanlar sunar, ancak Privy karma kimlik doğrulamaya (e-posta + cüzdan + sosyal) ve daha büyük uygulamaların ihtiyaç duyduğu bir politika motoruna daha fazla odaklanır. Web3Auth, MPC anahtar bölme üzerine yoğunlaşır; Magic daha geniş bir "magic-link" ürünü sunar. Hem temiz bir dahil etme kullanıcı arayüzü hem de cüzdanların ne yapabileceği üzerinde ayrıntılı kontrol istediğinizde Privy'yi seçin.
Privy Solana'yı destekliyor mu?
Evet. Gömülü cüzdanlar Solana ana ağında ve geliştirme ağında çalışır ve React SDK, işlemler için imzalama ve gönderme için `getSolanaProvider()`'ı sunar. Aynı uygulamada hem EVM hem de Solana'yı yapılandırabilirsiniz.
Kullanıcılar kendi cüzdanlarını getirebilir mi?
Evet. MetaMask, Coinbase Wallet, WalletConnect, Phantom ve düzinelerce diğer cüzdan kutudan çıktığı gibi çalışır. Privy, harici cüzdanları bağlı hesaplar olarak kabul eder, bu nedenle aynı kullanıcı DID'si hem gömülü hem de harici anahtarlara sahiptir.
Privy çökerse ne olur?
Kullanıcılar dışa aktarılan cüzdanlara erişimlerini sürdürürler, çünkü anahtar kullanıcının tarayıcı enclave'inde yaşar. Üretim uygulamaları için cüzdan dışa aktarılabilirliğini etkinleştirin ve bir yedekleme yolu belgeleyin. Satıcı risk modelleri hakkında daha fazla bilgi için kimlik sağlayıcılarını karşılaştırma kılavuzuna bakın.
Privy MFA'yı destekliyor mu?
Evet. TOTP, SMS ve geçiş anahtarları hepsi yerleşiktir ve politika motoru aracılığıyla belirli eylemler (token gönderme, cüzdanları dışa aktarma) için MFA'yı zorunlu kılabilirsiniz.
Uygulamamın kodu sunucu tarafında mı yoksa istemci tarafında mı çalışıyor?
Her ikisi de. İstemci SDK'sı giriş kullanıcı arayüzünü ve imzalamayı yönetir; sunucu SDK'sı tokenları doğrular ve kullanıcı verilerini getirir. Uygulama gizli anahtarınızı asla tarayıcıya göndermeyin.