Titanium.Cloud

> Titanium.Cloud

The top level Cloud module for making calls to Appcelerator Cloud Services (ACS).

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 using REST APIs, which may be used with any client technology that supports HTTP.

The Titanium.Cloud module's specialized objects, such as Titanium.Cloud.Users, make accessing ACS as simple as using any of Titanium's other APIs, due to their familiar and intuitive API schemas. You can also use the sendRequest method to invoke ACS REST APIs directly. This approach requires some additional configuration for each method call, but it lets you use new ACS APIs as soon as they are available.

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

Using the Titanium.Cloud Module

The Titanium.Cloud module is bundled with the Titanium SDK as an optional CommonJS module. To use it, import the module with require('ti.cloud'), and then begin calling the methods on its various objects. For example, the following code uses the Titanium.Cloud.Users.login method to login the user with the specified login and password:

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

Cloud.Users.login({
    login: 'test@mycompany.com',
    password: 'test_password'
}, function (e) {
    if (e.success) {
        var user = e.users[0];
        alert('Success:\n' +
            'id: ' + user.id + '\n' +
            'sessionId: ' + Cloud.sessionId + '\n' +
            'first name: ' + user.first_name + '\n' +
            'last name: ' + user.last_name);
    } else {
        alert('Error:\n' +
            ((e.error && e.message) || JSON.stringify(e)));
    }
});

Invoking ACS REST APIs Directly with sendRequest()

The Titanium.Cloud.sendRequest method lets you directly invoke ACS REST APIs. The following example, equivalent to the previous one, invokes the users/login.json method directly to login a user.

Cloud.sendRequest({
    url : "users/login.json",
    method : "POST",
    data : {
        login : 'test@mycompany.com',
        password : 'test_password'
    }
}, function(e) {// The callback called when the request completes
    if (e.success) {
        var user = e.users[0];
        alert('Success:\n' + 
            'id: ' + user.id + '\n' + 
            'sessionId: ' + Cloud.sessionId + '\n' + 
            'first name: ' + user.first_name + '\n' + 
            'last name: ' + user.last_name);
    } else {
        alert('Error:\n' + ((e.error && e.message) || JSON.stringify(e)));
    }
});

tiapp.xml Properties

Studio will create a pair of API keys (Development and Production) for each Titanium application depending on the user preference specified when creating the proejct. These keys will be stored in the tiapp.xml file. One of the keys will be used during application builds depending on the build type (development or production).

The supported properties in the tiapp.xml file are:

<property name="acs-api-key-development" type="string">YOUR DEVELOPMENT API KEY HERE</property>
<property name="acs-api-key-production" type="string">YOUR PRODUCTION API KEY HERE</property>
<property name="acs-api-key" type="string">YOUR API KEY HERE</property>

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>

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>

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>

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

Cloud.useSecure = false;

  • 2.0
  • 3.3
  • 2.0
  • 2.0
  • 1.8
  • 3.1
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
  • 3.3
  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1
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
  • 3.3
  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1
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
  • 3.3
  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1
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.3
  • 3.0
  • 3.0
  • 3.0
  • 3.1

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
  • 3.3
  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1

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
  • 3.3
  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1

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
  • 3.3
  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1

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
( parameters, callback ) : void
Makes a REST API call to the ACS server. ...

Makes a REST API call to the ACS server.

This method lets you easily call ACS REST APIs directly. You provide the REST API endpoint relative to the ACS base API URL (users/login.json for example), the appropriate HTTP method type (GET, POST, or DELETE), and the data to send with the request.

As with the built-in Cloud methods, like Titanium.Cloud.Users.login, the method's callback function parameter is passed a CloudResponse object that contains meta-data about the request, and the actual response payload. If the REST method call completed successfully, CloudResponse.success is true, or false if the call failed. If CloudResponse.error is true, CloudResponse.message will contain a string that describes the error.

If the method call completed successfully, the CloudResponse object contains an additonal object for the actual response payload. The name and type of this object depends on the REST endpoint that was invoked. The ACS API documentation specifies the return type for each REST endpoint. For example, the users/login.json endpoint returns a single element array named users that contains the Users object for the logged-in user.

For example:

Cloud.sendRequest({
    url : "users/login.json",
    method : "POST",
    data : {
        login : 'test@mycompany.com',
        password : 'test_password'
    }
}, function(e) {// The callback called when the request completes
    if (e.success) {
        var user = e.users[0];
        alert('Success:\n' + 
            'id: ' + user.id + '\n' + 
            'sessionId: ' + Cloud.sessionId + '\n' + 
            'first name: ' + user.first_name + '\n' + 
            'last name: ' + user.last_name);
    } else {
        alert('Error:\n' + ((e.error && e.message) || JSON.stringify(e)));
    }
});

By default, the base URL for each REST call is the public URL (api.cloud.appcelerator.com/v1). For virtual private cloud (VPC) deployments, you can specify a different URL by modifying the acs-base-url property of your project's tiapp.xml file (see tiapp.xml Properties above).

Parameters

  • parameters : Dictionary

    A Dictionary containing the parameters to send with the request. It must contain the following key-value pairs:

    • url -- A string specifying the last fragment of the request URL.
    • method -- A string specifying the HTTP method to use: "GET", "POST", "PUT", or "DELETE".
    • data -- A Dictionary containing name-value pairs to send in the request.
  • callback : Callback<CloudResponse>

    Callback function to execute when a response is received.

Returns

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

Sets the value of the accessToken property.

  • 2.1.2
  • 3.3
  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1

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
  • 3.3
  • 2.1.2
  • 2.1.2
  • 2.1.2
  • 3.1

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