# Audience API

## bulkSetTags

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

기기 목록에 대한 태그 값을 설정합니다.

<Aside type="caution" title="중요">
  `bulkSetTags` 메서드를 사용할 때는 최소 50개 기기에 대한 태그 값이 설정되었는지 확인하세요. 단일 기기에 태그를 설정하려면 [`setTags`](/ko/developer/api-reference/device-api/#settags) 메서드를 사용하세요.
</Aside>

#### 요청 본문

| 이름                                           | 타입    | 설명                                                                 |
| ---------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| application\*  | String  | [Pushwoosh 애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code)                                                     |
| auth\*         | String  | Pushwoosh 제어판의 [API 액세스 토큰](/ko/developer/api-reference/api-identifiers/#api-access-token).                              |
| create\_missing\_tags                          | Boolean | true인 경우, 누락된 태그가 자동으로 생성됩니다.                            |
| devices\*      | Object  | 기기 배열입니다.                                                           |
| devices.hwid                                   | String  | user\_id 또는 push\_token 대신 기기를 식별하는 데 사용할 수 있습니다. [자세히 알아보기](/ko/developer/api-reference/api-identifiers/#hardware-id)         |
| devices.user\_id                               | String  | hwid 또는 push\_token 대신 사용자를 식별하는 데 사용할 수 있습니다. [자세히 알아보기](/ko/developer/api-reference/api-identifiers/#user-id)               |
| devices.push\_token                            | String  | hwid 또는 user\_id 대신 기기를 식별하는 데 사용할 수 있습니다. [자세히 알아보기](/ko/developer/api-reference/api-identifiers/#push-token)                |
| devices.list\_operator                         | String  | 목록 유형의 [태그](/ko/developer/api-reference/api-identifiers/#tag)에 대한 값을 설정하는 방법을 정의합니다: set, append 또는 remove |
| devices.tags\* | Object  | 지정된 태그에 대해 설정할 값입니다.                                       |

<Tabs>
  <TabItem label="성공">
    ```json
    {
      "request_id": "작업 상태를 얻기 위해 GET 메서드에서 사용할 request_id",
      "status": "Pending"
    }
    ```
  </TabItem>

  <TabItem label="오류">
    ```json
    {
      "message": "invalid request"
    }
    ```
  </TabItem>
</Tabs>


```json title="요청:"
{
  "application": "application code",   // 필수. Pushwoosh 앱 코드
  "auth": "Pushwoosh auth token",      // 필수. Pushwoosh 제어판의 API 액세스 토큰
  "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"
    }
  }]
}

```

```json title="응답:"
{
  "request_id": "작업 상태를 얻기 위해 GET 메서드에서 사용할 request_id",
  "status": "Pending"
}
```

## bulkSetTags 상태

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

`/bulkSetTags` 작업의 상태를 반환합니다.

#### 경로 파라미터

| 이름        | 타입   | 설명                                |
| ----------- | ------ | ------------------------------------------ |
| request\_id | String | 이전 `/bulkSetTags` 호출에서 받은 요청 ID |

#### 쿼리 파라미터

| 이름     | 타입    | 설명                                             |
| -------- | ------- | ------------------------------------------------------- |
| detailed | Boolean | (true/false) 기기별 상세 정보 반환 여부 |

```json title="응답:"
{
  "request_id": "요청 ID",
  "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 애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code) |
| auth | string | 예 | [API 액세스 토큰](/ko/developer/api-reference/api-identifiers/#api-access-token). |
| devices | array | 예 | 기기 객체의 배열입니다. 각 객체는 기기와 관련 데이터를 나타냅니다. 자세한 내용은 아래 **기기 객체 파라미터** 표를 참조하세요. |

#### 기기 객체 파라미터

| 파라미터       | 타입     | 필수 | 설명                                                                                     |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid          | string | 예      | 기기의 [하드웨어 ID](/ko/developer/api-reference/api-identifiers/#hardware-id) 또는 고유 식별자입니다.                                           |
| push_token    | string | 예      | 기기의 [푸시 토큰](/ko/developer/api-reference/api-identifiers/#push-token)입니다.                                                                     |
| platform      | integer| 예      | 플랫폼 식별자입니다. [자세히 알아보기](/ko/developer/api-reference/messages-api/api-prerequisites/#platforms) |
| list_operator | string | 아니요       | 목록 유형 태그에 대한 작업을 결정합니다: <br/> - **"append"**: 지정된 값을 태그 목록에 추가합니다. <br/> - **"remove"**: 지정된 값을 태그 목록에서 제거합니다. <br/> **참고**: `list_operator` 파라미터가 지정되지 않은 경우, 태그 목록의 모든 기존 값은 제공된 값으로 대체됩니다. |
| tags          | object | 아니요       | 기기에 할당된 사용자 정의 [태그](/ko/developer/api-reference/api-identifiers/#tag)입니다. 태그는 세분화를 위해 사용되는 키-값 쌍입니다.            |



#### 요청 예시

```json
{
  "application": "application code",   // 필수. Pushwoosh 앱 코드
  "auth": "Pushwoosh auth token",      // 필수. Pushwoosh 제어판의 API 액세스 토큰
  "devices": [{                        // 필수. 기기 배열
    "hwid": "device hwid",             // 필수. 기기의 고유 식별자 (이메일일 수 있음).
    "push_token": "device push token", // 필수. 기기의 푸시 알림 토큰.
    "platform": 14,                    // 필수. 기기 플랫폼 (예: 이메일의 경우 14).
    "list_operator": "append",         // 선택. 목록 태그용. 목록 유형의 태그에 지정된 값을 추가하거나 제거합니다.
    "tags": {                          // 선택. 지정된 태그에 대해 설정할 값입니다.
      "language": "en",                //           올바른 값 유형을 사용하세요.
      "CSV_Import": "summer_camp"
    }
  },
  {
    "hwid": "device hwid 2",           // 필수. 두 번째 기기의 고유 식별자.
    "push_token": "device push token 2", // 필수. 기기의 푸시 알림 토큰.
    "platform": 14,                    // 필수. 기기 플랫폼.
    "list_operator": "remove",         // 선택. 목록 유형의 태그에서 값을 추가하거나 제거합니다.
    "tags": {                          // 선택. 지정된 태그에서 제거할 값입니다.
      "language": "en",
      "CSV_Import": "summer_camp2"
    }
  },
  {
    "hwid": "device hwid 3",           // 필수. 세 번째 기기의 고유 식별자.
    "push_token": "device push token 3", // 필수. 기기의 푸시 알림 토큰.
    "platform": 14,                    // 필수. 기기 플랫폼.
    "tags": {                          // 선택. 지정된 태그에 대해 설정할 값입니다.
      "language": "en",
      "CSV_Import": "summer_camp3"
    }
  }]
}

```

### 응답

이 메서드는 작업 ID로 응답하며, 이 ID를 사용하여 대량 등록 프로세스의 상태와 결과를 추적할 수 있습니다.

```json
{
  "request_id": "작업 상태를 얻기 위해 GET 메서드에서 사용할 request_id",
  "status": "Pending"
}

```

## bulkRegisterDevice 상태

다음 **GET** 요청을 통해 대량 등록 프로세스의 상태를 확인할 수 있습니다:

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

| 파라미터 | 타입 | 필수 | 설명 |
| ----- | ----- | ----- | ----- |
| request_id | string | 예 | POST 요청에 의해 반환된 요청 ID입니다. |
| 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 애플리케이션 코드](/ko/developer/api-reference/api-identifiers/#application-code) |
| auth | string | 예 | [API 액세스 토큰](/ko/developer/api-reference/api-identifiers/#api-access-token) |
| devices | array | 예 | 기기 객체의 배열입니다. 각 객체는 기기와 관련 데이터를 나타냅니다. 자세한 내용은 아래 **기기 객체 파라미터** 표를 참조하세요. |

#### 기기 객체 파라미터

| 파라미터       | 타입     | 필수 | 설명                                                                                     |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid          | string | 예      | 기기의 하드웨어 ID 또는 고유 식별자입니다. [자세히 알아보기](/ko/developer/api-reference/api-identifiers/#hardware-id)                                          |



#### 요청 예시

```json
{
  "application": "application code",   // 필수. Pushwoosh 앱 코드
  "auth": "Pushwoosh auth token",      // 필수. Pushwoosh 제어판의 API 액세스 토큰
  "devices": [{                        // 필수. 기기 배열
    "hwid": "device hwid",             // 필수. 기기의 고유 식별자 (이메일일 수 있음).
  },
  {
    "hwid": "device hwid 2",           // 필수. 두 번째 기기의 고유 식별자.
  },
  {
    "hwid": "device hwid 3",           // 필수. 세 번째 기기의 고유 식별자.
  }]
}

```

### 응답

이 메서드는 작업 ID로 응답하며, 이 ID를 사용하여 대량 프로세스의 상태와 결과를 추적할 수 있습니다.

```json
{
  "request_id": "작업 상태를 얻기 위해 GET 메서드에서 사용할 request_id",
  "status": "Pending"
}

```

## bulkUnregisterDevice 상태

다음 **GET** 요청을 통해 대량 등록 해제 프로세스의 상태를 확인할 수 있습니다:

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

| 파라미터 | 타입 | 필수 | 설명 |
| ----- | ----- | ----- | ----- |
| request_id | string | 예 | POST 요청에 의해 반환된 요청 ID입니다. |
| 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"
    }
  ]
}

```