Add Cloud Connector Devices to Your App
In this article, we will show you how to add Cloud Connector devices to your application. We also provide screenshots that illustrate the flow from a user perspective.
We use "Withings Device" as our sample Cloud Connector. Withings uses a proprietary cloud for its devices, which include blood pressure monitors, wearables, scales, and thermometers. "Withings Device" is an ARTIK cloud services device type configured as a Cloud Connector. The Cloud Connector can connect directly to the Withings cloud to obtain data from Withings devices.
A Cloud Connector is a category of device type. To add a Cloud Connector to an application, it must exist as a device type on ARTIK cloud services. Creating a Cloud Connector is covered in the article Using Cloud Connectors.
- Build an application to manage Cloud Connector devices provides a more extensive development tutorial.
Step 1: Create an application and request device permissions
Create an application on the Developer Dashboard. Choose "Withings Device" as the device type. Check "Read" and "Write" permissions for this device type.
Step 2: Connect a device
In order to add a device of type "Withings Device" on ARTIK cloud services, you will need to call the Create a device REST API. We will name this device "My Withings".
Step 3: Authenticate with the third-party cloud
After "My Withings" is added to the user's ARTIK Cloud account, the user must authenticate this device with the Withings cloud and grant ARTIK cloud services permission to access data on the Withings account. Only after doing so can "My Withings" receive data from the user's physical device via the Withings cloud.
To do this, your application needs to call the Authenticate a Cloud Connector device REST API. This API call triggers a sequence of redirections between ARTIK cloud services, the Withings cloud, and your application. The user will be prompted to enter his/her credentials at Withings and grant permission to ARTIK cloud services to access the data.
Step 4: Get the data from the third-party cloud
In order to obtain the most recent data from the "My Withings" device, one of the simplest ways would be to call the Get messages API.
Step 5: Add clean-up functionality
For a better usability experience, your application should give the end user the options to delete a device and revoke the authorization with the third-party cloud. All these can be easily done by calling the corresponding APIs.
The user experience
This is how our sample app looks from a user perspective.
The user logs into their ARTIK Cloud Account.
After granting the app permissions to access data from the "Withings Device" Cloud Connector, the user can connect the device to ARTIK cloud services (Step 2).
The user clicks the "Authorize" button and signs into their Withings account to authenticate the device (Step 3).
The Cloud Connector is now authenticated and can receive data via the Withings cloud (Step 4)!
The user can later click the button to revoke authorization or delete the device (Step 5).
It is that simple to add devices with third-party clouds to your application.
Here are a few more tips:
- Read our blog post "Build an application to manage Cloud Connector devices" for the details and a sample application.
- See the Works With page to find device types verified to work with ARTIK cloud services.
- To check if a device type is a Cloud Connector, log into the API Console, look for the "Get Device Types" API call, enter the name of the device type, and then make the API call. See if
hasCloudConnectorin the response is true.
- If the third-party cloud does not require authentication, you can skip Step 3 above.