تخطي إلى المحتوى الرئيسي

مرجع API

واجهة API للتحليلات

واجهة API للتحليلات

توفر واجهة API للتحليلات بيانات أداء القائمة لأصحاب المطاعم ونقطة نهاية تتبع لتسجيل تفاعلات العملاء.

GET /api/analytics

استرداد بيانات التحليلات لمطعمك.

المصادقة: مطلوبة (رمز Bearer). وتتحقق أيضًا من ملكية المطعم.

الاستجابة (200 OK)

{
  "success": true,
  "data": {
    "totalViews": 1250,
    "uniqueVisitors": 890,
    "averageDuration": 45.2,
    "topItems": [
      {
        "id": "uuid",
        "name": "Margherita Pizza",
        "views": 340
      }
    ],
    "modelCoverage": 0.85
  }
}

ملاحظة: يشير الحقل modelCoverage إلى النسبة المئوية لعناصر القائمة التي لديها نموذج 3D بحالة READY (في 3D Menu Pro فقط). ويستخدم LEFT JOIN مع الجدول three_d_models حيث status = 'READY'.

POST /api/analytics/track

تسجيل مشاهدة صفحة جديدة. يستخدمها عميل عارض القائمة.

المصادقة: عامة (لا يلزم رمز)

جسم الطلب

{
  "restaurantId": "uuid",
  "menuItemId": "uuid"
}

الاستجابة (201 Created)

{
  "success": true,
  "data": {
    "id": "uuid"
  }
}

مهم: تغلّف الاستجابة البيانات في data.data — استخدم response.data?.id من JSON المُحلَّل، وليس response.id.

PATCH /api/analytics/track

تحديث سجل مشاهدة موجود ببيانات المدة والتفاعل.

المصادقة: عامة (لا يلزم رمز)

جسم الطلب

{
  "viewId": "uuid",
  "duration": 45,
  "interactions": 3
}

الاستجابة (200 OK)

{
  "success": true,
  "data": {
    "id": "uuid",
    "duration": 45,
    "interactions": 3
  }
}

ملاحظة: استخدم دائمًا fetch مع keepalive: true لاستدعاءات تتبع التحليلات. لا تستخدم navigator.sendBeacon، الذي لا يدعم إلا POST بنوع المحتوى text/plain.