Tag Alias API

Last updated:2023-11-16

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

https://push.api.engagelab.cc/v4/devices

Query the Number of Tags Under an AppKey

Destination URL

GET /v4/tags_count
          GET /v4/tags_count

        
This code block in the floating window

Request Example

Request Headers

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

        
This code block in the floating window

Example Example

curl -X GET http://127.0.0.1/v4/tags_count?tags=tag1&tags=tag2&platform=ios -u "appKey:appSecret"
          curl -X GET http://127.0.0.1/v4/tags_count?tags=tag1&tags=tag2&platform=ios -u "appKey:appSecret"

        
This code block in the floating window

Request Parameters

  • Tag: Query the specified tag string, required field, up to 1000 tags are allowed to be queried at a time (tags=tag1&tags=tag2&tags=tag3)
  • platform: Query the specified platform, required field, optional values ​​are android, ios, other values ​​are not allowed.

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 the message field indicates the error message.

Successful Return

{ "tagsCount": { "tag1": 0, "tag2": 1, "tag3": 2 } }
          {
    "tagsCount": {
        "tag1": 0,
        "tag2": 1,
        "tag3": 2
    }
}

        
This code block in the floating window

Failed Return

{ "error": { "code": 21008, "message": "app_key is not a 24 size string or does not exist" } }
          {
    "error": {
        "code": 21008,
        "message": "app_key is not a 24 size string or does not exist"
    }
}

        
This code block in the floating window

Querying device aliases and labels

  • Get all the attributes of the current device, including tags, alias.

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", }
          {"tags": ["tag1", "tag2"],
 "alias": "alias1",
}

        
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.

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", }
          {
    "tags": {
        "add": [
            "tag1",
            "tag2"
        ],
        "remove": [
            "tag3",
            "tag4"
        ]
    },
    "alias": "alias1",

}

        
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。

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

"{error":{ {"code":27002, "message":"unknown error"} } }
          "{error":{
{"code":27002, "message":"unknown error"}
}
}

        
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_ids": [
    "registration_id1"
  ]
}

        
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.

TAG/alias quota information query interface

Query related quota information of the specified AppKey, platform, and tag. The number of tags in a single query cannot exceed 1,000.

Calling address

GET /v4/tags/quota-info?tags=tag1&platform=android Authorization: Basic (base64 auth string) Accept: application/json
          GET /v4/tags/quota-info?tags=tag1&platform=android
Authorization: Basic (base64 auth string)
Accept: application/json

        
This code block in the floating window

Request example

curl --location 'https://push.api.engagelab.cc/v4/tags/quota-info?platform=android&tags=tag1&tags=tag2' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic YjA2MTBmZGE0M2JmNmFkMTczNGNjMWY2OmQyNGMzZDk1Yzk1M2M3YmFkNzRkM2Q5YQ=='
          curl --location 'https://push.api.engagelab.cc/v4/tags/quota-info?platform=android&tags=tag1&tags=tag2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YjA2MTBmZGE0M2JmNmFkMTczNGNjMWY2OmQyNGMzZDk1Yzk1M2M3YmFkNzRkM2Q5YQ=='

        
This code block in the floating window

Return successfully

{ "data": { "totalTagQuota": 100000, "useTagQuota": 1, "totalAliasQuota": 100000, "useAliasQuota": 3, "tagUidQuotaDetail": [ { "tagName": "tag1", "totalUidQuota": 100000, "useUidQuota": 0 }, { "tagName": "tag2", "totalUidQuota": 100000, "useUidQuota": 0 } ] } }
          {
    "data": {
        "totalTagQuota": 100000,
        "useTagQuota": 1,
        "totalAliasQuota": 100000,
        "useAliasQuota": 3,
        "tagUidQuotaDetail": [
            {
                "tagName": "tag1",
                "totalUidQuota": 100000,
                "useUidQuota": 0
            },
            {
                "tagName": "tag2",
                "totalUidQuota": 100000,
                "useUidQuota": 0
            }
        ]
    }
}

        
This code block in the floating window

Return field definition:

  • totalTagQuota: Indicates the total quota of tags under the application.
  • useTagQuota: Indicates the used tag quota.
  • totalAliasQuota: Indicates the total quota of aliases under the application.
  • useAliasQuota: Indicates the used alias quota.
  • tagUidQuota: Indicates the quota of the number of devices for a single tag.
  • useUidQuota: Indicates the details of the number of devices bound to each tag.

return on failure

{ "error": { "code": 27002, "message": "Illegal parameter" } }
          {
    "error": {
        "code": 27002,
        "message": "Illegal parameter"
    }
}

        
This code block in the floating window

HTTP Status Codes

Reference document: Http-Status-Code

Business Return code

Code Description Detailed Explanation HTTP Status Code
21004 Authentication Error Invalid appkey. 401
27000 System Memory Error Please retry. 500
27001 Parameter Error Verification information is empty. 401
27002 Parameter Error Invalid parameter. 400
27004 Parameter Error Verification failed. 401
27005 Parameter Error Invalid regisID format. 400
21008 Parameter Error app_key is not a 24-character string or does not exist. 400
27010 Parameter Error Alias is already bound to another regid. 400
27011 System Limit The number of tags bound to the device exceeds the limit. A device can bind up to 100 tags. 401
27012 Parameter Error The tag that the device wants to bind does not exist. 401
27013 Parameter Error The number of tags in the application exceeds the limit. An application can create up to 100,000 tags. 401
27014 System Limit The number of device bindings in the tag exceeds the limit. A tag can bind up to 100,000 devices. 401
27015 Parameter Error The Alias bound to the device does not exist. 401
27016 System Limit The number of aliases in the application exceeds the limit. An application can create up to 100,000 aliases. 401
27017 Parameter Error The length of the tag exceeds 40 characters. 401
在文档中心打开