Tag Alias API

The Device API is used to query, set, update, and delete a device's tag and alias information on the server side. When using it, be careful to avoid having tags set on the server side overwritten by the client side.

• If you are not familiar with tag and alias logic, it is recommended that you use only one side: either the client side or the server side.
• If both sides are used at the same time, make sure your application can properly handle tag and alias synchronization.

For detailed information about tags and aliases, please refer to the API documentation for the corresponding client platform.

• web - tag, alias

Constraints and Rules 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.
• Device TAG binding limit: Each device can be bound to up to 100 Tags.
• Device quantity limit: Under a single Tag, you can add up to 100,000 devices.

If you are a paid plan user and would like to adjust the usage limits for a paid AppKey, please contact our sales team at Sales@engagelab.com.

Constraints and Rules for alias Usage

• Device and alias mapping relationship: One alias can correspond to only one device and cannot correspond to multiple devices. Likewise, each device can map to only one alias within the appkey scope and cannot map to 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 paid plan user and would like to adjust the usage limits for a paid AppKey, please contact our sales team at Sales@engagelab.com.

API Overview

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

It includes three groups of APIs: device, tag, and alias. Among them:

• device is used to query/set various properties of a device, including tags and alias;
• tag is used to query/set/delete device tags;
• alias is used to query/set/delete device aliases.

Another key piece of information you need is the registration ID:

The device's registration_id is obtained after client integration. For details, see the Web API documentation.

The server side does not provide an API to obtain the device's registration_id value. Developers need to obtain the registration ID from the client side and upload it to the developer server for storage.

Query the Number of Tags Under an AppKey

Endpoint

              
              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?tags=tag1&tags=tag2&platform=ios -u "appKey:appSecret"

            

Request Parameters

• tags: Queries the specified tag strings. Required. Up to 1000 tags can be queried in a single request (tags=tag1&tags=tag2&tags=tag3).
• platform: Queries the specified platform. Required. Valid values are android, ios, hmos, and web. Other values are not allowed.

Response Example

• A successful response returns a JSON object containing a tagsCount field, which is a collection of key-value pairs where the key is the tag name and the value is the count under that tag.
• If the request fails, a JSON object containing error information is returned. The code field indicates the error code, and the message field indicates the error message.

Successful Response

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

            

Failed Response

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

            

Query a Device's Alias and Tags

• Gets all properties of the current device, including tags and alias.

Endpoint

              
              GET /v4/devices/{registration_id}

            

Request Example

Request Headers

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

            

Request Parameters

• registration_id: Required. The device's registration_id.

Response Example

Successful Response

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

            

Response Data

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

            

• If the statistical item cannot be found, it is null; otherwise, it is the value of the statistical item.

Set a Device's Alias and Tags

• Updates the specified properties of the current device. Currently supports tags and alias.

Endpoint

              
              POST /v4/devices/{registration_id}

            

Request Example

Request Headers

              
              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

• registration_id: Required. The device's registration_id.
• tags: Supports add, remove, or an empty string. When the tags parameter is an empty string, it means all tags will be cleared. add/remove is used to add or remove the specified tags.
• alias: Updates the device's alias property. When the alias is an empty string, the alias of the specified device is deleted.

Response Example

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

Query the Tag List

• Gets the list of all tags in the current application.

Endpoint

              
              GET /v4/tags/

            

Request Example

Request Headers

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

            

Request Parameters

• None

Response Example

Successful Response

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

            

Response Data

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

            

• If the statistical item cannot be found, it is null; otherwise, it is the value of the statistical item.

Query the Binding Relationship Between a Device and a Tag

• Queries whether a device belongs to a tag.

Endpoint

              
              GET /v4/tags/{tag_value}/registration_ids/{registration_id}

            

Request Example

Request Headers

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

            

Request Parameters

• tag_value: Required. The tag to query.
• registration_id: Required. The device's registration_id.

Response Example

Successful Response

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

            

Response Data

              
              {"result": true}

            

Update a Tag

• Adds or removes devices for a tag.

Endpoint

              
              POST /v4/tags/{tag_value}

            

Request Example

Request Headers

              
              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

• tag_value: Required. The tag to query.
• action: Operation type, with two options: "add" and "remove", indicating whether this request is to add or remove.
• registration_ids: The device registration_id values to be added or removed.
• add/remove: Supports up to 1000 items each.

Response Example

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

Delete a Tag

Deletes a tag and the association between the tag and devices.

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

Request Example

Request Headers

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

            

Request Parameters

• tag_value: Required. The tag to query.
• platform: Optional. If omitted, the default is all platforms.

Response Example

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

Query an Alias (Binding Relationship with a Device)

              
              GET /v4/aliases/{alias_value}
Get the device under the specified alias.

            

Query an Alias

• Gets the device under the specified alias.

Endpoint

              
              GET /v4/aliases/{alias_value}

            

Request Example

Request Headers

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

            

Request Parameters

• alias_value: Required. The alias to query.
• platform: Optional. If omitted, the default is all platforms.

Response Example

Successful Response

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

            

Response Data

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

            

• If the statistical item cannot be found, it is null; otherwise, it is the value of the statistical item.

Delete an Alias

Deletes an alias and the binding relationship between the alias and devices.

              
              DELETE /v4/aliases/{alias_value}

            

Request Example

Request Headers

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

            

Request Parameters

• alias_value: Required. The alias to delete.
• platform: Optional. If omitted, the default is all platforms.

Response Example

• Success

              
              success

            

• Failure

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

            

Get User Online Status

Endpoint

              
              POST /v4/devices/status/

            

Request Example

Request Headers

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

            

Request Data

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

            

Request Parameters

• registration_ids: The user registration_id values for which online status is needed. Up to 1000 registration_id values are supported per query.
• This API can be called only for AppKeys that have applied for and enabled this service.

Response Example

Successful Response

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

            

Response Data

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

            

Response Data

• online
  • true: online within the last 10 minutes
  • false: not online within the last 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 the last online time was more than two days ago
• For invalid regid values or regid values that do not belong to the appkey, validation will fail.

TAG/alias Quota Information Query API

Queries the relevant quota information for the specified AppKey, platform, and tag. No more than 1000 tags can be queried at a time.

Endpoint

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

            

Successful Response

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

            

Response Field Descriptions:

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

Failed Response

              
              {
  "error": {
    "code": 27002,
    "message": "Invalid parameters"
  }
}

            

HTTP Status Codes

Reference document: Http-Status-Code

Business Response Codes