Tag Alias API

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

• If you are not familiar with the logic of tags and aliases, it is recommended that you use either the client side or the server side only.
• 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.

• Android - tag, alias
• iOS - tag, alias
• HarmonyOS - tag, alias

Limits 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 your paid AppKey, please contact our business team at Sales@engagelab.com.

Limits and Rules for Alias Usage

• Mapping between device and alias: One alias can correspond to only one device and cannot correspond to multiple devices. Similarly, within the scope of an AppKey, each device can map to only one alias and cannot map to multiple 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 your paid AppKey, please contact our business team at Sales@engagelab.com.

API Overview

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

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

• device is used to query/set various device attributes, 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 required is the registration ID:

The device registration_id is obtained after client integration. For details, see the API documentation for Android, iOS, and HarmonyOS.

The server side does not provide an API to obtain the device registration_id value. Developers need to obtain the registration ID on 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 Header

              
              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: Query the specified tag strings. Required. Up to 1,000 tags can be queried at a time (tags=tag1&tags=tag2&tags=tag3).
• platform: Query the specified platform. Required. Valid values are android, ios, and hmos. 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

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

Endpoint

              
              GET /v4/devices/{registration_id}

            

Request Example

Request Header

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

            

Request Parameters

• registration_id: Required. The device 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 a statistic item is not found, it is null; otherwise, it is the value of the statistic item.

Set a Device's Alias and Tags

• Update the specified attributes of the current device. Currently supports tags and alias.

Endpoint

              
              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

• registration_id: Required. The device registration_id.
• tags: Supports add, remove, or an empty string. When the tags parameter is an empty string, it clears all tags. add/remove means adding or removing the specified tags.
• alias: Updates the device alias attribute. 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

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

Endpoint

              
              GET /v4/tags/

            

Request Example

Request Header

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

            

Request Parameters

• None

Request Example

Successful Response

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

            

Response Data

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

            

• If a statistic item is not found, it is null; otherwise, it is the value of the statistic item.

Query the Binding Relationship Between a Device and a Tag

• Query whether a device is under a tag.

Endpoint

              
              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

• tag_value: Required. The tag to query.
• registration_id: Required. The device 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

• Add or remove devices for a tag.

Endpoint

              
              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

• tag_value: Required. The tag to query.
• action: Operation type, with two options: add and remove, indicating whether this request adds or removes devices.
• registration_ids: The device registration_id values to add or remove.
• add/remove: Supports up to 1,000 entries 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

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

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

Request Example

Request Header

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

            

Request Parameters

• tag_value: Required. The tag to query.
• platform: Optional. If not specified, all platforms are used by default.

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 Alias (Binding Relationship with Devices)

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

            

Query Alias

• Get the devices under the specified alias.

Endpoint

              
              GET /v4/aliases/{alias_value}

            

Request Example

Request Header

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

            

Request Parameters

• alias_value: Required. The alias to query.
• platform: Optional. If not specified, all platforms are used by default.

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 a statistic item is not found, it is null; otherwise, it is the value of the statistic item.

Delete Alias

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

              
              DELETE /v4/aliases/{alias_value}

            

Request Example

Request Header

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

            

Request Parameters

• alias_value: Required. The alias to delete.
• platform: Optional. If not specified, all platforms are used by default.

Response Example

• Success

              
              success

            

• Failure

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

            

Get User Online Status

Endpoint

              
              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: The user registration_id values whose online status is needed. Up to 1,000 registration_id values are supported per query.
• This API can be called only for an AppKey that has been approved for this feature.

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.
• Invalid regid values or regid values that do not belong to the AppKey will fail validation.

TAG/Alias Quota Information Query API

Query quota information related to the specified AppKey, platform, and tag. No more than 1,000 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://pushapi-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 device quota for 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 Return Codes