Audience API

bulkSetTags

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

为设备列表设置标签值。

重要

使用 bulkSetTags 方法时，请确保为至少 50 台设备设置标签值。要为单个设备设置标签，请使用 setTags 方法。

请求正文

名称	类型	描述
application*	String	Pushwoosh application code
auth*	String	来自 Pushwoosh 控制面板的 API access token。
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	定义如何为列表类型的 tags 设置值：set、append 或 remove
devices.tags*	Object	为指定标签设置的值。

成功

{
  "request_id": "用于在 GET 方法中获取作业状态的 request_id",
  "status": "Pending"
}

错误

{
  "message": "invalid request"
}

请求：

{
  "application": "application code",   // 必需。Pushwoosh 应用代码
  "auth": "Pushwoosh auth token",      // 必需。来自 Pushwoosh 控制面板的 API access token
  "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": "用于在 GET 方法中获取作业状态的 request_id",
  "status": "Pending"
}

bulkSetTags status

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

返回 /bulkSetTags 操作的状态

路径参数

名称	类型	描述
request_id	String	来自前一个 /bulkSetTags 调用的请求 ID

查询参数

名称	类型	描述
detailed	Boolean	(true/false) 是否返回每个设备的详细信息

响应：

{
  "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 application code
auth	string	是	API access token。
devices	array	是	设备对象数组。每个对象代表一个设备及其相关数据。详情请参见下方的 设备对象参数 表。

设备对象参数

参数	类型	必需	描述
hwid	string	是	设备的 硬件 ID 或唯一标识符。
push_token	string	是	设备的 Push token。
platform	integer	是	平台标识符。了解更多
list_operator	string	否	确定列表类型标签的操作： - “append”: 将指定的值添加到标签列表。 - “remove”: 从标签列表中删除指定的值。 注意：如果未指定 list_operator 参数，标签列表中的所有现有值都将被提供的值替换。
tags	object	否	分配给设备的自定义 tags。标签是用于分段的键值对。

请求示例

{
  "application": "application code",   // 必需。Pushwoosh 应用代码
  "auth": "Pushwoosh auth token",      // 必需。来自 Pushwoosh 控制面板的 API access token
  "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，可用于跟踪批量注册过程的状态和结果。

{
  "request_id": "用于在 GET 方法中获取作业状态的 request_id",
  "status": "Pending"
}

bulkRegisterDevice status

您可以通过发出以下 GET 请求来检查批量注册过程的状态：

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

参数	类型	必需	描述
request_id	string	是	POST 请求返回的请求 ID。
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 application code
auth	string	是	API access token
devices	array	是	设备对象数组。每个对象代表一个设备及其相关数据。详情请参见下方的 设备对象参数 表。

设备对象参数

参数	类型	必需	描述
hwid	string	是	设备的硬件 ID 或唯一标识符。了解更多

请求示例

{
  "application": "application code",   // 必需。Pushwoosh 应用代码
  "auth": "Pushwoosh auth token",      // 必需。来自 Pushwoosh 控制面板的 API access token
  "devices": [{                        // 必需。设备数组
    "hwid": "device hwid",             // 必需。设备的唯一标识符（可以是电子邮件）。
  },
  {
    "hwid": "device hwid 2",           // 必需。第二个设备的唯一标识符。
  },
  {
    "hwid": "device hwid 3",           // 必需。第三个设备的唯一标识符。
  }]
}

响应

该方法会返回一个操作 ID，可用于跟踪批量处理过程的状态和结果。

{
  "request_id": "用于在 GET 方法中获取作业状态的 request_id",
  "status": "Pending"
}

bulkUnregisterDevice status

您可以通过发出以下 GET 请求来检查批量注销过程的状态：

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

参数	类型	必需	描述
request_id	string	是	POST 请求返回的请求 ID。
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"
    }
  ]
}