انتقل إلى المحتوى
NanoFlags
ابدأ مجانًا

التجارب

track()‎ وبروتوكول الأحداث

تُخبر أحداث المقاييس التجربةَ بما فعلته الوحدات التي تعرّضت. تشرح هذه الصفحة track() في SDK جافاسكريبت، والبروتوكول الذي تطبّقه حِزم SDK الأخرى: أي التقييمات تُعدّ تعرّضات، وكيف تُجزَّأ الوحدات، ونقطتا النهاية في الحافة.

track()‎

@nanoflags/sdk
client.track(eventName: string, ctx?: Context): void
client.track(eventName: string, value: number | null | undefined, ctx?: Context): void

client.track("signup_completed", { key: user.id });
client.track("order_total", 129.5, { key: user.id });
  • eventName: من 1 إلى 64 حرفًا من الأحرف والأرقام و_ . : / -، ويبدأ بحرف أو رقم. يجب أن يطابق اسم الحدث لمقياس في الكتالوج؛ والأحداث التي لا يستخدمها أي مقياس تُسقَط.
  • value: رقم منتهٍ اختياري تستخدمه مقاييس القيمة (مثل مجموع الطلب). وتتجاهله مقاييس التحويل والعدد.
  • ctx: السياق نفسه الذي تقيّم به الأعلام. لا تُقرأ منه إلا خاصية (أو خصائص) الوحدة وتُجزَّأ، ولا يغادر العملية شيء آخر.
  • متزامنة، لا ترمي استثناءً أبدًا، ولا تُجري أي إدخال أو إخراج بنفسها. الاسم أو القيمة غير الصالحين يُطلقان error برمز config ويُسقَط الحدث.

الوحدات

الوحدة هي الخاصية التي يوزّع بها الإطلاق التدريجي للتجربة: key افتراضيًا، أو bucketBy في القاعدة. تُبلغ track() عن الحدث تحت key وتحت خاصية الوحدة لكل تجربة في الحزمة المستخدمة (مثل accountId)، فمرّر المعرّفات نفسها التي تقيّم بها. ويمكن للمتصفح الإبلاغ عن التحويلات لتجارب على أعلام الخادم ما دام يمرّر الهوية نفسها.

الإرسال

  • تُحفظ في الذاكرة (5,000 تعرّض و5,000 حدث كحد أقصى) وتُرسل كل 5 ثوانٍ (experiments.flushIntervalMs)، وأسرع عند انتظار 100 عنصر، وعند flush() / close(). في الدوال بلا خوادم، استدعِ await client.flush() قبل الإرجاع.
  • تُرسل التعرّضات أولًا ثم أحداث track. يُعاد إرسال التعرّضات بعد خطأ شبكة أو 429 أو 5xx (فهي تُزال تكراراتها)، أما أحداث track فتُرسل مرة واحدة على الأكثر.
  • experiments: false يعطّل التعرّضات وtrack() معًا. ولا ينطبق أخذ عيّنات القياس (events.sampleRate) عليهما أبدًا.

البروتوكول لمطوّري حِزم SDK

تطبّق كل حزمة SDK من NanoFlags تدعم التجارب الأجزاء الأربعة أدناه بدقة؛ وSDK جافاسكريبت هو المرجع (exposureOf() في المحرّك، وunitHash() في SDK).

بيانات التجربة في الحزم

ما دامت التجربة قيد التشغيل وبيئتها منشورة، يحمل العلم في الحزمة كائن experiment. يتجاهله التقييم، ولا يُستخدم إلا لتسجيل التعرّضات. ولا تتلقاه مفاتيح المتصفح إلا للأعلام المكشوفة للعميل.

bundle.flags[key].experiment
{
  "id": "3f1c2b8e-7d52-4c1a-9a43-1f0e6d5b2c11",
  "key": "one-page-checkout",
  "ruleId": "r2",
  "unit": "key",
  "traffic": 100,
  "seed": "exp:3f1c2b8e-7d52-4c1a-9a43-1f0e6d5b2c11",
  "variants": [{ "key": "control", "value": false }, { "key": "treatment", "value": true }]
}

متى يكون التقييم تعرّضًا

  1. للعلم كائن experiment، وسبب التقييم تطابق قاعدة، ومعرّف قاعدته يساوي ruleId.
  2. يحتوي السياق على الخاصية unit (افتراضيًا key) كنص غير فارغ أو رقم؛ وصيغتها النصية هي الهوية.
  3. إذا كانت traffic أقل من 100: bucketOf(seed, identity) < traffic بتوزيع المحرّك (MurmurHash3 x86 بطول 32 بت لـ seed + ":" + identity، باقي القسمة على 10,000، مقسومًا على 100).
  4. القيمة المقدَّمة تساوي تمامًا إحدى قيم variants[].value؛ ومفتاح ذلك المتغيّر هو المتغيّر.

سجّل كل ثلاثية (تجربة، وحدة، متغيّر) مرة واحدة في كل عملية؛ ولا تسجّل من التقييم الجماعي (كل الأعلام دفعة واحدة) أو من جلسات الاختبار. ولا تأخذ التعرّضات بالعيّنة أبدًا.

تجزئة الوحدة

unit
unit = lowercase hex SHA-256 of the UTF-8 string
  "nanoflags-unit-v1\n" + project + "\n" + environment + "\n" + attribute + "\n" + identity

project, environment: bundle.project and bundle.environment (keys)
attribute:            the unit attribute ("key", "accountId", …)

متّجه اختبار: المشروع commerce، والبيئة production، والخاصية key، والهوية user-1 ← 1080ed9b5d7279af40f8645e827ac76c42472fdb4a6b33071f2196d9b11817b9. وترفض الحافة كل ما ليس 64 حرفًا ست عشريًا صغيرًا.

نقاط النهاية

نقطة النهايةالمحتوىالرد
POST /v1/exposures{ "sdk": "go/0.3.0", "exposures": [{ "experiment", "variant", "unit" }] }202 { accepted, duplicates, ignored, capped }
POST /v1/track{ "sdk": "go/0.3.0", "events": [{ "event", "unit", "value"? }] }202 { accepted, attributed, pending, ignored, capped }
  • المصادقة: Authorization: Bearer بمفتاح SDK للعميل (nf_pub_) أو للخادم (nf_srv_). تحصل مفاتيح CI والمسؤول على 403.
  • 500 عنصر و128 KB كحد أقصى لكل طلب (أرسل 100 في كل طلب). تُسقَط الحقول غير المعروفة؛ والعناصر غير الصالحة تُفشل الطلب برمز 400 ورسالة تسمّي العنصر.
  • 401 مفتاح غير معروف · 429 تجاوز حد المعدل (التزم بـ Retry-After) · 503 غير متاح مؤقتًا. أعد إرسال التعرّضات عند 429 و5xx وأخطاء الشبكة، ولا تُعد إرسال أحداث track.
  • capped: true: استُنفدت الحصة اليومية للبيئة، وأُسقطت الدفعة.
انظر أيضًا
التجارب للإعداد والإحصاء، وواجهة HTTP للحافة لنقاط نهاية SDK الأخرى.