Tag Alias API

Device API is used to query, set, update, and delete device tag and alias information on the server side. When using it, care should be taken not to let the tags set by the server side be overwritten by the client side.

• If you are not familiar with tags, the logic of alias suggests only using either client or server.
• If it is used on both sides at the same time, please confirm that your application can handle the synchronization of tags and aliases.

For more information about tag and alias, please refer to the API description of the corresponding client platform.

• web-tag,alias

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 are a subscriber to our paid plan and would like to adjust the usage limit of your paid AppKey, please contact our business team 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 are a subscriber to our paid plan and would like to adjust the usage limit of your paid AppKey, please contact our business team at: Sales@engagelab.com

API overview

Device API is used to query, set, update, and delete device tag and alias information on the server side.

Contains three sets of APIs: device, tag, and alias. in:

• device is used to query/set various properties 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 device alias.

The key information that needs to be used is the registration ID:

The registration_id of the device is obtained after the client is integrated, see the API documentation on the Web for details;

The server does not provide an API to obtain the registrationID value of the device, and the developer needs to obtain the registration ID from the client and upload it to the developer server for storage.

Call address

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

Query the alias and label of the device

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

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 parameters

-N/A

Return example

Returned successfully

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

        

Return data

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

        

• null if no statistic is found, otherwise 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}

        

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"
}

        

Request parameters

• tags: support add, remove or empty string. When the tags parameter is an empty string, it means clearing all tags; under add/remove, the specified tag is added or deleted;
• alias: Update the alias attribute of the device; when the alias is an empty string, delete the alias of the specified device.

Return example

Returned successfully

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

        

Return data

          success

        

Failed to Return

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

        

Query tag list

• Get a list of all tags currently applied.

Call address

          GET /v4/tags/

        

Request example

Request Header

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

        

Request parameters

• None

Request example

Returned successfully

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

        

Return data

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

        

• null if no statistic is found, otherwise the value of the statistic.

Query the binding relationship between the device and the label

• Query whether a device is under the 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 parameters

• registration_id Required, registration_id of the device

Return example

Returned successfully

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

        

Return data

          {"result": true/false}

        

Update tags

• Add or remove devices for a label.

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 operation type, there are two options: "add" and "remove", indicating whether this Request is "add" or "delete";
• registration_ids device registration_id to be added/deleted;
• add/remove supports up to 1000 each.

Return example

Returned successfully

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

        

Return data

          success

        

Failed to Return

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

        

Remove tags

Delete 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=web
   Authorization: Basic (base64 auth string)
   Accept: application/json

        

Request parameters

• platform is an optional parameter, if not filled, it defaults to all platforms.

Return example

Returned successfully

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

        

Return data success

Failed to Return

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

        

Query alias (binding relationship with device)

          GET /v4/aliases/{alias_value}
Get the devices under the specified alias, and output up to 10;

        

Query alias

• Get the devices under the specified alias, output up to 10, and output more than 10 by default.

Call address

          GET /v4/aliases/{alias_value}

        

Request example

Request Header

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

        

Request parameters

• platform is an optional parameter, if not filled, it defaults to all platforms.

Return example

Returned successfully

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

        

Return data

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

        

• null if no statistic is found, otherwise the value of the statistic.

Remove alias

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

          DELETE /v4/aliases/{alias_value}

        

Request example

Request Header

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

        

Request parameters

• platform is an optional parameter, if not filled, it defaults to all platforms.

Return example

• success

             success

        

• fail

             {"code":2xxxx, "message":"unknown 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 User registration_id that needs to be online, and supports querying up to 1000 registration_ids.
• You need to apply for an Appkey that has opened this service before you can Call this API.

Return example

Returned successfully

          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 within 10 minutes;
  • false: offline for 10 minutes;
• last_online_time
  • when online is true, this field is not Returned;
  • When online is false and this field is not Returned, it means that the last online time was two days ago;
• For invalid regids or regids that do not belong to the appkey, the verification will fail.

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

        

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=='

        

Return successfully

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

        

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"
    }
}

        

HTTP Status Codes

Reference document: Http-Status-Code

Business Return code