Tag Alias API
Device API is used to query, set, update and delete the tag,alias information of the device on the server side, when using it, you need to be careful not to let the tag set on the server side be overwritten by the client.
- If you are not familiar with tag, the logic of alias is recommended to use only one of the two, client-side or server-side.
- If you are using both, please make sure your application can handle the synchronization of tags and aliases.
For more information about tag,alias, please refer to the API description of the corresponding client platform.
Usage restrictions
- aliases and devices only support 1-to-1 relationships, not 1-to-many or many-to-1 relationships
- The maximum number of aliases under a single appkey is 100,000
- The maximum number of Tags under a single appkey is 10,000
- The maximum number of devices under a single Tag is 100,000
- A single device can only set up to 100 Tags
API Overview
Device API is used to query, set, update and delete the tag,alias information of the device on the server side.
It contains three APIs: device, tag, alias:
- device is used to query / set various attributes of the device, including tags, alias;
- tag is used to query/set/delete the tag of the device;
- alias is used to query/set/delete the alias of the device.
The registration ID is also a key piece of information that needs to be used:
The registration_id of the device is obtained after client-side integration, see the API documentation for Android and iOS for details;
The server side does not provide API to get the registration ID value of the device, the developer needs to get the registration ID on the client side and upload it to the developer server for storage.
Call address
API URL: https://push.api.engagelab.cc/v4/devices
Querying device aliases and labels
- Get all the attributes of the current device, including tags, alias, mobile number.
Call address
GET /v4/devices/{registration_id}
Request Example
Request Header
GET /v4/devices/{registration_id}
Authorization: Basic (base64 auth string)
Accept: application/json
Request Parameter
- 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"
}
- If the statistic is not found, it is null, otherwise it is the value of the statistic
Set the alias and label of the device
- Update the specified attributes of the current device, currently supports tags, alias, mobile number mobile.
Call address
POST /v4/devices/{registration_id}
Request Example
Request Header
POST /v4/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 Parameter
- tags: supports add, remove or empty string. When tags parameter is empty string, it means clear all tags; under add/remove, it means add or remove the specified tag;
- alias: update the alias attribute of the device; when alias is an empty string, remove the alias of the specified device;
- mobile: the mobile number associated with the device; when mobile is empty, it means empty the mobile number associated with the device.
Return Example
Successful return
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Return Data
success
Failed return
{"code":2xxxx, "message":"unknow err"}
Check the list of tags
- Get a list of all the tags of the current application.
Call address
GET /v4/tags/
Request Example
Request Header
GET /v4/tags/
Authorization: Basic (base64 auth string)
Accept: application/json
Request Parameter
- None
Request Example
Successful return
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Return Data
{
"tags": [
"tag1",
"tag2"
]
}
- The value of the statistic is null if no statistic is found, otherwise it is the value of the statistic.
Query the binding relationship between device and tag
- Queries if a device is under tag.
Call address
GET /v4/tags/{tag_value}/registration_ids/{registration_id}
Request Example
Request Header
GET /v4/tags/{tag_value}/registration_ids/090c1f59f89
Authorization: Basic (base64 auth string)
Accept: application/json
Request Parameter
- registration_id 必须,设备的 registration_id
Return Example
Successful return
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Return Data
{"result": true/false}
Update tab
- Add or remove devices for a tag.
Call address
POST /v4/tags/{tag_value}
Request Example
Request Header
POST /v4/tags/{tag_value}
Authorization: Basic (base64 auth string)
Accept: application/json
Request Data
{
"registration_ids":{
"add": [
"registration_id1",
"registration_id2"
],
"remove": [
"registration_id1",
"registration_id2"
]
}
}
Request Parameters
- action action type, with two options: "add", "remove", which identifies whether the request is for "add" or "remove".
- registration_ids The registration_id of the device to be added/removed.
- add/remove supports up to 1000 devices each.
Return Example
Successful return
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Return Data
success
Failure to return
{"code":2xxxx, "message":"unknow err"}
Delete Tag
Deletes a tag, and the association between the tag and the device.
Call address
DELETE /v4/tags/{tag_value}
Request Example
Request Header
DELETE /v4/tags/{tag_value}?platform=android,ios
Authorization: Basic (base64 auth string)
Accept: application/json
Request Parameter
- platform Optional parameter, default to all platforms if not filled.
Return Example
Successful return
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-
Return Data
success
Failure to return
{"code":2xxxx, "message":"unknow err"}
Query alias (binding relationship with the device)
GET /v4/aliases/{alias_value}
Gets the devices under the specified alias;
Call address
GET /v4/aliases/{alias_value}
Request Example
Request Header
GET /v4/aliases/{alias_value}?platform=android,ios
Authorization: Basic (base64 auth string)
Accept: application/json
Request Parameter
- platform Optional parameter, default to all platforms if not filled.
Return Example
Successful return
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Return Data
{
"registration_ids": [
"registration_id1",
"registration_id2"
]
}
- The value of the statistic is null if no statistic is found, otherwise it is the value of the statistic.
Delete Alias
Deletes an alias and the binding relationship of that alias to the device.
DELETE /v4/aliases/{alias_value}
Request Example
Request Header
DELETE /v4/aliases/{alias_value}?platform=android,ios
Authorization: Basic (base64 auth string)
Accept: application/json
Request Parameters
- platform Optional parameter, default to all platforms if not filled.
Return Example
- Success
success
- Failed
{"code":2xxxx, "message":"unknow err"}
Get user online status
Call address
POST /v4/devices/status/
Request Example
Request Header
POST /v4/devices/status/
Authorization: Basic (base64 auth string)
Accept: application/json
Request Data
{
"registration_ids": [
"010b81b3582",
"0207870f1b8",
"0207870f9b8"
]
}
Request Parameters
- registration_ids requires the registration_id of the user with online status, and supports querying up to 1000 registration_ids.
- This API can be called only if you have applied for an Appkey that has opened this service.
Return Example
Successful return
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Return Data
[
{
"regid": "010b81b3582",
"online": true
},
{
"regid": "0207870f1b8",
"online": false,
"last_online_time": "2014-12-16 10:57:07"
},
{
"regid": "0207870f9b8",
"online": false
}
]
Return Data
- online
- true: online for 10 minutes or less;
- false: not online for 10 minutes; false: not online for 10 minutes;
- last_online_time
- When online is true, this field is not returned.
- when online is false and the field does not return, then the last online time is two days ago;
- The verification will fail for invalid regid or regid that does not belong to the appkey.
HTTP Status Code
Reference Document:Http-Status-Code
Business Return Code
Code | Description | Detailed explanation | HTTP Status Code |
---|---|---|---|
21004 | Authentication error | appkey is illegal | 401 |
27000 | System memory error | Please try again | 500 |
27001 | Parameter error | The calibration information is empty | 401 |
27002 | Parameter error | Illegal parameters | 400 |
27004 | Parameter error | Calibration failed | 401 |
27005 | Parameter error | regisID format is illegal | 400 |