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

## bulkSetTags

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

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

<Aside type="caution" title="هام">
  عند استخدام طريقة `bulkSetTags`، تأكد من تعيين قيم الوسوم لـ 50 جهازًا على الأقل. لتعيين وسوم لجهاز واحد، استخدم طريقة [`setTags`](/ar/developer/api-reference/device-api/#settags).
</Aside>

#### جسم الطلب

| الاسم | النوع | الوصف |
| ---------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| application\* | سلسلة نصية (String) | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code) |
| auth\* | سلسلة نصية (String) | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| create\_missing\_tags | قيمة منطقية (Boolean) | إذا كانت القيمة true، يتم إنشاء الوسوم المفقودة تلقائيًا. |
| devices\* | كائن (Object) | مصفوفة من الأجهزة. |
| devices.hwid | سلسلة نصية (String) | يمكن استخدامه لتعريف جهاز بدلاً من user\_id أو push\_token. [اعرف المزيد](/ar/developer/api-reference/api-identifiers/#hardware-id) |
| devices.user\_id | سلسلة نصية (String) | يمكن استخدامه لتعريف مستخدم بدلاً من hwid أو push\_token. [اعرف المزيد](/ar/developer/api-reference/api-identifiers/#user-id) |
| devices.push\_token | سلسلة نصية (String) | يمكن استخدامه لتعريف جهاز بدلاً من hwid أو user\_id. [اعرف المزيد](/ar/developer/api-reference/api-identifiers/#push-token) |
| devices.list\_operator | سلسلة نصية (String) | يحدد كيفية تعيين القيم لـ [الوسوم](/ar/developer/api-reference/api-identifiers/#tag) من نوع القائمة: set، append، أو remove |
| devices.tags\* | كائن (Object) | القيم التي سيتم تعيينها للوسوم المحددة. |

<Tabs>
  <TabItem label="نجاح (OK)">
    ```json
    {
      "request_id": "request_id to use in GET method to obtain job status",
      "status": "Pending"
    }
    ```
  </TabItem>

  <TabItem label="خطأ (Error)">
    ```json
    {
      "message": "invalid request"
    }
    ```
  </TabItem>
</Tabs>


```json title="الطلب:"
{
  "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"
    }
  }]
}

```

```json title="الاستجابة:"
{
  "request_id": "request_id to use in GET method to obtain job status",
  "status": "Pending"
}
```

## bulkSetTags status

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

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

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

| الاسم | النوع | الوصف |
| ----------- | ------ | ------------------------------------------ |
| request\_id | سلسلة نصية (String) | request id من استدعاء `/bulkSetTags` السابق |

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

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

```json title="الاستجابة:"
{
  "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](/ar/developer/api-reference/api-identifiers/#application-code) |
| auth | سلسلة نصية (string) | نعم | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token). |
| devices | مصفوفة (array) | نعم | مصفوفة من كائنات الأجهزة. يمثل كل كائن جهازًا وبياناته المرتبطة به. انظر التفاصيل في جدول **معلمات كائن الجهاز** أدناه. |

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

| المعلمة | النوع | مطلوب | الوصف |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid | سلسلة نصية (string) | نعم | [معرف الجهاز (hardware ID)](/ar/developer/api-reference/api-identifiers/#hardware-id) أو معرف فريد للجهاز. |
| push_token | سلسلة نصية (string) | نعم | [رمز الدفع (Push token)](/ar/developer/api-reference/api-identifiers/#push-token) للجهاز. |
| platform | عدد صحيح (integer) | نعم | معرف المنصة. [اعرف المزيد](/ar/developer/api-reference/messages-api/api-prerequisites/#platforms) |
| list_operator | سلسلة نصية (string) | لا | يحدد الإجراء للوسوم من نوع القائمة: <br/> - **"append"**: إضافة القيمة المحددة إلى قائمة الوسم. <br/> - **"remove"**: إزالة القيمة المحددة من قائمة الوسم. <br/> **ملاحظة**: إذا لم يتم تحديد المعلمة `list_operator`، فسيتم استبدال جميع القيم الحالية في قائمة الوسم بالقيم المقدمة. |
| tags | كائن (object) | لا | [الوسوم](/ar/developer/api-reference/api-identifiers/#tag) المخصصة المعينة للجهاز. الوسوم هي أزواج من المفاتيح والقيم تستخدم للتقسيم. |



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

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

```

### الاستجابة

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

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

```

## bulkRegisterDevice status

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

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

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


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

```json
{
  "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](/ar/developer/api-reference/api-identifiers/#application-code) |
| auth | سلسلة نصية (string) | نعم | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) |
| devices | مصفوفة (array) | نعم | مصفوفة من كائنات الأجهزة. يمثل كل كائن جهازًا وبياناته المرتبطة به. انظر التفاصيل في جدول **معلمات كائن الجهاز** أدناه. |

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

| المعلمة | النوع | مطلوب | الوصف |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid | سلسلة نصية (string) | نعم | معرف الجهاز (hardware ID) أو معرف فريد للجهاز. [اعرف المزيد](/ar/developer/api-reference/api-identifiers/#hardware-id) |



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

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

```

### الاستجابة

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

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

```

## bulkUnregisterDevice status

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

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

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


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

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

```