Titanium.Cloud

The top level Cloud module.

Appcelerator Cloud Services (ACS) provides a wide array of automatically-scaled data storage and web services, such as user logins, photo uploads, checkins, status updates, and push notifications, without the need to learn multiple third-party SDKs or do any server-side programming. Remote calls to ACS are done via a single REST API, which may be used with almost any web technology that has access to an HTTP client.

The Titanium.Cloud module makes accessing ACS as simple as using any of Titanium's other APIs, due to its familiar and intuitive API schema.

For a more detailed overview of ACS and how to configure an application to use it, refer to the Integrating with Appcelerator Cloud Services and ACS Quickstart guides.

Beta ACS APIs

Be aware that ACS APIs that are in pre-release form (marked "Beta" in the ACS documentation) may be subject to change. During this period, while they are not supported directly by the Titanium.Cloud module, they may be accessed using the REST API.

Using the Titanium.Cloud Module

This module is not included in the Titanium namespace, but it is bundled with the Titanium SDK as an optional CommonJS module. To use it, import the module using require:

var Cloud = require('ti.cloud');

Authentication

Your app must prove that it is allowed to talk to ACS. This keeps your data secure by preventing anyone from making requests to ACS that impersonate your app. ACS provides several means of authentication:

• 3-Legged OAuth. With 3-legged OAuth, the user and application are authenticated at the same time. User login (or signup) is done using a separate authentication server, which returns a time-limited access token to the application. The application uses the access token to authenticate all subsequent requests.

• 2-Legged OAuth. This is a process by which a key and secret are used to sign each request made by your app. When the ACS server receives your request, the secret is used along with the data sent in the request to calculate another signature. If sent signature and calculated signature match, the request will be processed.

• API Key. In this method, the application passes a pre-provisioned API key with each request.

When using 2-Legged OAuth or API key authentication, the application presents its own UI to prompt the user for username and password. Then the application calls login or create method to authenticate the user, passing in the username and password. Once logged in, the application can store the sessionId returned by ACS in secure storage in order to persist the session when the application restarts.

When using 3-Legged OAuth, the module presents an authentication dialog to the user when secureLogin or secureCreate method is called. The user's login and password are not available to the application. The application can store the accessToken returned by the authentication server in secure storage so that it does not need to present the login dialog each time the application restarts. Unlike session IDs, however, access tokens expire after a period of time. The application owner can configure the expiration time through the ACS website.

The Ti.Cloud module does not provide a mechanism for securely storing a sessionId or accessToken; the application must provide storage that matches its security requirements.

By default, Ti.Cloud always uses SSL for communicating with the ACS servers, unless the useSecure flag is set to false.

3-Legged OAuth, using secureLogin and secureCreate is the preferred authentication method in most cases. However, if your application is using 3-Legged OAuth, all of its clients must use 3-Legged OAuth, so there may be cases where another authentication strategy is required.

tiapp.xml Properties

Titanium Studio will create a pair of keys (Development and Production) for each Titanium application depending on the user preference specified during new project creation. This pair of keys will be stored in tiapp.xml and one of the keys will be used during application build depending on the build type (development or production).

The supported properties in tiapp.xml are:

<property name="acs-api-key-development" type="string">YOUR DEVELOPMENT API KEY HERE</property>
<property name="acs-oauth-key-development" type="string">YOUR DEVELOPMENT OAUTH KEY HERE</property>
<property name="acs-oauth-secret-development" type="string">YOUR DEVELOPMENT OAUTH SECRET HERE</property>

<property name="acs-api-key-production" type="string">YOUR PRODUCTION API KEY HERE</property>
<property name="acs-oauth-key-production" type="string">YOUR PRODUCTION OAUTH KEY HERE</property>
<property name="acs-oauth-secret-production" type="string">YOUR PRODUCTION OAUTH SECRET HERE</property>

<property name="acs-api-key" type="string">YOUR API KEY HERE</property>
<property name="acs-oauth-key" type="string">YOUR OAUTH KEY HERE</property>
<property name="acs-oauth-secret" type="string">YOUR OAUTH SECRET HERE</property>

The value for each setting that will be used is based on the following rules:

• OAuth is preferred over apiKey. If both the OAuth key and OAuth secret are provided then OAuth will be used; otherwise, apiKey will be used.
• If a deployment-specific setting is provided (production or development) then that value will be used for the current deployment environment.

There is also an optional setting to allow you to change the base URL for ACS requests. You will most likely never need to specify this. It can be specified deployment-specific, or generic:

<property name="acs-base-url-development" type="string">DEVELOPMENT API URL HERE</property>
<property name="acs-base-url-production" type="string">PRODUCTION API URL HERE</property>
<property name="acs-base-url" type="string">API URL HERE</property>

<property name="acs-authbase-url-development" type="string">AUTHENTICATION URL HERE</property>
<property name="acs-authbase-url-production" type="string">AUTHENTICATION URL HERE</property>
<property name="acs-authbase-url" type="string">AUTHENTICATION URL HERE</property>

• 2.0
• 2.0
• 2.0