This SDK helps you connect your iOS, tvOS, watchOS, and macOS applications to ARTIK cloud services. It exposes a number of methods to easily execute REST and WebSockets calls to ARTIK cloud services.
Connect with ARTIK cloud services and handle its response asynchronously.
DevicesAPI.get(id: "example-id").done { device in
if device.isSharable() {
device.share(email: "[email protected]").catch { error in
print(error)
}
} else {
device.removeFromArtik().done {
print("We couldn't share the device, so it was removed.")
}.catch { error in
print(error)
}
}
}.catch { error in
print(error)
}- Alamofire >= 4.7.3
- PromiseKit >= 6.5.1
- ObjectMapper >= 3.3.0
- CryptoSwift >= 0.12.0
- Starscream >= 3.0.6
CocoaPods 1.1 or higher is required.
Specify ArtikCloudSwift in your PodFile using one of the following:
source 'https://github.com/CocoaPods/Specs.git'
pod 'ArtikCloudSwift'Then run the following command:
pod install
Drop ArtikCloudSwift.xcodeproj into your project and add ArtikCloudSwift.framework to your application's embedded frameworks.
import ArtikCloudSwiftBefore you begin making requests, provide the client ID and redirect URI of your application.
ArtikCloudSwiftSettings.clientID = "my-clientid"
ArtikCloudSwiftSettings.redirectURI = "my-uri://"To learn how to create an application on ARTIK cloud services and obtain its client ID (application ID) and redirect URI, read our documentation.
API calls require authentication, and you must obtain a Token through any of the available authentication flows. These flows are implemented in AuthenticationAPI. This How To guide describes how to choose the best authentication flow for your use case.
Once you have obtained a Token, set it using one of the following methods:
ArtikCloudSwiftSettings.setUserToken(_ token: UserToken)
ArtikCloudSwiftSettings.setApplicationToken(_ token: ApplicationToken)
ArtikCloudSwiftSettings.setDeviceToken(_ token: DeviceToken)Each time a token is used, its validity is verified locally (if possible). For a UserToken that has expired, the framework will attempt to refresh it with ARTIK cloud services before executing the request. This can be disabled by setting ArtikCloudSwiftSettings.attemptToRefreshToken = false.
If you plan on using multiple Token types for different requests, you can set preferredTokenForRequests to a certain Token.Type. The framework will first attempt to use this token type before falling back on other types if unavailable. For example, to prioritize the current ApplicationToken:
ArtikCloudSwiftSettings.preferredTokenForRequests = ApplicationToken.selfWhen using certain APIs, ARTIK cloud services will attempt a callback to your application, such as when using the Authorization Code authentication flow or upgrading a device type for Monetization. For this to work, first make sure that the redirect URI of your application (server-side), your URL scheme (client-side), and ArtikCloudSwiftSettings.redirectURI are set to the same value.
Once your application receives a callback, identify which flow it is targeting by passing the URL to ArtikCloudSwiftSettings.identifyRedirectEndpoint(_ callback: URL). Use the RedirectEndpoint value returned to determine how to process it.
// iOS Example
func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
if let endpoint = ArtikCloudSwiftSettings.identifyRedirectEndpoint(url) {
switch endpoint {
case .cloudAuthorization:
// User was authorizing a Cloud Connector
case .monetization:
// User has attempted to upgrade a device
do {
if try MonetizationAPI.processUpgradeCallback(url) == .accepted {
// Device was upgraded!
}
} catch {
// Unable to determine upgrade result
}
case .logout:
// User has logged out
default:
// Default Callback, used for Authentication flows
// Using Authorization Code + PKCE for example...
AuthenticationAPI.processAuthorizationCodeCallback(url, usingPKCE: true).done { token in
// We got a Token!
}.catch { error -> Void in
// Something went wrong...
}
}
}
return true
}Rate limiting is used by most endpoints on the platform, regardless of the type of authentication used, to prevent abuse of our services. When you reach a limit, you will have to wait for the specific time window to expire before you can try again. This framework will attempt to do this for you by waiting the required amount of time and re-attempting the request automatically. You can adjust the maximum amount of attempts and the maximum acceptable wait time for a window to expire using ArtikCloudSwiftSettings's rateLimitAttemptsCount and rateLimitAttemptsThreshold. You can disable this feature by setting the maximum number of attempts to 0. In the case where the framework fails to recover or this feature is disabled, an ArtikError.rateLimit will be thrown.
You can set ArtikCloudSwiftSettings.delegate to stay informed of various usage-related data. All methods are optional.
func maxPayload(_ size: UInt64)Called every time a response is received specifying the API's maximum accepted payload size.
func rateLimit(_ rate: APIRateLimit)Called after an API is used, informing you of the current state of your rate limit.
func organizationQuota(_ quota: APIOrganizationQuota)Called after an API is used, informing you of your remaining organization quota.
func deviceQuota(_ quota: APIDeviceQuota)Called after an API is used counting towards a device's quota.
func tokenRefreshed(_ token: UserToken)Called each time the current UserToken has been refreshed. Use this method to save the newly refreshed token if needed.
ARTIK cloud services' WebSockets are easily accesible using their respective implementations: EventsWebsocket, LiveWebsocket, and DeviceWebsocket. Once initialized, use .connect() and .disconnect() to initiate or terminate their connections. You can also make use of their delegates to react to any of their connection events, messages, etc.
NOTE: Websocket features are not available on watchOS at this time (missing access to CFNetwork String constants).
func websocketDidConnect(socket: ArtikWebsocket)Called when the socket has successfuly established a connection.
func websocketDidDisconnect(socket: ArtikWebsocket, reconnecting: Bool, error: Error?)Called when the socket has been disconnected, indicating if it was due to an error and if it is attempting to reconnect.
func websocketEncounteredError(socket: ArtikWebsocket, error: Error)Called when an error occured while performing an operation.
func websocketDidReceiveEvent(socket: EventsWebsocket, event: EventsWebsocket.EventType, uid: String?, aid: String?, did: String?, dtid: String?, ts: ArtikTimestamp)Called when the socket receives an event.
func websocketDidReceiveMessage(socket: LiveWebsocket, mid: String, data: [String:Any], sdid: String, sdtid: String?, uid: String?, ts: ArtikTimestamp)Called when the socket receives a message.
func websocketDidReceiveAction(socket: DeviceWebsocket, mid: String, data: [String:Any], ddid: String)Called when the socket receives an action for a device.
Markup documentation is available for all API methods in their respective source files.
You can also refer to our documentation.
- Users
- Devices
- Device Types
- Messages
- Monetization
- Subscriptions
- Notifications
- Rules
- Scenes
- Machine Learning
- Device Management
If you are not familiar with ARTIK cloud services, we have extensive documentation at https://developer.artik.cloud/documentation
The full ARTIK cloud services API specification can be found at https://developer.artik.cloud/documentation/api-reference/
Check out advanced sample applications at https://developer.artik.cloud/documentation/tutorials/code-samples/
To create and manage your services and devices on ARTIK cloud services, create an account at https://developer.artik.cloud
Also see the ARTIK cloud services blog for tutorials, updates, and more: http://artik.io/blog/cloud
Licensed under the Apache License. See LICENSE.
Copyright © 2017-2018 Samsung Electronics Co., Ltd.