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.

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

            

Example Example

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

            

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

            

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.

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

            

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

            

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 Parameter

• 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

Successful return

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

            

Return data

              
              success

            

Failed to Return

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

            

Delete the device

• Delete the device.

Call address

              
              DELETE /v4/devices/{registration_id}

            

Request example

Request Header

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

            

Request data

• N/A

Request parameters

• N/A

Return example

Returned successfully

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

            

Return data

              
              success

            

Failed to Return

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

            

Query tag list

• 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 Parameters

• None

Request example

Returned successfully

              
              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

• 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 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

Returned successfully

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

            

Return Data

              
              success

            

Failed to Return

              
              {
    "error": {
        "code": 27005,
        "message": "registration id is illegal",
        "data": "{\"invalid_regids\":[\"18071adc021ff8df80\",\"100d85592955c1f1058\"]}"
    }
}

            

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

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

            

Query alias (binding relationship with the device)

              
              GET /v4/aliases/{alias_value}

            

• Get the devices under the specified alias.

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

            

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

Delete 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

            

• Failed

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

            

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

            

Request example

              
              curl --location 'https://webpushapi-sgp.engagelab.com/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