واجهة برمجة تطبيقات الجمهور (Audience API)

تسجّل واجهة برمجة تطبيقات الجمهور (Audience API) الأجهزة وتلغي تسجيلها وتعيّن لها العلامات بشكل مجمّع. تقبل كل طريقة مجمّعة قائمة بالأجهزة في طلب واحد، وتعالجها في الخلفية، وتُرجع request_id. مرّر request_id هذا إلى طريقة الحالة المقابلة للتحقق من النتيجة. استخدم الطرق المجمّعة لعمليات الاستيراد وتحديثات العلامات الكبيرة، وواجهة برمجة تطبيقات الجهاز لجهاز واحد.

bulkSetTags

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

يُعيّن قيم الوسوم لقائمة الأجهزة.

جسم الطلب

الاسم	النوع	الوصف
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	القيم التي سيتم تعيينها للوسوم المحددة.

موافق
خطأ

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

{
  "message": "invalid request"
}

{
  "application": "application code",   // required. Pushwoosh app code
  "auth": "Pushwoosh auth token",      // required. API access token from Pushwoosh Control Panel
  "create_missing_tags": false,        // optional. Should automatically create missing tags
  "devices": [{                        // required. Array of devices
    "hwid": "device hwid",             // optional. Can be used to identify a device instead of
                                       //           "user_id" or "push_token".
    "user_id": "user ID",              // optional. Can be used to identify a user instead of "hwid" or "push_token".
    "push_token": "device push token", // optional. Can be used to identify a device instead of "hwid" or "user_id".
    "list_operator": "set",            // required. For list tags. Defines how to set values for
                                       //           tags of the list type: set, append, or remove
    "tags": {                          // required. Values to set for the tags specified.
      "tag_name": "tagvalue",          //           use correct value type
      "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

معلمات المسار

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

معلمات الاستعلام

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

{
  "request_id": "id of the request",
  "status": "Completed",          // also "Pending", "Failed"
  "progress": 100,                // jobs progress 0-100
  "devices_success": 100,         // good devices
  "devices_not_found": 0,         // devices not found in Pushwoosh
  "devices_failed": 0,            // errored
  "devices": [{                   // device report (only in detailed = true)
    "hwid": "device hwid",
    "status": "done",             // also "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 token) للجهاز.
platform	integer	نعم	معرف المنصة. اعرف المزيد
list_operator	string	لا	يحدد الإجراء للوسوم من نوع القائمة: - “append”: إضافة القيمة المحددة إلى قائمة الوسم. - “remove”: إزالة القيمة المحددة من قائمة الوسم. ملاحظة: إذا لم يتم تحديد معلمة `list_operator`، فسيتم استبدال جميع القيم الموجودة في قائمة الوسم بالقيم المقدمة.
tags	object	لا	الوسوم المخصصة المعينة للجهاز. الوسوم هي أزواج مفتاح-قيمة تستخدم للتقسيم.

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

{
  "application": "application code",   // required. Pushwoosh app code
  "auth": "Pushwoosh auth token",      // required. API access token from Pushwoosh Control Panel
  "devices": [{                        // required. Array of devices
    "hwid": "device hwid",             // required. Unique identifier for the device (can be an email).
    "push_token": "device push token", // required. Push notification token for the device.
    "platform": 14,                    // required. Device platform (e.g., 14 for email).
    "list_operator": "append",         // optional. For list tags. Adds or removes the specified value(s) from the tag of list type.
    "tags": {                          // optional. Values to set for the specified tags.
      "language": "en",                //           use correct value type.
      "CSV_Import": "summer_camp"
    }
  },
  {
    "hwid": "device hwid 2",           // required. Unique identifier for the second device.
    "push_token": "device push token 2", // required. Push notification token for the device.
    "platform": 14,                    // required. Device platform.
    "list_operator": "remove",         // optional. Adds or removes values from tags of the list type.
    "tags": {                          // optional. Values to remove from the specified tags.
      "language": "en",
      "CSV_Import": "summer_camp2"
    }
  },
  {
    "hwid": "device hwid 3",           // required. Unique identifier for the third device.
    "push_token": "device push token 3", // required. Push notification token for the device.
    "platform": 14,                    // required. Device platform.
    "tags": {                          // optional. Values to set for the specified tags.
      "language": "en",
      "CSV_Import": "summer_camp3"
    }
  }]
}

الاستجابة

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

{
  "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	نعم	معرف الجهاز أو المعرف الفريد للجهاز. اعرف المزيد

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

{
  "application": "application code",   // required. Pushwoosh app code
  "auth": "Pushwoosh auth token",      // required. API access token from Pushwoosh Control Panel
  "devices": [{                        // required. Array of devices
    "hwid": "device hwid",             // required. Unique identifier for the device (can be an email).
  },
  {
    "hwid": "device hwid 2",           // required. Unique identifier for the second device.
  },
  {
    "hwid": "device hwid 3",           // required. Unique identifier for the third device.
  }]
}

الاستجابة

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

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