Titanium 3.X

Titanium.Cloud

> 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.

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:

  • apiKey is preferred over OAuth. If apiKey is provided then apiKey will be used; otherwise, OAuth 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>

By default, Ti.Cloud always uses SSL for communicating with the ACS servers. This behavior can be overridden by setting the URLs with their non-SSL counterpart.

<property name="acs-base-url" type="string">http://api.cloud.appcelerator.com</property>
<property name="acs-authbase-url" type="string">http://secure-identity.cloud.appcelerator.com</property>

Pre 3.1.1 Release behavior

Before Release 3.1.1 specify URLs without the protocol:

<property name="acs-base-url" type="string">api.cloud.appcelerator.com</property>
<property name="acs-authbase-url" type="string">secure-identity.cloud.appcelerator.com</property>

To disable SSL, add this line to the application code:

Cloud.useSecure = false;

  • 2.0
  • 2.0
  • 2.0
  • 3.1.2
Defined By

Properties

Titanium.Cloud
accessToken : String

Identifies the current access token when using 3-Legged OAuth

Identifies the current access token when using 3-Legged OAuth

Contains the access token after successfully calling Titanium.Cloud.Users.secureCreate or Titanium.Cloud.Users.secureLogin, and null after successfully calling Titanium.Cloud.Users.logout.

All calls made using the Cloud module automatically use this value and, thus, it only needs to be used when manually making calls to the ACS servers using Titanium.Network.HTTPClient.

The accessToken is not persisted across application sessions by the module. An application can persist the accessToken by saving the value in secure storage and restoring the value of this property in the next application session.

The accessToken is not used with 2-legged OAuth or API key authentication; use sessionId instead.

  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1.2
apiName : Stringreadonly

The name of the API that this proxy corresponds to.

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Button returns Ti.UI.Button.

  • 3.2
  • 3.2
  • 3.2
  • 3.2
  • 3.2
  • 3.2
Indicates if the proxy will bubble an event to its parent. ...

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

  • 3.0
  • 3.0
  • 3.0
Titanium.Cloud
: Boolean
Indicates whether internal debug logging should be output to the console. ...

Indicates whether internal debug logging should be output to the console.

Default: false

Titanium.Cloud
expiresIn : Numberreadonly

Indicates the number of seconds before the access token expires

Indicates the number of seconds before the access token expires

Contains the number of seconds until the access token expires after successfully calling Titanium.Cloud.Users.secureCreate or Titanium.Cloud.Users.secureLogin, and null after successfully calling Titanium.Cloud.Users.logout.

  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1.2
Titanium.Cloud
ondatastream : Callback<CloudStreamProgress>

Function to be called at regular intervals as the request data is being received.

Function to be called at regular intervals as the request data is being received.

Set this property before calling any ACS method for which you want to track the transmission.

When you are done tracking the transmission, set this to null.

Titanium.Cloud
onsendstream : Callback<CloudStreamProgress>

Function to be called at regular intervals as the request data is being transmitted.

Function to be called at regular intervals as the request data is being transmitted.

Set this property before calling any ACS method for which you want to track the transmission.

When you are done tracking the transmission, set this to null.

Titanium.Cloud
sessionId : String

Identifies the current session

Identifies the current session

Contains the session identifier after successfully calling Titanium.Cloud.Users.create or Titanium.Cloud.Users.login, and null after successfully calling Titanium.Cloud.Users.logout.

All calls made using the Cloud module automatically use this value and, thus, it only needs to be used when manually making calls to the ACS servers using Titanium.Network.HTTPClient.

The session identifier is not persisted across application sessions by the module. An application can persist the session identifier by saving the value in secure storage and restoring the value of this property in the next application session.

The sessionId is not used with 3-legged OAuth authentication; use accessToken instead.

  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1.2
Titanium.Cloud
: Booleanremoved
Indicates whether to use SSL when sending requests to ACS. ...

Indicates whether to use SSL when sending requests to ACS.

This property has been removed

3.1.1

To disable SSL, set the acs-base-url and acs-authbase-url properties in the tiapp.xml using the HTTP URL. To enable SSL, use the HTTPS URL.

<property name="acs-base-url" type="string">http://api.cloud.appcelerator.com</property>

Default: true

Defined By

Methods

Applies the properties to the proxy. ...

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

  • 3.0
  • 3.0
  • 3.0

Parameters

  • props : Dictionary

    A dictionary of properties to apply.

Returns

  • void
Titanium.Cloud
( ) : String
Gets the value of the accessToken property. ...

Gets the value of the accessToken property.

  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1.2

Returns

  • String
Gets the value of the apiName property. ...

Gets the value of the apiName property.

  • 3.2
  • 3.2
  • 3.2
  • 3.2
  • 3.2
  • 3.2

Returns

  • String
Gets the value of the bubbleParent property. ...

Gets the value of the bubbleParent property.

  • 3.0
  • 3.0
  • 3.0

Returns

  • Boolean
Titanium.Cloud
( ) : Boolean
Gets the value of the debug property. ...

Gets the value of the debug property.

Returns

  • Boolean
Titanium.Cloud
( ) : Number
Gets the value of the expiresIn property. ...

Gets the value of the expiresIn property.

  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1.2

Returns

  • Number
Titanium.Cloud
( ) : Callback<CloudStreamProgress>
Gets the value of the ondatastream property. ...

Gets the value of the ondatastream property.

Returns

Titanium.Cloud
( ) : Callback<CloudStreamProgress>
Gets the value of the onsendstream property. ...

Gets the value of the onsendstream property.

Returns

Titanium.Cloud
( ) : String
Gets the value of the sessionId property. ...

Gets the value of the sessionId property.

  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1.2

Returns

  • String
Titanium.Cloud
( ) : Booleanremoved
Gets the value of the useSecure property. ...

Gets the value of the useSecure property.

This method has been removed since 3.1.1

Returns

  • Boolean
Titanium.Cloud
( ) : Booleandeprecated
Checks if there is a stored user session. ...

Checks if there is a stored user session.

deprecated since 2.1.2

See accessToken and sessionId for details on persisting session data.

True is returned after successfully calling Titanium.Cloud.Users.create or Titanium.Cloud.Users.login, and false after successfully calling Titanium.Cloud.Users.logout.

Returns

  • Boolean
Titanium.Cloud
( ) : Stringdeprecated
Returns the stored user session identifier. ...

Returns the stored user session identifier.

deprecated since 2.1.2

See accessToken and sessionId for details on persisting session data.

A value is returned after successfully calling Titanium.Cloud.Users.create or Titanium.Cloud.Users.login, and null after successfully calling Titanium.Cloud.Users.logout.

All calls made using the Cloud module automatically use this value and, thus, it only needs to be used when manually making calls to the ACS servers using Titanium.Network.HTTPClient.

Returns

  • String
Titanium.Cloud
( accessToken ) : void
Sets the value of the accessToken property. ...

Sets the value of the accessToken property.

  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1.2

Parameters

  • accessToken : String

    New value for the property.

Returns

  • void
( bubbleParent ) : void
Sets the value of the bubbleParent property. ...

Sets the value of the bubbleParent property.

  • 3.0
  • 3.0
  • 3.0

Parameters

  • bubbleParent : Boolean

    New value for the property.

Returns

  • void
Titanium.Cloud
( debug ) : void
Sets the value of the debug property. ...

Sets the value of the debug property.

Parameters

  • debug : Boolean

    New value for the property.

Returns

  • void
Titanium.Cloud
( ondatastream ) : void
Sets the value of the ondatastream property. ...

Sets the value of the ondatastream property.

Parameters

Returns

  • void
Titanium.Cloud
( onsendstream ) : void
Sets the value of the onsendstream property. ...

Sets the value of the onsendstream property.

Parameters

Returns

  • void
Titanium.Cloud
( sessionId ) : void
Sets the value of the sessionId property. ...

Sets the value of the sessionId property.

  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1.2

Parameters

  • sessionId : String

    New value for the property.

Returns

  • void
Titanium.Cloud
( useSecure ) : voidremoved
Sets the value of the useSecure property. ...

Sets the value of the useSecure property.

This method has been removed since 3.1.1

Parameters

  • useSecure : Boolean

    New value for the property.

Returns

  • void