مرجع API

عنوان URL الأساسي: https://api.analytics.house (أو Worker الخاص بك إذا كنت تستضيف الخدمة ذاتيًا). الاستجابات بصيغة JSON. تتطلب نقاط النهاية التي تستلزم المصادقة Authorization: Bearer <token> باستخدام الرمز المُستلَم من /auth/login.

إرسال الأحداث: POST /collect

نقطة نهاية عامة (دون رمز مصادقة). تُرجع 202 فورًا، وتُكتب الأحداث في الخلفية.

curl -X POST https://api.analytics.house/collect \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_PROJECT_KEY",
    "events": [
      { "event_name": "pageview", "event_type": "pageview", "path": "/pricing", "session_id": "s1" },
      { "event_name": "signup", "event_type": "custom", "properties": { "plan": "pro" } }
    ]
  }'

حقول الحدث: event_name (مطلوب)، وevent_type، وpath، وreferrer، وsession_id، وuser_id، وtimestamp (بصيغة ISO 8601)، وutm_source، وutm_medium، وutm_campaign، وproperties (كائن). تُتجاهَل الروبوتات. عند تجاوز حد معدل الطلبات تتلقى 429 مع Retry-After. وإذا كان المشروع يحدد قائمة بالمواقع المسموح بها، فإن طلبات المتصفح الصادرة من أي موقع آخر تتلقى 403. تُشكّل الأحداث الصادرة عن الزائر نفسه بفارق لا يتجاوز 30 دقيقة زيارةً واحدة، وتُطبَّق وسوم UTM الخاصة بصفحة الهبوط على بقية الزيارة. يُتجاهَل session_id ما لم يُعطِّل المشروع الوضع الصارم، ويُخزَّن user_id دائمًا على هيئة تجزئة يومية.

الحساب

• POST /auth/register: { "email", "password" }
• POST /auth/login: يُرجع { "token", "user", "expires_at" }
• GET /auth/me: يُرجع بيانات الحساب الحالي
• PUT /auth/me: بإرسال { "email", "current_password" } يُحدَّث البريد الإلكتروني للحساب ويُرجَع رمز مُجدَّد
• POST /auth/change-password: { "current_password", "new_password" }
• DELETE /auth/me: بإرسال { "password", "code" } يُحذف الحساب وجميع المشاريع التي يملكها نهائيًا (الحقل code مطلوب فقط عند تفعيل المصادقة الثنائية)
• POST /auth/forgot-password: بإرسال { "email" } يُرسَل رابط لإعادة التعيين صالح لمرة واحدة عبر البريد الإلكتروني. وتكون الاستجابة نفسها سواء أكان الحساب موجودًا أم لا.
• POST /auth/reset-password: { "token", "password" }
• POST /auth/logout: الجلسات رموز عديمة الحالة (stateless)، لذا يكفي أن يتخلص العميل من رمزه.
• POST /auth/verify-email: بإرسال { "token" } المأخوذ من الرابط الوارد في رسالة التحقق (دون الحاجة إلى جلسة). يرسل POST /auth/verify-email/resend رابطًا جديدًا. تبدأ الحسابات الجديدة والعناوين المُغيَّرة بحالة «غير مُتحقَّق منه»، ولا تصل الدعوات والتقارير ورسائل التنبيه إلا إلى العناوين المُتحقَّق منها.

المصادقة الثنائية (TOTP)

• POST /auth/2fa/setup: بإرسال { "password" } يُرجَع مفتاح سري وعنوان URI من نوع otpauth:// لتطبيق المصادقة لديك.
• POST /auth/2fa/enable: بإرسال { "code" } يُؤكَّد الرمز الأول وتُرجَع رموز استرداد صالحة لمرة واحدة (تُعرض مرة واحدة فقط).
• POST /auth/2fa/disable: { "password", "code" }
• عند تفعيل المصادقة الثنائية، يُرجع POST /auth/login القيمة { "two_factor_required": true, "challenge_token" }. أكمِل تسجيل الدخول عبر POST /auth/2fa/verify مع { "challenge_token", "code" } (رمز من 6 أرقام أو رمز استرداد) خلال 5 دقائق.

المشاريع

• GET /projects, POST /projects ({ "name" })
• GET | PUT | DELETE /projects/:id. مفاتيح settings: strict_privacy، وgeo_detail، وephemeral_raw، وai_assistant، وrespect_dnt (true/false)، وk_anonymity (من 0 إلى 100)، وallowed_hostnames (قائمة؛ يشمل *.example.com النطاقات الفرعية). تبدأ المشاريع الجديدة بالقيم strict_privacy: true وgeo_detail: false وk_anonymity: 5.

قراءة البيانات

• GET /projects/:id/stats?start=ISO&end=ISO: الإجماليات، والسلاسل الزمنية، والتفصيلات (افتراضيًا آخر 7 أيام، وبحد أقصى 366 يومًا)، بما في ذلك المصادر (تظهر مشاهدات الصفحات التي لا مُحيل لها بالقيمة (direct))، ومصدر UTM ووسيطه وحملته، وصفحات الدخول والخروج. أضِف compare=1 للحصول أيضًا على الفترة السابقة المساوية لها في الطول ضمن previous. ويتضمن كل حدث مخصّص conversion_rate (النسبة المئوية للزوار الذين أطلقوه).
• عوامل التصفية: أضِف معاملًا واحدًا أو أكثر بصيغة f=dimension:value، مثل f=country:DE&f=path:/pricing. الأبعاد: path، وreferrer (استخدم (direct) عند عدم وجود مُحيل)، وcountry، وregion، وcity، وbrowser، وdevice، وos، وutm_source، وutm_medium، وutm_campaign، وevent. حتى 5 عوامل تصفية؛ وتقرأ الاستعلامات المُصفّاة الأحداث الخام، لذا يقتصر النطاق الزمني على 92 يومًا.
• GET /projects/:id/props?event=Outbound%20Link&key=url: أكثر القيم تكرارًا لخاصية واحدة من خصائص الحدث (حتى 20 قيمة، وبحد زمني 92 يومًا).
• GET /projects/:id/events?limit=100&offset=0: الأحداث الفردية، الأحدث أولًا (تصل قيمة limit إلى 500). للمالك والمسؤولين فقط؛ أما المشاهدون ومفاتيح الإحصاءات فيحصلون على البيانات المجمّعة فقط.
• GET /projects/:id/realtime: الزوار خلال آخر 5 دقائق، والصفحات خلال آخر 30 دقيقة.

تُخزَّن الإحصاءات مؤقتًا لنحو 30 ثانية. راجع الخصوصية والبيانات لمعرفة طريقة احتساب الزوار.

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

يتكوّن مسار التحويل من 2 إلى 6 خطوات مرتّبة. وكل خطوة إما { "type": "page", "value": "/pricing" } (أنهِ القيمة بالرمز * للمطابقة بالبادئة) أو { "type": "event", "value": "signup" }. تُحتسب الخطوات بالترتيب لكل جلسة (علامة تبويب واحدة في المتصفح).

• GET /projects/:id/funnels, POST /projects/:id/funnels ({ "name", "steps" })
• GET /projects/:id/funnels/:funnelId?start=ISO&end=ISO: العدد في كل خطوة، ونسبة التحويل من الخطوة السابقة، ونسبة التحويل الإجمالية، ونسبة التسرّب.
• DELETE /projects/:id/funnels/:funnelId

روابط المشاركة العامة

• ينشئ POST /projects/:id/share رمز رابط للقراءة فقط (أو يُرجع الرمز الموجود)؛ ويُلغيه DELETE /projects/:id/share.
• GET /public/:token, /public/:token/stats, /public/:token/props: المعاملات نفسها المذكورة أعلاه، دون مصادقة. ولا تتضمن أبدًا مفتاح API الخاص بك أو الأحداث الخام.

تصدير CSV

• GET /projects/:id/export?start=ISO&end=ISO: الأرقام التي تستند إليها لوحة التحكم (الملخص، والسلاسل الزمنية، والتفصيلات).
• GET /projects/:id/export?what=events&start=ISO&end=ISO: الأحداث الخام، حتى 20,000 صف، وبحد زمني 92 يومًا.

الإيرادات وعمق التمرير

• أرسل الإيرادات في properties.revenue (رقم)، ويمكنك اختياريًا إرسال properties.currency (وفق ISO 4217، والقيمة الافتراضية USD) ضمن حدث مخصّص.
• GET /projects/:id/revenue: الإجماليات، وعدد الطلبات، ومتوسط قيمة الطلب، والإيراد لكل زائر، مجمّعة حسب العملة (لا تُجمع أبدًا عبر عملات مختلفة).
• GET /projects/:id/scroll: عيّنات عمق التمرير (يجب أن يتضمن سكربت التتبع data-scroll="true"). لا تُحتسب هذه العيّنات أحداثًا أو جلسات أو حالات ارتداد.

الفريق، ومفاتيح API للإحصاءات، والتقارير، والاستيراد

• GET/POST /projects/:id/members, DELETE /projects/:id/members/:userId, DELETE /projects/:id/invites?email=. الأدوار: المشاهد (قراءة) والمسؤول (إدارة). ولا يدير الفريق إلا المالك.
• يُرجع POST /projects/:id/keys مفتاح إحصاءات للقراءة فقط (ea_sk_...) مرة واحدة. استخدمه في Authorization: Bearer مع نقاط النهاية stats وprops وrealtime وrevenue وscroll وfunnels. لا تُكشف الأحداث الخام ولا مفتاح استقبال الأحداث أبدًا. أبطِل المفتاح باستخدام DELETE /projects/:id/keys/:id.
• GET/PUT /projects/:id/reports (frequency: off | weekly | monthly). يرسل POST /projects/:id/reports/test معاينة إلى البريد الإلكتروني لحسابك (3 مرات في الساعة). تُرسَل رسائل البريد الإلكتروني عبر Cloudflare Email Service.
• POST /projects/:id/import مع { "csv": "date,visitors,..." }: الإجماليات اليومية من Plausible وSimple Analytics وما شابههما. تُرفض التواريخ التي تتداخل مع أيام جُمعت بياناتها. ويزيل DELETE البيانات المستوردة.

بيان الخصوصية ووكيل Worker من الطرف الأول

• GET /projects/:id/privacy: يُرجع حالة تدوير الملح التشفيري الحالي، وتجزئة Subresource Integrity (sha384) لملف /tracker.js، وإعدادات سياسة الخصوصية المفعّلة (strict_privacy، وephemeral_raw، وk_anonymity)، وسكربت وكيل Cloudflare Worker من الطرف الأول جاهزًا للنشر.
• GET /public/:token/privacy: بيان عام للقراءة فقط للتحقق من الخصوصية، مخصّص للوحات التحكم المُشارَكة.

إسناد البحث بالذكاء الاصطناعي، وCore Web Vitals، ودرع الروبوتات، والملاحظات، وWebhooks

• يتضمن GET /projects/:id/stats الحقول ai_sources (ChatGPT وPerplexity وClaude وGemini وCopilot وDeepSeek وغيرها)، وchannels (7 قنوات اكتساب تلقائية)، وanomalies (رصد الارتفاعات والانخفاضات المفاجئة في حركة المرور باستخدام z-score).
• GET /projects/:id/vitals?start=ISO&end=ISO: يُرجع score (مؤشر التجربة الحقيقية من 0 إلى 100)، وmetrics (المئينات p50/p75/p95 ونسب الأداء الجيد والضعيف لكلٍّ من LCP وINP وCLS وTTFB وFCP)، وتفصيل زمن الاستجابة حسب كل مسار.
• GET /projects/:id/bots?start=ISO&end=ISO: يُرجع أعدادًا يومية تحفظ الخصوصية لزواحف تدريب الذكاء الاصطناعي (GPTBot، وClaudeBot، وGoogle-Extended)، ومساعدات البحث بالذكاء الاصطناعي (PerplexityBot، وOAI-SearchBot)، وروبوتات محركات البحث (Googlebot).
• GET | POST /projects/:id/annotations وDELETE /projects/:id/annotations/:annId: ثبّت إطلاقات المنتجات والمحطات التسويقية على تواريخ UTC في المخطط الزمني.
• GET | POST /projects/:id/alerts، وDELETE /projects/:id/alerts/:webhookId، وPOST /projects/:id/alerts/:webhookId/test: اضبط تنبيهات Slack وDiscord وHTTPS (مع الحماية من SSRF) والبريد الإلكتروني للارتفاعات المفاجئة في حركة المرور وانخفاضاتها وتغيّرات الأهداف. ويسرد GET /projects/:id/alerts/log التنبيهات التي أُرسلت.
• GET /public/:token/badge.svg?metric=visitors|pageviews&period=24h|7d|30d&style=emerald|blue|slate: شارة SVG مباشرة لحركة المرور قابلة للتضمين في ملفات README على GitHub وفي تذييلات المواقع.

«اسأل تحليلاتك» وأخطاء JavaScript

• POST /projects/:id/ask مع { "question": "Which pages grew this month?" }: إجابات بلغة واضحة تستند إلى الأرقام المجمّعة فقط (لا تصل الأحداث الخام ولا معرّفات الزوار إلى الذكاء الاصطناعي أبدًا). حتى 10 أسئلة في الدقيقة لكل مستخدم.
• GET /projects/:id/errors?start=ISO&end=ISO: أخطاء JavaScript مجمّعة حسب الرسالة والملف والسطر. لا يرسلها سكربت التتبع إلا مع data-errors="true"، ولا تُحتسب أبدًا ضمن حركة المرور.

خرائط النقرات ومسارات التصفح

• GET /projects/:id/clicks?start=ISO&end=ISO: الصفحات التي تتوفر لها بيانات نقرات. أضِف path=/pricing للحصول على عناصرها (النقرات، والنقرات الغاضبة وغير المستجيبة، والنسبة)؛ وأضِف selector=... للحصول على شبكة 10 × 10 تبيّن مواضع النقرات. تُخفى العناصر التي يقل عدد نقراتها عن حد إخفاء الهوية من النوع k الخاص بالمشروع.
• GET /projects/:id/journeys?path=/pricing&start=ISO&end=ISO: الصفحات التي تمت زيارتها قبل الصفحة المحددة وبعدها مباشرةً ضمن زيارة واحدة؛ وتُدمَج الخطوات التي سلكتها زيارات أقل من الحد في «أخرى». تقرأ الأحداث الفردية، لذا يقتصر النطاق الزمني على 92 يومًا.
• يُعلِّم GET /projects/:id/errors كل نوع خطأ ظهر لأول مرة خلال الفترة بالحقل is_new، ويمكن إطلاق التنبيهات عند new_error.

حالة الخدمة

نقطة النهاية GET /public/status عامة. وهي تُراقَب ذاتيًا (بفحص كل 15 دقيقة)، ولا تمثّل اتفاقية مستوى خدمة (SLA).