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

البداية

البدء السريع

من حساب فارغ إلى علم يُقيَّم في شيفرتك، ثم تغيير منشور يصل إلى تلك الشيفرة، في نحو عشر دقائق. كل تقييم محلي: يحتفظ الـ SDK بالإعداد في الذاكرة ويجيب بشكل متزامن.

1. أنشئ مساحة عمل ومشروعًا

أنشئ حسابًا، وأكّد عنوان بريدك الإلكتروني، ثم أدخل اسم مساحة العمل (عادةً اسم شركتك أو فريقك) واسم أول مشروع. تنضم إلى مساحة عمل قائمة بدلًا من ذلك؟ اطلب من مديرها دعوة عنوان بريدك؛ تُقبل الدعوة تلقائيًا عند تسجيلك.

تريد الاختصار؟ صفحة الترحيب التي تُفتح بعد ذلك فيها مسبقًا مفتاح متصفح لبيئة Development وعلم اسمه welcome-banner، مع مقتطف جاهز للنسخ وزر بدّله (Flip it) لترى التغيير يصل. والخطوات أدناه تفعل الشيء نفسه بعلمك ومفتاحك.

يبدأ كل مشروع جديد بثلاث بيئات:

  • Development وStaging: النشر فيهما مباشر.
  • Production: محمية (لا يستطيع تخفيف سياسة النشر فيها إلا المالك). في خطتي Team وScale تُنشأ وهي تشترط تغييرًا مراجَعًا بموافقة مستقلة ونجاح فحوص السيناريوهات؛ أمّا في Explore فالموافقات الإلزامية وفحوص السيناريوهات غير متاحة، فتُنشر Production مباشرة مثل غيرها.

2. اختر بيئة

للعلم مسودة إعداد واحدة لكل بيئة، وكل بيئة تنشر نسخها المرقّمة الخاصة. استخدم Development في هذا الدليل، واخترها من محدِّد البيئة أسفل الشريط الجانبي. ويستطيع المديرون إضافة بيئات من الإعدادات ← البيئات (Settings → Environments).

3. أنشئ علمًا

افتح الأعلام ← علم جديد (Flags → New flag)، واختر مفتاحًا (مثل checkout-v2) ونوعًا (boolean أو string أو number أو json). لا يمكن تغيير المفتاح ولا النوع لاحقًا. فعّل خيار مكشوف للعميل (Client-exposed) إن كانت شيفرة المتصفح ستقرأ العلم: مفاتيح المتصفح لا تستلم إلا الأعلام المكشوفة للعميل.

في مسودة Development، شغّل العلم وقدّم مثلًا true لـ 10 % من المستخدمين: اختر إضافة قاعدة (Add rule)، واحذف شرطها الفارغ (القاعدة بلا شروط تطابق كل سياق)، واجعل عندئذٍ (Then) على أطلق تدريجيًا إلى (roll out to) بنسبة 10 %، ثم اختر حفظ المسودة (Save draft). الحفظ يغيّر المسودة فقط؛ ولا تراها حِزم SDK حتى تنشر.

4. أنشئ مفتاح SDK

من الإعدادات ← مفاتيح SDK (Settings → SDK keys) (بدور المدير)، أنشئ مفتاحًا لبيئة Development. يقرأ المفتاح بيئة واحدة بالضبط. ويظهر المفتاح كاملًا مرة واحدة؛ إذ لا تخزّن NanoFlags إلا بصمته. ضعه في مدير الأسرار لديك.

  • Server (nf_srv_…): الإعداد الكامل للخوادم الموثوقة. وهو سرّ.
  • Client (nf_pub_…): آمن للمتصفح، ولا يستلم إلا الأعلام المكشوفة للعميل. ويستطيع قراءته كل من يملك الصفحة.

مفاتيح CI (nf_ci_…) والمدير (nf_adm_…) مخصّصة لخطوط التكامل وأداة سطر الأوامر، وترفضها نقاط نهاية الـ SDK. انظر المفاتيح ونطاقاتها.

5. ثبّت الـ SDK

sh
npm install @nanoflags/sdk
لغات خوادم أخرى
يستخدم هذا الدليل جافاسكريبت. لـ Python (pip install nanoflags) انظر SDK بايثون، ولـ Go انظر SDK لغة Go؛ وتتوفر حزم أصلية لـ Java و.NET وPHP وRuby. ولتطبيقات الجوال: React Native وFlutter وiOS وAndroid. ويمكن للغات الأخرى استخدام مزوّد OpenFeature OFREP.

حزمة واحدة تغطي Node والمتصفحات وبيئات تشغيل الحافة (@nanoflags/sdk)، وReact (@nanoflags/sdk/react)، ونقل جلسات الاختبار في Node (@nanoflags/sdk/node). بصيغة ESM مع أنواع TypeScript. ويحتاج الاتصال الحي إلى WebSocket عام (Node 22 أو أحدث، والمتصفحات، وDeno، وBun)؛ وإلا يعود الـ SDK إلى أحداث الخادم (SSE) والاستطلاع الدوري.

6. قيّم مع قيمة احتياط صريحة

كل دالة قراءة تأخذ قيمة احتياط (fallback): القيمة التي يستخدمها تطبيقك عندما لا تستطيع NanoFlags الإجابة (لم يُحمَّل إعداد بعد، أو العلم غير معروف، أو النوع خاطئ). اختر القيمة الآمنة لمستخدميك، وهي عادةً السلوك الحالي.

Node

server.ts
import { createClient } from "@nanoflags/sdk";

const flags = createClient({
  sdkKey: process.env.NANOFLAGS_SDK_KEY!, // nf_srv_…
  baseUrl: "https://edge.nanoflags.io",
  service: "checkout-api",               // shown as the service that reports a revision
});

flags.on("error", (e) => console.warn(e.code, e.message)); // attach before ready(): load errors are emitted while it waits
await flags.ready(); // never rejects; check flags.status

const enabled = flags.boolean("checkout-v2", false, { key: user.id, signedIn: true, region: "US" });

أنشئ عميلًا واحدًا لكل عملية وأعد استخدامه. واستدعِ flags.close() عند الإيقاف: الاتصال الحي يبقي عملية Node حيّة حتى ذلك الحين. وفي السكربتات قصيرة العمر والدوال عديمة الخادم (serverless) استدعِ close() أو مرّر streaming: false.

المتصفح

flags.ts
import { createClient } from "@nanoflags/sdk";

export const flags = createClient({
  sdkKey: "nf_pub_…", // client key: only client-exposed flags are delivered
  baseUrl: "https://edge.nanoflags.io",
  service: "web",
});

flags.on("error", (e) => console.warn(e.code, e.message)); // attach before ready(): load errors are emitted while it waits
await flags.ready();
const ranking = flags.string("search-ranking", "relevance-v2", { key: user.id });
لا تضع مفتاح nf_srv_ في متصفح أبدًا. قواعد الأعلام المكشوفة للعميل مرئية لكل من يملك مفتاح العميل، والتقييم يجري على جهاز المستخدم: لا تستخدم أعلام المتصفح للتفويض وصلاحيات الوصول.

المتصفح بدون أداة تجميع

في صفحة HTML عادية، استورد نسخة وحدات ES من شبكة CDN عامة لحزم npm (هنا jsDelivr). الحزمة بلا اعتماديات تشغيل، فهذا هو الإعداد كله. في بيئة الإنتاج، يُفضَّل تثبيت الحزمة وتقديمها من نطاقك.

index.html
<script type="module">
  // Pin the exact version: an unpinned URL changes under you when a new release ships.
  import { createClient } from "https://cdn.jsdelivr.net/npm/@nanoflags/sdk@0.5.1/+esm";

  const visitor = localStorage.getItem("vid") ?? crypto.randomUUID();
  localStorage.setItem("vid", visitor);
  const flags = createClient({ sdkKey: "nf_pub_…", baseUrl: "https://edge.nanoflags.io", service: "landing" });
  flags.on("error", (e) => console.warn(e.code, e.message));
  await flags.ready();
  document.body.classList.toggle("new-hero", flags.boolean("new-hero", false, { key: visitor }));
  flags.on("update", () => document.body.classList.toggle("new-hero", flags.boolean("new-hero", false, { key: visitor })));
</script>

React

app.tsx
import { createClient } from "@nanoflags/sdk";
import { NanoFlagsProvider, useFlag, useFlagsStatus } from "@nanoflags/sdk/react";

const client = createClient({ sdkKey: "nf_pub_…", baseUrl: "https://edge.nanoflags.io", service: "web" });

export function App({ user }: { user: { id: string; plan: string } }) {
  return (
    <NanoFlagsProvider client={client} context={{ key: user.id, plan: user.plan }}>
      <Checkout />
    </NanoFlagsProvider>
  );
}

function Checkout() {
  const v2 = useFlag("checkout-v2", false); // boolean accessor, chosen from the fallback's type
  const { status, revision } = useFlagsStatus();
  return v2 ? <NewCheckout /> : <OldCheckout />;
}

خاصية السياق key هي الهوية الثابتة المستخدمة في الطرح بالنسب المئوية. مرّرها في كل تقييم قد يصل إلى طرح تدريجي؛ ومن دونها يُعامل السياق على أنه خارج نطاق التوزيع.

7. انشر

عُد إلى لوحة التحكم واختر مراجعة التغييرات (Review changes) في صفحة العلم (أو مراجعة المسودة ونشرها (Review & publish draft) في نظرة عامة) لتفتح نشر المسودة (Publish draft) لبيئة Development. تعرض المراجعة الفرق بين النسخة المنشورة والمسودة. والنشر يأخذ لقطة من المسودة كاملة في نسخة ثابتة لا تتغير (r1، r2، …). وإن نشر شخص آخر في الأثناء، يُرفض النشر بالرسالة تغيّرت البيئة الهدف (Destination changed) بدل الكتابة فوق نسخته.

في Team وScale، تشترط Production للخطوة نفسها تغييرًا بموافقة مستقلة ونجاح السيناريوهات: انظر التغييرات والموافقات.

8. شاهده يصل

تستلم حِزم SDK المتصلة النسخة الجديدة عبر الاتصال الحي دون استطلاع. استمع إليها:

ts
flags.on("update", ({ revision, previousRevision, transport, latencyMs }) => {
  console.log(`now on r${revision} (was r${previousRevision}) via ${transport}`, latencyMs);
});
// the error listener from step 6 is still attached; on errors the last bundle keeps serving

قيمة transport هي "live" عندما تُدفع النسخة، و"stream" عندما تُجلب بعد حدث من الخادم، و"poll" في غير ذلك. وقياسات الانتشار الحالية منشورة في صفحة الحالة.

في لوحة التحكم، تعرض صفحة الترحيب (/app/welcome) ← فحص الاتصال (Connection check) النسخة التي أبلغت عنها الخدمة آخر مرة. ويعني البلاغ أن عملية واحدة تستخدم هذا المفتاح كانت قد حمّلت تلك النسخة لحظة الإبلاغ؛ ولا يثبت أن كل النسخ العاملة فعلت. انظر ما الذي تثبته الإشارة المُبلَّغ عنها.

الخطوات التالية

  1. المفاهيم: المسودات والنسخ والتغييرات والسيناريوهات والشرائح وتوزيع الطرح.
  2. مرجع الـ SDK: الخيارات والحالات ووسائل النقل والتخزين والقياس.
  3. CI (بالإنجليزية): شغّل فحوص السيناريوهات على كل طلب دمج.