Tag Alias API

最新の更新: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 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 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

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

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"

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

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}

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

Return Data

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

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

Request Data

{ "tags": { "add": [ "tag1", "tag2" ], "remove": [ "tag3", "tag4" ] }, "alias": "alias1", }
          {
    "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
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

        
このコードブロックは、フローティングウィンドウに表示されます

Return Data

success
          success

        
このコードブロックは、フローティングウィンドウに表示されます

Failed to Return

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

        
このコードブロックは、フローティングウィンドウに表示されます

Delete the device

  • Delete the device.

Call address

DELETE /v4/devices/{registration_id}
          DELETE /v4/devices/{registration_id}

        
このコードブロックは、フローティングウィンドウに表示されます

Request example

Request Header

DELETE /v4/devices/{registration_id} Authorization: Basic (base64 auth string) Accept: application/json
          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
          HTTP/1.1 200 OK
   Content-Type: application/json; charset=utf-8

        
このコードブロックは、フローティングウィンドウに表示されます

Return data

success
          success

        
このコードブロックは、フローティングウィンドウに表示されます

Failed to Return

{ "error":{ "code":27002, "message":"unknown error" } }
          {
  "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/
          GET /v4/tags/

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

Request Parameters

  • None

Request Example

Returned 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

        
このコードブロックは、フローティングウィンドウに表示されます

Return Data

{ "tags": [ "tag1", "tag2" ] }
          {
  "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}
          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
          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
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

        
このコードブロックは、フローティングウィンドウに表示されます

Return Data

{"result": true/false}
          {"result": true/false}

        
このコードブロックは、フローティングウィンドウに表示されます

Update tags

  • Add or remove devices for a tag.

Call address

POST /v4/tags/{tag_value}
          POST /v4/tags/{tag_value}

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

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
          HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-8

        
このコードブロックは、フローティングウィンドウに表示されます

Return Data

success
          success

        
このコードブロックは、フローティングウィンドウに表示されます

Failed to Return

{ "error": { "code": 27005, "message": "registration id is illegal", "data": "{\"invalid_regids\":[\"18071adc021ff8df80\",\"100d85592955c1f1058\"]}" } }
          {
    "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}
          DELETE /v4/tags/{tag_value}

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

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-
          HTTP/1.1 200 OK 
 Content-Type: application/json; charset=utf-

        
このコードブロックは、フローティングウィンドウに表示されます

Return Data success

Failed to Return

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

        
このコードブロックは、フローティングウィンドウに表示されます

Query alias (binding relationship with the device)

GET /v4/aliases/{alias_value}
          GET /v4/aliases/{alias_value}

        
このコードブロックは、フローティングウィンドウに表示されます
  • 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}
          GET /v4/aliases/{alias_value}

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

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
          HTTP/1.1 200 OK 
  Content-Type: application/json; charset=utf-8

        
このコードブロックは、フローティングウィンドウに表示されます

Return Data

{ "registration_ids": [ "registration_id1", "registration_id2" ] }
          {
   "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}
          DELETE /v4/aliases/{alias_value}

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

Request Parameters

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

Return Example

  • Success
success
            success

        
このコードブロックは、フローティングウィンドウに表示されます
  • Failed
{ "error":{ "code":27002, "message":"unknown error" } }
          {
  "error":{
    "code":27002, 
    "message":"unknown error"
    }
}

        
このコードブロックは、フローティングウィンドウに表示されます

Get user online status

Call address

POST /v4/devices/status/
          POST /v4/devices/status/

        
このコードブロックは、フローティングウィンドウに表示されます

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

        
このコードブロックは、フローティングウィンドウに表示されます

Request Data

{ "registration_ids": [ "010b81b3582", "0207870f1b8", "0207870f9b8" ] }
          {
  "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
          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 } ]
          [
  {
    "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
          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=='
          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 } ] } }
          {
    "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" } }
          {
    "error": {
        "code": 27002,
        "message": "Illegal parameter"
    }
}

        
このコードブロックは、フローティングウィンドウに表示されます

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
在文档中心打开
icon
営業に連絡する