Working with the API

You are currently viewing the AWS SDK for Mobile documentation which is a collection of low-level libraries. Use the Amplify libraries for all new app development. Learn more

You can view the Mobile SDK API reference here.

Establish Connection

Before you can publish/subscribe to a topic, you need to establish a connection. You can do that using one of the following methods provided by the SDK.

Certificate based mutual authentication

To connect with the AWS IoT Core service on the standard MQTT port 8883, you can use the connect API as shown below.

1func mqttEventCallback(_ status: AWSIoTMQTTStatus ) {
2 print("connection status = \(status.rawValue)")
3}
4
5iotDataManager.connect(
6 withClientId: "<YOUR_CLIENT_ID>",
7 cleanSession: true,
8 certificateId: "<YOUR_CERTIFICATE_ID>",
9 statusCallback: mqttEventCallback
10)

The AWS IoT Core service also allows you to connect devices using MQTT with certificate based mutual authentication on port 443. You can do this using the connectUsingALPN API as shown below. See MQTT with TLS client authentication on port 443 for more information.

1func mqttEventCallback(_ status: AWSIoTMQTTStatus ) {
2 print("connection status = \(status.rawValue)")
3}
4
5iotDataManager.connectUsingALPN(
6 withClientId: "<YOUR_CLIENT_ID>",
7 cleanSession: true,
8 certificateId: "<YOUR_CERTIFICATE_ID>",
9 statusCallback: mqttEventCallback
10)

You can take a look at the API Reference to get more information.

AWS Credentials based Authentication

This method uses AWS Signature Version 4 Credentials to sign the request to connect to the AWS IoT endpoint.

1func mqttEventCallback(_ status: AWSIoTMQTTStatus ) {
2 print("connection status = \(status.rawValue)")
3}
4
5iotDataManager.connectUsingWebSocket(
6 withClientId: "<YOUR_CLIENT_ID>",
7 cleanSession: true,
8 statusCallback: mqttEventCallback
9)

You can take a look at the API Reference to know more information.

Custom Authentication

AWS IoT allows you to define custom authorizers that allow you to manage your own authentication and authorization strategy using a custom authentication service and a Lambda function. Custom authorizers allow AWS IoT to authenticate your devices and authorize operations using bearer token authentication and authorization strategies. See AWS IoT Custom Authentication for more details.

Please follow the steps outlined in Setting up Custom Authentication to create the custom authorizer and configure the workflow with AWS IoT.

Once the custom authorizer workflow is configured, you can establish a connection as follows:

1func mqttEventCallback(_ status: AWSIoTMQTTStatus ) {
2 print("connection status = \(status.rawValue)")
3}
4
5iotDataManager.connectUsingWebSocket(
6 withClientId: uuid,
7 cleanSession: true,
8 customAuthorizerName: "<name-of-the-custom-authorizer>",
9 tokenKeyName: "<key-name-for-the-token>",
10 tokenValue: "<token>",
11 tokenSignature: "<signature-of-the-token>",
12 statusCallback: mqttEventCallback
13)

You can take a look at the API Reference to know more information. This feature is available in the AWS SDK for iOS starting from 2.8.4 version. See AWSIoT - 2.8.4 for more details.

Subscribe to a topic

In order to start receiving messages from your provider, you need to subscribe to a topic as follows;

1iotDataManager.subscribe(
2 toTopic: "myTopic",
3 qoS: .messageDeliveryAttemptedAtMostOnce, /* Quality of Service */
4 messageCallback: {
5 (payload) ->Void in
6 let stringValue = NSString(data: payload, encoding: String.Encoding.utf8.rawValue)!
7
8 print("Message received: \(stringValue)")
9 }
10)

Subscribe to multiple topics

To subscribe for multiple topics, just call subscribe() for each topic you wish to subscribe.

Publish to a topic

To send a message to a topic, use publishString() method with your topic name and the message:

1iotDataManager.publishString(
2 "Hello to all subscribers!",
3 onTopic: "myTopic",
4 qoS:.messageDeliveryAttemptedAtMostOnce
5)

Unsubscribe from a topic

To stop receiving messages from a topic, you can use unsubscribeTopic() method:

1iotDataManager.unsubscribeTopic("myTopic")
2
3// You will no longer get messages for "myTopic"

Close Connection

In order to disconnect, you need to close the connection as follows:

1iotDataManager.disconnect()

API Reference

For the complete API documentation for AWS IoT, visit our API reference.