واجهة برمجة تطبيقات التجزئة (الفلاتر)

createFilter

POST https://api.pushwoosh.com/json/1.3/createFilter

تُنشئ فلترًا جديدًا.

نص الطلب

الاسم	مطلوب	النوع	الوصف
auth*	نعم	string	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
name*	نعم	string	اسم الفلتر.
filter_expression*	نعم	string	تعبير تم إنشاؤه وفقًا لقواعد لغة التجزئة. مثال: T(“City”, eq, “Madrid”) لتجزئة المستخدمين الذين مدينتهم هي مدريد.
application	لا	string	رمز تطبيق Pushwoosh. هذا المعامل قابل للاستخدام فقط مع الإعداد عالي السرعة؛ تجاهله في الحالات الأخرى.
expiration_date	لا	string	انتهاء صلاحية الفلتر. سيتم حذف الفلتر تلقائيًا في تاريخ محدد، ما لم يتم استخدامه في إعداد مسبق أو موجز RSS.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "name": "filter name"
  }
}

مثال

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "name": "City = Madrid",
    "filter_expression": "T(\"City\", eq, \"Madrid\")",
    "application": "B18XX-XXXXX",
    "expiration_date": "2025-01-01"
  }
}

// إنشاء فلاتر للمناطق الزمنية
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "name": "Timezone Filter",
    "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])"
  }
}

listFilters

POST https://api.pushwoosh.com/json/1.3/listFilters

تُرجع قائمة بالشرائح (الفلاتر) المتاحة مع شروطها.

نص الطلب

الاسم	مطلوب	النوع	الوصف
auth*	نعم	string	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
application*	نعم	string	رمز تطبيق Pushwoosh

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "filters": [{
      "code": "52551-F2F42",
      "name": "City = Madrid",
      "filter_expression": "T(\"City\", eq, \"madrid\")",
      "expiration_date": "2025-01-01",
      "application": "B18XX-XXXXX"
    }]
  }
}

مثال

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "application": "B18XX-XXXXX"
  }
}

deleteFilter

POST https://api.pushwoosh.com/json/1.3/deleteFilter

تحذف فلترًا موجودًا.

نص الطلب

الاسم	النوع	الوصف
auth*	string	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
name*	string	اسم الفلتر.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

مثال

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "name": "filter name"
  }
}

exportSegment

POST https://api.pushwoosh.com/api/v2/audience/exportSegment

طلب مجدول. يُصدّر قائمة المشتركين الذين يندرجون تحت شروط الفلتر المحددة.

نص الطلب

الاسم	مطلوب	النوع	الوصف
auth*	نعم	string	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
filterExpression*	نعم	string	شروط الفلتر
exportData	لا	array	البيانات المراد تصديرها. القيم الممكنة: "hwids", "push_tokens", "users", "tags", "location". إضافة "location" يضيف عمودي Latitude و Longitude إلى ملف CSV المُصدَّر. إذا تم حذف exportData، يتم تضمين Latitude و Longitude في التصدير افتراضيًا.
filterCode	لا	string	رمز الفلتر مُعد مسبقًا، يمكن استخدامه بدلاً من filterExpression. يمكن الحصول عليه من واجهة برمجة التطبيقات /listFilters أو شريط عنوان متصفحك عند عرض الفلتر في لوحة التحكم.
applicationCode	مطلوب إذا كنت تستخدم filterExpression أو filterCode.	string	رمز تطبيق Pushwoosh
generateExport	لا	boolean	افتراضيًا يتم تعيينه على true، وتحتوي الاستجابة على رابط لتنزيل الملف. إذا كان false، فسيتم إرسال عدد الأجهزة فقط في الاستجابة.
format	لا	string	يحدد تنسيق الملف المُصدَّر: “csv” أو “json_each_line”. إذا تم حذفه، يتم إنشاء ملف CSV.
tagsList	لا	array	يحدد العلامات (Tags) المراد تصديرها. للحصول على علامات محددة فقط، يجب أن تحتوي مصفوفة “exportData” على القيمة “tags”.
includeWithoutTokens	لا	boolean	اضبطه على true لتضمين المستخدمين الذين ليس لديهم رموز إشعارات في الملف المُصدَّر. القيمة الافتراضية هي false.

200 ناجح

{
  "task_id": "177458"
}

مثال

{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // مطلوب. رمز الوصول إلى API من لوحة تحكم Pushwoosh
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // شروط الفلتر، ارجع إلى دليل لغة التجزئة للصيغة
  "filterCode": "12345-67890",                              // رمز الفلتر المُعد مسبقًا، يمكن استخدامه بدلاً من filterExpression
  "applicationCode": "00000-AAAAA",                         // مطلوب إذا كنت تستخدم `filterExpression` أو `filterCode`. رمز تطبيق Pushwoosh. يمكن الحصول عليه من طلب API /listFilters أو شريط عنوان متصفحك أثناء عرض الفلتر في لوحة التحكم.
  "generateExport": true,                                   // إذا كان false، سيتم إرسال عدد الأجهزة فقط في الاستجابة؛ افتراضيًا، تحتوي الاستجابة على رابط لتنزيل ملف CSV
  "format": "json_each_line",                               // تنسيق الملف لتقديم البيانات فيه: "csv" – يتم تنزيل ملف .csv؛ "json" – ملف JSON مع جميع الأجهزة المصدرة؛ أو "json_each_line" – سطر JSON لكل جهاز. إذا لم يتم تحديده، فإن CSV هو التنسيق الافتراضي.
  "exportData": ["hwids", "tags"],                          // اختياري. البيانات المراد تصديرها. القيم الممكنة: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys"
  "tagsList": ["Name", "Level"],                            // اختياري. يحدد العلامات المراد تصديرها. للحصول على العلامات المحددة فقط، يجب إرسال القيمة "tags" داخل مصفوفة "exportData" أو أن تكون "exportData" فارغة.
  "includeWithoutTokens": true                              // اختياري. اضبطه على true لتضمين المستخدمين الذين ليس لديهم رموز إشعارات في الملف المُصدَّر. الافتراضي هو false.
}

ملاحظة

يرجى الاطلاع على مرجع لغة التجزئة لكتابة تعبيرات الفلتر هنا.

على سبيل المثال، لتصدير جميع المشتركين في تطبيق معين، استخدم شروط الفلتر التالية:

{
  "auth": "yxoPUlwqm…………pIyEX4H",            // رمز الوصول إلى API من لوحة تحكم Pushwoosh
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // تعبير الفلتر يشير إلى شريحة التطبيق
  "applicationCode": "AAAAA-BBBBB"           // رمز تطبيق Pushwoosh المطلوب
}

تنبيه

في الاستجابة، ستحصل على task_id للحصول على الملف الناتج. بعد ذلك، قم باستدعاء /exportSegment/result مع task_id هذا في نص الطلب لاسترداد الملف الناتج.

exportSegment results

POST https://api.pushwoosh.com/api/v2/audience/exportSegment/result

يسترد الرابط إلى ملف CSV مع نتائج /exportSegment.

نص الطلب

الاسم	النوع	الوصف
auth*	String	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
task_id*	String	المعرف الذي تم استلامه في استجابة /exportSegment الخاصة بك.

200: موافق

{
  "devicesCount": "24735",
  "csvFilename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip",
  "status": "completed"
}

مرر “task_id” الذي تلقيته في استجابة /exportSegment في نص طلب /exportSegment/result.

في استجابة /exportSegment/result، ستتلقى المعامل “filename”. اتبع الرابط الموجود في قيمة هذا المعامل لتنزيل أرشيف ZIP تلقائيًا. قم بفك ضغط الأرشيف لاسترداد ملف CSV أو JSON (حسب “format” المحدد في طلبك) الذي يحتوي على بيانات الأجهزة.

بدءًا من 3 أبريل 2025، يلزم الحصول على إذن لتنزيل الملف:

• إذا كنت تقوم بالتنزيل عبر متصفح، فما عليك سوى تسجيل الدخول إلى لوحة تحكم Pushwoosh للوصول.
• إذا كنت تقوم بالتنزيل عبر برنامج خادم، فقم بتضمين الترويسة التالية في طلبك: Authorization: Token YOUR_API_TOKEN

إذا حددت “exportData” في طلب /exportSegment الخاص بك، فسيحتوي الملف الذي تم تنزيله على البيانات المطلوبة فقط. بشكل افتراضي، يحتوي الملف على بيانات المستخدم التالية:

الحقل	الوصف	مثال على القيمة
Hwid	معرف الجهاز (Hardware ID)	01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8
User ID	معرف المستخدم (User ID) الذي يربط جهازًا بمستخدم معين. إذا لم يتم تعيين معرف مستخدم، يتم استخدام HWID.	user8192
Push Token	معرف فريد يتم تعيينه لجهاز بواسطة بوابات الرسائل السحابية. اعرف المزيد	eeeb2fd7…0fc3547
Type	نوع المنصة (عدد صحيح).	1
Type (humanized)	نوع المنصة (نص).	iOS
Age	قيمة علامة العمر الافتراضية.	29
ApplicationVersion	قيمة علامة إصدار التطبيق الافتراضية.	1.12.0.0
City	قيمة علامة المدينة الافتراضية.	us, boston
TagName	قيمة علامة تم إنشاؤها في حسابك.	TagValue