التجارب
track() وبروتوكول الأحداث
track() في SDK جافاسكريبت، والبروتوكول الذي تطبّقه حِزم SDK الأخرى: أي التقييمات تُعدّ تعرّضات، وكيف تُجزَّأ الوحدات، ونقطتا النهاية في الحافة.في هذه الصفحة
track()
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. يتجاهله التقييم، ولا يُستخدم إلا لتسجيل التعرّضات. ولا تتلقاه مفاتيح المتصفح إلا للأعلام المكشوفة للعميل.
{
"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 }]
}متى يكون التقييم تعرّضًا
- للعلم كائن
experiment، وسبب التقييم تطابق قاعدة، ومعرّف قاعدته يساويruleId. - يحتوي السياق على الخاصية
unit(افتراضيًاkey) كنص غير فارغ أو رقم؛ وصيغتها النصية هي الهوية. - إذا كانت
trafficأقل من 100:bucketOf(seed, identity) < trafficبتوزيع المحرّك (MurmurHash3 x86 بطول 32 بت لـseed + ":" + identity، باقي القسمة على 10,000، مقسومًا على 100). - القيمة المقدَّمة تساوي تمامًا إحدى قيم
variants[].value؛ ومفتاح ذلك المتغيّر هو المتغيّر.
سجّل كل ثلاثية (تجربة، وحدة، متغيّر) مرة واحدة في كل عملية؛ ولا تسجّل من التقييم الجماعي (كل الأعلام دفعة واحدة) أو من جلسات الاختبار. ولا تأخذ التعرّضات بالعيّنة أبدًا.
تجزئة الوحدة
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: استُنفدت الحصة اليومية للبيئة، وأُسقطت الدفعة.