واجهة برمجة تطبيقات علامات الميزات

علامة الميزة (feature flag) هي مفتاح تشغيل عن بُعد له خصائص يقرؤها SDK لكل جهاز. تدير واجهة برمجة التطبيقات هذه علامات التطبيق: وهي العمليات نفسها المتاحة في Audience → Feature Flags في لوحة التحكم. لقراءة العلامات على موقع ويب أو في تطبيق جوال، استخدم Web SDK أو Android SDK أو iOS SDK.

عنوان URL الأساسي

https://rpc-api.svc-nue.pushwoosh.com

يتم تقديم جميع نقاط النهاية عبر HTTPS. تستخدم الطلبات والاستجابات application/json.

المصادقة

يجب أن يتضمن كل طلب ترويسة Authorization تحتوي على رمز API للخادم الخاص بك:

Authorization: Api YOUR_API_TOKEN

تتطلب قراءة العلامات الوصول إلى التطبيق. ويتطلب إنشاؤها وتغييرها صلاحية إدارته.

اصطلاحات

تسمية الحقول: تقبل أجسام الطلبات lowerCamelCase أو snake_case. تستخدم الاستجابات snake_case، كما في كائن علامة الميزة.
النسب المئوية بنقاط الأساس: percent_bp من 0 إلى 10000، حيث 2000 تعني 20%.
الإصدارات: تحمل كل علامة version. تأخذ Update و SetRulePercent و Reshuffle الإصدار الذي قرأته آخر مرة، وتفشل مع VERSION_CONFLICT إذا تغيرت العلامة منذ ذلك الحين، بحيث لا تستبدل التعديلات المتزامنة بعضها بعضًا أبدًا. اقرأ العلامة مرة أخرى وأعد المحاولة.
الحالات: active أو killed أو archived. تغيّر Kill و Unkill و Archive و Restore الحالة فقط ولا تأخذ إصدارًا.

نقاط النهاية

لكل نقطة نهاية REST أداة MCP بالمعلمات نفسها:

الطريقة	المسار	الوصف	أداة MCP
`GET`	`/api/applications/{application_code}/feature_flags`	سرد علامات التطبيق	`list_feature_flags`
`GET`	`/api/applications/{application_code}/feature_flags/{key}`	الحصول على علامة واحدة	`get_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags`	إنشاء علامة	`create_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}`	استبدال الاسم والوصف والخصائص والقواعد	`update_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/rules/{rule_id}/percent`	تغيير نسبة طرح قاعدة واحدة	`set_feature_flag_rule_percent`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/kill`	إيقاف العلامة للجميع	`kill_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/unkill`	إعادة تشغيل علامة موقوفة	`unkill_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/archive`	أرشفة علامة	`archive_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/restore`	استعادة علامة مؤرشفة	`restore_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/reshuffle`	اختيار عينة جديدة من المستخدمين	`reshuffle_feature_flag`
`GET`	`/api/applications/{application_code}/feature_flags/{key}/history`	سرد تغييرات علامة	`list_feature_flag_history`

تعيد كل نقطة نهاية باستثناء List و History القيمة { "flag": { ... } }، أي كائن علامة الميزة بعد العملية.

سرد

GET /api/applications/{application_code}/feature_flags

يأخذ الطلب هذه المعلمات:

المعلمة	الموضع	النوع	الوصف
`application_code`	path	string	رمز التطبيق.
`status`	query	string	اختياري. `active` أو `killed` أو `archived`. احذفه لسرد جميع العلامات.

يعيد { "flags": [ ... ] }، وهي مصفوفة من كائنات علامة الميزة.

الحصول على

GET /api/applications/{application_code}/feature_flags/{key}

يعيد علامة واحدة مع خصائصها وقواعدها و version الحالي.

إنشاء

ينشئ علامة نشطة. يُنشئ الخادم rule_id لكل قاعدة.

POST /api/applications/{application_code}/feature_flags

يحتوي جسم الطلب على هذه الحقول:

المعلمة	النوع	مطلوب	الوصف
`key`	string	نعم	يطابق `^[A-Za-z0-9_.-]{1,58}$`. فريد في التطبيق، بما في ذلك العلامات المؤرشفة، ويُقارن دون تمييز حالة الأحرف. لا يمكن تغييره لاحقًا.
`name`	string	لا	اسم العرض، حتى 255 حرفًا.
`description`	string	لا	الوصف.
`properties`	مصفوفة من كائنات الخاصية	لا	حتى 50 خاصية.
`defaults`	object	نعم، إذا كانت هناك خصائص	قيمة كل خاصية للأجهزة التي تكون العلامة متوقفة لها، مفهرسة بمفتاح الخاصية. يجب أن تطابق كل قيمة نوع الخاصية.
`rules`	مصفوفة من كائنات القاعدة	لا	قواعد مرتبة، حتى 10. القاعدة الأولى التي تطابق شريحتها الجهاز هي التي تحدد النتيجة.

مثال على الطلب

{
  "key": "new_checkout",
  "name": "New checkout",
  "properties": [
    { "key": "button_color", "type": "string" },
    { "key": "show_apple_pay", "type": "boolean" }
  ],
  "defaults": { "button_color": "blue", "show_apple_pay": false },
  "rules": [
    {
      "name": "Beta testers",
      "filter_code": "XXXXX-XXXXX",
      "percent_bp": 10000,
      "overrides": { "button_color": "green", "show_apple_pay": true }
    },
    {
      "name": "Everyone else",
      "filter_code": "",
      "percent_bp": 2000,
      "overrides": { "button_color": "orange" }
    }
  ]
}

تحديث

يستبدل اسم العلامة ووصفها وخصائصها وقيمها الافتراضية وقواعدها. لا تتغير الحالة هنا أبدًا. أرسل جميع الحقول، وليس المتغيرة فقط.

POST /api/applications/{application_code}/feature_flags/{key}

يأخذ الجسم نفسه الخاص بـ إنشاء دون key، بالإضافة إلى version من آخر قراءة لك. احتفظ بـ rule_id لكل قاعدة موجودة. تُنشأ القاعدة التي لا تحتوي على rule_id كقاعدة جديدة. لا يمكن تغيير نوع الخاصية بعد إنشائها.

تحديث نسبة القاعدة

يغيّر نسبة طرح قاعدة واحدة. يحتفظ المستخدمون الذين لديهم العلامة بالفعل بها عند زيادة النسبة المئوية.

POST /api/applications/{application_code}/feature_flags/{key}/rules/{rule_id}/percent

{ "percentBp": 5000, "version": 3 }

الإيقاف وإعادة التشغيل

يوقف POST .../feature_flags/{key}/kill العلامة لكل جهاز، فيحصل الجهاز بعدها على القيم الافتراضية للخصائص. يتم الاحتفاظ بالقواعد والخصائص.

يعيد POST .../feature_flags/{key}/unkill تشغيل علامة موقوفة بقواعدها كما كانت.

يأخذ كلاهما جسمًا فارغًا {}.

الأرشفة والاستعادة

يوقف POST .../feature_flags/{key}/archive إرسال العلامة إلى الأجهزة. لا تُحتسب العلامة المؤرشفة ضمن حد الخطة لعدد العلامات لكل تطبيق، ويظل مفتاحها محجوزًا.

يعيد POST .../feature_flags/{key}/restore العلامة المؤرشفة بحالة killed، بحيث لا تعمل من تلقاء نفسها أبدًا. استدعِ unkill لطرحها مرة أخرى.

يأخذ كلاهما جسمًا فارغًا {}.

إعادة الخلط

يضع كل مستخدم في حاوية (bucket) جديدة، بحيث تختار النسب المئوية نفسها عينة مختلفة من المستخدمين. يفقد بعض المستخدمين الذين لديهم العلامة مفعّلة هذه العلامة، ويحصل عليها آخرون.

POST /api/applications/{application_code}/feature_flags/{key}/reshuffle

{ "confirm": true, "version": 3 }

يجب أن تكون قيمة confirm هي true. وإلا يفشل الطلب مع CONFIRM_REQUIRED.

السجل

يعيد تغييرات العلامة، من الأحدث إلى الأقدم: من أجرى كل تغيير، ومتى، وما الحقول التي تغيّرت. مثل Get، يحتاج إلى الوصول إلى التطبيق، ويعيد 404 عندما لا يكون التطبيق أو العلامة موجودًا.

GET /api/applications/{application_code}/feature_flags/{key}/history

يأخذ الطلب هذه المعلمات:

المعلمة	الموضع	النوع	الوصف
`application_code`	path	string	رمز التطبيق.
`key`	path	string	مفتاح العلامة.
`page`	query	integer	اختياري. رقم الصفحة، بدءًا من `0`.
`per_page`	query	integer	اختياري. عدد الإدخالات في الصفحة، `20` افتراضيًا، وحتى `100`.

يعيد { "entries": [ ... ], "total": N }، حيث total هو عدد الإدخالات في جميع الصفحات. يحتوي كل إدخال على هذه الحقول:

الحقل	النوع	الوصف
`version`	integer	إصدار العلامة الناتج عن هذا التغيير.
`action`	string	`create` أو `update` أو `set_percent` أو `kill` أو `unkill` أو `archive` أو `restore` أو `reshuffle`.
`user_id`	string	معرّف مستخدم لوحة التحكم الذي أجرى التغيير. القيمة `0` لتغيير تم باستخدام رمز API أو بواسطة خدمة من Pushwoosh.
`user_email`	string	البريد الإلكتروني لذلك المستخدم. فارغ عندما يكون المستخدم محذوفًا أو تكون قيمة `user_id` هي `0`.
`by_api_token`	boolean	`true` عندما يتم التغيير باستخدام رمز API. `false` لتغيير أجراه مستخدم أو خدمة من Pushwoosh.
`api_token_name`	string	الاسم الذي كان لرمز API وقت التغيير. يبقى بعد حذف الرمز. فارغ عندما لا يكون للرمز اسم أو تكون قيمة `by_api_token` هي `false`.
`created`	string	وقت التغيير، بتنسيق RFC 3339.
`flag`	كائن علامة الميزة	العلامة بعد التغيير.
`changes`	array	الحقول التي تختلف عن الإصدار السابق. فارغة في `create` و `reshuffle`، وفي أقدم إدخال لعلامة أُنشئت قبل بدء تسجيل السجل، لعدم وجود إصدار سابق للمقارنة به.

يحتوي كل عنصر من changes على field و before و after. يحمل before و after القيم مرمّزة كسلاسل JSON، لذا تأتي القيمة النصية بين علامتي اقتباس. يأخذ field هذه القيم:

`field`	ما الذي تغيّر
`name`, `description`, `status`	حقل العلامة الذي يحمل هذا الاسم.
`properties`	الخصائص وقيمها الافتراضية.
`rules[<rule_id>]`	قاعدة واحدة. للقاعدة المضافة، يكون `before` فارغًا. للقاعدة المحذوفة، يكون `after` فارغًا.
`rules.order`	ترتيب القواعد.

مثال على الاستجابة

{
  "entries": [
    {
      "version": 4,
      "action": "set_percent",
      "user_id": "12345",
      "user_email": "owner@example.com",
      "by_api_token": false,
      "api_token_name": "",
      "created": "2026-10-14T09:30:00Z",
      "flag": { "key": "new_checkout", "status": "active", "version": 4 },
      "changes": [
        {
          "field": "rules[r_1a2b3c4d]",
          "before": "{\"rule_id\":\"r_1a2b3c4d\",\"name\":\"Beta testers\",\"filter_code\":\"XXXXX-XXXXX\",\"percent_bp\":2000,\"overrides\":{\"button_color\":\"green\"}}",
          "after": "{\"rule_id\":\"r_1a2b3c4d\",\"name\":\"Beta testers\",\"filter_code\":\"XXXXX-XXXXX\",\"percent_bp\":5000,\"overrides\":{\"button_color\":\"green\"}}"
        }
      ]
    }
  ],
  "total": 4
}

كائن flag في المثال مختصر. يُسجَّل السجل للتغييرات بدءًا من 13 أكتوبر 2026. لا تعيد العلامة التي ليس لها تغييرات مسجلة أي إدخالات.

قراءة العلامات لجهاز

تقرأ حزم SDK العلامات من نقطة نهاية منفصلة. لا تحتاج إلى استدعائها عند استخدام Web SDK أو Android SDK أو iOS SDK، لأنها تختار المضيف وتخزّن الاستجابة مؤقتًا بنفسها.

POST https://api.pushwoosh.com/api/v2/device-api/getFeatureFlags

يحتوي نص الطلب على هذه الحقول:

الحقل	النوع	الوصف
`application`	string	رمز التطبيق.
`hwid`	string	HWID الخاص بالجهاز.
`etag`	string	اختياري. قيمة `etag` لآخر استجابة يحتفظ بها الجهاز.

تحتوي الاستجابة على هذه الحقول:

الحقل	النوع	الوصف
`flags`	object	العلامات مفهرسة حسب مفتاح العلامة. لكل منها `enabled` و `rule_id` و `properties`. تكون قيمة `rule_id` هي `default` عندما لا تتطابق أي قاعدة، وتكون فارغة للعلامة الموقوفة. لا تُضمَّن العلامات المؤرشفة.
`etag`	string	أرسله مع الطلب التالي.
`not_modified`	boolean	`true` عندما تكون قيمة `etag` المرسلة حديثة. عندها يُحذف `flags` ويحتفظ الجهاز بنسخته.
`partial`	boolean	`true` عندما لم تتم مطابقة شرائح الجهاز في الوقت المناسب. لا تخزّن هذه الاستجابة مؤقتًا.

في خطة لا تتضمن علامات الميزات، تكون الاستجابة فارغة.

الكائنات

كائن علامة الميزة

تعيد كل نقطة نهاية العلامة بهذا الشكل:

الحقل	النوع	الوصف
`application_code`	string	التطبيق الذي تنتمي إليه العلامة.
`key`	string	مفتاح العلامة.
`name`	string	اسم العرض.
`description`	string	الوصف.
`status`	string	`active` أو `killed` أو `archived`.
`properties`	مصفوفة من كائنات الخاصية	خصائص العلامة.
`defaults`	object	قيمة كل خاصية للأجهزة التي تكون العلامة متوقفة لها.
`rules`	مصفوفة من كائنات القاعدة	قواعد مرتبة.
`version`	integer	أعد إرساله مع `Update` و `SetRulePercent` و `Reshuffle`.
`created`	string	وقت الإنشاء، بتنسيق RFC 3339.
`updated`	string	وقت آخر تغيير، بتنسيق RFC 3339.
`last_modified_by_user_id`	string	مستخدم لوحة التحكم الذي غيّر العلامة آخر مرة. القيمة `0` عندما يتم آخر تغيير باستخدام رمز API أو بواسطة خدمة من Pushwoosh.

كائن الخاصية

تصف الخاصية قيمة واحدة يقرؤها SDK من العلامة:

الحقل	النوع	الوصف
`key`	string	يطابق `^[A-Za-z0-9_]{1,64}$`، وهو فريد داخل العلامة.
`type`	string	`string` أو `number` أو `boolean` أو `json`. لا يمكن تغييره بعد إنشاء الخاصية.

كائن القاعدة

تحدد القاعدة من تُفعَّل له العلامة وبأي قيم:

الحقل	النوع	الوصف
`rule_id`	string	يُنشئه الخادم، وهو `r_` متبوعًا بـ 8 أرقام سداسية عشرية، ويبقى ثابتًا عبر التحديثات. اتركه فارغًا لقاعدة جديدة.
`name`	string	اسم القاعدة.
`filter_code`	string	الشريحة التي يجب أن يطابقها الجهاز. القيمة الفارغة تطابق كل جهاز. يمكن أن تحتوي الشريحة فقط على شروط الوسوم (Tag) والموقع والتطبيق والقائمة.
`percent_bp`	integer	حصة المستخدمين المطابقين التي تُفعَّل لها العلامة، `0`–`10000`. يتوقف الجهاز الذي يطابق الشريحة عند هذه القاعدة حتى لو وقع خارج النسبة المئوية.
`overrides`	object	قيم الخصائص التي تحل محل القيم الافتراضية للأجهزة التي تفعّل هذه القاعدة العلامة لها، مفهرسة بمفتاح الخاصية.

الأخطاء

يعيد الطلب المرفوض أحد رموز حالة HTTP هذه:

حالة HTTP	المعنى
`400 Bad Request`	الطلب غير صالح (`field_violations`) أو لا تسمح به حالة العلامة أو الخطة (`Type`). راجع تنسيقات الجسم والأسباب أدناه.
`401 Unauthorized`	ترويسة `Authorization` مفقودة أو الرمز غير صالح.
`403 Forbidden`	لا يمكن للرمز إدارة التطبيق، أو التطبيق تطبيق نظام.
`404 Not Found`	التطبيق أو العلامة غير موجودة.
`409 Conflict`	يقوم طلب آخر بتغيير العلامة نفسها في هذه اللحظة. أعد محاولة الطلب.
`500 Internal Server Error`	فشل غير متوقع في الخادم. الجسم هو `{"message": "Sorry, an unexpected error occurred"}`.

يعيد الطلب غير الصالح 400 مع قائمة بانتهاكات الحقول. يذكر كل انتهاك الحقل والسبب ووسيطات السبب:

{
  "code": 3,
  "message": "validation failed",
  "details": [
    {
      "@type": "type.googleapis.com/pushwoosh.rpc.errors.v3.BadRequest",
      "field_violations": [
        {
          "field": "key",
          "description": "a feature flag with this key already exists in the application",
          "reason": "KEY_TAKEN",
          "args": { "key": "new_checkout" }
        }
      ]
    }
  ]
}

يعيد الطلب الذي لا تسمح به حالة العلامة أو الخطة 400 مع شرط مسبق واحد فاشل. يبدأ الحقلان Type و Description فيه بحرف كبير:

{
  "code": 9,
  "message": "precondition failed",
  "details": [
    {
      "@type": "type.googleapis.com/pushwoosh.rpc.errors.v3.FailedPrecondition",
      "Type": "VERSION_CONFLICT",
      "Description": "feature flag was changed: version 3 was sent, the current one is 4"
    }
  ]
}

يأخذ reason لانتهاك الحقل و Type للشرط المسبق الفاشل هذه القيم:

السبب	الدافع
`KEY_INVALID`	المفتاح لا يطابق `^[A-Za-z0-9_.-]{1,58}$`.
`KEY_TAKEN`	علامة أخرى في التطبيق، بما في ذلك المؤرشفة، لديها هذا المفتاح.
`TEXT_INVALID`	الاسم أو الوصف طويل جدًا أو يحتوي على أحرف محظورة.
`PROPERTIES_LIMIT`	أكثر من 50 خاصية.
`PROPERTY_KEY_INVALID`	مفتاح خاصية غير صالح أو مكرر.
`PROPERTY_TYPE_INVALID`	نوع خاصية ليس `string` أو `number` أو `boolean` أو `json`.
`PROPERTY_TYPE_IMMUTABLE`	يغيّر الطلب نوع خاصية موجودة.
`VALUE_INVALID`	قيمة افتراضية أو قيمة تجاوز مفقودة، أو لا تطابق نوع الخاصية، أو متداخلة بعمق يزيد عن 5 مستويات.
`PROPERTIES_TOO_LARGE`	قيم خصائص العلامة تتجاوز 10,000 بايت.
`RULES_LIMIT`	أكثر من 10 قواعد.
`RULE_NOT_FOUND`	`rule_id` ليس من قواعد العلامة.
`PERCENT_INVALID`	`percent_bp` خارج النطاق `0`–`10000`.
`OVERRIDE_UNKNOWN_PROPERTY`	تشير قيمة تجاوز إلى خاصية غير موجودة في العلامة.
`SEGMENT_NOT_FOUND`	شريحة القاعدة غير موجودة أو تنتمي إلى تطبيق آخر.
`INVALID_SEGMENT_TYPE`	تحتوي شريحة القاعدة على شرط لا تستطيع العلامات تقييمه: حدث، أو ثابت، أو خارجي، أو آخر تحديث، أو أفضل وقت للإرسال.
`FLAG_DEPENDENCY`	تحتوي شريحة القاعدة على شرط علامة ميزة، ولا يمكن لعلامة أن تعتمد على علامة أخرى. تعيده `Create` و `Update` و `Restore`، مع رمز الشريحة في `filter_code`.
`CONFIRM_REQUIRED`	تم إرسال `Reshuffle` دون `confirm: true`.
`TAG_CONFLICT`	يحتوي الحساب على وسم مخصص باسم `PW_FF_` متبوعًا بمفتاح العلامة.
`FEATURE_FLAGS_NOT_ALLOWED`	خطة الحساب لا تتضمن علامات الميزات.
`FLAGS_LIMIT`	يحتوي التطبيق على عدد العلامات غير المؤرشفة الذي تسمح به الخطة.
`VERSION_CONFLICT`	تغيرت العلامة منذ `version` الذي أرسلته.
`PAYLOAD_TOO_LARGE`	ستشغل علامات التطبيق أكثر من 64 KB في استجابة جهاز واحد.
`STATUS_CONFLICT`	لا تسمح الحالة بالعملية، على سبيل المثال إيقاف علامة مؤرشفة.