بوابة المطوّرين

بوابة المطوّرين على navvo.io/developer هي أسرع طريقة للعمل مع واجهة Navvo البرمجية. إنها وحدة تحكّم بالنقر لكل ما قد تفعله عبر REST — المؤسسات والمشاريع ومفاتيح API والاستخدام الحيّ وتحليلات البحث وبيئة اختبار للطلبات.

كل ما في البوابة مرتبط بحسابك: فأنت لا ترى وتدير إلا المؤسسات والمشاريع والمفاتيح التي أنشأتها.

التنظيم

تنقسم البوابة إلى خمس علامات تبويب:

1. إعداد مساحة عمل

افتح علامة تبويب مساحة العمل وأنشئ مؤسسة (يُولَّد لها مُعرِّف URL تلقائيًا). داخل بطاقة كل مؤسسة، أضف مشروعًا أو أكثر — عادةً واحدًا لكل تطبيق أو بيئة (مثلاً تطبيق السائق وتطبيق الراكب، أو تجريبي وإنتاج).

2. إصدار مفتاح API

انتقل إلى علامة تبويب مفاتيح API واملأ نموذج إنشاء مفتاح API:

عند النقر على إصدار مفتاح API، يُعرَض السرّ الكامل مرّة واحدة في لافتة مميّزة. انسخه فورًا — إذ تُخزِّن Navvo تجزئة فقط، فلا يمكن عرضه مجدّدًا أبدًا.

3. إدارة مفاتيحك

يُظهر كل مفتاح في مفاتيح API الخاصة بك تسميته، والأحرف الأربعة الأخيرة، والخطة، والحالة، وعدد النطاقات، ووقت آخر استخدام، ومقياسَي استخدام حيّين (الطلبات في هذه الدقيقة واليوم، مقابل حصّة المفتاح — يتحدّثان تلقائيًا).

يُظهر المفتاح الذي جعلته Navvo غير محدود شارة Unlimited. ويواصل مقياساه عدّ الطلبات في هذه الدقيقة واليوم، لكنهما يعرضانها دون سقف (1,240 / Unlimited، دون شريط ودون لون تحذير)، لأن المفتاح لا حصّة له تمتلئ.

إجراءات كل مفتاح هي:

قصر المفتاح على مواقعك أو خوادمك

في تعديل، املأ المواقع المسموح بها (Allowed websites) لمفتاح يُستخدم في صفحات الويب (example.com أو *.example.com أو localhost:3000)، أو عناوين IP المسموح بها (Allowed IP addresses) لمفتاح يُستخدم من خوادمك (203.0.113.7 أو 198.51.100.0/24). اكتب عنصرًا واحدًا في كل سطر. يظهر في صفّ المفتاح المقيَّد Locked to …، وتحصل الطلبات الآتية من أي مكان آخر على 403. راجع المصادقة ← تقييد المفتاح لقواعد المطابقة.

4. التجربة في بيئة الاختبار

تتيح لك علامة تبويب بيئة الاختبار إطلاق طلبات حقيقية إلى واجهة Navvo ومشاهدة الاستجابة الحيّة.

1. اختر مفتاح API — وهذا إلزامي. تعرض القائمة مفاتيحك أنت فقط، فلا يغادر السرّ الخادم أبدًا: تُمرِّر البوابة الطلب من جهة الخادم بهويّة المفتاح الذي اخترته.
2. اختر نقطة نهاية من القائمة المنسّقة للقراءة فقط (البحث، الترميز الجغرافي، الأماكن، التوجيه، الفحص الصحّي، …). ولنقاط نهاية POST (حسابية للقراءة فقط، مثل التوجيه) يمكنك تعديل جسم JSON. تكشف بيئة الاختبار عمدًا نقاط النهاية الآمنة غير المُعدِّلة فقط.
3. أرسل الطلب — يكون الزرّ معطّلاً حتى تختار مفتاحًا.

تعرض لوحة الاستجابة حالة HTTP وزمن الرحلة وجسم JSON المنسّق. تطبّق بيئة الاختبار فحوصات نطاق المفتاح وحالة تفعيله قبل التمرير: إذا كان المفتاح المختار غير مفعّل، أو يفتقد نطاقًا تحتاجه نقطة النهاية، فستحصل على 403 يوضّح الخطأ بالضبط — وسيلة سريعة للتحقّق من صحّة إعداد المفتاح قبل الإطلاق. ولا تطبّق قيود المفتاح الخاصة بالمواقع وعناوين IP، لأن الطلب يعمل على خوادم Navvo نيابةً عنك.

5. متابعة تحليلات البحث

تعرض علامة تبويب تحليلات البحث عمليات البحث التي تمّت بمفاتيح API لمشروع واحد. ولا يرى تحليلات المشروع إلا مالكه؛ أمّا المشروع القديم الذي لا مالك له فلا يرى تحليلاته إلا أعلى دور إداري في Navvo (super_admin). اختر مشروعًا ونطاقًا من 7 أو 30 أو 90 يومًا (تُحسب الأيام بتوقيت عمّان):

• ستّ بطاقات: عدد عمليات البحث، ونسبة البحث بلا نتائج، ونسبة النقر، ومتوسّط موضع النقر، ونسبة التحويل، والوسيط لزمن الاستجابة. وأيّ نسبة تستند إلى أقلّ من 30 عملية بحث تظهر بعبارة بيانات غير كافية بدل رقم مضلِّل.
• عمليات البحث يوميًا، على شكل مخطّط أو جدول.
• أكثر الاستعلامات والاستعلامات بلا نتائج، 20 من كلٍّ منهما، مع عدد عمليات البحث ونسبة البحث بلا نتائج ونسبة النقر والتحويلات وآخر ظهور لكلّ استعلام. وقائمة الاستعلامات بلا نتائج هي أسرع طريقة لاكتشاف الأماكن والتهجئات التي يتوقّعها مستخدموك ولا يجدونها.

تبقى نسبتا النقر والتحويل فارغتين إلى أن يُبلغ تطبيقك عمّا فتحه المستخدمون، عبر أحداث البحث المرسلة لعمليات بحث حملت معرّف جلسة وافق عليه المستخدم.

اختر مدة احتفاظ Navvo بعمليات البحث

الانتقال من 90 إلى 30 يومًا يحذف عمليات البحث الأقدم في التنظيف الليلي التالي. ولا يمكن استعادة البيانات المحذوفة، لذا تطلب البوابة تأكيدك أولًا. وتسرد صفحة تحليلات البحث والخصوصية ما يتضمّنه سجلّ البحث وما لا يُخزَّن أبدًا. وباختصار: نصّ الاستعلام بعد حذف عناوين البريد الإلكتروني وأرقام الهواتف وغيرها من التفاصيل الشخصية، والمرشّحات والنتائج، ومنطقة تقريبية بدل الإحداثيات. ولا تحتوي سجلّات البحث على عنوان IP نفسه أبدًا. وبمعزل عن ذلك، وأيًّا كان هذا الإعداد، يسجّل قياس الاستخدام العنوان الذي يأتي منه كل استدعاء بمفتاح API (وهو عادةً خادمك، أو جهاز مستخدمك عند استخدام المفتاح من متصفّح أو تطبيق) لأغراض الفوترة ومنع إساءة الاستخدام. ويمكن لأيّ طلب منفرد أن يبقى خارج التحليلات عبر analytics=false.

عبر الواجهة البرمجية

تقبل نقاط النهاية هذه رمز bearer نفسه الذي تستخدمه بقية البوابة، وتتبع قاعدة الوصول نفسها المطبّقة على علامة التبويب:

curl "https://navvo.io/api/v1/developer/projects/PROJECT_ID/search-analytics?days=30" \
  -H "Authorization: Bearer $NAVVO_TOKEN"

curl -X PATCH "https://navvo.io/api/v1/developer/projects/PROJECT_ID/search-settings" \
  -H "Authorization: Bearer $NAVVO_TOKEN" -H "Content-Type: application/json" \
  -d '{"analytics":"90"}'

تقبل GET …/search-analytics المعامل days بقيمة 7 أو 30 أو 90 (الافتراضي 30) وتُعيد:

{
  "project": { "id": "…", "name": "Rider App", "slug": "rider-app", "organization": { "id": "…", "name": "Acme Mobility", "slug": "acme-mobility" } },
  "range": { "days": 30, "from": "2026-09-01", "to": "2026-09-30", "timeZone": "Asia/Amman" },
  "settings": { "analytics": "30", "retentionDays": 30, "isDefault": true },
  "available": true,
  "overview": {
    "searches": 1240, "requests": 1512, "sessions": 0,
    "zeroRate": 0.06, "ctr": null, "avgClickPos": null, "conversionRate": null,
    "p50Ms": 38, "p95Ms": 190, "hybridShare": 0,
    "insufficient": { "zeroRate": false, "ctr": true, "avgClickPos": true, "conversionRate": true },
    "series": [{ "day": "2026-09-30", "searches": 52, "zero": 3, "clicks": 0, "conversions": 0 }]
  },
  "topQueries": {
    "total": 318,
    "items": [{ "query": "pharmacy", "qNorm": "pharmacy", "searches": 96, "sessions": 0, "zeroRate": 0, "ctr": null, "avgClickPos": null, "conversions": 0, "lastSeen": "2026-09-30T11:02:11.000Z" }]
  },
  "zeroResultQueries": { "total": 21, "items": [] }
}

• النسب كسور عشرية (0.06 = 6%)، وتعني null أنه لم يكن هناك ما يُقسَم عليه.
• لا يحتسب searches نقرات المفاتيح التي استبدلها المستخدم نفسه باستعلام أطول خلال 10 ثوانٍ، بينما يحتسب requests كلّ استدعاء.
• hybridShare هي نسبة عمليات البحث التي أسهمت فيها المطابقة حسب المعنى.
• تعني available: false أن التحليلات غير متاحة مؤقتًا، فتكون الأرقام فارغة لا أصفارًا.
• مع analytics: "off" تكون قيمة overview هي null وتكون القائمتان فارغتين.

تقبل PATCH …/search-settings الجسم {"analytics": "off" | "30" | "90"} وتُعيد المشروع مع إعداداته الجديدة في settings.

حذف عمليات بحث مستخدم واحد. إذا طلب منك أحد مستخدميك حذف بياناته، فاستدعِ DELETE …/search-sessions/SESSION_ID بمعرّف الجلسة الذي أرسله تطبيقك عنه في X-Navvo-Session:

curl -X DELETE "https://navvo.io/api/v1/developer/projects/PROJECT_ID/search-sessions/SESSION_ID" \
  -H "Authorization: Bearer $NAVVO_TOKEN"

يزيل ذلك عمليات البحث وأحداث النقر الخاصة بتلك الجلسة خلال آخر 91 يومًا، ويعيد عدد ما حُذف: {"project": {…}, "deleted": {"queries": 12, "events": 3}}. لا تخزّن Navvo سوى تجزئة يومية لمعرّف الجلسة، ولذلك يجب أن يأتي المعرّف نفسه منك؛ أما عمليات البحث المرسَلة بلا معرّف جلسة فلا يمكن ربطها بمستخدم ولا تتأثر. لا يستطيع استدعاءه إلا مالك المشروع، ويُسجَّل كل استدعاء في سجل التدقيق من دون المعرّف. والمعرّف غير الصحيح الصيغة يعيد 400.

تفضّل الواجهة البرمجية؟

كل ما في البوابة مدعوم بنقاط نهاية /developer/* الموثّقة في المصادقة ← إدارة المفاتيح، فيمكنك أتمتة إدارة المؤسسات والمشاريع والمفاتيح في أدواتك الخاصة.