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

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	انتهاء صلاحية الفلتر. سيتم حذف الفلتر تلقائيًا في التاريخ المحدد، ما لم يتم استخدامه في Preset أو RSS Feed.

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"
  }
}

// creating Filters for Timezones
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
    "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 access token from Pushwoosh Control Panel
    "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", "ad_identifiers". إضافة "location" يضيف عمودي Latitude و Longitude إلى ملف CSV المصدر. إذا تم حذف exportData، يتم تضمين Latitude و Longitude في التصدير افتراضيًا. "ad_identifiers" يضيف أعمدة MADID، و Email SHA256، و Phone SHA256 لإنشاء ملف مصدر Google Customer Match أو Meta Custom Audience — انظر ملاحظة تصدير معرفات الإعلانات أدناه.
filterCode	لا	string	رمز الفلتر مُعد مسبقًا، يمكن استخدامه بدلاً من filterExpression. يمكن الحصول عليه من واجهة برمجة تطبيقات /listFilters أو من شريط عنوان متصفحك عند عرض الفلتر في لوحة التحكم.
applicationCode	مطلوب إذا كنت تستخدم filterExpression أو filterCode.	string	رمز تطبيق Pushwoosh
generateExport	لا	boolean	افتراضيًا يتم تعيينه على true، ويحتوي الرد على رابط لتنزيل الملف. إذا كان false، فسيتم إرسال عدد الأجهزة فقط في الرد.
format	لا	string	يحدد تنسيق الملف المصدر: “csv” أو “json_each_line”. إذا تم حذفه، يتم إنشاء ملف CSV.
tagsList	لا	array	يحدد Tags المراد تصديرها. للحصول على Tags المحددة فقط، يجب أن تحتوي مصفوفة “exportData” على القيمة “tags”.
includeWithoutTokens	لا	boolean	اضبط على true لتضمين المستخدمين الذين ليس لديهم push tokens في الملف المصدر. الافتراضي هو false.

200 ناجح

{
  "task_id": "177458"
}

مثال

{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // required. API access token from Pushwoosh Control Panel
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // filter conditions, refer to the Segmentation Language guide for syntax
  "filterCode": "12345-67890",                              // pre-made filter code, can be used instead of filterExpression
  "applicationCode": "00000-AAAAA",                         // Required if you're using either `filterExpression` or `filterCode`. Pushwoosh app code. Can be obtained from /listFilters API request or address bar of your browser while viewing the filter in Control Panel.
  "generateExport": true,                                   // if false, devices count only will be sent in response; by default, a response contains a link to download the CSV file
  "format": "json_each_line",                               // format of the file to present the data in: "csv" – the .csv file is downloaded; "json" – a JSON file with all expored devices; or "json_each_line" – JSON line for each device. If not specified, CSV is the default format.
  "exportData": ["hwids", "tags"],                          // optional. Data to export. Possible values: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys", "ad_identifiers"
  "tagsList": ["Name", "Level"],                            // optional. Specifies tags to export. To obtain the specific tags only, the "tags" value should be sent within the "exportData" array or the "exportData" be empty.
  "includeWithoutTokens": true                              // optional. Set to true to include users without push tokens in the exported file. Default is false.
}

ملاحظة

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

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

{
  "auth": "yxoPUlwqm…………pIyEX4H",            // API access token from Pushwoosh Control Panel
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // Filter expression referencing app segment
  "applicationCode": "AAAAA-BBBBB"           // Required Pushwoosh app code
}

تنبيه

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

نتائج exportSegment

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

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

نص الطلب

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

200: موافق

{
  "devicesCount": "24735",
  "filename": "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) الذي يربط جهازًا بمستخدم معين. إذا لم يتم تعيين User ID، يتم استخدام HWID.	user8192
Push Token	معرف فريد يتم تعيينه لجهاز بواسطة بوابات الرسائل السحابية. اعرف المزيد	eeeb2fd7…0fc3547
Type	نوع المنصة (عدد صحيح).	1
Type (humanized)	نوع المنصة (سلسلة نصية).	iOS
Age	قيمة Tag العمر الافتراضي.	29
ApplicationVersion	قيمة Tag إصدار التطبيق الافتراضي.	1.12.0.0
City	قيمة Tag المدينة الافتراضي.	us, boston
TagName	قيمة Tag تم إنشاؤه في حسابك.	TagValue

تصدير معرفات الإعلانات

أضف "ad_identifiers" إلى exportData للحصول على ملف منسق للتحميل مباشرة كمصدر Google Customer Match أو Meta Custom Audience. هذه القيمة اختيارية فقط — لا يتم تضمينها أبدًا افتراضيًا، حتى عند حذف exportData. لا يكون لها تأثير إلا عند تعيين format على "csv". طلبها مع "json" أو "json_each_line" لا يُرجع خطأ، ولكن يتم حذف الأعمدة أدناه بصمت من هذه التنسيقات.

الحقل	الوصف
MADID	معرف الإعلان المحمول (GAID أو IDFA)، يتم تحويله إلى أحرف صغيرة.
Email SHA256	تجزئة SHA-256 لبريد المستخدم الإلكتروني، يتم تحويله إلى أحرف صغيرة وتقليمه قبل التجزئة.
Phone SHA256	تجزئة SHA-256 لرقم هاتف المستخدم بتنسيق E.164 قبل التجزئة.

لا يزال يتم تصدير صف لمستخدم ليس لديه أي من المعرفات الثلاثة، مع ترك أعمدة MADID و Email SHA256 و Phone SHA256 فارغة.

تصدير نشاط التطبيق لكل مستخدم

ملاحظة

إحصائيات الحملة تُرجع أعداد الفتح/الإرسال مجمعة حسب الساعة والمنصة. لا يوجد عمود hwid أو user_id. لمعرفة أي المستخدمين فتحوا التطبيق ومتى، قم بتصدير شريحة مبنية على حدث PW_ApplicationOpen بدلاً من ذلك.

PW_ApplicationOpen مخصص للجوال فقط. بالنسبة لمشروع الويب، لا يُرجع تصدير الشريحة أي صفوف، لأن الحدث لا يتم إطلاقه هناك أبدًا.

1. قم ببناء تعبير فلتر على حدث PW_ApplicationOpen، محددًا بالفترة التي تحتاجها. استخدم عوامل تاريخ الحدث، على سبيل المثال “تم فتحه بالأمس”:

Event("AAAAA-BBBBB", "PW_ApplicationOpen", date daysago eq 1)

2. استدعِ /exportSegment مع filterExpression و applicationCode و exportData: ["hwids", "users"].
3. استدعِ /exportSegment/result مع task_id المُرجع لتنزيل ملف CSV مع عمودي Hwid و User ID لكل جهاز فتح التطبيق في تلك الفترة.

تنبيه

User ID يحمل أي معرف تقوم بتعيينه لجهاز. إذا لم تقم بتعيين واحد، فإنه يعود إلى HWID. يخبرك التصدير بمن فتح التطبيق خلال الفترة المفلترة. إنه ليس سجل أحداث لكل فتحة مع عمود طابع زمني، لذا قم ببناء شريحة واحدة لكل يوم (أو فترة) إذا كنت بحاجة إلى تفصيل يومي.