Tag Alias API
Last updated:2023-06-19

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}
          GET /v4/devices/{registration_id}

        
This code block in the floating window

Request Example

Request Header

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

        
This code block in the floating window

Request Parameter

  • N/A

Return Example

Return successfully

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

        
This code block in the floating window

Return Data

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

        
This code block in the floating window
  • 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}
          POST /v4/devices/{registration_id}

        
This code block in the floating window

Request Example

Request Header

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

        
This code block in the floating window

Request Data

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

        
This code block in the floating window

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
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

        
This code block in the floating window

Return Data

success
          success

        
This code block in the floating window

Failed return

{"code":2xxxx, "message":"unknow err"}
          {"code":2xxxx, "message":"unknow err"}

        
This code block in the floating window

Check the list of tags

  • Get a list of all the tags of the current application.

Call address

GET /v4/tags/
          GET /v4/tags/

        
This code block in the floating window

Request Example

Request Header

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

        
This code block in the floating window

Request Parameter

  • None

Request Example

Successful return

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

        
This code block in the floating window

Return Data

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

        
This code block in the floating window
  • 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}
          GET /v4/tags/{tag_value}/registration_ids/{registration_id}

        
This code block in the floating window

Request Example

Request Header

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

        
This code block in the floating window

Request Parameter

  • registration_id  必须,设备的 registration_id

Return Example

Successful return

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

        
This code block in the floating window

Return Data

{"result": true/false}
          {"result": true/false}

        
This code block in the floating window

Update tab

  • Add or remove devices for a tag.

Call address

POST /v4/tags/{tag_value}
          POST /v4/tags/{tag_value}

        
This code block in the floating window

Request Example

Request Header

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

        
This code block in the floating window

Request Data

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

        
This code block in the floating window

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
          HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-8

        
This code block in the floating window

Return Data

success
          success

        
This code block in the floating window

Failure to return

{"code":2xxxx, "message":"unknow err"}
          {"code":2xxxx, "message":"unknow err"}

        
This code block in the floating window

Delete Tag

Deletes a tag, and the association between the tag and the device.

Call address

DELETE /v4/tags/{tag_value}
          DELETE /v4/tags/{tag_value}

        
This code block in the floating window

Request Example

Request Header

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

        
This code block in the floating window

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-
          HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-

        
This code block in the floating window

Return Data success

Failure to return

{"code":2xxxx, "message":"unknow err"}
            {"code":2xxxx, "message":"unknow err"}

        
This code block in the floating window

Query alias (binding relationship with the device)

GET /v4/aliases/{alias_value} Gets the devices under the specified alias;
          GET /v4/aliases/{alias_value}
Gets the devices under the specified alias;

        
This code block in the floating window

Call address

GET /v4/aliases/{alias_value}
          GET /v4/aliases/{alias_value}

        
This code block in the floating window

Request Example

Request Header

GET /v4/aliases/{alias_value}?platform=android,ios Authorization: Basic (base64 auth string) Accept: application/json
          GET /v4/aliases/{alias_value}?platform=android,ios
  Authorization: Basic (base64 auth string) 
  Accept: application/json

        
This code block in the floating window

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
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

        
This code block in the floating window

Return Data

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

        
This code block in the floating window
  • 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}
          DELETE /v4/aliases/{alias_value}

        
This code block in the floating window

Request Example

Request Header

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

        
This code block in the floating window

Request Parameters

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

Return Example

  • Success
success
            success

        
This code block in the floating window
  • Failed
{"code":2xxxx, "message":"unknow err"}
            {"code":2xxxx, "message":"unknow err"}

        
This code block in the floating window

Get user online status

Call address

POST /v4/devices/status/
          POST /v4/devices/status/

        
This code block in the floating window

Request Example

Request Header

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

        
This code block in the floating window

Request Data

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

        
This code block in the floating window

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
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

        
This code block in the floating window

Return Data

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

        
This code block in the floating window

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
在文档中心打开