tencent cloud

TDMQ for MQTT

Release Notes and Announcements
Release Notes
Product Introduction
TDMQ Product Series Introduction and Selection
What Is TDMQ for MQTT
Scenarios
Technical Architecture
Product series
MQTT Protocol Compatibility Notes
Comparison with Apache
High Availability
Product Constraints and Usage Quota
Basic Concepts
Supported Regions
Billing
Billing Overview
Renewal Instructions
Viewing Consumption Details
Overdue Payment Instructions
Refund
Getting Started
Guide for Getting Started
Preparations
Public Network Access
VPC Network Access
User Guide
Usage Process Guide
Configuring Account Permission
Creating a Cluster
Managing Topic
Connecting to the Cluster
Querying Messages
Managing Client
Managing a Cluster
Viewing Monitoring Metrics and Configuring Alarm Policies
Data Integration
Integrating Data Into SCF
Integrating Data Into CKafka
Integrating Data into RocketMQ
Development Guide
MQTT 5 Advanced Features
Data Plane HTTP API Description
Quota and Flow Control Mechanism Description
Configuring a Custom Domain Name
Configuring SQL Filtering
Configuring Point-to-Point Subscription
MQTT over QUIC
Managing Client Subscription
Message Enhancement Rule
Use Cases
Must-Knows for MQTT Client Development
Observability
Topic and Wildcard Subscriptions
​​API Reference
History
Introduction
API Category
Making API Requests
Cluster APIs
Topic APIs
Authorization Policy APIs
User APIs
Client APIs
Message Enhancement Rule APIs
Message APIs
Data Types
Error Codes
SDK Reference
Access Point Format
Java SDK
C SDK
Javascript/Node.JS/Mini Program
Go SDK
iOS SDK
JavaScript SDK
Dart SDK
Python SDK
.NET
Security and Compliance
Permission Management
FAQs
Related Agreement
Privacy Policy
Data Privacy And Security Agreement
TDMQ for MQTT Service Level Agreement
Contact Us
DocumentationTDMQ for MQTTSDK ReferenceiOS SDK

iOS SDK

Focus Mode
Font Size
Last updated: 2026-04-01 16:37:51

Feature Overview

CocoaMQTT is an MQTT client library written in Swift, designed specifically for iOS, macOS, and tvOS platforms.

CocoaMQTT supports MQTT 3.1.1 and MQTT 5.0 protocols, providing a complete MQTT feature implementation including connection, publish, subscribe, QoS, SSL/TLS, WebSocket, and other capabilities.

Cloud Resource Preparation

Please refer to resource creation operation steps to complete cloud resource preparation.

Environment Preparation

System Requirements

iOS 10.0+ / macOS 10.12+ / tvOS 10.0+
Xcode 12.0+
Swift 5.0+

Installing CocoaMQTT via CocoaPods

Add to your Podfile file:
target 'YourTarget' do
    pod 'CocoaMQTT', '~> 2.1.6'
end
Then execute:
pod install
Note:
CocoaMQTT 2.x supports both MQTT 3.1.1 and MQTT 5.0 protocols, with different class names used for distinction (CocoaMQTT for 3.1.1 and CocoaMQTT5 for 5.0).

Installing via Swift Package Manager

In Xcode:
1. Choose File > Swift Packages > Add Package Dependency.
2. Enter repository URL: https://github.com/emqx/CocoaMQTT.git.
3. Select version number or version range.
4. Import the module in your code: import CocoaMQTT.

Installing via Carthage

Add to the Cartfile file:
github "emqx/CocoaMQTT" "master"
Execute:
carthage update --platform iOS,macOS,tvOS --use-xcframeworks
Then drag the generated .xcframework into the project and set it to "Embed & Sign".

Sample Code

Note:
This document is based on CocoaMQTT version 2.1.9. If you are using a different version, the APIs may differ.

Key APIs Overview for MQTT 5.0

When using MQTT 5.0 (CocoaMQTT5), please note the following key points:
1. Connection response callback parameters: didConnectAck receives 3 parameters
mqtt.didConnectAck = { mqtt, ack, properties in
    // ack is of the CocoaMQTTCONNACKReasonCode type.
    // properties is of the MqttDecodeConnAck? type.
}
2. Connection success status: Use .success instead of .accept
if ack == .success {  // Correct
    // Connection successful
}
3. Subscription method: Use an array of MqttSubscription objects
let subscriptions = [
    MqttSubscription(topic: "home/test", qos: .qos1)
]
mqtt.subscribe(subscriptions)
4. Receive message callback: Receive 4 parameters. payload is of [UInt8] type
mqtt.didReceiveMessage = { mqtt, message, id, properties in
    // message.payload is of the [UInt8] type and needs to be converted.
    let content = String(data: Data(message.payload), encoding: .utf8) ?? ""
}
5. Publish message: The properties parameter is required
mqtt.publish(topic, withString: message, qos: .qos1, properties: MqttPublishProperties())
6. Publish acknowledgement callback: Receive 3 parameters
mqtt.didPublishAck = { mqtt, id, properties in
    print("Publish acknowledgement - ID: \\(id)")
}
7. Subscription result callback: Receive 4 parameters
mqtt.didSubscribeTopics = { mqtt, success, failed, properties in
    // success is of the [(String, CocoaMQTTQoS)] type.
}
MQTT 5
MQTT 5 TLS
MQTT 3.1.1
MQTT 3.1.1 TLS

import CocoaMQTT

class MQTTManager {
    var mqtt: CocoaMQTT5!
    
    func setupMQTT() {
        // Get the access point from the MQTT console:
        // For users implementing VPC connectivity via Private Link, use the private network access point.
        // For users accessing over the public network, ensure the public network security policy permits access, and the machine running the program has public network connectivity.
        let host = "mqtt-xxx.mqtt.tencenttdmq.com"
        let port: UInt16 = 1883
        
        // A valid client identifier contains digits 0–9, lowercase letters a–z, and uppercase letters A–Z, with a total length of 1–23 characters.
        // See https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901059.
        let clientID = "QuickStart"
        
        mqtt = CocoaMQTT5(clientID: clientID, host: host, port: port)
        
        // In the console, on the Authentication tab, create an account and copy the username and password.
        mqtt.username = "YOUR_USERNAME"
        mqtt.password = "YOUR_PASSWORD"
        
        mqtt.keepAlive = 60
        mqtt.cleanSession = true
        mqtt.autoReconnect = true
        
        // Set the callback.
        mqtt.didConnectAck = { mqtt, ack, _ in
            print("Connection response: \\(ack)")
            
            if ack == .success {
                // MQTT topic
                let pubTopic = "home/test"
                
                // Subscribe to a topic.
                let subscriptions = [
                    MqttSubscription(topic: pubTopic, qos: .qos1),
                    MqttSubscription(topic: "home/#", qos: .qos1),
                    MqttSubscription(topic: "home/+", qos: .qos1)
                ]
                mqtt.subscribe(subscriptions)
                print("Subscribed to the topic")
            }
        }
        
        mqtt.didPublishMessage = { mqtt, message, id in
            print("Message published successfully - ID: \\(id)")
        }
        
        mqtt.didPublishAck = { mqtt, id, _ in
            print("Received publish acknowledgement - ID: \\(id)")
        }
        
        mqtt.didReceiveMessage = { mqtt, message, _, _ in
            let content = String(data: Data(message.payload), encoding: .utf8) ?? ""
            print("Received message - Topic: \\(message.topic), QoS: \\(message.qos.rawValue), Content: [\\(content)]")
        }
        
        mqtt.didSubscribeTopics = { mqtt, success, failed, _ in
            print("Subscription successful: \\(success)")
            if !failed.isEmpty {
                print("Subscription failed: \\(failed)")
            }
        }
        
        mqtt.didDisconnect = { mqtt, error in
            if let error = error {
                print("Disconnected: \\(error.localizedDescription)")
            } else {
                print("Disconnected")
            }
        }
        
        // Connect to the server.
        _ = mqtt.connect()
    }
    
    func publishMessages() {
        let pubTopic = "home/test"
        let total = 16
        
        for i in 0..<total {
            let message = "Hello MQTT \\(i)"
            print("Preparing to publish message \\(i)")
            mqtt.publish(pubTopic, withString: message, qos: .qos1, properties: MqttPublishProperties())
            print("Message published \\(i)")
            
            // Delay 3 seconds.
            Thread.sleep(forTimeInterval: 3)
        }
        
        // Disconnect after 3 seconds.
        Thread.sleep(forTimeInterval: 3)
        mqtt.disconnect()
    }
}

import CocoaMQTT

class MQTTManagerTLS {
    var mqtt: CocoaMQTT5!
    
    func setupMQTT() {
        // Get the access point from the MQTT console:
        // For users implementing VPC connectivity via Private Link, use the private network access point.
        // For users accessing over the public network, ensure the public network security policy permits access, and the machine running the program has public network connectivity.
        let host = "mqtt-xxx.mqtt.tencenttdmq.com"
        let port: UInt16 = 8883
        
        // A valid client identifier contains digits 0–9, lowercase letters a–z, and uppercase letters A–Z, with a total length of 1–23 characters.
        // See https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901059.
        let clientID = "QuickStartTls"
        
        mqtt = CocoaMQTT5(clientID: clientID, host: host, port: port)
        
        // In the console, on the Authentication tab, create an account and copy the username and password.
        mqtt.username = "YOUR_USERNAME"
        mqtt.password = "YOUR_PASSWORD"
        
        mqtt.keepAlive = 60
        mqtt.cleanSession = true
        mqtt.autoReconnect = true
        
        // Enable SSL/TLS.
        mqtt.enableSSL = true
        mqtt.allowUntrustCACertificate = false
        
        // Set the callback.
        mqtt.didConnectAck = { mqtt, ack, _ in
            print("Connection response: \\(ack)")
            
            if ack == .success {
                // MQTT topic
                let topicName = "home/test"
                
                // Subscribe to a topic.
                let subscriptions = [
                    MqttSubscription(topic: topicName, qos: .qos1),
                    MqttSubscription(topic: "home/#", qos: .qos1),
                    MqttSubscription(topic: "home/+", qos: .qos1)
                ]
                mqtt.subscribe(subscriptions)
            }
        }
        
        mqtt.didPublishMessage = { mqtt, message, id in
            print("Message published successfully - ID: \\(id)")
        }
        
        mqtt.didPublishAck = { mqtt, id, _ in
            print("Received publish acknowledgement - ID: \\(id)")
        }
        
        mqtt.didReceiveMessage = { mqtt, message, _, _ in
            let content = String(data: Data(message.payload), encoding: .utf8) ?? ""
            print("Received message - Topic: \\(message.topic), QoS: \\(message.qos.rawValue), Content: [\\(content)]")
        }
        
        mqtt.didSubscribeTopics = { mqtt, success, failed, _ in
            for (topic, qos) in success {
                print("Subscription successful - Topic: \\(topic), Granted-QoS: \\(qos)")
            }
            if !failed.isEmpty {
                print("Subscription failed: \\(failed)")
            }
        }
        
        mqtt.didDisconnect = { mqtt, error in
            if let error = error {
                print("Disconnected: \\(error.localizedDescription)")
            } else {
                print("Disconnected")
            }
        }
        
        // Connect to the server.
        _ = mqtt.connect()
    }
    
    func publishMessages() {
        let topicName = "home/test"
        let total = 16
        
        for i in 0..<total {
            let message = "Hello MQTT \\(i)"
            print("Preparing to publish message \\(i)")
            mqtt.publish(topicName, withString: message, qos: .qos1, properties: MqttPublishProperties())
            print("Message published \\(i)")
            
            // Delay 3 seconds.
            Thread.sleep(forTimeInterval: 3)
        }
        
        // Disconnect after 3 seconds.
        Thread.sleep(forTimeInterval: 3)
        mqtt.disconnect()
    }
}



import CocoaMQTT

class MQTTManager311 {
    var mqtt: CocoaMQTT!
    
    func setupMQTT() {
        // Get the access point from the MQTT console:
        // For users implementing VPC connectivity via Private Link, use the private network access point.
        // For users accessing over the public network, ensure the public network security policy permits access, and the machine running the program has public network connectivity.
        let host = "mqtt-xxx.mqtt.tencenttdmq.com"
        let port: UInt16 = 1883
        
        // A valid client identifier contains digits 0–9, lowercase letters a–z, and uppercase letters A–Z, with a total length of 1–23 characters.
        // See https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901059.
        let clientID = "QuickStart"
        
        mqtt = CocoaMQTT(clientID: clientID, host: host, port: port)
        
        // In the console, on the Authentication tab, create an account and copy the username and password.
        mqtt.username = "YOUR_USERNAME"
        mqtt.password = "YOUR_PASSWORD"
        
        mqtt.keepAlive = 60
        mqtt.cleanSession = true
        mqtt.autoReconnect = true
        
        // Set the proxy.
        mqtt.delegate = self
        
        // Connect to the server.
        _ = mqtt.connect()
    }
    
    func publishMessages() {
        // Ensure that the first-level topic "home" has been created in the MQTT console.
        let pubTopic = "home/test"
        let total = 16
        
        for i in 0..<total {
            let message = "Hello MQTT \\(i)"
            print("Preparing to publish message \\(i)")
            mqtt.publish(pubTopic, withString: message, qos: .qos1)
            print("Message published \\(i)")
            
            // Delay 3 seconds.
            Thread.sleep(forTimeInterval: 3)
        }
        
        // Disconnect after 3 seconds.
        Thread.sleep(forTimeInterval: 3)
        mqtt.disconnect()
    }
}

// MARK: - CocoaMQTTDelegate
extension MQTTManager311: CocoaMQTTDelegate {
    func mqtt(_ mqtt: CocoaMQTT, didConnectAck ack: CocoaMQTTConnAck) {
        print("Connection response: \\(ack)")
        
        if ack == .accept {
            // Ensure that the first-level topic "home" has been created in the MQTT console.
            let pubTopic = "home/test"
            let topicFilters = [pubTopic, "home/#", "home/+"]
            
            // Subscribe to a topic.
            mqtt.subscribe(topicFilters, qos: [.qos1, .qos1, .qos1])
            print("Subscribed to \\(topicFilters.count) topic(s)")
        }
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didPublishMessage message: CocoaMQTTMessage, id: UInt16) {
        print("Message published successfully - ID: \\(id)")
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didPublishAck id: UInt16) {
        print("Received publish acknowledgement - Packet-ID: \\(id)")
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didReceiveMessage message: CocoaMQTTMessage, id: UInt16) {
        let content = message.string ?? ""
        print("Received message - Topic: \\(message.topic), QoS: \\(message.qos.rawValue), Dup: \\(message.duplicated), Retained: \\(message.retained), Content: [\\(content)]")
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didSubscribeTopics success: NSDictionary, failed: [String]) {
        print("Subscription successful: \\(success)")
        if !failed.isEmpty {
            print("Subscription failed: \\(failed)")
        }
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didUnsubscribeTopics topics: [String]) {
        print("Unsubscribe: \\(topics)")
    }
    
    func mqttDidPing(_ mqtt: CocoaMQTT) {
        // Heartbeat
    }
    
    func mqttDidReceivePong(_ mqtt: CocoaMQTT) {
        // Heartbeat response
    }
    
    func mqttDidDisconnect(_ mqtt: CocoaMQTT, withError err: Error?) {
        if let error = err {
            print("Disconnected: \\(error.localizedDescription)")
        } else {
            print("Disconnected")
        }
    }
}

import CocoaMQTT

class MQTTManager311TLS {
    var mqtt: CocoaMQTT!
    
    func setupMQTT() {
        // Get the access point from the MQTT console:
        // For users implementing VPC connectivity via Private Link, use the private network access point.
        // For users accessing over the public network, ensure the public network security policy permits access, and the machine running the program has public network connectivity.
        let host = "mqtt-xxx.mqtt.tencenttdmq.com"
        let port: UInt16 = 8883
        
        // A valid client identifier contains digits 0–9, lowercase letters a–z, and uppercase letters A–Z, with a total length of 1–23 characters.
        // See https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901059.
        let clientID = "ClientQuickStartTls"
        
        mqtt = CocoaMQTT(clientID: clientID, host: host, port: port)
        
        // In the console, on the Authentication tab, create an account and copy the username and password.
        mqtt.username = "YOUR_USERNAME"
        mqtt.password = "YOUR_PASSWORD"
        
        mqtt.keepAlive = 60
        mqtt.cleanSession = true
        mqtt.autoReconnect = true
        
        // Enable SSL/TLS.
        mqtt.enableSSL = true
        mqtt.allowUntrustCACertificate = false
        
        // Set the proxy.
        mqtt.delegate = self
        
        // Connect to the server.
        _ = mqtt.connect()
    }
    
    func publishMessages() {
        // Ensure that the first-level topic "home" has been created in the MQTT console.
        let topic = "home/test"
        let total = 16
        
        for i in 0..<total {
            let message = "Hello MQTT \\(i)"
            print("Preparing to publish message \\(i)")
            mqtt.publish(topic, withString: message, qos: .qos1)
            print("Message published \\(i)")
            
            // Delay 1 second.
            Thread.sleep(forTimeInterval: 1)
        }
        
        // Disconnect after 3 seconds.
        Thread.sleep(forTimeInterval: 3)
        mqtt.disconnect()
    }
}

// MARK: - CocoaMQTTDelegate
extension MQTTManager311TLS: CocoaMQTTDelegate {
    func mqtt(_ mqtt: CocoaMQTT, didConnectAck ack: CocoaMQTTConnAck) {
        print("Connection response: \\(ack)")
        
        if ack == .accept {
            let topicFilters = ["home/test"]
            
            // Subscribe to a topic.
            mqtt.subscribe(topicFilters, qos: [.qos1])
            print("Subscribed to \\(topicFilters.count) topics")
        }
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didPublishMessage message: CocoaMQTTMessage, id: UInt16) {
        // Message published
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didPublishAck id: UInt16) {
        print("Received publish acknowledgement - Packet-ID: \\(id)")
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didReceiveMessage message: CocoaMQTTMessage, id: UInt16) {
        let content = message.string ?? ""
        print("Received message - Topic: \\(message.topic), QoS: \\(message.qos.rawValue), Content: [\\(content)]")
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didSubscribeTopics success: NSDictionary, failed: [String]) {
        print("Subscription successful: \\(success)")
    }
    
    func mqtt(_ mqtt: CocoaMQTT, didUnsubscribeTopics topics: [String]) {
        print("Unsubscribe: \\(topics)")
    }
    
    func mqttDidPing(_ mqtt: CocoaMQTT) {
        // Heartbeat
    }
    
    func mqttDidReceivePong(_ mqtt: CocoaMQTT) {
        // Heartbeat response
    }
    
    func mqttDidDisconnect(_ mqtt: CocoaMQTT, withError err: Error?) {
        if let error = err {
            print("Disconnected: \\(error.localizedDescription)")
        } else {
            print("Disconnected")
        }
    }
}

Parameter Description

Parameter
Description
pubTopic
Target topic for the message to be published.
Message topics can contain multiple levels, separated by '/'. The first-level topic needs to be created on the Topic Tab in the console. For details, refer to Topic Names and Topic Filters.
topicFilters
One or more subscription expressions.
Subscription expressions can contain wildcards. For details, refer to Topic Names and Topic Filters.
qos
QoS array. The array length must match the number of Topic Filters elements.
The most commonly used QoS is 1, which is At-Least-Once delivery. For details, refer to Quality of Service levels and protocol flows.
host
MQTT instance endpoint host address, which can be copied from the Basic Information > Access Information section of the target cluster in the console, as shown below.
Standard access point: mqtt-xxx.mqtt.tencenttdmq.com (port 1883)
TLS access point: mqtt-xxx.mqtt.tencenttdmq.com (port 8883)
Standard WebSocket access point: mqtt-xxx.mqtt.tencenttdmq.com (port 80, path /mqtt)
TLS WebSocket access point: mqtt-xxx.mqtt.tencenttdmq.com (port 443, path /mqtt)

clientID
Unique identifier of the device, such as vehicle identification number (VIN) and product serial number.
A valid client identifier contains digits 0–9, lowercase letters a–z, and uppercase letters A–Z, with a total length of 1–23 characters. For details, refer to Client Identifier.
username
Connection username, which can be copied from the Authentication Management page on the cluster details page in the console.

password
Password matching the connection username, which can be copied from the Authentication Management page on the cluster details page in the console.

Previous Topic: Go SDKNext Topic: JavaScript SDK

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback