DEV Community

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

Posted on • Originally published at apidog.com

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

لا يزال إعداد المستخدمين لتطبيقات Web3 من أكبر العوائق أمام دخول المستخدمين الجدد. عبارات الاسترداد، وامتدادات المتصفح، ورسوم الغاز، كلها تعقد عملية التسجيل وتجعلها تستغرق وقتًا طويلًا. يقدم Privy API حلًا عمليًا عبر توفير محفظة مدمجة لكل مستخدم جديد، مع تجربة تسجيل دخول تقليدية (بريد إلكتروني، SMS، Google، Apple، أو محفظة MetaMask موجودة). بهذا تتيح للمستخدمين الانضمام بسرعة دون الحاجة لأي برامج إضافية. جرّب Apidog اليوم يدعم Privy المحافظ لتطبيقات كبرى مثل Blackbird وFriend.tech وOpenSea وغيرها، ويعمل مع Ethereum وSolana وجميع سلاسل EVM. في هذا الدليل ستجد خطوات عملية: إنشاء تطبيق Privy، ربطه بـ React SDK، التحقق من الرموز المميزة على الخادم، توقيع المعاملات بالمحافظ المدمجة، وإرسال Webhooks. إذا كنت ترغب بمقارنة أدوات مثل أدوات مطوري MetaMask، احتفظ بهذه الصفحة للرجوع السريع.

💡قبل تجربة الكود، اعتمد على Apidog لمراقبة وتحليل كل طلب HTTPS يصدره Privy SDK. ببساطة، وجه تطبيقك إلى وكيل محلي، راقب الحمولات الفعلية، وحل مشاكل المصادقة بسرعة بدلًا من تتبع السجلات يدويًا. ## خلاصة القول (TL;DR) - Privy يجمع بين محافظ مدمجة وتسجيل دخول عبر البريد أو الشبكات الاجتماعية أو المحافظ الخارجية في SDK واحد. - React SDK يوفر `PrivyProvider`, `useLogin`, `useWallets`, و`usePrivy` لإدارة المصادقة والتوقيع. - استخدم `@privy-io/server-auth` للتحقق من رموز الوصول على الخادم قبل الوثوق بهوية المستخدم. - دعم كامل لـ Ethereum وSolana وسلاسل EVM مع تصدير اختياري للمفاتيح وتوقيعات تفويض للعمليات الحساسة. - Webhooks للتزامن الفوري عند إنشاء المستخدم أو تسجيل دخوله أو تحديث المحفظة. - محرك السياسات يتيح MFA، قوائم السماح، وقواعد معاملات دون تعديل الكود الأساسي. ## ما هو Privy API؟ Privy عبارة عن منصة مصادقة ومحافظ، توفر لتطبيقك: - واجهة مستخدم تسجيل دخول قابلة للتخصيص، - محفظة مدمجة آمنة لكل مستخدم، - نقاط نهاية REST للتحقق من المستخدمين من جانب الخادم. المحفظة المدمجة تعيش في منطقة آمنة (secure enclave)، فلا Privy ولا خادمك يرى المفتاح الخاص. يمكن للمستخدم تصدير مفتاحه متى شاء. النموذج التسعيري يعتمد على عدد المحافظ النشطة شهريًا. الفئة المجانية حتى 1000 مستخدم نشط، Pro تبدأ من 149$/شهر، وفئة Enterprise لاحتياجات أكبر. ## المصادقة والإعداد 1. سجل في privy.io وأنشئ تطبيق جديد. 2. احصل على: - **App ID** (`clxxxxx...`) لاستخدامه في SDK العميل. - **App secret** لاستخدامه في SDK الخادم. 3. حدد طرق تسجيل الدخول المسموحة، اختر السلسلة الافتراضية، وأضف نطاقك إلى قائمة السماح. 4. ثبّت React SDK: ```bash npm install @privy-io/react-auth ``` 5. غلف تطبيقك بـ `PrivyProvider`: ```jsx import { PrivyProvider } from '@privy-io/react-auth'; export default function App({ Component, pageProps }) { return ( ); } ``` استخدم `createOnLogin` لإنشاء محفظة تلقائيًا عند أول تسجيل دخول، وتحكم في السلاسل المدعومة من نفس الإعدادات. ## نقاط النهاية الأساسية واستدعاءات SDK ### بدء تسجيل الدخول وقراءة المستخدم استخدم `usePrivy` و`useWallets` لإدارة جلسة المستخدم والمحافظ: ```jsx import { usePrivy, useWallets } from '@privy-io/react-auth'; function LoginButton() { const { ready, authenticated, login, logout, user } = usePrivy(); const { wallets } = useWallets(); if (!ready) return

Loading...

; if (!authenticated) return تسجيل الدخول; const embedded = wallets.find((w) => w.walletClientType === 'privy'); return (

مرحبًا {user.email?.address ?? user.id}

  <p>المحفظة: {embedded?.address}</p>
  <button onClick={logout}>تسجيل الخروج</button>
</div>

);
}



`useWallets` يرجع جميع محافظ المستخدم، ويمكنك تمييز المحافظ المدمجة عبر `walletClientType`. هذا النمط مفيد لتطبيقات تعتمد على محافظ Privy كما في <a href="http://apidog.com/blog/best-crypto-wallet-api?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation">هذه المقارنة</a>.

### توقيع معاملة
لتوقيع معاملة Ethereum:


```jsx
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 استخدم getSolanaProvider ومرر معاملة متسلسلة. إذا أردت محاكاة نمط Alchemy، اعتمد Privy للمفتاح وAlchemy لـ RPC كما هو موضح في هذا الدليل.

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

ثبّت SDK الخادم:

npm install @privy-io/server-auth

تحقق من الرمز المميز JWT في كل طلب:

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 هو معرف المستخدم (DID)
    return Response.json({ userId: claims.userId });
  } catch (err) {
    return new Response('Unauthorized', { status: 401 });
  }
}

يمكنك أيضًا جلب بيانات المستخدم كاملة عبر privy.getUser(userId) للتحقق من الحسابات المرتبطة.

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

يسمح Privy بتصدير المفتاح الخاص بسهولة:

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

const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>تصدير المفتاح الخاص</button>

سيعرض Privy نافذة آمنة، ولن يصل تطبيقك مباشرة للمفتاح.

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

للعمليات الحساسة، استخدم توقيعات التفويض عبر إعداد السياسات من لوحة التحكم. يمكنك فرض MFA، قوائم السماح، أو موافقة من الخادم. راجع دليل التفويض في Privy للتفاصيل. مع MFA (TOTP، SMS، passkey)، تعزز حماية الحسابات بشكل كبير.

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

لتزامن المستخدمين والمحافظ تلقائيًا:

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: نطاق التطبيق غير مضاف لقائمة السماح. أضف النطاق من لوحة التحكم.
  • wallet_not_ready: حاولت قراءة المحافظ قبل أن تصبح ready صحيحة. انتظر ready.
  • حدود المعدل: REST API يسمح بـ 100 طلب/ثانية في الخطة المجانية. استخدم التجميع أو التخزين المؤقت عند الحاجة.

استخدم Apidog لإعادة تشغيل webhook وفحصه محليًا حتى تنجح جميع المعالجات.

تسعير Privy

  • مجاني: حتى 1000 محفظة نشطة/شهر، تسجيل دخول أساسي، محافظ EVM + Solana.
  • Pro: 149$ شهريًا، حدود أعلى، جميع ميزات webhooks، تطبيق تجريبي.
  • Enterprise: اتفاقيات مستوى خدمة مخصصة، دعم وهندسة عند الطلب، سياسات مخصصة.

للمزيد راجع privy.io/pricing.

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

جميع استدعاءات Privy من الواجهة الخلفية هي REST عادي، ويمكن اختبارها مباشرة عبر Apidog:

  1. أنشئ مجموعة Privy في Apidog.
  2. ضع App ID وApp secret كمتغيرات بيئة.
  3. اختبر نقاط النهاية مثل:
    • GET /api/v1/users/{userId}
    • POST /api/v1/users/{userId}/wallets

سجل حمولات webhook من لوحة التحكم، وأعد تشغيلها على بيئة التطوير لضبط المعالجة. أنشئ اختبارات تلقائية لتتحقق من صلاحية JWT ورجوع الأخطاء الصحيحة عند انتهاء الصلاحية.

نزّل Apidog مجانًا وتجاوز مشاكل cURL. إذا كنت انتقلت من Postman، اقرأ هذا الدليل لترى الفرق في سير العمل.

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

كيف يختلف Privy عن Web3Auth أو Magic؟

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

هل يدعم Privy شبكة Solana؟

نعم، المحافظ المدمجة تعمل على mainnet وdevnet. استخدم getSolanaProvider() لتوقيع المعاملات. يمكنك تفعيل كل من EVM وSolana بنفس التطبيق.

هل يمكن للمستخدمين ربط محافظهم الخاصة؟

نعم. MetaMask وCoinbase Wallet وWalletConnect وPhantom مدعومة تلقائيًا. تعتبر المحافظ الخارجية حسابات مرتبطة بنفس معرف المستخدم.

ماذا لو تعطل Privy؟

المستخدم يحتفظ بمحفظته إذا قام بتصدير المفتاح. فعّل دومًا خيار تصدير المحفظة ووضح للمستخدمين مسار الطوارئ. لمزيد من أنماط المخاطر راجع دليل مقارنة موفري الهوية.

هل يدعم Privy المصادقة متعددة العوامل (MFA)؟

نعم، يدعم TOTP وSMS وpasskeys، ويمكنك فرضها على إجراءات محددة عبر السياسات.

هل يجب تنفيذ الكود من جهة الخادم أم العميل؟

كلاهما: Client SDK لإدارة الجلسة والتوقيع، Server SDK للتحقق من الرموز وجلب بيانات المستخدم. لا ترسل App Secret أبدًا للعميل.

Top comments (0)