POST /v1/events

متتبّع أحداث عام الغرض. استخدمه لأي شيء تحتاج تحليلات عليه ولا يكون اشتراكًا:

• مشاهدات الصفحة
• إرسال نماذج العملاء المحتملين (Lead)
• تتبع النقرات على صفحات الهبوط
• أحداث مخصصة يحددها التاجر

إن كانت بياناتك تحمل هوية مستخدم ذات معنى (email/phone)، استخدم /v1/signups بدلًا منها — تمنحك إزالة تكرار لكل مستخدم. /v1/events للبيانات عالية الحجم بلا هوية.

المصادقة

مفتاح عام + HMAC. نفس مخطط /v1/signups. خادمك الخلفي يوقّع كل نداء.

الجسم

{
  "name":       "lead_submitted",
  "properties": { "plan": "pro", "country": "DZ", "form": "footer" },
  "nonce":      "32-hex-single-use"
}

الحقل	النوع	إلزامي	ملاحظات
name	string ≤ 64	✅	اسم الحدث. snake_case مستحسن.
properties	object		قيم قابلة لـ JSON. تُحفظ كما هي.
nonce	32-hex string	✅	لاستخدام واحد لكل مفتاح، صالح ساعة

name مفهرس للتصفية السريعة وقت الاستعلام. التزم بمعجم صغير ثابت — تجنّب توليد الأسماء ديناميكيًا (مثل viewed_product_42 سيء؛ استخدم name="viewed_product" مع properties.product_id=42).

الاستجابة 202

{
  "data": { "status": "queued", "kind": "event", "store_id": 13 },
  "meta": { "request_id": "...", "api_version": "v1", "edge": true }
}

نفس تدفّق الاشتراكات: مُجدوَل على الحافة في ~30 مللي ثانية، يُكتب في الخادم خلال 5 ثوانٍ.

إزالة التكرار

طبقة واحدة: (store_id, nonce) UNIQUE. لا توجد إزالة تكرار قائمة على البريد. إن أرسلت حدثين بنفس الـ nonce، يُسجَّل الثاني بـ status = 'duplicate' ويُتجاهل. وإلا كل نداء يُحسب.

مثال عملي: تتبع مشاهدات الصفحة (Node.js، خادمي)

import crypto from 'node:crypto';

export async function trackEvent(name, properties = {}) {
  const KEY_ID = process.env.DZ_PUBLIC_KEY;
  const SECRET = process.env.DZ_SIGNING_SECRET;
  const nonce = crypto.randomBytes(16).toString('hex');
  const ts    = Math.floor(Date.now() / 1000).toString();
  const body  = JSON.stringify({ name, properties, nonce });
  const hash  = crypto.createHash('sha256').update(body).digest('hex');
  const sig   = crypto.createHmac('sha256', SECRET).update(`${KEY_ID}\n${nonce}\n${ts}\n${hash}`).digest('hex');

  await fetch('https://api.dzbuild.app/v1/events', {
    method: 'POST',
    headers: {
      'Authorization': `DZ-Public ${KEY_ID}`,
      'X-DZ-Timestamp': ts, 'X-DZ-Nonce': nonce, 'X-DZ-Signature': sig,
      'Content-Type': 'application/json',
    },
    body,
  });
}

// داخل Express middleware:
app.use((req, res, next) => {
  trackEvent('page_view', { path: req.path, ua: req.get('user-agent') }).catch(() => {});
  next();
});

لاحظ أننا لا ننتظر النداء من middleware مشاهدات الصفحة — fire-and-forget لكي لا يُحظر طلب المستخدم. الحافة تردّ في ~30 مللي ثانية على أي حال، لكن هذا يحمي من مشاكل شبكة عابرة.

ما يُحسب من حصتك

كل نداء /v1/events ناجح يزيد usage.event.total و usage.event.billable. لا يوجد "قراءات مجانية ثم كتابات قابلة للفوترة" هنا — الأحداث قابلة للفوترة من الطلب الأول.

إن ارتفع حجم الأحداث، اجمع من جانبك: خزّنها في طابور خاص، واطلق نداء /v1/events لكل حدث منطقي على دفعات من 1 (لا نقبل دُفعات في v1؛ ميزة لـ v1.1 للقياس عالي الحجم).

الأخطاء

نفس /v1/signups. انظر الأخطاء.

متى لا تستعمل /v1/events

• لـ طلبات الواجهة — تأتي من الواجهة وتُطلق webhook order.created تلقائيًا. لا تُكرّر الإطلاق.
• لـ أحداث داخلية لا تتعلق ببيانات التاجر (استهلاك CPU، نتائج cache). استعمل APM حقيقيًا.
• لـ أحجام ضخمة (>1M حدث/يوم). ابنِ خط تحليلاتك واصدّر فقط التجميعات هنا.