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.
Rules and Restrictions for TAG Usage
- TAG Quantity Limit: Under a single appkey, you can create up to 100,000 Tags.
- TAG Length Limit: The maximum length of each Tag is 40 bytes. Valid characters include letters (case sensitive), numbers, underscores, and Chinese characters.
- TAG Binding Limit for Devices: Each device can bind up to 100 Tags.
- Device Quantity Limit: Under a single Tag, you can add up to 100,000 devices.
If you need to increase these limits, please contact us at: Sales@engagelab.com
Rules and Restrictions for alias Usage
- Device to alias Mapping: An alias can only correspond to one device, not multiple devices. Similarly, each device within the appkey range can only map to one alias, not multiple aliases.
- alias Quantity Limit: Under a single appkey, you can create up to 100,000 aliases.
- alias Length Limit: The maximum length of each alias is 40 bytes. Valid characters include letters (case sensitive), numbers, underscores, and Chinese characters.
If you need to increase these limits, please contact us at: Sales@engagelab.com
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
Query the Number of Tags Under an AppKey
Destination URL
GET /v4/tags_count
Request Example
Request Headers
GET /v4/tags_count
Authorization: Basic (base64 auth string)
Accept: application/json
Request Example
curl -X GET http://127.0.0.1/v4/tags_count/ -u "appKey:appSecret"
Request Parameters
- N/A
Response Examples
- A successful response will return a JSON object containing a
tagsCount
field. This is a key-value pair collection where the key is the tag name and the value is the count of that tag. - If the request fails, a JSON object containing error information will be returned. The
code
field indicates the error code, and themessage
field indicates the error message.
Successful Return
{
"tagsCount": {
"tag1": 0,
"tag2": 1,
"tag3": 2
}
}
Failed Return
{
"error": {
"code": 21008,
"message": "app_key is not a 24 size string or does not exist"
}
}
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"
]
}
- 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 |
21008 | Parameter error | app_key is not a 24 size string or does not exist | 400 |
27010 | Parameter error | The alias is already bound to another regid | 400 |