كيفية استخدام Privy API: محافظ مدمجة و Social Auth لـ Web3

لا يزال إعداد المستخدمين لتطبيق Web3 يبعد معظم الأشخاص عند الخطوة الأولى. عبارات الاسترداد (Seed phrases)، وامتدادات المتصفح، ورسوم الغاز (gas fees) تحول عملية التسجيل بنقرتين إلى صراع يستغرق عشر دقائق. يعالج Privy API هذه الفجوة من خلال تزويد كل مستخدم جديد بمحفظة مدمجة خلف تسجيل دخول مألوف: البريد الإلكتروني، الرسائل النصية، جوجل، أبل، أو محفظة موجودة مثل MetaMask. تحصل على مستخدم متمرس في عالم العملات المشفرة دون مطالبة أي شخص بتثبيت إضافة متصفح.

يدعم Privy الآن المحافظ لتطبيقات مثل Blackbird وFriend.tech وOpenSea والآلاف من التطبيقات الأخرى، ويشمل المنتج Ethereum وSolana وأي سلسلة EVM. يرشدك هذا الدليل خلال سير عمل المطور الكامل: إنشاء تطبيق Privy، وربط React SDK، والتحقق من الرموز المميزة على الخادم، وتوقيع المعاملات باستخدام المحافظ المدمجة، وإرسال Webhooks. إذا كنت ترغب أيضًا في مقارنة الخيارات مثل أدوات مطوري MetaMask، فابقِ هذه الصفحة مفتوحة وتنقل بينها ذهابًا وإيابًا.

💡

قبل أن تقرأ الكود، ملاحظة حول أداة. Apidog هي الطريقة التي يجب أن تفحص بها كل طلب HTTPS تقوم به حزم SDK الخاصة بـ Privy خلف الكواليس. وجّه تطبيقك إلى وكيل محلي (local proxy)، والتقط الحمولة الفعلية، وقم بتصحيح أخطاء المصادقة في ثوانٍ بدلاً من تتبع السجلات.

زر

خلاصة القول (TL;DR)

يجمع Privy المحافظ المدمجة مع تسجيل الدخول عبر البريد الإلكتروني، الرسائل النصية، الشبكات الاجتماعية، والمحافظ الخارجية تحت مظلة SDK واحدة.
تكشف React SDK عن الـ `hooks` التالية: `PrivyProvider`, `useLogin`, `useWallets`, و `usePrivy` لتغطية تدفق المصادقة والتوقيع الكامل.
تتحقق `@privy-io/server-auth` من رموز الوصول المميزة (access tokens) على الواجهة الخلفية (backend) الخاصة بك حتى تتمكن من الوثوق بمعرف المستخدم (user ID) في كل طلب.
تدعم المحافظ Ethereum وSolana وسلاسل EVM الأخرى، مع إمكانية التصدير الاختيارية وتوقيعات التفويض للعمليات الرئيسية.
تُطلق Webhooks عند إنشاء المستخدم وتسجيل الدخول وأحداث المحفظة، لتبقى قاعدة بياناتك متزامنة دون الحاجة للاستقصاء المتكرر (polling).
يضيف محرك سياسة Privy مصادقة متعددة العوامل (MFA)، وقوائم السماح (allowlists)، وقواعد المعاملات دون الحاجة لتغيير (forking) كود تطبيقك.

ما هو Privy API؟

Privy هي منصة للبنية التحتية للمصادقة والمحافظ. تمنح تطبيقك ثلاثة أشياء: واجهة مستخدم لتسجيل الدخول، ومحفظة مدمجة يتم توفيرها لكل مستخدم، ومجموعة من نقاط نهاية REST لعمليات التحقق من جانب الخادم. تعيش المحفظة المدمجة في منطقة آمنة (secure enclave)، لذا لا يرى Privy أبدًا المفتاح الخاص ولا الواجهة الخلفية لتطبيقك. يمكن للمستخدمين تصدير مفتاحهم لاحقًا إذا أرادوا الانتقال إلى محفظة ذاتية الحفظ؛ هذه الاختيارية جزء كبير من العرض.

تفرض المنصة رسومًا لكل محفظة نشطة شهريًا، مما يعني أنه يمكنك إطلاق نموذج أولي مجانًا وتوسيع الأسعار مع نمو الانتشار. تغطي الفئة المجانية 1000 مستخدم نشط شهريًا، وتبدأ فئة Pro بسعر 149 دولارًا شهريًا، وتتعامل فئة Enterprise مع اتفاقيات مستوى الخدمة (SLAs) المخصصة.

المصادقة والإعداد

ابدأ من privy.io وأنشئ تطبيقًا جديدًا من لوحة التحكم. ستحصل على قيمتين تهمانك:

معرف التطبيق (App ID) (`clxxxxx...`) لـ SDK العميل
المفتاح السري للتطبيق (App secret) لـ SDK الخادم

قم بتعيين طرق تسجيل الدخول المسموح بها (البريد الإلكتروني، الرسائل النصية، جوجل، أبل، 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` منفصل.

نقاط النهاية الأساسية واستدعاءات SDK

تتعامل React SDK الخاصة بـ Privy مع معظم التدفقات، لذا نادرًا ما تصل إلى REST الخام. ومع ذلك، تستخدم server SDK وحمولات الـ webhook نفس تنسيق الرمز المميز، لذا فإن معرفة 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` ومرر معاملة متسلسلة. إذا كنت ترغب في محاكاة أنماط الوصول إلى البيانات من مزودين مثل Alchemy، فإن Privy يعمل بشكل جيد جنبًا إلى جنب معهم؛ Privy يتعامل مع المفتاح، وAlchemy يتعامل مع RPC.

التحقق من الرموز المميزة على الخادم

قم بتثبيت server SDK:

npm install @privy-io/server-auth

يحمل كل طلب مصادق عليه من الواجهة الأمامية (frontend) الخاصة بك رمز وصول Privy المميز (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)`) للتحقق من الحسابات المرتبطة، وعناوين المحفظة، والبيانات الوصفية المخصصة.

تصدير محفظة مدمجة

يسمح Privy للمستخدمين بتصدير مفتاحهم الخاص في أي وقت. تجربة المستخدم (UX) هي `hook` واحد:

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

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

يعرض Privy نافذة iframe منبثقة آمنة؛ لا يلمس تطبيقك أبدًا مادة المفتاح.

توقيعات التفويض ومحرك السياسات

للعمليات الحساسة (التحويلات الكبيرة، تسجيل الدخول من جهاز جديد)، يدعم Privy **توقيعات التفويض**. تحدد سياسة في لوحة التحكم، وترفقها بتطبيقك، ويفرض Privy المصادقة متعددة العوامل (MFA)، أو قوائم السماح (allowlists)، أو الموافقات الموقعة من الخادم قبل إتمام المعاملة. تتوفر التفاصيل في دليل مفتاح تفويض Privy. بالاشتراك مع خيارات MFA (TOTP، SMS، مفتاح المرور passkey)، يغلق هذا معظم ثغرات الاستيلاء على الحساب التي تتركها المحافظ العادية مفتوحة.

خطافات الويب (Webhooks)

ينشر Privy أحداث JSON إلى نقطة النهاية الخاصة بك عند تغييرات دورة حياة المستخدم والمحفظة:

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 من لوحة التحكم قبل كتابة أي شيء في قاعدة بياناتك.

الأخطاء الشائعة وحدود المعدل

تظهر بعض الأخطاء بشكل متكرر:

`invalid_token`: انتهت صلاحية JWT الخاص بالواجهة الأمامية. استدعِ `getAccessToken()` من `usePrivy` مباشرة قبل الجلب؛ الرموز المميزة صالحة لمدة ساعة واحدة.
`403 origin_not_allowed`: عنوان URL للنشر الخاص بك ليس ضمن قائمة السماح في لوحة تحكم Privy. أضف `https://yourapp.com` وأي نطاقات معاينة.
`wallet_not_ready`: قرأت `useWallets` قبل أن تصبح `ready` صحيحة. قم بتقييد جميع استدعاءات المحفظة على علامة `ready`.
حدود المعدل (Rate limits): تسمح نقاط نهاية REST بـ 100 طلب في الثانية لكل تطبيق في الفئة المجانية. معظم التطبيقات لا تصل إلى هذا الحد أبدًا؛ إذا وصلت، قم بتجميع استدعاءات `getUser` أو التخزين المؤقت (cache) حسب معرف المستخدم.

استخدم Apidog لإعادة تشغيل webhook فاشل محليًا. الصق الحمولة الخام في طلب، وقم بتحرير رأس التوقيع (signature header)، واضرب خادم التطوير الخاص بك مرارًا وتكرارًا حتى ينجح المعالج.

تسعير Privy

مجاني: حتى 1000 محفظة نشطة شهريًا، طرق تسجيل الدخول الأساسية، محافظ مدمجة على EVM + Solana.
احترافي (Pro): 149 دولارًا شهريًا، حدود أعلى للمحافظ النشطة شهريًا (MAW)، مجموعة webhooks كاملة، تطبيق تجريبي (staging app).
مؤسسي (Enterprise): اتفاقية مستوى خدمة مخصصة (custom SLA)، دعم مخصص، هندسة عند الطلب (on-call engineering)، قواعد محرك سياسات مخصصة.

راجع privy.io/pricing للأرقام الحالية؛ تتغير المستويات مع نمو المنتج.

اختبار Privy API باستخدام Apidog

تخفي client SDK الخاصة بـ Privy استدعاءات HTTPS، ولكن كل عملية تحقق من الرمز المميز، وبحث عن المستخدم، وwebhook تتعامل معها الواجهة الخلفية (backend) الخاصة بك هي طلب REST عادي. هذا هو المكان الذي تبرز فيه قيمة Apidog. أنشئ مجموعة Privy في Apidog، وأدخل معرف التطبيق (app ID) والمفتاح السري (secret) كمتغيرات بيئة، واستدعِ نقاط نهاية مثل `GET /api/v1/users/{userId}` أو `POST /api/v1/users/{userId}/wallets` دون مغادرة الأداة.

يمكنك أيضًا تسجيل حمولات webhook من لوحة التحكم، وحفظها كطلبات Apidog، وإعادة تشغيلها مقابل نفق محلي (local tunnel). قم بإعداد اختبارات آلية تتحقق من أن JWT صالح يُرجع كائن مستخدم، وأن JWT منتهي الصلاحية يُرجع 401؛ قم بتشغيلها عند كل نشر. نزّل Apidog مجانًا وتجاوز تعقيدات cURL. إذا كنت قد انتقلت بالفعل من Postman، فإن دليل سير العمل جنبًا إلى جنب يغطي عملية الترحيل الكاملة.

زر

الأسئلة الشائعة

كيف يختلف Privy عن Web3Auth أو Magic؟ جميع الثلاثة يقدمون محافظ مدمجة، لكن Privy يركز بشكل أكبر على المصادقة المختلطة (البريد الإلكتروني + المحفظة + الشبكات الاجتماعية) ومحرك السياسات الذي تحتاجه التطبيقات الكبيرة. يركز Web3Auth على تقسيم مفتاح MPC؛ بينما يقدم Magic منتجًا أوسع للمصادقة عبر الروابط السحرية (magic-link). اختر Privy عندما تريد واجهة مستخدم واضحة للإعداد وتحكمًا دقيقًا في ما يمكن أن تفعله المحافظ.

هل يدعم Privy شبكة Solana؟ نعم. تعمل المحافظ المدمجة على شبكات Solana الرئيسية والتطويرية (mainnet و devnet)، وتكشف React SDK عن `getSolanaProvider()` لتوقيع وإرسال المعاملات. يمكنك تهيئة كل من EVM وSolana في نفس التطبيق.

هل يمكن للمستخدمين إحضار محفظتهم الخاصة؟ نعم. تعمل MetaMask وCoinbase Wallet وWalletConnect وPhantom وعشرات المحافظ الأخرى تلقائيًا. يتعامل Privy مع المحافظ الخارجية كحسابات مرتبطة، لذا فإن نفس معرف المستخدم (user DID) يمتلك كلاً من المفاتيح المدمجة والخارجية.

ماذا يحدث إذا تعطل Privy؟ يحتفظ المستخدمون بإمكانية الوصول إلى المحافظ المصدرة، حيث يعيش المفتاح في منطقة المتصفح الآمنة للمستخدم. بالنسبة لتطبيقات الإنتاج، قم بتمكين إمكانية تصدير المحفظة ووثّق مسارًا احتياطيًا. راجع دليل مقارنة موفري الهوية لمزيد من المعلومات حول أنماط مخاطر البائعين.

هل يدعم Privy المصادقة متعددة العوامل (MFA)؟ نعم. يتم تضمين TOTP والرسائل النصية (SMS) ومفاتيح المرور (passkeys) جميعًا، ويمكنك طلب المصادقة متعددة العوامل لإجراءات محددة (إرسال الرموز المميزة، تصدير المحافظ) عبر محرك السياسات.

هل يعمل كود تطبيقي من جانب الخادم أم من جانب العميل؟ كلاهما. يتعامل Client SDK مع واجهة مستخدم تسجيل الدخول والتوقيع؛ ويتحقق server SDK من الرموز المميزة ويجلب بيانات المستخدم. لا ترسل سر تطبيقك أبدًا إلى المتصفح.