Tag Feature

Last updated: 2021-08-17 16:46:12

    Tag is a feature used in targeted push where you can call TPNS SDKs or server APIs to bind one or more tags to devices. After that, you can push messages based on the tags, which makes lean operations easier.

    Tag Push Scenarios

    User engagement and reactivation

    Application operation often requires message reminders for new users, which is an important part of the new user experience design and improves the retention rate of new users. By selecting the new devices tag provided by TPNS during push, you can push messages to users registered on the specified date with speed and ease.
    In addition, we also provide the inactive users tag, with which you can specify users who have not been active for N days as the push target and push messages to them for user reactivation, thus increasing the number of active application users.

    Event subscription notification

    Your live streaming application will stream a football match at 18:00 on October 24, and the live stream will be available for reservation on October 20. You want to push a message about the upcoming start to users who subscribe to this program before the live stream starts.
    If a user subscribes to this program, the title 10241800 Football can be used as a tag to bind to the user device token. When the live stream is about to start, you can select the Football tag to push a notification to inform the user of the match start. After the match ends, you can call the TPNS tag unbinding API to unbind the 10241800 Football tag from the device token.

    Renewal notification

    You want to push a renewal notification in your application A to users whose membership will expire in three days. Assume that a device token is bound to tags football and deadline:20200210. If a user renews the membership for a month on February 9, 2020, you need to replace the tag deadline:20200210 with deadline:20200310, i.e., the tag deadline can have only one value (the latest value). In this case, you can call the key-value overriding API to unbind the tag deadline:20200210 and then bind the tag deadline:20200310 without affecting other tags. When pushing a renewal notification (scheduled push is supported), set the tag to the current date plus three days; for example, if the current date is March 7, 2020, you can push the renewal notification to devices with the tag deadline:20200310.

    Tag Overview

    TPNS provides two types of tags: custom tags and TPNS preset tags. Tag categories are as follows:

    Tag Type Scenario tag_type Built in TPNS Limit Example
    Custom tag Custom tag, such as meeting ID, class ID, and user hobbies (like basketball and digital products) xg_user_define
  • Up to 10,000 custom tags are allowed (to increase the quota, submit a ticket)
  • One device token can be bound to up to 100 custom tags (to increase the quota, submit a ticket)
  • One custom tag can be bound to an unlimited number of device tokens
  • love_basketball, love_shopping, male
    Preset tag Application version xg_auto_version Preset in TPNS, unlimited 1.0.1, 1.0.2
    Province xg_auto_province guangdong, hunan, shanghai
    Active information xg_auto_active 20200521, 20200522
    TPNS SDK version xg_auto_sdkversion 1.1.5.4, 1.1.6.1
    System version xg_auto_systemversion 10.0.0, 12.4.5
    System language xg_auto_systemlanguage zh, en, ja
    Country/Region xg_auto_country CN, US (uppercase letters)
    Phone brand xg_auto_devicebrand xiaomi, huawei
    Model xg_auto_deviceversion Samsung Note4, Vivo Y75A
    Continuously active Does not support API call currently Devices active in the last N days. Value range: [1,30]. Format: string Devices active in the last "10" days
    Continuously inactive Does not support API call currently Devices inactive in the last N days. Value range: [1,30]. Format: string Devices inactive in the last "10" days
    Recently registered Does not support API call currently
  • Devices recently registered. The tag value is [startDate, endDate] in the format of [YYYYmmdd,YYYYmmdd]
  • The range between `startDate` and `endDate` cannot exceed 30 days
  • `endDate` cannot be the current date
  • `startDate` cannot be more than 90 days ago
  • `startDate` and `endDate` can be the same
  • Devices registered within [20200901,20200910]
    Note:

    When you push by tag through API, you need to use the tag_type built in TPNS to set the tag type.

    Preparations

    Managing custom tags

    You can custom device tag names. Currently, TPNS allows you to set tags through RESTful APIs and device SDKs.

    Method 1. Set tags through RESTful APIs
    Bind and unbind a custom tag:
    See Tag Binding and Unbinding.

    Method 2. Set tags through device SDKs
    For the iOS SDK, see here.
    For the Android SDK, see Setting custom tag.

    Note:

    • One device can be bound to up to 100 tags (to increase the quota, submit a ticket).
    • One application can be bound to up to 10,000 tags (to increase the quota, submit a ticket).
    • One tag can contain up to 50 bytes.
    • Up to 500 tags can be bound or unbound in one request.

    Custom tag use cases and keywords

    Tag push is suitable for scenarios where more than 10 devices are bound to a tag and less than 10 pushes are required per day. For other scenarios, account push (binding an account instead of a tag to multiple devices for push) is recommended.

    Keyword
    A colon (:) is the keyword for separating the key and value in a key-value pair for user tag binding. For example, if you assign the tag level:3 to a device token, the TPNS backend will take level as the tag key and 3 as the tag value, while the original tag level:3 is pushed. Storage based on key-value is mainly to facilitate subsequent overwriting of tags of the same type.

    Binding/Unbinding tags

    TPNS provides APIs for binding/unbinding a single tag to/from a single device, a single tag to/from multiple devices, multiple tags to/from a single device, and multiple tags to/from multiple devices.

    Binding/Unbinding a single tag to/from a single device

    Recommended scenarios

    1. Call the device SDK API, for example, to get a user's subscribed channel in the application and bind/unbind the channel tag to/from the device token.
    2. Call the RESTful API occasionally, for example, to perform integration testing.

    Tag binding method

    {
      "operator_type": 1,
      "tag_list": ["tag"],
      "token_list": ["token"]
    }
    

    Tag unbinding method

    {
      "operator_type": 2,
      "tag_list": ["tag"],
      "token_list": ["token"]
    }
    

    Use limits

    • A tag can contain up to 50 bytes.
    • The API is called synchronously.
    Binding/Unbinding multiple tags to/from a single device

    Recommended scenarios

    1. Call the device SDK API, for example, to get a user's characteristics tags such as age, province, and gender in the application and bind/unbind them to/from the device token in batches.
    2. Call the Restful API, for example, to get a device's user subscription information tags such as marital status and hobbies (football, movies, etc,) through other internal channels, bind/unbind them to/from the device token in batches.

    Tag binding method

    {
       "operator_type": 3,
       "tag_list": ["tag1","tag2"],
       "token_list": ["token"]
    }
    

    Tag unbinding method

    {
      "operator_type": 4,
      "tag_list": ["tag1","tag2"],
      "token_list": ["token"]
    }
    

    Use limits

    • A tag can contain up to 50 bytes.
    • Up to 500 tags can be included in one call.
    • The API is called synchronously.
    Binding/Unbinding a single tag to/from multiple devices

    Recommended scenarios
    Call the RESTful API, for example, to bind/unbind the football tag to/from all users who like/dislike football in batches.

    Tag binding method

    {
       "operator_type": 7,
       "tag_list": ["tag"],
       "token_list": ["token1","token2"]
    }
    

    Tag unbinding method

    {
       "operator_type": 8,
       "tag_list": ["tag"],
       "token_list": ["token1","token2"]
    }
    

    Use limits

    • A tag can contain up to 50 bytes.
    • Up to 500 device tokens can be included in one call.
    • The API is called synchronously.
    Binding/Unbinding multiple tags to/from multiple devices

    Recommended scenarios
    Call the RESTful API, for example, to bind/unbind the football and basketball tags to/from all users who like/dislike football and basketball in batches.

    Tag binding method

    {
       "operator_type": 9,
       "tag_token_list": [{"tag":"tag1","token":"token1"},{"tag":"tag2","token":"token2"}]
    }
    

    Tag unbinding method

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

    Use limits

    • A tag can contain up to 50 bytes.
    • Up to 500 device tokens can be included in one call.
    • The API is called synchronously.

    Tag overriding

    TPNS provides two tag overriding methods: general overriding and overriding by tag category (key-value overriding). In key-value overriding, a colon (:) is used to separate the key and value in a key-value pair.

    General overriding

    Recommended scenarios

    1. Call the device SDK API. For example, if all channel information subscribed by a device has expired, you need to unbind all the channel tags from the device. However, traversing all tags to unbind them one by one is inconvenient. In this case, you can call this API to overwrite the tags.
    2. Call the RESTful API. For example, to set new tags for a device so that it will not be affected by legacy tags, this API can be called to overwrite them.

    Tag overriding method

    {
       "operator_type": 6,
       "tag_list": ["test", "level:1",, "level:2"], 
       "token_list": ["token"]
    }
    

    Use limits

    • A tag can contain up to 50 bytes.
    • The API is called asynchronously. You are recommended to set the call interval to longer than 1 second.
    Key-value overriding

    Recommended scenarios

    1. Call the device SDK API.
    2. Call the RESTful API.

    Instructions: a colon (:) is used for separating the key and value in a key-value pair. For example, level:2 indicates that the device level is 2. Assume that the device level is upgraded to 3, then you need to delete the tag level:2 before adding the tag level:3. If you know that the device has only the tag level:2, you can call the general overriding API to overwrite it. However, a device usually has multiple tags. If the device has another tag test and you want to delete only the tag level:2, you need to manipulate all tags of the device or call the relevant TPNS API to find the corresponding legacy tag and delete it, which is inconvenient. In this case, you can call this API to overwrite only tags with the key level.

    Tag overriding method

    {
       "operator_type": 6,
       "tag_list": ["test:2", "level:3"], 
       "token_list": ["token"]
    }
    

    API description: key-value overwriting can be performed properly only when all tags in the tag_list have a colon (:). For example, if a token has the tags test and level:1, after this API is called, the tag list of the token will include test, test:2, and level:3.
    Use limits

    • A tag can contain up to 50 bytes.
    • Up to 500 tags can be included in one call.
    • The API is called asynchronously. You are recommended to set the call interval to longer than 1 second.

    Tag deletion scenarios

    TPNS provides two tag deletion methods: deleting all tags of a single device and deleting specific tags of an application.

    Deleting all tags of a single device

    Recommended scenarios

    1. Call the device SDK API.
    2. Call the RESTful API.

    Instructions: you can use this API to delete all legacy tags of a device. This API is generally used to delete expired tags or set tags again after misoperations.

    Tag deletion method

    {
       "operator_type": 5,
       "token_list": ["token"]
    }
    

    Use limits

    • A tag can contain up to 50 bytes.
    • The API is called asynchronously. You are recommended to set the call interval to longer than 1 second.
    Deleting specific tags of an application

    Recommended scenarios
    Call the RESTful API.
    Instructions: you can use this API to delete specific tags of an application, i.e., removing them from the tag list of the application after unbinding them from bound devices. This API is generally used to delete disused tags. For example, you can call this API to delete testing tags added during test after the application is officially released.
    Tag deletion method

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

    Use limits

    • A tag can contain up to 50 bytes.
    • Up to 500 tags can be included in one call.
    • The API is called asynchronously. You are recommended to set the call interval to longer than 1 second.

    Managing preset tags

    • Preset tags are tags maintained on the TPNS platform, i.e., tags automatically collected by the SDK when user devices are registered with or connected to the TPNS server. Currently, TPNS preset tags include application version, system version, province, active information, system language, SDK version, country/region, phone brand, and phone model.
    • All devices are bound to the latest preset tags, which will automatically replace the corresponding legacy ones. For example, if the current application version of a device is 1.0.1, when the application is upgraded to 1.0.2, the device will be automatically unbound from the v1.0.1 tag and then bound to the v1.0.2 tag.

    Querying tags bound to devices

    To query specific preset and custom tags by device token, go to the TPNS console and select Message Management > Troubleshooting Tools.
    See the figure below:

    Getting Started

    Tag push allows you to push messages by preset or custom tags or combinations of preset and custom tags (combined by the "AND" or "OR" relationship) according to your operational requirements.

    Using the console for tag push

    You can push a message by tag in the Tencent Cloud console as follows.

    1. Select the tag type, e.g., custom tag or a category of preset tags.
    2. Select the tags for which you want to push a message after selecting the tag type.

      After a tag is selected, the number of devices bound to the selected tag will also be displayed. The tag combination in the figure above indicates to push a message to male users in Guangdong and Jiangsu who were active on 2020-04-23, 2020-04-22, or 2020-04-21. Then, click Preview to push the message to the corresponding target devices.

    Calling the push API for tag push

    Set the audience_type (push target) in the push API request parameter to tag to enable tag push. For more information, see Push API.
    API example: push a message to male users in Guangdong and Jiangsu who were active on 2020-04-23, 2020-04-22, or 2020-04-21.

    {
       "audience_type": "tag",
       "tag_rules": [
           {
               "tag_items": [
                   {
                       "tags": [
                           "guangdong",
                           "jiangsu"
                       ],
                       "is_not": false,
                       "tags_operator": "OR",
                       "items_operator": "OR",
                       "tag_type": "xg_auto_province"  
                   },
                   {
                       "tags": [
                           "20200421",
                           "20200422",
                           "20200423"
                       ],
                       "is_not": false,
                       "tags_operator": "OR",
                       "items_operator": "AND",
                       "tag_type": "xg_auto_active"
                   }
               ],
               "operator": "OR",
               "is_not": false
           },
           {
               "tag_items": [
                   {
                       "tags": [
                           "male"
                       ],
                       "is_not": false,
                       "tags_operator": "OR",
                       "items_operator": "OR",
                       "tag_type": "xg_user_define"
                   }
               ],
               "operator": "AND",
               "is_not": false
           }
       ],
       "message_type": "notify",
       "message": {
       "title": "Test title",
       "content": "Test content",
       "android": {
        "ring": 1,
           "ring_raw": "ring",
           "vibrate": 1,
           "lights": 1,
           "clearable": 1,
           },
         "custom_content":"{\"key\":\"value\"}"
       }
    }
    }
    

    FAQs

    1. Will the API for querying bound devices by tag be made publicly available?
      The API is currently for internal use only and will not be made publicly available in the future for the sake of system stability. You can select a tag on the push page in the console to query its bound devices.

    2. Will the API for querying bound tags by device token be made publicly available?
      The API is currently for internal use only and will not be made publicly available in the future for the sake of system stability. You can enter a token in the toolkit in the console to query its bound tags.