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

Analytics API

توفّر Analytics API وصولاً برمجياً إلى تحليلات المنتج، بما فيها استعلامات الأحداث والمسارات والتحليل الاستبقائي وتحليل المسارات وcohorts.

كل نقاط النهاية في هذه الصفحة نسبية إلى عنوان الأساس https://api-eu1.joryio.com. راجع نظرة عامة على API.

المصادقة​

تتطلب جميع النقاط المصادقة بمفتاح API:

Authorization: Bearer YOUR_API_KEY
X-Workspace-Id: YOUR_WORKSPACE_ID

مستكشف الأحداث​

عرض الأحداث​

احصل على ملخص لجميع الأحداث المتتبعة.

GET /analytics/events

معاملات الاستعلام:

المعاملالنوعالوصف
startDatestringتاريخ البدء، YYYY-MM-DD
endDatestringتاريخ النهاية، YYYY-MM-DD
searchstringتصفية باسم الحدث
limitnumberأقصى نتائج، الافتراضي 100

الاستجابة:

{
  "events": [
    {
      "eventName": "signup_completed",
      "totalCount": 15420,
      "uniqueUsers": 12350,
      "lastSeen": "2024-01-15T14:30:00Z"
    }
  ],
  "total": 45
}

الحصول على اتجاه حدث​

احصل على أعداد الأحداث مع مرور الوقت.

POST /analytics/events/trend

نص الطلب:

{
  "eventNames": ["signup_completed", "purchase_completed"],
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "timeGranularity": "day"
}

الاستجابة:

[
  {
    "date": "2024-01-01",
    "count": 523,
    "uniqueUsers": 498
  }
]

الحصول على خصائص حدث​

اعرض خصائص حدث محدد.

GET /analytics/events/:eventName/properties

الاستجابة:

[
  {
    "propertyName": "plan_type",
    "valueCount": 4
  },
  {
    "propertyName": "source",
    "valueCount": 12
  }
]

الحصول على توزيع خاصية​

احصل على توزيع قيم خاصية لحدث.

POST /analytics/events/property-breakdown

نص الطلب:

{
  "eventName": "purchase_completed",
  "property": "payment_method",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31"
}

الاستجابة:

{
  "total": 5420,
  "values": [
    { "value": "credit_card", "count": 3250, "percentage": 59.96 },
    { "value": "paypal", "count": 1520, "percentage": 28.04 },
    { "value": "bank_transfer", "count": 650, "percentage": 11.99 }
  ]
}

تحليل المسار​

إنشاء مسار​

احفظ تعريف مسار جديد.

POST /analytics/funnels

نص الطلب:

{
  "name": "Signup to Purchase",
  "steps": [
    {
      "id": "step_1",
      "order": 0,
      "eventName": "signup_completed",
      "filters": []
    },
    {
      "id": "step_2",
      "order": 1,
      "eventName": "onboarding_completed",
      "filters": []
    },
    {
      "id": "step_3",
      "order": 2,
      "eventName": "purchase_completed",
      "filters": []
    }
  ],
  "conversionWindowDays": 7
}

عرض المسارات​

GET /analytics/funnels

تحليل مسار​

شغّل التحليل على مسار محفوظ.

POST /analytics/funnels/:id/analyze

نص الطلب:

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "breakdown": {
    "type": "event_property",
    "property": "utm_source"
  }
}

الاستجابة:

{
  "totalUsers": 10000,
  "overallConversion": 12.5,
  "steps": [
    {
      "id": "step_1",
      "order": 0,
      "eventName": "signup_completed",
      "enteredCount": 10000,
      "conversionRate": 100,
      "dropOffRate": 0
    },
    {
      "id": "step_2",
      "order": 1,
      "eventName": "onboarding_completed",
      "enteredCount": 6500,
      "conversionRate": 65,
      "dropOffRate": 35
    },
    {
      "id": "step_3",
      "order": 2,
      "eventName": "purchase_completed",
      "enteredCount": 1250,
      "conversionRate": 19.23,
      "dropOffRate": 80.77
    }
  ],
  "breakdown": [
    {
      "breakdownValue": "google",
      "overallConversion": 15.2,
      "steps": [...]
    }
  ]
}

تحليل مسار سريع​

حلّل من دون حفظ.

POST /analytics/funnels/quick-analyze

تحليل الاحتفاظ​

تحليل الاحتفاظ​

POST /analytics/retention/analyze

نص الطلب:

{
  "startEvent": "signup_completed",
  "returnEvent": "session_started",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "timeUnit": "week",
  "periods": 8
}

الاستجابة:

{
  "timeUnit": "week",
  "cohorts": [
    {
      "cohortDate": "2024-01-01",
      "cohortSize": 1250,
      "periods": [
        { "period": 0, "retainedCount": 1250, "retentionRate": 100 },
        { "period": 1, "retainedCount": 562, "retentionRate": 44.96 },
        { "period": 2, "retainedCount": 375, "retentionRate": 30.0 }
      ]
    }
  ],
  "overallRetention": [100, 45.2, 31.5, 25.8, 22.1, 19.5, 17.8, 16.2]
}

تصدير الاحتفاظ​

POST /analytics/retention/export

يعيد بيانات CSV.

تحليل المسارات​

تحليل المسارات​

POST /analytics/paths/analyze

نص الطلب:

{
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "startEvent": "landing_page_view",
  "direction": "forward",
  "maxSteps": 5,
  "minPathCount": 10,
  "minPathPercent": 0.5,
  "maxBranchesPerStep": 5,
  "excludeEvents": ["heartbeat", "scroll"]
}

يضبط minPathCount، المستخدمين المطلقين، وminPathPercent، نسبة المستخدمين المؤهلين من 0 إلى 100، عتبة التكرار: يجب أن يتجاوز المسار الأكبر منهما، فتحافظ النسبة على قابلية الاستخدام في مساحات العمل بمختلف الأحجام. ويحد maxBranchesPerStep، من 1 إلى 50 والافتراضي 8، مخطط التدفق إلى أبرز الأحداث التالية في كل خطوة ليبقى مقروءاً مع الحجم الكبير.

الاستجابة:

{
  "totalUsers": 25000,
  "totalPaths": 342,
  "paths": [
    {
      "path": ["landing_page_view", "signup_started", "signup_completed"],
      "count": 3250,
      "percentage": 13.0
    }
  ],
  "sankey": {
    "nodes": [
      { "id": "landing_page_view_0", "name": "landing_page_view" }
    ],
    "links": [
      { "source": "landing_page_view_0", "target": "signup_started_1", "value": 5200 }
    ]
  }
}

Cohorts​

إنشاء Cohort​

POST /analytics/cohorts

نص الطلب:

{
  "name": "Power Users",
  "description": "Users who engage frequently",
  "rules": [
    {
      "type": "event",
      "operator": "did_count",
      "eventName": "session_started",
      "count": 10,
      "timeWindow": { "value": 30, "unit": "day" }
    }
  ]
}

عرض Cohorts​

GET /analytics/cohorts

الحصول على Cohort​

GET /analytics/cohorts/:id

تحديث Cohort​

PUT /analytics/cohorts/:id

حذف Cohort​

DELETE /analytics/cohorts/:id

تحديث عدد Cohort​

POST /analytics/cohorts/:id/refresh

إنشاء شريحة من Cohort​

اربط Cohort بشريحة لاستهداف الحملات.

POST /analytics/cohorts/:id/create-segment

نص الطلب:

{
  "segmentName": "Power Users Segment"
}

لوحات التحكم​

إنشاء لوحة تحكم​

POST /analytics/dashboards

نص الطلب:

{
  "name": "Executive Dashboard",
  "description": "Key metrics overview",
  "widgets": [
    {
      "id": "widget-1",
      "type": "metric",
      "title": "Active Users",
      "config": {
        "eventName": "session_started",
        "metric": "unique_users"
      },
      "layout": { "x": 0, "y": 0, "width": 3, "height": 2 }
    }
  ]
}

عرض لوحات التحكم​

GET /analytics/dashboards

الحصول على لوحة تحكم​

GET /analytics/dashboards/:id

تحديث لوحة تحكم​

PUT /analytics/dashboards/:id

حذف لوحة تحكم​

DELETE /analytics/dashboards/:id

التحليلات الفورية​

الحصول على المستخدمين النشطين​

GET /analytics/realtime/active-users

الاستجابة:

{
  "count": 1523,
  "trend": 5.2
}

تدفق أحداث حي، SSE​

GET /analytics/realtime/events/stream

يعيد تدفق Server-Sent Events للأحداث الحية.

استجابات الأخطاء​

تعيد كل النقاط استجابات الخطأ القياسية:

{
  "statusCode": 400,
  "message": "Invalid date range",
  "error": "Bad Request"
}
رمز الحالةالوصف
400طلب غير صالح أو خطأ تحقق
401غير مصادق
403ممنوع
404المورد غير موجود
500خطأ داخلي في الخادم