tag alias API

• need to know tag，alias For detailed information, please refer to the corresponding client platform API illustrate.

  • Android - tag,alias
  • iOS - tag,alias
  • HarmonyOS - tag,alias

API Overview

Device API Used to query, set, update, and delete devices on the server side tag, alias information.

Contains device, tag, alias three groups API. in:

• device Used to query/set various properties of the device, including tags, alias；
• tag Tags used to query/set/delete devices;
• alias Alias ​​used to query/set/delete the device.

The key information that needs to be used is also registration ID：

• equipment registration_id Obtained after client integration, view details Android、 iOS、 HarmonyOSof API document;
• Not provided by the server API to obtain equipment registrationID Value needs to be obtained by the developer on the client side registration The ID is then uploaded to the developer server for storage.

Calling address

https://device.jpush.cn

Call verification

For details, see REST API Outlined Authentication method illustrate.

Query the alias and label of the device

• Get all properties of the current device, including tags, alias,phone number mobile。

Calling address

          GET /v3/devices/{registration_id}

        

Request example

Request Header

          GET /v3/devices/{registration_id}
  Authorization: Basic (base64 auth string)
  Accept: application/json

        

Request Parameters

• N/A

Return example

Return successfully

          HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

        

return data

          {
     "tags": ["tag1", "tag2"],
     "alias": "alias1",
     "mobile": "13012345678"
}

        

• The statistical item cannot be found. null, otherwise it is the value of the statistical item

Set device aliases and labels

• Update the specified attributes of the current device, currently supported tags, alias,phone number mobile。
• To use the SMS service, please combine it with the server SMS_MESSAGE field.

Calling address

          POST /v3/devices/{registration_id}

        

Request example

Request Header

          POST /v3/devices/{registration_id}
  Authorization: Basic (base64 auth string)
  Accept: application/json

        

Request data

          {
        "tags":{
            "add": [
                "tag1",
                "tag2"
            ],
            "remove": [
                "tag3",
                "tag4"
            ]
        },
        "alias": "alias1",
        "mobile":"13012345678"
    }

        

Request Parameters

• tags:support add, remove Or an empty string. when tags When the parameter is an empty string, it means clearing all tags；add/remove The following is to add or delete the specified tag；
  • once add/remove tag The upper limit of 100 each, each tag The name length is limited to 40 bytes, and the total length cannot exceed 1000 byte. (To judge the length, you need to use UTF-8 coding)
  • Can be called multiple times API settings, a device (registrationID) can be set tag The upper limit is 1000 one, application tag There is no limit to the total number
  • Valid tag composition: letters (case sensitive), numbers, underscores, Chinese characters, special characters @!#$&*+=.|
• alias: Update the alias attribute of the device; when the alias is an empty string, delete the alias of the specified device;
  • Notice:JiguangAt 2020/03/10 Limit the upper limit of "Alias ​​Settings", allowing up to 10 devices to be bound. If more than 10 devices are allowed, an error will be reported. 7015, if you need a higher limit, please contact business, please read for details announcement。
  • Valid aliases consist of: letters (case sensitive), numbers, underscores, Chinese characters, special characters @!#$&*+=.|
  • limit:alias Name length is limited to 40 bytes. (To judge the length, you need to use UTF-8 coding)
• mobile: Mobile phone number associated with the device; when mobile When it is an empty string, it means clearing the mobile phone number associated with the device.

Return example

Return successfully

          HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

        

return data

• N/A

Query alias

• Get specified alias For devices under, a maximum of 10 can be output, and if the number exceeds 10, 10 will be output by default.
• For customers who have adjusted a higher upper limit through the "Set device alias" interface, if they need to return to a higher upper limit, please contact businessApply to adjust the upper limit of the number returned by the query.

Calling address

          GET /v3/aliases/{alias_value}

        

Request example

Request Header

          GET /v3/aliases/{alias_value}?platform=android,ios,quickapp,hmos&new_format=true
  Authorization: Basic (base64 auth string)
  Accept: application/json

        

Request Parameters

• platform Optional parameter, if not filled in, it will default to all platforms.
• new_format Optional parameters, for true Indicates returning according to the new format, not passing or as false It means returning in the old format.

Return example

Return successfully

          HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

        

Old return data

          {
    "registration_ids": [
        "registration_id1",
        "registration_id2"
    ]
}

        

New return data

          {
    "data": [
        {
            "registration_id": "160a3797c806b5dbb10",
            "platform": "ios",
            "last_online_date": "2022-07-18"
        },
        {
            "registration_id": "120a3797c806b5dbb10",
            "platform": "android",
            "last_online_date": "2022-01-18"
        },
        {
            "registration_id": "150a3797c806b5drf05",
            "platform": "hmos",
            "last_online_date": "2024-04-25"
        } 
    ]
}

        

• The statistical item cannot be found. null, otherwise it is the value of the statistical item.

Delete alias

Delete an alias and the binding relationship between the alias and the device.

          DELETE /v3/aliases/{alias_value}

        

Request example

Request Header

          DELETE /v3/aliases/{alias_value}?platform=android,ios,quickapp,hmos
  Authorization: Basic (base64 auth string)
  Accept: application/json

        

Request Parameters

• platform Optional parameter, if not filled in, it will default to all platforms.

Return example

• N/A

Delete device alias

• Unbind the relationship between devices and aliases in batches.

Calling address

          POST /v3/aliases/{alias_value}

        

Request example

Request Header

          POST /v3/aliases/{alias_value}
  Authorization: Basic (base64 auth string)
  Accept: application/json

        

Request data

          {
  "registration_ids":{"remove": ["registration_id1", "registration_id2"]}
}

        

Request Parameters

• registration_ids Required parameters, need to match thealiasunboundregistration_idvalue, up to supported1000indivualregistration_id。

Return example

Return successfully

          HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

        

return on failure

          HTTP/1.1 400 BAD REQUEST
  Content-Type: application/json; charset=utf-8

        

          {
    "error":{"code":7013,"illegal_rids":["010922a358e"]}
}

        

Query tag list

• Get a list of all tags currently applied, each platform returns up to 100 indivual.

Calling address

          GET /v3/tags/

        

Request example

Request Header

          GET /v3/tags/
  Authorization: Basic (base64 auth string)
  Accept: application/json

        

Request Parameters

• None

Return example

Return successfully

          HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

        

return data

          {
    "tags": [
        "tag1",
        "tag2"
    ]
}

        

• The statistical item cannot be found. null, otherwise it is the value of the statistical item.

Query the binding relationship between devices and tags

• Check whether a device is present tag Down.

Calling address

          GET /v3/tags/{tag_value}/registration_ids/{registration_id}

        

Request example

Request Header

          GET /v3/tags/{tag_value}/registration_ids/090c1f59f89
  Authorization: Basic (base64 auth string)
  Accept: application/json

        

Request Parameters

• registration_id necessary, equipment registration_id

Return example

Return successfully

          HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

        

return data

          {
     "result": true/false
}

        

Update label

• Add or remove devices from a label.

Calling address

          POST /v3/tags/{tag_value}

        

Request example

Request Header

          POST /v3/tags/{tag_value}
  Authorization: Basic (base64 auth string)
  Accept: application/json

        

Request data

          {
        "registration_ids":{
            "add": [
                "registration_id1",
                "registration_id2"
            ],
            "remove": [
                "registration_id3",
                "registration_id4"
            ]
        }
}

        

Request Parameters

• action Operation type, there are two options: "add"，"remove", indicating whether this request is "add" or "delete".
• registration_ids Devices to be added/removed registration_id。
• add/remove Each supports up to 1000 indivual;

Return example

Return successfully

          HTTP/1.1 200 OK
 Content-Type: application/json; charset=utf-8

        

return on failure

          {
    "error": {
        "code": 7016,
        "illegal_rids": [
            "160a3797c8824c6b905"
        ]
    }
}

        

Delete tag

Delete a label and the association between the label and the device.

Calling address

          DELETE /v3/tags/{tag_value}

        

Request example

Request Header

          DELETE /v3/tags/{tag_value}?platform=android,ios,quickapp,hmos
  Authorization: Basic (base64 auth string)
  Accept: application/json

        

Request Parameters

• platform Optional parameter, if not filled in, it will default to all platforms.

Return example

• N/A

Get user online status (VIP）

• Check whether the user is online. If you need to activate this interface, please contact:Business customer service。

Calling address

          POST /v3/devices/status/

        

Request example

Request Header

          POST /v3/devices/status/
  Authorization: Basic (base64 auth string)
  Accept: application/json

        

Request data

          {
    "registration_ids": [
        "010b81b3582",
        "0207870f1b8",
        "0207870f9b8"
    ]
}

        

Request Parameters

• registration_ids Users who need online status registration_id, supports query at most 1000 indivual registration_id；
• You need to apply to open this business Appkey to call this API。

Return example

Return successfully

          HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8

        

return data

          {
     "010b81b3582": {
         "online": true
     },
     "0207870f1b8": {
          "online": false,
          "last_online_time": "2014-12-16 10:57:07"
     },
     "0207870f9b8": {
          "online": false
    }
}

        

Return Parameters

• online

  • true: Online within 10 minutes;
  • false: Not online within 10 minutes;

• last_online_time

  • when online for true When, this field is not returned;
  • when online for false, and if this field is not returned, it means that the last time online was two days ago;

• for invalid regid or does not belong to the appkey of regid,Should registration The result returned by id is empty;

Test equipment management (VIP）

• Supports adding/deleting/querying/modifying test devices to ensure that each push in test mode only reaches test users; for detailed function logic, please refer to the document:test mode
• If you need to open this interface, please contact:Business customer service。

Add test equipment

• Interface path:/v3/test/model/add

• Request method:POST

• Request parameters:

          {
    "device_name":string,  //开发者自定义的设备名称
    "registration_id":string, //极光生成的设备唯一标识
}

        

• Return parameters

          // 正常返回
无（未出现错误不返回参数）

// 错误返回
{
    "error": {
        "code":int,
        "message":string
    }
}

        

Remove test device

• Interface path:/v3/test/model/delete/{registration_id}

• Request method:DELETE

• Request parameters:

          registration_id：极光生成的设备唯一标识

        

• Return parameters

          // 正常返回
无（未出现错误不返回参数）

// 错误返回
{
    "error": {
        "code":int,
        "message":string
    }
}

        

Get a list of test equipment

• Interface path:/v3/test/model/list?page=1&page_size=10&device_name=""&registration_id=""

• Request method:GET

• Request parameters:

          registration_id：精确查询，string类型，极光生成的设备唯一标识
device_name：模糊查询，string类型，开发者自定义的设备名称
page：查询页数，int类型
page_size：每页记录条数，int类型

说明：
1. 查询参数 registration_id 和 device_name 只能存在其一，不支持同时传递
2. page 和 page_size不传默认返回所有数据（默认为1和200），二者要么都传，要么都不传

        

• Return parameters

          正常返回
{
    "total":int
    "detail":[{
        "device_name":string,  //设备名称
        "device_model":string,  //设备型号
        "registration_id":string,  //极光生成的设备唯一标识
        "registration_time":string,  //设备注册时间，格式：2025-01-01 00:00:00 
        "create_time":string  //信息添加时间，格式：2025-01-01 00:00:00 
    }]
    "page":int
    "page_size":int
}

错误返回
{
    "error": {
        "code":int,
        "message":string
    }
}

        

Modify test equipment

• Interface path:/v3/test/model/update

• Request method:PUT

• Request parameters:

          //只支持修改名字
{
    "registration_id"：string //极光生成的设备唯一标识
    "device_name"：string //开发者自定义的设备名称
}

        

• Return parameters

          // 正常返回
无（未出现错误不返回参数）

// 错误返回
{
    "error": {
        "code":int,
        "message":string
    }
}

        

call returns

Business return code

refer to

Reference documentation:Http-Status-Code