ThingWorx Edge iOS SDK
  
ThingWorx Edge iOS SDK
The ThingWorx iOS SDK provides a lightweight, but fully functional, implementation of the ThingWorx AlwaysOn protocol. Designed to minimize memory footprint, the SDK makes it easy to integrate client applications with the ThingWorx platform. The goal of the SDK is to make it simple to connect any iOS mobile devices to the ThingWorx platform.
Built on top of the C SDK, the iOS SDK is at feature parity with the C SDK, with the exception of tunneling. Tunneling is not supported.
Purpose
The iOS SDK allows you to create an application that communicates with the ThingWorx platform. The SDK uses the AlwaysOn Websockets protocol for communication. This protocol allows persistent websocket connections that can operate through a firewall. The persistence enables two-way, low latency communication between the device and server.
The SDK supports the concepts of a Virtual Thing, remote properties, services, and events that correspond to the characteristics of a Remote Thing that is defined on the ThingWorx platform.
The primary purpose of the SDK follows:
To make it easy to establish and manage a secure, AlwaysOn connection with a ThingWorx platform.
To enable simple programmatic interaction with entities running on the ThingWorx platform, including the properties, services, and events that are exposed by Remote Things created on a ThingWorx platform.
\
To provide an abstraction layer and the infrastructure for developers to expose remote properties and services to the ThingWorx platform.
Prerequisites
The iOS documentation assumes that you have had basic ThingWorx training and that you are comfortable with iOS developments tools. The SDK is written in Objective C and can easily be imported into the XCode IDE to develop a client application. All examples provided with the SDK are written in Objective C.
It is also assumed that you are familiar with the development and runtime lifecycle for mobile applications. Typically mobile applications run on devices with limited resources, such as restricted battery power. The lifecycle of such an application and device is very different from applications that run on Windows machines or on Macintosh computers. It is important to be aware of this when building an application.
Contents of the SDK Bundle
The iOS SDK bundle contains a pre-configured, working example, called SteamSensor. The complete project for this example is provided. The bundle also includes API documentation (ThingWorxSDK.docset), which is compatible with XCode. The .framework file of the package contains all the SDK binaries. You import .framework into your XCode project to build an application. The version of the SDK can be found in the text file, version.txt.
The distribution bundle for the iOS SDK contains a quick-start document and API documentation. You can install the API documentation in your XCode environment and view it from there. To install the SDK documentation you need to copy ThingWorxSDK.docset to the directory, Library/Developer/Shared/Documentation/DocSets, on your system. Once you have copied ThingWorxSDK.docset, you can select Help > Documentation & API Reference in XCode.
Getting Started
It is easy to get up and going with the iOS SDK. If you have not already, refer to the quick-start document in the bundle. Keep in mind that after you create a project, you must take the following steps to create a ThingWorx iOS application. For more detailed instructions, launch the index.html file that is located in the <name_of_SDK_distribution_file>/ThingWorxSDK.docset/Contents/Resources/Documents subdirectory of the iOS SDK installation. The Quick Start section provides more details.
1. Import the .framework file by expanding the Frameworks folder in the project navigator. You can drag and drop the .framework file from the file system onto the Frameworks folder in your XCode project.
2. Add the linker flag, -ObjC, to the project.
* 
It is very important that you add this flag because it allows you to load the extensions used in the SDK. If you do not, the project will compile and build. However, when you try to run it, you will get errors, such as Cannot load NSString or some other base Foundation class. While the NSString class is a base foundation class, the application is trying to load an extension that the SDK has added to the class.
Remote Things in Composer
Before a client application can connect to the ThingWorx platform, a corresponding “RemoteThing” must exist on the platform. Use ThingWorx Composer to create the Remote Thing. Refer to the help for Composer for instructions.
As part of configuring a Remote Thing, you can assign permissions to services (design time and run time). The Subscribed Property Manager of the SDK calls two services that are not automatically assigned the same permissions as all other services. These services are GetEventSubscription and GetPropertySubscription. The Subscribed Properties Manager calls them every 60 seconds (by default). To assign permissions to these services (and avoid the error, Not authorized for ServiceInvoke), use the following Javascript code:
var params = {
principal: "TestUser" /* STRING */,
allow: true /* BOOLEAN */,
principalType: "User" /* STRING */,
resource: "GetEventSubscriptions" /* STRING */,
type: "ServiceInvoke" /* STRING */
};
me.AddRunTimePermission(params);

var params = {
principal: "TestUser" /* STRING */,
allow: true /* BOOLEAN */,
principalType: "User" /* STRING */,
resource: "GetPropertySubscriptions" /* STRING */,
type: "ServiceInvoke" /* STRING */
};
me.AddRunTimePermission(params);