API Description

Request method: POST.

request address/v3/device/tag

The API request address is corresponding to the service access point. Select the request address corresponding to the service access point of your application.

API feature
Tag API is the general term for all tag APIs. It includes various APIs for setting, updating, and deleting which are described as below:
For use cases of the tag feature, please see Tag Feature Use Instructions.

Parameter Description

Request parameters

• One application can have up to 10,000 custom tags, one device token can be bound to up to 100 customized tags (if you want to increase this limit, please submit a ticket), and one custom tag can be bound to an unlimited number of device tokens.
• If the API is being called just one time without setting up continuous tags, then there are no restrictions on the API call method.
• If the API is called by setting up continuous tags, then the following must be noted:
  • If there is a need to set up API calling by using continuous tags with more than 10 tags or more than 10 tokens, it is recommended that batch APIs be used. However, it is recommended that the interval between API calls be no less than 1s to guarantee correct tag operations.
  • If you are not using batch APIs, then the API for the next non-batched tag should be called after the returned value of the TPNS server is clearly obtained. It is not recommended that multi-thread async be used at the same time as performing tag API calling.
• Colon ":" is a keyword used by the TPNS backend for tag categorization. If ":" is included when a tag is set, then the string before the first ":" will be used as the category name of the tag. This is only used when operator_type is 6 (overwriting tags by category). For example, if the existing tags of a device are level:1, level:2, and male, you can directly use tag level:3 to overwrite tags level:1 and level:2 without having to unbind level:1 and level:2 one by one, and then bind tag level:4. For more information, please see the following sample request where operator_type is 6.

Response parameters

Samples

Sample tag binding and unbinding requests

• Add a single tag (tag1) to a single token (token1)

{
    "operator_type": 1,
    "platform": "android",
    "tag_list": [
        "tag1"
    ],
    "token_list": [
        "token1"
    ]
}

• Delete a single tag (tag1) from a single token (token1)

{
    "operator_type": 2,
    "platform": "android",
    "tag_list": [
        "tag1"
    ],
    "token_list": [
        "token1"
    ]
}

• Add multiple tags (tag1 and tag2) to a single token (token1)

{
    "operator_type": 3,
    "platform": "android",
    "tag_list": [
        "tag1",
        "tag2"
    ],
    "token_list": [
        "token1"
    ]
}

• Delete multiple tags (tag1 and tag2) from a single token (token1)

{
    "operator_type": 4,
    "platform": "android",
    "tag_list": [
        "tag1",
        "tag2"
    ],
    "token_list": [
        "token1"
    ]
}

• Delete all tags from a single token (token1)

{
    "operator_type": 5,
    "platform": "android",
    "tag_list": [
        "tag1",
        "tag2"
    ],
    "token_list": [
        "token1"
    ]
}

• Tag overwrites custom tags of token1.

{
    "operator_type": 6,
    "platform": "android",
    "tag_list": [
        "test:2",
        "level"
    ],
    "token_list": [
        "token1"
    ]
}

If one or more of the tags do not contain ":", then the test:2 and level tags overwrite all custom tags of token1.

• Batch overwrite custom tags of a single token (this API only overwrites custom but not all tags)

{
    "operator_type": 6,
    "platform": "android",
    "tag_list": [
        "test:2",
        "level:2"
    ],
    "token_list": [
        "token1"
    ]
}

If all the tags have ":", as the string before the first ":" is the tag category, only tags in the same category corresponding to the device will be overwritten; for example, test:2 will overwrite test:*, and level:2 will overwrite level:*, without affecting other tags.

• Add a single tag (tag1) to multiple tokens (token1 and token2)

{
    "operator_type": 7,
    "platform": "android",
    "tag_list": [
        "tag1"
    ],
    "token_list": [
        "token1",
        "token2"
    ]
}

• Delete a single tag (tag1) from multiple tokens (token1 and token2)

{
    "operator_type": 8,
    "platform": "android",
    "tag_list": [
        "tag1"
    ],
    "token_list": [
        "token1",
        "token2"
    ]
}

• Batch set tags

{
    "operator_type": 9,
    "platform": "android",
    "tag_token_list": [
        {
            "tag": "tag1",
            "token": "token1"
        }
    ]
}

• Batch delete tags (tag1, tag2, and tag3)

{
    "operator_type": 10,
    "platform": "android",
    "tag_token_list": [
        {
            "tag": "tag1",
            "token": "token1"
        },
        {
            "tag": "tag2",
            "token": "token2"
        },
        {
            "tag": "tag3",
            "token": "token3"
        }
    ]
}

Sample tag setting request

POST /v3/device/tag HTTP/1.1
Host: api.tpns.tencent.com
Content-Type: application/json
Authorization: Basic YTViNWYwNzFmZjc3YTplYTUxMmViNzcwNGQ1ZmI1YTZhOTM3Y2FmYTcwZTc3MQ==
Cache-Control: no-cache
Postman-Token: 4b82a159-afdd-4f5c-b459-de978d845d2f
{
    "operator_type": 1,
    "platform": "android",
    "tag_list": [
        "tag1"
    ],
    "token_list": [
        "token1"
    ]
}

Sample tag setting response

{
    "seq": 0,
    "ret_code": 0
}