Would you like to contribute to the Titanium docs? To get started, sign up for an account on the Appcelerator Wiki and sign our CLA.

Skip to end of metadata
Go to start of metadata


Appcelerator Dashboard can associate  API Builder applications with client applications. This lets you see, for example, what  API Builder applications a given application is using, or which service methods are being used the most.

For this correlation to occur, the application must include a custom HTTP header named x-native-id in each  API Builder application method call it makes. The value of this header must be set to the GUID assigned to the application when you initially created it. The GUID for an existing iOS or Android application can be found on the Overview tab in Dashboard, as shown below.

By default,  API Builder applications are automatically associated with applications built with Titanium.  You only need to add the x-native-id HTTP header to other applications not built with Titanium.

The following sections provide common approaches to adding custom HTTP headers to your iOS and Android network requests using well-known HTTP client libraries and frameworks.

Adding a custom HTTP header on iOS

The NSMutableURLRequest class provides the following helper methods for setting HTTP headers:

  • addValue:(NSString \*)value forHTTPHeaderField:(NSString *)
  • setValue:(NSString \*)value forHTTPHeaderField:(NSString *)
  • setAllHTTPHeaderFields:(NSDictionary *)

For example, the following uses the addValue method to add the x-native-id header to a request object: 

If you are using the CFNetwork framework, you can use the CFHTTPMessageSetHeaderFieldValue method of the CFHTTPMessage class. See the code listing in Creating a CFHTTP Request in the CFNetwork Programming Guide for an example of this approach.

Adding a custom HTTP custom header on Android

If you are using URLConnection, or any of its subclasses (HttpUrlConnectionHttpsURLConnection), you can use its addRequestProperty(String field, String new Value) method to add the HTTP header. The following example demonstrates adding the x-native-id header using this method: 

If your application uses the Apache Stack (org.apache.http namespace), the addHeader(java.lang.String, java.lang.String) is available to all classes that extend AbstractHttpMessage. The following example demonstrates adding the x-native-id header using this method: 


This section shows how to create a new  API Builder application and associate it with an iOS or Android application. Before you continue:

To create a new API Builder application, you call the appc cloud new sub-command followed by the application name. If you are a member of more than one Appcelerator Platform organization, you are prompted to select the desired organization in which to create the application. (If you belong to only one organization, you will not see this prompt.)

This creates a basic API Builder application with a single endpoint. To publish the application to ACS, cd to the newly created project and call acs publish

The output of the appc cloud publish command includes the URL where the application will be available: 


You can also find this URL on the Overview tab in Dashboard for your iOS or Android application (see above).

Add the application URL to your network call. For example, on iOS: 

Or, on Android: 

Viewing Custom Services in Dashboard

Once your application has made an API Builder application request, you can use Dashboard to view the association between the application and the service. You can see which custom services are being used by a specific application, get memory usage and CPU load data for each service, as well as view logs and metrics for individual service calls, such as response time, container ID, and IP addresses of connecting clients.

To view the custom services being used by an application in Dashboard:

  1. Select the application from the Dashboard apps menu.
  2. Select API Builder to view a table of custom API Builder applications used by the application.

  3. Select an API Builder application to view more details about the service.