Audience API

bulkSetTags

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

يحدد قيم العلامات (tags) لقائمة الأجهزة.

جسم الطلب (Request Body)

الاسم	النوع	الوصف
application*	String	كود تطبيق Pushwoosh
auth*	String	رمز الوصول لـ API من لوحة تحكم Pushwoosh.
create_missing_tags	Boolean	إذا كان true، يتم إنشاء العلامات المفقودة تلقائياً.
devices*	Object	مصفوفة من الأجهزة.
devices.hwid	String	يمكن استخدامه لتعريف جهاز بدلاً من user_id أو push_token. اعرف المزيد
devices.user_id	String	يمكن استخدامه لتعريف مستخدم بدلاً من hwid أو push_token. اعرف المزيد
devices.push_token	String	يمكن استخدامه لتعريف جهاز بدلاً من hwid أو user_id. اعرف المزيد
devices.list_operator	String	يحدد كيفية تعيين القيم للعلامات من نوع القائمة: set (تعيين)، append (إضافة)، أو remove (إزالة)
devices.tags*	Object	القيم المراد تعيينها للعلامات المحددة.

OK
خطأ

{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}

{
  "message": "invalid request"
}

{
  "application": "application code",   // مطلوب. كود تطبيق Pushwoosh
  "auth": "Pushwoosh auth token",      // مطلوب. رمز الوصول لـ API من لوحة تحكم Pushwoosh
  "create_missing_tags": false,        // اختياري. هل يجب إنشاء العلامات المفقودة تلقائياً
  "devices": [{                        // مطلوب. مصفوفة الأجهزة
    "hwid": "device hwid",             // اختياري. يمكن استخدامه لتعريف جهاز بدلاً من
                                       //           "user_id" أو "push_token".
    "user_id": "user ID",              // اختياري. يمكن استخدامه لتعريف مستخدم بدلاً من "hwid" أو "push_token".
    "push_token": "device push token", // اختياري. يمكن استخدامه لتعريف جهاز بدلاً من "hwid" أو "user_id".
    "list_operator": "set",            // مطلوب. لعلامات القائمة. يحدد كيفية تعيين القيم
                                       //           للعلامات من نوع القائمة: set، append، أو remove
    "tags": {                          // مطلوب. القيم المراد تعيينها للعلامات المحددة.
      "tag_name": "tagvalue",          //           استخدم نوع القيمة الصحيح
      "tag_name2": "tagvalue2"
    }
  }]
}

{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}

حالة bulkSetTags

GET https://api.pushwoosh.com/api/v2/audience/bulkSetTags/{request_id}?detailed=false

يُرجع حالة عملية /bulkSetTags.

معاملات المسار (Path Parameters)

الاسم	النوع	الوصف
request_id	String	معرف الطلب (request id) من استدعاء `/bulkSetTags` السابق

معاملات الاستعلام (Query Parameters)

الاسم	النوع	الوصف
detailed	Boolean	(true/false) ما إذا كان سيتم إرجاع معلومات مفصلة لكل جهاز

{
  "request_id": "id of the request",
  "status": "Completed",          // أيضاً "Pending"، "Failed"
  "progress": 100,                // تقدم الوظائف 0-100
  "devices_success": 100,         // الأجهزة الناجحة
  "devices_not_found": 0,         // الأجهزة غير الموجودة في Pushwoosh
  "devices_failed": 0,            // الأجهزة التي حدث بها خطأ
  "devices": [{                   // تقرير الجهاز (فقط عند detailed = true)
    "hwid": "device hwid",
    "status": "done",             // أيضاً "failed"، "not found"
    "tags": {
      "tagName": "ok",
      "tagName2": "tag not found",
      "tagName3": "wrong value. expect :string"
    }
  }]
}

bulkRegisterDevice

يقوم بتسجيل أجهزة متعددة في Pushwoosh في طلب واحد. كما يسمح بتحديد علامات مختلفة لكل جهاز.

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

معاملات جسم الطلب

المعامل	النوع	مطلوب	الوصف
application	string	نعم	كود تطبيق Pushwoosh
auth	string	نعم	رمز الوصول لـ API.
devices	array	نعم	مصفوفة من كائنات الأجهزة. يمثل كل كائن جهازاً والبيانات المرتبطة به. انظر التفاصيل في جدول معاملات كائن الجهاز أدناه.

معاملات كائن الجهاز

المعامل	النوع	مطلوب	الوصف
hwid	string	نعم	معرف الجهاز (Hardware ID) أو المعرف الفريد للجهاز.
push_token	string	نعم	رمز الـ Push للجهاز.
platform	integer	نعم	معرف المنصة. اعرف المزيد
list_operator	string	لا	يحدد الإجراء للعلامات من نوع القائمة: “append”: إضافة القيمة المحددة إلى قائمة العلامات. “remove”: إزالة القيمة المحددة من قائمة العلامات. ملاحظة: إذا لم يتم تحديد معامل `list_operator`، فسيتم استبدال جميع القيم الموجودة في قائمة العلامات بالقيم المقدمة.
tags	object	لا	علامات مخصصة معينة للجهاز. العلامات هي أزواج مفتاح-قيمة تستخدم للتقسيم (segmentation).

مثال الطلب

{
  "application": "application code",   // مطلوب. كود تطبيق Pushwoosh
  "auth": "Pushwoosh auth token",      // مطلوب. رمز الوصول لـ API من لوحة تحكم Pushwoosh
  "devices": [{                        // مطلوب. مصفوفة الأجهزة
    "hwid": "device hwid",             // مطلوب. المعرف الفريد للجهاز (يمكن أن يكون بريداً إلكترونياً).
    "push_token": "device push token", // مطلوب. رمز إشعار Push للجهاز.
    "platform": 14,                    // مطلوب. منصة الجهاز (على سبيل المثال، 14 للبريد الإلكتروني).
    "list_operator": "append",         // اختياري. لعلامات القائمة. يضيف أو يزيل القيمة (القيم) المحددة من العلامة من نوع القائمة.
    "tags": {                          // اختياري. القيم المراد تعيينها للعلامات المحددة.
      "language": "en",                //           استخدم نوع القيمة الصحيح.
      "CSV_Import": "summer_camp"
    }
  },
  {
    "hwid": "device hwid 2",           // مطلوب. المعرف الفريد للجهاز الثاني.
    "push_token": "device push token 2", // مطلوب. رمز إشعار Push للجهاز.
    "platform": 14,                    // مطلوب. منصة الجهاز.
    "list_operator": "remove",         // اختياري. يضيف أو يزيل القيم من العلامات من نوع القائمة.
    "tags": {                          // اختياري. القيم المراد إزالتها من العلامات المحددة.
      "language": "en",
      "CSV_Import": "summer_camp2"
    }
  },
  {
    "hwid": "device hwid 3",           // مطلوب. المعرف الفريد للجهاز الثالث.
    "push_token": "device push token 3", // مطلوب. رمز إشعار Push للجهاز.
    "platform": 14,                    // مطلوب. منصة الجهاز.
    "tags": {                          // اختياري. القيم المراد تعيينها للعلامات المحددة.
      "language": "en",
      "CSV_Import": "summer_camp3"
    }
  }]
}

الاستجابة

تستجيب الطريقة بمعرف عملية (operation ID)، والذي يمكن استخدامه لتتبع الحالة ونتائج عملية التسجيل الجماعي.

{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}

حالة bulkRegisterDevice

يمكنك التحقق من حالة عملية التسجيل الجماعي عن طريق إجراء طلب GET التالي:

GET https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice/{request_id}?detailed=true

المعامل	النوع	مطلوب	الوصف
request_id	string	نعم	معرف الطلب الذي تم إرجاعه بواسطة طلب POST.
detailed	boolean	لا	إذا تم تعيينه إلى `true`، تتضمن الاستجابة نتائج مفصلة لكل جهاز مسجل.

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

{
  "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782",
  "status": "Completed",
  "progress": 100,
  "devices_success": 4,
  "devices": [
    {
      "hwid": "user1@example.com",
      "status": "done"
    },
    {
      "hwid": "user2@example.com",
      "status": "done"
    },
    {
      "hwid": "user3@example.com",
      "status": "done"
    },
    {
      "hwid": "invalid_email@example.com",
      "status": "failed"
    }
  ]
}

bulkUnregisterDevice

يلغي تسجيل أجهزة متعددة من Pushwoosh في طلب واحد.

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

معاملات جسم الطلب

المعامل	النوع	مطلوب	الوصف
application	string	نعم	كود تطبيق Pushwoosh
auth	string	نعم	رمز الوصول لـ API
devices	array	نعم	مصفوفة من كائنات الأجهزة. يمثل كل كائن جهازاً والبيانات المرتبطة به. انظر التفاصيل في جدول معاملات كائن الجهاز أدناه.

معاملات كائن الجهاز

المعامل	النوع	مطلوب	الوصف
hwid	string	نعم	معرف الجهاز (Hardware ID) أو المعرف الفريد للجهاز. اعرف المزيد

مثال الطلب

{
  "application": "application code",   // مطلوب. كود تطبيق Pushwoosh
  "auth": "Pushwoosh auth token",      // مطلوب. رمز الوصول لـ API من لوحة تحكم Pushwoosh
  "devices": [{                        // مطلوب. مصفوفة الأجهزة
    "hwid": "device hwid",             // مطلوب. المعرف الفريد للجهاز (يمكن أن يكون بريداً إلكترونياً).
  },
  {
    "hwid": "device hwid 2",           // مطلوب. المعرف الفريد للجهاز الثاني.
  },
  {
    "hwid": "device hwid 3",           // مطلوب. المعرف الفريد للجهاز الثالث.
  }]
}

الاستجابة

تستجيب الطريقة بمعرف عملية، والذي يمكن استخدامه لتتبع الحالة ونتائج العملية الجماعية.

{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}

حالة bulkUnregisterDevice

يمكنك التحقق من حالة عملية إلغاء التسجيل الجماعي عن طريق إجراء طلب GET التالي:

GET https://api.pushwoosh.com/api/v2/audience/bulkUnregisterDevice/{request_id}?detailed=true

المعامل	النوع	مطلوب	الوصف
request_id	string	نعم	معرف الطلب الذي تم إرجاعه بواسطة طلب POST.
detailed	boolean	لا	إذا تم تعيينه إلى `true`، تتضمن الاستجابة نتائج مفصلة لكل جهاز تم إلغاء تسجيله.

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

{
  "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782",
  "status": "Completed",
  "progress": 100,
  "devices_success": 4,
  "devices": [
    {
      "hwid": "user1@example.com",
      "status": "done"
    },
    {
      "hwid": "user2@example.com",
      "status": "done"
    },
    {
      "hwid": "user3@example.com",
      "status": "done"
    },
    {
      "hwid": "invalid_email@example.com",
      "status": "failed"
    }
  ]
}