跳到内容
用户指南支持 请求演示 登录
Pushwoosh.com

设备 API

registerDevice

Anchor link to

POST https://api.pushwoosh.com/json/1.3/registerDevice

由 SDK 内部调用。为应用程序注册设备。

请求头
Anchor link to
名称必需值描述
Authorization是Token XXXX用于访问设备 API 的 API 设备令牌。将 XXXX 替换为您的实际设备 API 令牌。
请求体
Anchor link to
名称类型描述
application*stringPushwoosh 应用程序代码
push_tokenstring设备的 Push token (推送令牌)。
languagestring设备的语言区域设置。必须是符合 ISO-639-1 标准的小写双字母代码。
hwid*string用于识别设备的唯一字符串（iOS 上的 IDFV，Android 上的随机生成值）。了解更多
timezoneinteger设备的秒级时区偏移量。
device_type*integer设备类型。请参阅下面的可能值。
emailstring要注册的电子邮件地址（用于电子邮件用户，替代 HWID 和 push token）。
tagsobject分配给已注册设备的标签值。
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
示例
{
  "request": {
    "application": "XXXXX-XXXXX",        // 必需。Pushwoosh 应用程序代码
    "push_token": "dec301908b9ba8XXXXX57a58e40f96f5XXXXX2068674f5XXXXa25cdc250a2a41", // 可选。
    "hwid": "1CA6XXXXX-8DAC-XXXXX-XXXXX-B756288B6D3C",                                   // 必需。硬件设备 ID
    "idfa": "AEBE52E7-0XXXXX-455A-XXXXX-E57283966239",                                   // 可选。
    "timezone": 3600,                    // 可选。秒级偏移量
    "device_type": 1,                    // 必需。请参阅下面的可能值。对于电子邮件，
                                         //           请使用下面描述的 "emails" 参数。
    "email": "email_address@domain.com", // 用于为您的电子邮件项目注册电子邮件地址，
                                         //           替代 "hwid" 和 "push_token"
    "language": "en",                    // 可选。ISO 639-1|639-2 语言代码
    "userId": "Alex",                    // 可选。
    "tags": {                            // 可选。为已注册设备设置的标签值
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"], // 为列表类型的标签设置值列表
      "DateTag": "2024-10-02 22:11",     // 注意时间应为 UTC
      "BooleanTag": true                 // 有效值为：true, false
    },


    // 系统标签，可选
    "app_version": "1.2.3",
    "device_model": "Samsung SM-G355H",
    "os_version": "2.3",


    // 可选的 chrome/firefox 加密密钥
    "public_key": "BNmDO4BTKEMJqaqprTf7t/HBXXXXX/orcXXXXX/scS5CFP6XXXXXHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
    "auth_token": "RlRmCXXXXX/s7XXXXXjKFzoQ==",


    // 可选的 Chrome FCM 密钥 (用于 XMPP)
    "fcm_token": "BNmDO4BTKEMJXXXXXprTf7t/XXXXXBQ/orXXXXXc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
    "fcm_push_set": "RlXXXXXGM/s7XXXXXjKFzoQ=="
  }
}

可能的设备类型：

  • 1 – iOS
  • 3 – Android
  • 7 – Mac OS X
  • 8 – Windows
  • 9 – Amazon
  • 10 – Safari
  • 11 – Chrome
  • 12 – Firefox
  • 14 – Email
  • 17 – Huawei
  • 18 – SMS
  • 21 – WhatsApp

注册电子邮件设备

Anchor link to

要为您的应用注册电子邮件订阅者，请在您的 /registerDevice 或 /registerEmail 请求中发送 "email": "email_address@domain.com" 参数，如下所示：

请求示例
Anchor link to
{
  "request":{
    "application": "XXXXX-XXXXX",        // 必需。Pushwoosh 应用程序代码
    "email": "email_address@domain.com", // 必需。为您的电子邮件项目注册的电子邮件地址
    "language": "en",                    // 可选。ISO 639-1|639-2 语言代码
    "userId": "Alex",                    // 可选。
    "tags": {                            // 可选。为已注册设备设置的标签值
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"], // 为列表类型的标签设置值列表
      "DateTag": "2024-10-02 22:11",     // 注意时间应为 UTC
      "BooleanTag": true                 // 有效值为：true, false
    }
  }
}

注册 WhatsApp 设备

Anchor link to

要为您的应用注册 WhatsApp 设备，请遵循以下指南：

  • hwid：确保此字段包含 whatsapp: 前缀，后跟 E.164 格式的电话号码（例如，whatsapp:+0000000000）。电话号码必须有效，Pushwoosh 将对此进行验证。

  • Push token：不需要 push token，因为 hwid 将自动用作 push token。

  • device_type：将此字段设置为 21 以指定 WhatsApp 为平台。

请求示例
Anchor link to
{
  "request": {
    "application": "XXXXX-XXXXX",        // 必需。Pushwoosh 应用程序代码
    "hwid": "whatsapp:+0000000000",      // 必需。WhatsApp 前缀和有效的电话号码
    "timezone": 3600,                    // 可选。秒级时间偏移量
    "device_type": 21,                   // 必需。WhatsApp 设备类型为 21
    "language": "en",                    // 可选。ISO 639-1|639-2 语言代码
    "userId": "Alex",                    // 可选。用户标识符
    "tags": {                            // 可选。用于自定义分段的标签值
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",     // UTC 格式
      "BooleanTag": true
    },
    "app_version": "1.2.3",              // 可选。应用程序版本
    "device_model": "Samsung SM-G355H",  // 可选。设备型号
    "os_version": "2.3"                  // 可选。操作系统版本
  }
}

注册 SMS 设备

Anchor link to

要为您的应用注册 SMS 设备，请遵循以下指南：

  • hwid：确保此字段包含 E.164 格式的电话号码（例如，+0000000000）。电话号码必须有效，Pushwoosh 将对此进行验证。

  • Push token：不需要 push token，因为 hwid 将自动用作 push token。

  • device_type：将此必填字段设置为 18 以指定 SMS 为平台。

请求示例
Anchor link to
{
   "request": {
      "application": "XXXXX-XXXXX",           // 必需。Pushwoosh 应用程序代码
      "hwid": "+0000000000",                  // 必需。E.164 格式的有效电话号码
      "timezone": 3600,                       // 可选。秒级时间偏移量
      "device_type": 18,                      // 必需。SMS 设备类型为 18
      "language": "en",                       // 可选。ISO 639-1|639-2 语言代码
      "userId": "Alex",                       // 可选。用户标识符
      "tags": {                               // 可选。用于自定义分段的标签值
           "StringTag": "string value",
           "IntegerTag": 42,
           "ListTag": ["string1", "string2"],
           "DateTag": "2024-10-02 22:11",     // UTC 格式
           "BooleanTag": true
      },
      "app_version": "1.2.3",                 // 可选。应用程序版本
      "device_model": "Samsung SM-G355H",     // 可选。设备型号
      "os_version": "2.3"                     // 可选。操作系统版本
   }
}

状态码：

HTTP 状态码status_code描述
200200设备注册成功
200210参数错误。请参阅 status_message 获取更多信息。
400N/A格式错误的请求字符串
500500内部错误

unregisterDevice

Anchor link to

POST https://api.pushwoosh.com/json/1.3/unregisterDevice

移除设备的 push token。未注册的设备仍计入总设备数，并可通过应用内消息触达。由 SDK 内部调用。

请求头
Anchor link to
名称必需值描述
Authorization是Token XXXX用于访问设备 API 的 API 设备令牌。将 XXXX 替换为您的实际设备 API 令牌。
请求体
Anchor link to
名称类型描述
application*stringPushwoosh 应用程序代码
hwid*string在 /registerDevice 请求中使用的 硬件设备 ID。
{
    "status_code": 200,
    "status_message": "OK",
    "response": null
}
示例
{
  "request": {
    "application": "XXXXX-XXXXX",              // 必需。Pushwoosh 应用程序代码
    "hwid": "8f65b16XXXXXe7a6beceXXXXX530fb2"  // 必需。在 /registerDevice API 中使用的硬件设备 ID
  }
}

状态码：

HTTP 状态码status_code描述
200200设备成功取消订阅
200210参数错误。请参阅 status_message 获取更多信息。
400N/A格式错误的请求字符串
500500内部错误

setTags

Anchor link to

POST https://api.pushwoosh.com/json/1.3/setTags

为设备设置标签值。由 SDK 调用。

请求头
Anchor link to
名称必需值描述
Authorization是Token XXXX用于访问设备 API 的 API 设备令牌。将 XXXX 替换为您的实际设备 API 令牌。
请求体
Anchor link to
名称类型描述
application*stringPushwoosh 应用程序代码
hwid*string在 /registerDevice 请求中使用的 硬件设备 ID。
tags*object要设置的标签的 JSON 对象，发送 “null” 以移除值。
{
   "status_code": 200,
   "status_message": "OK",
   "response": null
}
示例
{
  "request":{
    "application": "XXXXX-XXXXX",               // 必需。Pushwoosh 应用程序代码
    "hwid": "8f65b16XXXXXe7a6becXXXXXe1530fb2", // 必需。在 /registerDevice API 中使用的硬件设备 ID
    "tags": {                                   // 必需。
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],        // 为列表类型的标签设置值列表
      "DateTag": "2024-10-02 22:11",            // 注意时间为 UTC
      "BooleanTag": true                        // 有效值为 - true, false
    }
  }
}

增加整数标签值

Anchor link to

要增加整数标签的值，请使用带有 “increment” 值的 operation 参数，如下所示：

{
  "request":{
    "application": "12345-67890",                   // 必需。Pushwoosh 应用程序代码
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // 必需。在 /registerDevice API 中使用的硬件设备 ID
    "tags": {                                       // 必需。
      "Level": {                                    // 标签名称
        "operation": "increment",                   // 按以下值的增量覆盖整数标签
        "value": 1                                  // 标签值的增量
      }
    }
  }
}

减少整数标签值

Anchor link to

要减少，请使用负数作为 “increment” 操作的值（-1, -2, -3,-n）：

{
  "request":{
    "application": "12345-67890",                   // 必需。Pushwoosh 应用程序代码
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // 必需。在 /registerDevice API 中使用的硬件设备 ID
    "tags": {                                       // 必需
      "Level": {                                    // 标签名称
        "operation": "increment",                   // 按以下值的减量覆盖整数标签
        "value": -1                                 // 标签值的减量
      }
    }
  }
}

附加列表标签值

Anchor link to

要使用新值扩展列表标签，请使用带有 “append” 值的 operation 参数，如下所示：

示例
{
  "request": {
    "hwid": "3d124a79XXXXf189XXXX7dfd9XXXXafd", // 必需。在 /registerDevice API 中使用的硬件设备 ID
    "application": "6XXXX-XXXX3",               // 必需。Pushwoosh 应用程序代码
    "tags": {                                   // 必需。
      "ListTag": {                              // 标签名称
        "operation": "append",                  // 将以下值附加到标签的值列表中
        "value": [                              // 要附加的值
          "tag2",
          "tag3"
        ]
      }
    }
  }
}

移除列表标签值

Anchor link to

要从列表标签中移除某些值，请使用 “remove” 操作，如下所示：

{
  "request":{
    "application": "12345-67890",                   // 必需。Pushwoosh 应用程序代码
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // 必需。在 /registerDevice API 中使用的硬件设备 ID
    "tags": {                                       // 必需。
      "In-App Product": {                           // 标签名称
        "operation": "remove",                      // 从列表标签中移除以下值
        "value": "outwear_02"                       // 要移除的一个或多个值
      }
    }
  }
}

按 UserID 设置标签

Anchor link to

要为与特定 User ID 关联的所有设备设置标签，请使用 “userId” 参数而不是 “hwid”。

示例
{
  "request":{
    "application": "AAAAA-BBBBB", // Pushwoosh 应用代码
    "userId": "some_user",        // 您想为其设置标签的用户 ID
    "tags": {                     // 要设置的标签和值
      "Language": "es"
    }
  }
}

状态码：

HTTP 状态码status_code描述
200200标签已成功设置
200210参数错误。请参阅 status_message 获取更多信息。
400N/A格式错误的请求字符串
500500内部错误

getTags

Anchor link to

POST https://api.pushwoosh.com/json/1.3/getTags

检索特定设备的标签列表及其对应值。

请求头
Anchor link to
名称必需值描述
Authorization是Token XXXX用于访问设备 API 的 API 设备令牌。将 XXXX 替换为您的实际设备 API 令牌。
请求体
Anchor link to
名称类型描述
application*stringPushwoosh 应用程序代码
userIdstringUser ID，用于替代 “hwid”。如果与 “hwid” 一起使用，则 “hwid” 优先。
hwidstring在 /registerDevice 请求中使用的 硬件设备 ID。
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "result": {
      "Language": "fr"
    }
  }
}
示例
{
  "request":{
    "application": "XXXXX-XXXXX",   // 必需。Pushwoosh 应用程序代码
    "hwid": "HWID",                 // 可选。在 /registerDevice API 中使用的硬件设备 ID
    "userId": "USER_ID"             // 可选。可用于替代 "hwid" 以检索特定用户的标签
  }
}

setBadge

Anchor link to

POST https://api.pushwoosh.com/json/1.3/setBadge

将设备的当前角标值发送到 Pushwoosh。由 SDK 内部调用。

请求头
Anchor link to
名称必需值描述
Authorization是Token XXXX用于访问设备 API 的 API 设备令牌。将 XXXX 替换为您的实际设备 API 令牌。
请求体
Anchor link to
名称类型描述
application*stringPushwoosh 应用程序代码
hwid*string在 /registerDevice 请求中使用的 硬件设备 ID。
badge*integer应用程序上的当前角标。
{
  "status_code": 200,
  "status_message": "OK"
}
示例
{
  "request":{
    "application": "XXXXX-XXXXX",               // 必需。Pushwoosh 应用程序代码
    "hwid": "8f65b16dXXXXe7a6XXXX9614XXXX0fb2", // 必需。在 /registerDevice API 中使用的硬件设备 ID
    "badge": 4                                  // 必需。应用程序上的当前角标
  }
}

由 SDK 内部调用。将设备的当前角标值发送到 Pushwoosh。当应用更改 iOS 设备上的角标值时，此操作会在内部发生。这使得角标自动递增功能能够正常工作。

applicationOpen

Anchor link to

POST https://api.pushwoosh.com/json/1.3/applicationOpen

注册应用打开事件。由 SDK 内部调用。

请求头
Anchor link to
名称必需值描述
Authorization是Token XXXX用于访问设备 API 的 API 设备令牌。将 XXXX 替换为您的实际设备 API 令牌。
请求体
Anchor link to
名称类型描述
application*stringPushwoosh 应用程序代码
hwid*string在 /registerDevice 请求中使用的 硬件设备 ID。
{
  "status_code": 200,
  "status_message": "OK"
}
示例
{
  "request": {
    "application": "XXXXX-XXXXX",              // 必需。Pushwoosh 应用程序代码
    "hwid": "8f65b16dXXXXe7a6XXXX9614eXXXXfb2" // 必需。在 /registerDevice API 中使用的硬件设备 ID
  }
}

pushStat

Anchor link to

POST https://api.pushwoosh.com/json/1.3/pushStat

注册推送打开事件。由 SDK 内部调用。

请求头
Anchor link to
名称必需值描述
Authorization是Token XXXX用于访问设备 API 的 API 设备令牌。将 XXXX 替换为您的实际设备 API 令牌。
请求体
Anchor link to
名称类型描述
application*stringPushwoosh 应用程序代码
hwid*string在 /registerDevice 请求中使用的 硬件设备 ID。
userIdstring要与推送打开事件关联的 User ID。
hashstring在推送通知中收到的哈希标签（推送有效负载的 “p” 参数）。
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
示例
{
  "request": {
    "application": "XXXXX-XXXXX",               // 必需。Pushwoosh 应用程序代码
    "hwid": "8f65b16dfXXXX7a6beXXXX14e1530fb2", // 必需。在 /registerDevice API 中使用的硬件设备 ID
    "userId": "USER012345",                     // 可选。要与推送打开事件关联的用户 ID
    "hash": "HASH_TAG"                          // 可选。在推送通知中收到的哈希标签
                                                //           （推送有效负载中的 "p" 参数）
  }
}

messageDeliveryEvent

Anchor link to

POST https://api.pushwoosh.com/json/1.3/messageDeliveryEvent

为设备注册推送送达事件。由 SDK 内部调用。

请求头
Anchor link to
名称必需值描述
Authorization是Token XXXX用于访问设备 API 的 API 设备令牌。将 XXXX 替换为您的实际设备 API 令牌。
请求体
Anchor link to
名称类型描述
application*stringPushwoosh 应用程序代码
hwid*string在 /registerDevice 请求中使用的 硬件设备 ID。
hashstring在推送通知中收到的哈希标签（推送有效负载的 “p” 参数）。
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
示例
 {
  "request": {
    "application": "XXXXX-XXXXX",               // 必需。Pushwoosh 应用程序代码
    "hwid": "8f65b16dfXXXX7a6bece9XXXX1530fb2", // 必需。在 /registerDevice API 中使用的硬件设备 ID
    "hash": "HASH_TAG"                          // 可选。在推送通知中收到的哈希标签
                                                //           （推送有效负载中的 "p" 参数）
  }
}