The top level Cloud module for making calls to ArrowDB and Arrow Push.
Appcelerator DB and Arrow Push 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 ArrowDB are done using REST APIs, which may be used with any client technology that supports HTTP.
The Cloud module's specialized objects, such as Users, make accessing
ArrowDB 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
ArrowDB REST APIs directly. This approach requires some additional configuration for each method call,
but it lets you use new ArrowDB APIs as soon as they are available.
For a more detailed overview of ArrowDB and how to configure an application to use it, refer to the Integrating with Appcelerator Cloud Services.
The Modules.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 Modules.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)));
}
});
The Modules.Cloud.sendRequest method lets you directly invoke ArrowDB 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)));
}
});
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 ArrowDB 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 ArrowDB 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>
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;
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 Modules.Cloud.Users.secureCreate or Modules.Cloud.Users.secureLogin, and null after successfully calling Modules.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 ArrowDB 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.
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.
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
Indicates whether internal debug logging should be output to the console.
Default: false
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 Modules.Cloud.Users.secureCreate or Modules.Cloud.Users.secureLogin, and null after successfully calling Modules.Cloud.Users.logout.
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.
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 ArrowDB method for which you want to track the transmission.
When you are done tracking the transmission, set this to null.
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 ArrowDB method for which you want to track the transmission.
When you are done tracking the transmission, set this to null.
Identifies the current session
Identifies the current session
Contains the session identifier after successfully calling Modules.Cloud.Users.create or Modules.Cloud.Users.login, and null after successfully calling Modules.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 ArrowDB 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.
Indicates whether to use SSL when sending requests to ArrowDB.
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
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.
A dictionary of properties to apply.
creates a security manager to authenticate specified HTTPS URLs.
This feature requires a Team or Enterprise subscription!
This feature requires the https module!
Authenticates a set of HTTPS servers by pinning an HTTPS server's URL to its
public key contained in the certificate.
The security manager will guarantee that all HTTPClient connections to this URL
are to a server that holds the private key corresponding to the public key embedded in the
certificate, therefore authenticating the server and preventing man-in-the-middle attacks.
By default, the base URL for each call in Modules.Cloud is the public URL (api.cloud.appcelerator.com).
So to use this feature by default, you will need to get api.cloud.appcelerator.der by simply executing these
2 commands:
echo -n | openssl s_client -connect api.cloud.appcelerator.com:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > api.cloud.appcelerator.com.crt openssl x509 -in api.cloud.appcelerator.com.crt -outform der -out api.cloud.appcelerator.com.der
For virtual private cloud (VPC) deployments, you can specify a different URL. After generating the X509 certifcate file in der format, you have to place it in the Resources folder in your titanium project. Before making any Cloud request, it is important to create security manager first, as shown:
Cloud.createX509CertificatePinningSecurityManager([ { url: "https://api.cloud.appcelerator.com", serverCertificate: "api.cloud.appcelerator.com.der" } ]);
Server URLs with the corresponding certificate to authenticate, specified as an array of dictionaries that must contain the following keys:
url: HTTPS URL pinned to the public key in the server certificateserverCertificate: X.509 certificate file in DER binary formatGets the value of the useSecure property.
This method 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>
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 Modules.Cloud.Users.create or Modules.Cloud.Users.login, and false after successfully calling Modules.Cloud.Users.logout.
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 Modules.Cloud.Users.create or Modules.Cloud.Users.login, and null after successfully calling Modules.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 ArrowDB servers using Titanium.Network.HTTPClient.
Makes a REST API call to the ArrowDB server.
This method lets you easily call ArrowDB REST APIs directly. You provide the REST API endpoint
relative to the ArrowDB 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 Modules.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 ArrowDB and Push 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).
A Dictionary containing the parameters to send with the request. It must contain the following key-value pairs:
Callback function to execute when a response is received.
Sets the value of the accessToken property.
New value for the property.
Sets the value of the bubbleParent property.
New value for the property.
Sets the value of the debug property.
New value for the property.
Sets the value of the lifecycleContainer property.
New value for the property.
Sets the value of the ondatastream property.
New value for the property.
Sets the value of the onsendstream property.
New value for the property.
Sets the value of the sessionId property.
New value for the property.
Sets the value of the useSecure property.
This method 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>
New value for the property.