# Titanium.Network

The top level network module.

Availability
0.8
0.8
9.2.0

# Overview

The Network module is used to access networking related functionality.

For TCP sockets, see Titanium.Network.Socket.TCP.

The legacy Titanium.Network.TCPSocket object is still required by the Titanium.Network.BonjourBrowser and Titanium.Network.BonjourService objects.

For all other socket needs, use Titanium.Network.Socket.TCP.

# App Transport Security

Starting with iOS 9, Apple introduced new security and compatibility guidelines for networking and connectivity, which include:

  • All connections must support TLS 1.2 or greater, and use forward secrecy ciphers supported by iOS
  • Certificates must use at least a SHA-256 fingerprint with either a 2048-bit or greater RSA key, or a 256-bit or greater ECC key
  • Application must be compatible with IPv6 DNS64/NAT64 networks as part of App Store submissions

Because of the new requirements, Titanium disables the App Transport Security (ATS) requirements, which only includes the TLS and certificate cipher requirements, to allow all connections by default.

If you wish to re-enable ATS, add the NSAppTransportSecurity dict to the ios plist section of the tiapp.xml file, then add the NSAllowArbitraryLoads key and set it to false, indicating that you want to manage your whitelisted URL's yourself.

<ti:app>
  <!-- ... -->
  <ios>
    <plist>
      <dict>
        <key>NSAppTransportSecurity</key>
        <dict>
          <key>NSAllowsArbitraryLoads</key>
          <false/>
        </dict>
      </dict>
    </plist>
  </ios>
  <!-- ... -->
</ti:app>

Listed below are other guidelines from Apple.

Avoid hard-coded IPv4 address literals

Try not to include hard-coded IPv4 address literals in your application, for example, 127.0.0.1.

Whitelist URLs

If ATS is enabled and the web service you are trying to contact does not support the new security guidelines, iOS will not allow you to connect to the service. An error will be returned in the network response stating the connection failed because it did not meet the ATS policy standards.

To allow the connection, you will need to add a NSAppTransportSecurity dict to the ios plist section of the tiapp.xml file. In the NSAppTransportSecurity dict, you add the NSExceptionDomains dict to whitelist specific domains.

For more information, see iOS Developer Library: App Transport Security (opens new window).

Example:

<ti:app>
  <!-- ... -->
  <ios>
    <plist>
      <dict>
        <key>NSAppTransportSecurity</key>
        <dict>
          <!-- 1) Default: Disable ATS completely -->
          <key>NSAllowsArbitraryLoads</key>
          <true/>

          <-- 2) Alternative: Define whitelisted domains -->
          <key>NSExceptionDomains</key>
          <dict>
            <!-- Loosen security measure for www.foo.com domain -->
            <key>www.foo.com</key>
            <dict>
              <!-- Set TLS v1.0 as the minimum TLS version -->
              <key>NSExceptionMinimumTLSVersion</key>
              <string>TLSv1.0</string>
              <!-- Can use other ciphers besides forward secrecy ciphers -->
              <key>NSExceptionRequiresForwardSecrecy</key>
              <false/>
              <!-- Allow HTTP connections -->
              <key>NSExceptionAllowsInsecureHTTPLoads</key>
              <true/>
            </dict>
          </dict>
        </dict>
      </dict>
    </plist>
  </ios>
  <!-- ... -->
</ti:app>

Test IPV6 DNS64/NAT64

If you submit your application to the iTunes Store, you should setup an IPv6 DNS64/NAT64 network to test your application to verify it is compatible with IPv6.

If you are running macOS 10.11 or greater, you can use your computer to setup a local IPv6 Wi-Fi network, which requires an Internet connection not through Wi-Fi.

To create the network, from System Preferences, enable Internet sharing with NAT64 network enabled to share your Wi-Fi connection.

For detailed instructions, see Mac Developer Library: Test for IPv6 DNS64/NAT64 Compatibility (opens new window).

# Properties

# allHTTPCookies READONLY

Availability
3.3.0
9.2.0
allHTTPCookies :Array<Titanium.Network.Cookie>

A list of all cookies in the cookie storage.


# apiName READONLY

Availability
3.2.0
3.2.0
9.2.0
apiName :String

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, Titanium.UI.Button returns Ti.UI.Button.


# bubbleParent

Availability
3.0.0
3.0.0
9.2.0
bubbleParent :Boolean

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


# lifecycleContainer

Availability
3.6.0

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.


# networkType READONLY

Availability
0.8
0.8
9.2.0
networkType :Number

Network type value as a constant.

One of the NETWORK constants defined in Titanium.Network.


# networkTypeName READONLY

Availability
0.8
0.8
9.2.0
networkTypeName :String

Network type as a String. Returns one of NONE, WIFI, LAN, MOBILE, or UNKNOWN.


# online READONLY

Availability
0.8
0.8
9.2.0
online :Boolean

Boolean value indicating if the device is connected to the network.

The online property is true if the device has network access via WiFi, LAN, or mobile/cellular network.

Note that if the device is connected to a private network without Internet access, then this property will be true as well. This means you cannot assume the device has Internet access if it's connected to the network.


# remoteDeviceUUID READONLY

Availability
0.8
9.2.0
remoteDeviceUUID :String

Remote device UUID if the device is registered with the Apple Push Notification Service, or null if it is not registered.


# remoteNotificationsEnabled READONLY

Availability
12.0.0
3.3.0
9.2.0
remoteNotificationsEnabled :Boolean

Indicates whether push notifications have been enabled using registerForPushNotifications.


# remoteNotificationTypes READONLY

Availability
0.8
9.2.0
remoteNotificationTypes :Array<Number>

Array of push notification type constants enabled for the application.

# Methods

# addEventListener

Availability
0.8
0.8
9.2.0
addEventListener(name, callback) void

Adds the specified callback as an event listener for the named event.

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to invoke when the event is fired.

Returns

Type
void

# addHTTPCookie

Availability
3.2.0
3.3.0
9.2.0
addHTTPCookie(cookie) void

Adds a cookie to the HTTP client cookie store.

On iOS, the cookie will override an existing cookie with the same name, domain and path, if any. The cookie's expiryDate property must be a date later than the creating date, otherwise the cookie will not persist in the cookie storage. On Android, any existing cookie with the same domain and name will be replaced with the new cookie. This is a bug in BasicCookieStore because based on RFC6265, an existing cookie can be evicted and replaced only when it has the same cookie-name, domain-value and path-value with the new cookie.

Parameters

Name Type Description
cookie Titanium.Network.Cookie

The cookie to add

Returns

Type
void

# addSystemCookie

Availability
3.2.0
addSystemCookie(cookie) void

Adds a cookie to the system cookie store.

On Android, Titanium.UI.WebView uses the system cookie store. Any existing cookie with the same domain, path and name will be replaced with the new cookie.

Parameters

Name Type Description
cookie Titanium.Network.Cookie

The cookie to add

Returns

Type
void

# applyProperties

Availability
3.0.0
3.0.0
9.2.0
applyProperties(props) void

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.

Parameters

Name Type Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# createBonjourBrowser

Availability
0.8
9.2.0
createBonjourBrowser(serviceType, domain[, parameters]) Titanium.Network.BonjourBrowser

Creates and returns a BonjourBrowser object.

Parameters

Name Type Description
serviceType String

Service to search for, must include the protocol type suffix (._tcp).

domain String

Bonjour service domain to conduct the search in.

parameters Dictionary<Titanium.Network.BonjourBrowser>

A dictionary object of properties defined in Titanium.Network.BonjourBrowser.

Returns


# createBonjourService

Availability
0.8
9.2.0
createBonjourService(name, type, domain[, parameters]) Titanium.Network.BonjourService

Creates and returns a BonjourService object.

Parameters

Name Type Description
name String

Name of the service. Must be a unique identifier for this service type and domain.

type String

Type of service. Must include the protocol identifier (._tcp).

domain String

Domain to publish the service in.

parameters Dictionary<Titanium.Network.BonjourService>

Dictionary object of properties defined in Titanium.Network.BonjourService.

Returns


# createCookie

Availability
3.2.0
3.3.0
9.2.0
createCookie([parameters]) Titanium.Network.Cookie

Creates and returns an instance of Titanium.Network.Cookie.

Parameters

Name Type Description
parameters Dictionary<Titanium.Network.Cookie>

Properties to set on a new object, including any defined by Titanium.Network.Cookie except those marked not-creation or read-only.

Returns


# createHTTPClient

Availability
0.8
0.8
9.2.0
createHTTPClient([parameters]) Titanium.Network.HTTPClient

Creates and returns an instance of Titanium.Network.HTTPClient.

Parameters

Name Type Description
parameters Dictionary<Titanium.Network.HTTPClient>

Properties to set on a new object, including any defined by Titanium.Network.HTTPClient except those marked not-creation or read-only.

Returns


# createTCPSocket DEPRECATED

Availability
1.2.0
createTCPSocket([parameters]) Titanium.Network.TCPSocket

DEPRECATED SINCE 1.7.0

Use Titanium.Network.Socket.TCP where possible.

Creates and returns an instance of Titanium.Network.TCPSocket.

Parameters

Name Type Description
parameters Dictionary<Titanium.Network.TCPSocket>

Properties to set on a new object, including any defined by Titanium.Network.TCPSocket except those marked not-creation or read-only.

Returns


# decodeURIComponent

Availability
0.8
0.8
9.2.0
decodeURIComponent(value) String

Returns a decoded version of a URI encoded value.

Parameters

Name Type Description
value String

URI encoded input value to be decoded.

Returns

Type
String

# encodeURIComponent

Availability
0.8
0.8
9.2.0
encodeURIComponent(value) String

Returns a URI encoded version of the specified URI component.

On iOS, this also escapes the following characters, which are allowed in a URL but may not be allowed or desirable inside a path component:

!*'();:@+$,/?%#[]=&

Parameters

Name Type Description
value String

Input value to be encoded.

Returns

Type
String

# fireEvent

Availability
0.8
0.8
9.2.0
fireEvent(name[, event]) void

Fires a synthesized event to any registered listeners.

Parameters

Name Type Description
name String

Name of the event.

event Dictionary

A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type
void

# getHTTPCookies

Availability
3.2.0
3.3.0
9.2.0
getHTTPCookies(domain, path, name) Array<Titanium.Network.Cookie>

Gets all the cookies with the domain, path and name matched with the given values from the HTTP client cookie store.

The domain matching and path matching follow RFC6265. If name is null, return all the cookies with the domain and path matched.

Parameters

Name Type Description
domain String

The domain of the cookie to get. It is case-insensitive.

path String

The path of the cookie to get. It is case-sensitive.

name String

The name of the cookie to get. It is case-sensitive.

Returns


# getHTTPCookiesForDomain

Availability
3.2.0
3.3.0
9.2.0
getHTTPCookiesForDomain(domain) Array<Titanium.Network.Cookie>

Gets all the cookies with the domain matched with the given values from the HTTP client cookie store.

The domain matching follows RFC6265.

Parameters

Name Type Description
domain String

The domain of the cookie to get. It is case-insensitive.

Returns


# getSystemCookies

Availability
3.2.0
getSystemCookies(domain, path, name) Array<Titanium.Network.Cookie>

Gets all the cookies with the domain, path and name matched with the given values from the system cookie store.

On Android, Titanium.UI.WebView uses the system cookie store. The domain matching and path matching follow RFC6265. If name is null, return all the cookies with the domain and path matched. The returned cookies only have their name and value properties returned.

Parameters

Name Type Description
domain String

The domain of the cookie to get. It is case-insensitive.

path String

The path of the cookie to get. It is case-sensitive.

name String

The name of the cookie to get. It is case-sensitive.

Returns


# registerForPushNotifications

Availability
0.8
0.8
9.2.0
registerForPushNotifications(config) void

Registers for push notifications with the Apple Push Notification Service.

Call this method to allow remote push notifications. It should usually be called on application start.

iOS Notes: Before calling this method, the application needs to call the registerUserNotificationSettings method and pass it the notification types to use. Setting the notification types with this method will have no effect and throws a warning.

Android Notes: Make sure to also add the <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/> permission in the <manifest> tag of your tiapp.xml. Example:

const win = Ti.UI.createWindow();
win.addEventListener("open", function() {
  console.log("Is enabled", Ti.Network.remoteNotificationsEnabled);

  Ti.Network.registerForPushNotifications({
    success: (e) => {
      console.log("success", e);
    },
    error: (e) => {
       console.log("error", e);
    }
  });
});
win.open();

The permission request will only be shown twice. After that it won't show up again and the user has to go to the app permissions to enable it.

Parameters

Name Type Description
config PushNotificationConfig

Dictionary specifying push-notification related options.

Returns

Type
void

# removeAllHTTPCookies

Availability
3.2.0
3.3.0
9.2.0
removeAllHTTPCookies() void

Removes all the cookies from the HTTP client cookie store.

Returns

Type
void

# removeAllSystemCookies

Availability
3.2.0
removeAllSystemCookies() void

Removes all the cookie from the system client cookie store.

On Android, Titanium.UI.WebView uses the system cookie store.

Returns

Type
void

# removeEventListener

Availability
0.8
0.8
9.2.0
removeEventListener(name, callback) void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

Returns

Type
void

# removeHTTPCookie

Availability
3.2.0
3.3.0
9.2.0
removeHTTPCookie(domain, path, name) void

Removes the cookie with the domain, path and name exactly the same as the given values from the HTTP client cookie store.

Parameters

Name Type Description
domain String

The domain of the cookie to remove. It is case-insensitive.

path String

The path of the cookie to remove. It is case-sensitive.

name String

The name of the cookie to remove. It is case-sensitive.

Returns

Type
void

# removeHTTPCookiesForDomain

Availability
3.2.0
3.3.0
9.2.0
removeHTTPCookiesForDomain(domain) void

Removes the cookies with the domain matched with the given values from the HTTP client cookie store.

The domain matching follows RFC6265.

Parameters

Name Type Description
domain String

The domain of the cookie to remove. It is case-insensitive.

Returns

Type
void

# removeSystemCookie

Availability
3.2.0
removeSystemCookie(domain, path, name) void

Removes the cookie with the domain, path and name exactly the same as the given values from the system cookie store.

On Android, Titanium.UI.WebView uses the system cookie store.

Parameters

Name Type Description
domain String

The domain of the cookie to remove. It is case-insensitive.

path String

The path of the cookie to remove. It is case-sensitive.

name String

The name of the cookie to remove. It is case-sensitive.

Returns

Type
void

# unregisterForPushNotifications

Availability
0.8
0.8
9.2.0
unregisterForPushNotifications() void

Unregisters the application for push notifications.

Per Apple's documentation, it is rarely necessary to call this method. See: unregisterForRemoteNotifications in the UIApplication Class Reference

For example, calling this method would be required if a new version of your application no longer supports push notifications.

Returns

Type
void

# Events

# change

Availability
0.8
0.8
9.2.0

Fired when network connectivity changes.

Properties

Name Type Description
networkTypeName String

New network type as a string.

online Boolean

Boolean indicating if the device is connected to the network.

networkType Number

New network type

reason String

Human-readable text describing the reason for the change.

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

# Constants

# NETWORK_LAN

Availability
0.8
0.8
9.2.0
NETWORK_LAN :Number

A networkType value indicating that the device is communicating over a local-area network.

This constant is also a possible value for the networkType property of the change event.


# NETWORK_MOBILE

Availability
0.8
0.8
9.2.0
NETWORK_MOBILE :Number

A networkType value indicating that the device is communicating over a mobile network.

This constant is also a possible value for the networkType property of the change event.


# NETWORK_NONE

Availability
0.8
0.8
9.2.0
NETWORK_NONE :Number

A networkType value indicating that no network is available.

This constant is also a possible value for the networkType property of the change event.


# NETWORK_UNKNOWN

Availability
0.8
0.8
9.2.0
NETWORK_UNKNOWN :Number

A networkType value indicating that the current network type is unknown.

This constant is also a possible value for the networkType property of the change event.


# NETWORK_WIFI

Availability
0.8
0.8
9.2.0
NETWORK_WIFI :Number

A networkType value indicating that the device is communicating over a WiFi network.

This constant is also a possible value for the networkType property of the change event.


# NOTIFICATION_TYPE_ALERT

Availability
0.8
9.2.0
NOTIFICATION_TYPE_ALERT :Number

Constant value for an Alert style push notification.


# NOTIFICATION_TYPE_BADGE

Availability
0.8
9.2.0
NOTIFICATION_TYPE_BADGE :Number

Constant value for a Badge style push notification.


# NOTIFICATION_TYPE_NEWSSTAND

Availability
0.8
9.2.0
NOTIFICATION_TYPE_NEWSSTAND :Number

Constant value for a Newsstand style push notification. Only available on iOS5 and later


# NOTIFICATION_TYPE_SOUND

Availability
0.8
9.2.0
NOTIFICATION_TYPE_SOUND :Number

Constant value for a Sound style push notification.


# PROGRESS_UNKNOWN

Availability
3.5.0
3.5.0
9.2.0
PROGRESS_UNKNOWN :Number

Constant value specifying that the progress of a download can not be calculated.


# TLS_VERSION_1_0

Availability
3.6.0
1.8.0.1
9.2.0
TLS_VERSION_1_0 :Number

Constant value specifying TLS version 1.0 for SSL.


# TLS_VERSION_1_1

Availability
3.6.0
1.8.0.1
9.2.0
TLS_VERSION_1_1 :Number

Constant value specifying TLS version 1.1 for SSL.


# TLS_VERSION_1_2

Availability
3.6.0
1.8.0.1
9.2.0
TLS_VERSION_1_2 :Number

Constant value specifying TLS version 1.2 for SSL.


# TLS_VERSION_1_3

Availability
8.3.0
8.3.0
9.2.0
TLS_VERSION_1_3 :Number

Constant value specifying TLS version 1.3 for SSL.