Feature Introduction
User Property is a new feature introduced in MQTT 5.0, allowing you to add custom key-value pair metadata to MQTT messages. With User Properties, you can pass additional information without modifying the message payload, enabling features such as message routing, data format identification, and device information reporting.
Tencent Cloud MQTT service fully supports the MQTT 5.0 User Property feature, providing stable and reliable message transmission.
Feature Description
Uses key-value pair format with UTF-8 encoding.
Allows unlimited number of properties, constrained only by the maximum packet length.
Supports duplicate key names.
Attaches to most MQTT 5.0 control packets (see supported packet types below).
Forwards transparently by the server without modifying property content.
Use Cases
Data Format Identification: Labels the data format in the message so that the server can directly select the corresponding parser.
Message Routing: Marks the target system of messages through user properties, enabling application-level message distribution.
File Transfer: Stores file metadata in user properties, while the message payload directly carries binary data.
Device Information Reporting: Carries device model, firmware version, and other information during connection, facilitating device management and permission control.
Operation Instructions
Prerequisites
An MQTT instance has been created.
The client SDK supports the MQTT 5.0 protocol.
Configuring at Connection
const mqtt = require('mqtt')
const client = mqtt.connect('mqtt://your-endpoint.mqtt.tencentcloudmq.com:1883', {
protocolVersion: 5,
properties: {
userProperties: {
device_type: 'sensor',
version: '1.0.0'
}
}
})
Configuring When Publishing Messages
client.publish('sensor/temperature', '25.6', {
qos: 1,
properties: {
userProperties: {
sensor_id: 'TH-001',
location: 'room_A'
}
}
})
Receiving and Reading Messages
client.on('message', (topic, payload, packet) => {
const userProps = packet.properties.userProperties
console.log('User properties:', userProps)
console.log('Message content:', payload.toString())
})
Must-Knows
Performance Optimization
Avoid carrying a large number of user properties in high-frequency reporting messages.
Properly control the quantity and size of properties to reduce network transmission overhead.
Security
Do not transmit sensitive credentials such as passwords, tokens, or keys in user properties.
Do not transmit personal privacy data such as phone numbers or ID card numbers.
Encrypt sensitive information before transmission.
Related Notes
Supported Packet Types
User properties can be used in the following MQTT 5.0 control packets:
|
CONNECT, CONNACK | Connection requests and responses |
PUBLISH, PUBACK, PUBREC, PUBREL, PUBCOMP | Message publishing and acknowledgment |
SUBSCRIBE, SUBACK | Subscription requests and responses |
UNSUBSCRIBE, UNSUBACK | Unsubscription requests and responses |
DISCONNECT, AUTH | Disconnection and authentication |
WILL PROPERTIES | Will message properties |
Version Compatibility
User properties are supported only in the MQTT 5.0 protocol.
If the subscriber uses the MQTT 3.x protocol, the server automatically strips user properties and delivers only the message payload.
Both publishers and subscribers are recommended to use the MQTT 5.0 protocol for full feature support.
FAQs
Will the Server Modify User Properties?
No. Tencent Cloud MQTT service only transparently forwards user properties and does not modify the property content.
Can the Same Key Appear Multiple Times?
Yes. The MQTT 5.0 protocol allows duplicate key names, and the receiver will receive an array containing multiple values.
Do User Properties Affect the QoS Level of Messages?
No. User properties, as part of the message, are transmitted according to the message's specified QoS level.
How to Check Whether the Message Successfully Carries User Properties?
You can print packet.properties.userProperties in the message callback function of the subscriber to view the received user properties.