حِزم SDK
OpenFeature (OFREP): أي لغة
في هذه الصفحة
العنوان الأساسي والمفاتيح
- العنوان الأساسي:
https://edge.nanoflags.io. ويضيف المزوّد/ofrep/v1/...بنفسه. - المصادقة: مفتاح SDK الخاص بك، مرسلًا في
Authorization: Bearer <key>أو فيX-API-Key: <key>.- مفتاح الخادم (
nf_srv_…): للخوادم. يقيّم كل أعلام بيئته. - مفتاح المتصفح (
nf_pub_…): لتطبيقات الويب والجوال. لا يرى إلا الأعلام الموسومة client-exposed، وأي علم آخر يُجاب بـFLAG_NOT_FOUND. - لا تضع مفتاح خادم في تطبيق متصفح أو جوال أبدًا.
- مفتاح الخادم (
- النتائج نفسها كما في حِزم SDK: تقيّم الحافة على النسخة المنشورة الموقّعة الحالية لبيئتك، بمحرك التقييم نفسه الذي تستخدمه حِزم NanoFlags، فيحصل السياق نفسه على القيمة نفسها في الحالتين.
@nanoflags/sdk مع @nanoflags/openfeature-provider؛ وفي Python حزمة nanoflags؛ وفي Go SDK لغة Go؛ وفي Java و.NET وPHP وRuby حزم Java و.NET وPHP وRuby؛ وفي تطبيقات الجوال حزم React Native وFlutter وiOS وAndroid. ولكلٍّ منها مزوّد OpenFeature خاص. واستخدم OFREP لكل لغة أخرى.البدء السريع
في كل الأمثلة، targetingKey هو الهوية المستخدمة في الطرح بالنسب المئوية، وعادةً معرّف المستخدم أو الحساب. وتطابق قواعدُ الاستهداف كلَّ خاصية أخرى.
Go
go get github.com/open-feature/go-sdk/openfeature github.com/open-feature/go-sdk-contrib/providers/ofrepimport (
"context"
"os"
"github.com/open-feature/go-sdk-contrib/providers/ofrep"
"github.com/open-feature/go-sdk/openfeature"
)
provider := ofrep.NewProvider("https://edge.nanoflags.io", ofrep.WithBearerToken(os.Getenv("NANOFLAGS_SERVER_KEY")))
if err := openfeature.SetProviderAndWait(provider); err != nil {
panic(err)
}
client := openfeature.NewClient("checkout")
evalCtx := openfeature.NewEvaluationContext("user-123", map[string]any{"region": "US", "plan": "pro"})
enabled, _ := client.BooleanValue(context.Background(), "checkout-v2", false, evalCtx)Python
pip install openfeature-sdk openfeature-provider-ofrepimport os
from openfeature import api
from openfeature.evaluation_context import EvaluationContext
from openfeature.contrib.provider.ofrep import OFREPProvider
key = os.environ["NANOFLAGS_SERVER_KEY"]
api.set_provider(OFREPProvider("https://edge.nanoflags.io", headers_factory=lambda: {"Authorization": f"Bearer {key}"}))
client = api.get_client()
ctx = EvaluationContext(targeting_key="user-123", attributes={"region": "US", "plan": "pro"})
enabled = client.get_boolean_value("checkout-v2", False, ctx)للأعلام الرقمية التي تحمل أعدادًا صحيحة استخدم get_integer_value؛ فدالة get_float_value في مزوّد Python ترفض القيمة JSON 25.
Java
<dependency>
<groupId>dev.openfeature</groupId>
<artifactId>sdk</artifactId>
<version>1.23.0</version>
</dependency>
<dependency>
<groupId>dev.openfeature.contrib.providers</groupId>
<artifactId>ofrep</artifactId>
<version>0.0.2</version>
</dependency>import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import dev.openfeature.contrib.providers.ofrep.OfrepProvider;
import dev.openfeature.contrib.providers.ofrep.OfrepProviderOptions;
import dev.openfeature.sdk.*;
import java.util.Map;
OfrepProviderOptions options = OfrepProviderOptions.builder()
.baseUrl("https://edge.nanoflags.io")
.headers(ImmutableMap.of("Authorization", ImmutableList.of("Bearer " + System.getenv("NANOFLAGS_SERVER_KEY"))))
.build();
OpenFeatureAPI.getInstance().setProviderAndWait(OfrepProvider.constructProvider(options));
Client client = OpenFeatureAPI.getInstance().getClient();
EvaluationContext ctx = new ImmutableContext("user-123", Map.of("region", new Value("US"), "plan", new Value("pro")));
boolean enabled = client.getBooleanValue("checkout-v2", false, ctx);.NET
dotnet add package OpenFeature
dotnet add package OpenFeature.Providers.Ofrepusing OpenFeature;
using OpenFeature.Model;
using OpenFeature.Providers.Ofrep;
using OpenFeature.Providers.Ofrep.Configuration;
var options = new OfrepOptions("https://edge.nanoflags.io")
{
Headers = new Dictionary<string, string>
{
["Authorization"] = $"Bearer {Environment.GetEnvironmentVariable("NANOFLAGS_SERVER_KEY")}",
},
};
await Api.Instance.SetProviderAsync(new OfrepProvider(options));
var client = Api.Instance.GetClient();
var ctx = EvaluationContext.Builder()
.SetTargetingKey("user-123")
.Set("region", "US")
.Set("plan", "pro")
.Build();
var enabled = await client.GetBooleanValueAsync("checkout-v2", false, ctx);جافاسكريبت: Node.js (مفتاح خادم)
npm install @openfeature/server-sdk @openfeature/ofrep-providerimport { OpenFeature } from "@openfeature/server-sdk";
import { OFREPProvider } from "@openfeature/ofrep-provider";
await OpenFeature.setProviderAndWait(
new OFREPProvider({ baseUrl: "https://edge.nanoflags.io", headers: [["Authorization", `Bearer ${process.env.NANOFLAGS_SERVER_KEY}`]] }),
);
const client = OpenFeature.getClient();
const enabled = await client.getBooleanValue("checkout-v2", false, { targetingKey: "user-123", region: "US" });جافاسكريبت: المتصفح (مفتاح متصفح)
npm install @openfeature/web-sdk @openfeature/ofrep-web-providerimport { OpenFeature } from "@openfeature/web-sdk";
import { OFREPWebProvider } from "@openfeature/ofrep-web-provider";
await OpenFeature.setContext({ targetingKey: "user-123", region: "US" });
await OpenFeature.setProviderAndWait(
new OFREPWebProvider({
baseUrl: "https://edge.nanoflags.io",
headers: [["X-API-Key", "nf_pub_…"]], // browser keys are public by design
pollInterval: 30_000,
}),
);
const enabled = OpenFeature.getClient().getBooleanValue("checkout-v2", false);يجلب مزوّد الويب كل الأعلام المكشوفة للعميل في طلب واحد ثم يقيّم محليًا. ويعيد الفحص كل pollInterval مع If-None-Match، فتجيب NanoFlags بـ 304 Not Modified ما لم يتغير شيء.
يوجد مزوّدون للغات أخرى أيضًا (PHP وRuby وSwift وKotlin/Android وغيرها). انظر منظومة OpenFeature. واضبط كلًّا منها بالعنوان الأساسي نفسه وترويسة المفتاح نفسها.
ما الذي تحصل عليه
| الحالة | reason | variant |
|---|---|---|
| العلم موقوف في هذه البيئة (تُقدَّم قيمة off الخاصة به) | DISABLED | off |
| العلم بلا قواعد | STATIC | default |
| لم تطابق أي قاعدة (تُقدَّم القيمة الافتراضية للعلم) | DEFAULT | default |
| طابقت قاعدة ذات قيمة ثابتة | TARGETING_MATCH | معرّف القاعدة |
| طابق طرح بنسبة مئوية | SPLIT | <rule id>:rollout أو <rule id>:otherwise |
تتضمن flagMetadata القيمة revision، أي النسخة المنشورة التي قُيّمت. وعند مطابقة قاعدة تتضمن أيضًا ruleIndex وruleId، وللطرح التدريجي inRollout. وعلم JSON قيمته null يعيد القيمة الافتراضية في شيفرتك.
ملاحظة عن الأعلام الموقوفة: مزوّدا Python وجافاسكريبت يعيدان قيمة الإيقاف للعلم، أمّا مزوّد Go فيعيد القيمة الافتراضية في شيفرتك.
الأخطاء
| رمز الخطأ | متى | HTTP (علم واحد) |
|---|---|---|
FLAG_NOT_FOUND | العلم غير موجود، أو طلب مفتاح متصفح علمًا غير مكشوف للعميل | 404 |
TARGETING_KEY_MISSING | وصل العلم إلى طرح بنسبة مئوية والسياق بلا targetingKey | 400 |
INVALID_CONTEXT | context ليس كائنًا، أو targetingKey ليس نصًّا | 400 |
PARSE_ERROR | جسم الطلب ليس JSON | 400 |
TYPE_MISMATCH | طلبت نوعًا مختلفًا عمّا يحمله العلم (يكتشفه المزوّد)، أو إعداد العلم لا يطابق نوعه | 400 / المزوّد |
GENERAL | تعذّر تقييم العلم | 400 |
عند حدوث خطأ، يعيد المزوّد القيمة الافتراضية في شيفرتك مع رمز الخطأ. وعلى مستوى HTTP تجيب الحافة بـ:
401لمفتاح مفقود أو مجهول أو ملغى.403لمفاتيح CI والمدير. استخدم مفتاح SDK.429معRetry-Afterعندما يتجاوز المفتاح 1,000 تقييم لكل 10 ثوانٍ في موقع واحد من مواقع Cloudflare. وتُحسب مفاتيح المتصفح لكل شبكة زائر. ويتوقف المزوّدون حتى الوقت المذكور فيRetry-After.503معRetry-Afterإذا تعذّر تحميل الإعداد كليًا. وهذا نادر: تواصل الحافة تقديم آخر إعداد موقّع أثناء تعذّر الوصول إلى قاعدة البيانات.
HTTP الخام
curl -X POST https://edge.nanoflags.io/ofrep/v1/evaluate/flags/checkout-v2 \
-H "Authorization: Bearer $NANOFLAGS_SERVER_KEY" -H "Content-Type: application/json" \
-d '{"context":{"targetingKey":"user-123","region":"US"}}'
# {"key":"checkout-v2","value":true,"reason":"TARGETING_MATCH","variant":"us","metadata":{"revision":42,"ruleIndex":0,"ruleId":"us"}}
curl -X POST https://edge.nanoflags.io/ofrep/v1/evaluate/flags \
-H "X-API-Key: nf_pub_…" -H "Content-Type: application/json" \
-d '{"context":{"targetingKey":"user-123"}}'
# {"flags":[{"key":"checkout-v2","value":false,"reason":"DEFAULT","variant":"default","metadata":{"revision":42}}, ...],
# "metadata":{"revision":42,"environment":"production"}} (header ETag: "…"; send it back as If-None-Match to get 304)جرّبه الآن بمفتاح العرض العام: nf_pub_4ced72c484c4f388a900aeeaf81e130c110c11730d555dd8 (العلمان demo-new-checkout وdemo-accent).
الحدود
- لا تُطبَّق جلسات الاختبار المشتركة (
x-nanoflags-session) على تقييمات OFREP. - لا تُبلَّغ تقييمات OFREP كأحداث تقييم، فلا تظهر في رؤى استخدام الأعلام.
- لا توجد قناة دفع (
eventStreams). مزوّدو المتصفح يستطلعون دوريًا، والاستطلاع رخيص بفضل إجابات304.