مفتاح API غير صالح: اعثر على المفتاح الخاطئ في دقائق
الـ SDK يرفض مفتاحك، أو الاستقبال يرجع أخطاء مصادقة، أو الأحداث تختفي بصمت. الحل غالبًا واحد من أربعة أخطاء في التعامل مع المفتاح.
كيف تبدو المشكلة
تظهر أعطال المصادقة مع AllStak بطريقتين: خطأ مصادقة صريح في سجلات تطبيقك عند إرسال الـ SDK، أو — وهذا الأكثر — أحداث لا تصل أبدًا لأن نقطة الاستقبال رفضتها. وكلاهما يعود إلى مفتاح API الذي قدّمه تطبيقك.
مفاتيح AllStak بشكل ask_live_… وتُنسخ لكل مشروع من اللوحة. وأي شيء يغيّر هذه السلسلة أو يقتطعها أو يستبدلها — أخطاء الاقتباس، مسافات زائدة، مفتاح مشروع آخر، أو مفتاح دُوِّر بعد نشرك — يعطي العرَض نفسه.
الأسباب الجذرية الشائعة
مفتاح مشروع آخر
المفاتيح مرتبطة بمشروع واحد. نسخ مفتاح من مشروع آخر في المؤسسة نفسها يصادق بنجاح لذلك المشروع — فتظهر أحداثك هناك، أو تفشل إن كان المفتاح ملغى.
مسافات أو علامات اقتباس في متغيّر البيئة
سطر جديد زائد من النسخ واللصق، أو علامات اقتباس دخلت ضمن القيمة (ALLSTAK_API_KEY="ask_live_…" في بعض صيغ ملفات البيئة)، أو مسافة في البداية — كلها تجعل المفتاح غير صالح بايتًا ببايت.
المفتاح غائب عن بيئة التشغيل
تفصل أطر العمل بين متغيّرات وقت البناء ووقت التشغيل — في Next.js لا ترى شيفرة المتصفح إلا متغيّرات NEXT_PUBLIC_* المضمّنة وقت البناء، بينما تقرأ شيفرة الخادم process.env وقت التشغيل. ومفتاح مضبوط في مكان ومطلوب في الآخر يصل undefined.
مفتاح ملغى أو مُدوَّر
إذا دُوِّر المفتاح في اللوحة، فكل نشر ما زال يحمل القيمة القديمة يبدأ بالفشل في المصادقة من تلك اللحظة — وغالبًا يُلاحَظ بعد أيام كتوقف مفاجئ في الأحداث.
التشخيص خطوة بخطوة
ابدأ من اللوحة وانطلق للخارج: المفتاح نفسه أولًا، ثم كيف يصل إلى عمليتك.
- 1
انسخ المفتاح من إعدادات المشروع من جديد
افتح المشروع الصحيح في لوحة AllStak وانسخ مفتاحه من جديد. تأكد أنه يبدأ بـ ask_live_ وأنك داخل المشروع الذي تتوقع ظهور الأحداث فيه — لا مشروع شقيق.
- 2
افحص القيمة بحثًا عن مسافات وعلامات اقتباس
اطبع طول المفتاح وأول وآخر حرف منه في سجل تصحيح (لا المفتاح كاملًا أبدًا). طول يزيد بحرف أو حرفين، أو مفتاح يبدأ بعلامة اقتباس، يكشف تلف النسخ واللصق فورًا.
- 3
تحقّق من وجود المتغيّر وقت التشغيل
اطبع في السجل هل المتغيّر مضبوط عند تهيئة الـ SDK — في العملية والسياق نفسيهما اللذين يعملان في الإنتاج. وتذكّر الفصل بين وقت البناء ووقت التشغيل: حزمة المتصفح تحتاج المفتاح مضمّنًا وقت البناء (مثل VITE_ALLSTAK_API_KEY و NEXT_PUBLIC_*)، والخادم يقرأه عند بدء التشغيل.
- 4
تحقّق هل دُوِّر المفتاح
قارن المفتاح المنشور بالمفتاح الحالي في إعدادات المشروع. إذا اختلفا فقد دوّره أحدهم — حدّث مخزن أسرارك وأعد نشر كل خدمة تستخدمه.
- 5
أعد النشر وتأكد بحدث تجريبي
بعد تصحيح القيمة، أعد النشر (تُقرأ متغيّرات البيئة عند بدء العملية) وأطلق خطأ تجريبيًا واحدًا. إذا ظهر في المشروع الصحيح، فمسار المفتاح سليم من البداية للنهاية.
كيف تمنع تكرارها
- احفظ المفتاح في مدير أسرار أو متغيّر CI — مصدر حقيقة واحد لكل بيئة.
- لا تودِع المفاتيح في مستودع الشيفرة أبدًا؛ استخدم ملفات .env محليًا وأسرار المنصّة في النشر.
- عند تدوير مفتاح، حدّث كل نشر يستخدمه في نافذة التغيير نفسها.
- أضف سطر سجل عند بدء التشغيل يؤكد وجود متغيّر المفتاح (الوجود فقط، لا القيمة أبدًا).
ما زلت عالقًا؟
إذا كان المفتاح مطابقًا لإعدادات المشروع تمامًا والمصادقة ما زالت تفشل، تحقّق من صفحة حالة AllStak، ثم راسلنا على [email protected] باسم مشروعك والوقت التقريبي للأعطال (لا ترسل المفتاح نفسه أبدًا) — ونستطيع فحص ما وصل إلى الاستقبال.
الأسئلة الشائعة
كيف يبدو مفتاح API في AllStak؟
تبدأ المفاتيح بـ ask_live_ وتُنسخ لكل مشروع من لوحة AllStak. لكل مشروع مفتاحه الخاص؛ وتُصادَق الأحداث وتُوجَّه إلى المشروع المالك للمفتاح.
ليش المفتاح يشتغل محليًا ويفشل في الإنتاج؟
غالبًا فجوة في متغيّرات البيئة: القيمة موجودة في .env المحلي لكنها لم تُضف لبيئة الإنتاج، أو احتاجها إطار عملك وقت البناء (مثل NEXT_PUBLIC_* / VITE_*) وجرى البناء بدونها.
هل من الآمن كشف المفتاح في شيفرة المتصفح؟
حِزم المتصفح تشحن مفتاح الاستقبال للعميل بالضرورة — وهو لا يسمح إلا بإرسال الأحداث لمشروعك، لا بقراءة البيانات. ومع ذلك أبقِه في متغيّرات البيئة حتى يظل التدوير تغيير إعداد لا تغيير شيفرة.
ما مصير الأحداث المرسلة بمفتاح قديم مُدوَّر؟
تُرفض عند نقطة الاستقبال ولا يمكن استرجاعها. حدّث المفتاح في كل مكان وأعد النشر فورًا بعد التدوير.
استكشف المزيد
مفتاح واحد، منصّة واحدة
انسخ مفتاح مشروعك وضعه في متغيّر بيئة، وستبدأ أخطاؤك وسجلاتك وتتبّعاتك بالتدفق. ابدأ مجانًا.