# Titanium.Network
> The top level network module.
- Source: https://titaniumsdk.com/docs/sdk/12.6.2/Titanium.Network
- Titanium SDK version: 12.6.2
- Kind: module
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 0.1
- Extends: Titanium.Module
- Inheritance: Titanium.Module > Titanium.Proxy
The `Network` module is used to access networking related functionality.
For TCP sockets, see [Titanium.Network.Socket.TCP](https://titaniumsdk.com/docs/sdk/Titanium.Network.Socket.TCP.md).
The legacy [Titanium.Network.TCPSocket](https://titaniumsdk.com/docs/sdk/Titanium.Network.TCPSocket.md) object is still required
by the [BonjourBrowser](https://titaniumsdk.com/docs/sdk/Titanium.Network.BonjourBrowser.md) and
[BonjourService](https://titaniumsdk.com/docs/sdk/Titanium.Network.BonjourService.md) objects.
For all other socket needs, use [Titanium.Network.Socket.TCP](https://titaniumsdk.com/docs/sdk/Titanium.Network.Socket.TCP.md).
### 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.
``` xml
NSAppTransportSecurity
NSAllowsArbitraryLoads
```
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](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33).
Example:
``` xml
NSAppTransportSecurity
NSAllowsArbitraryLoads
<-- 2) Alternative: Define whitelisted domains -->
NSExceptionDomains
www.foo.com
NSExceptionMinimumTLSVersion
[string](https://titaniumsdk.com/docs/sdk/Global.String.md)TLSv1.0
NSExceptionRequiresForwardSecrecy
NSExceptionAllowsInsecureHTTPLoads
```
**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](https://developer.apple.com/library/content/documentation/NetworkingInternetWeb/Conceptual/NetworkingOverview/UnderstandingandPreparingfortheIPv6Transition/UnderstandingandPreparingfortheIPv6Transition.html#//apple_ref/doc/uid/TP40010220-CH213-SW16).
## Properties
### allHTTPCookies
- Type: Array
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.3.0
- Permission: read-only
A list of all cookies in the cookie storage.
### NETWORK_LAN
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
A [networkType](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#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](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#change) event.
### NETWORK_MOBILE
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
A [networkType](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#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](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#change) event.
### NETWORK_NONE
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
A [networkType](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#networkType) value indicating that no
network is available.
This constant is also a possible value for the `networkType` property of the
[change](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#change) event.
### NETWORK_UNKNOWN
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
A [networkType](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#networkType) value indicating that the
current network type is unknown.
This constant is also a possible value for the `networkType` property of the
[change](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#change) event.
### NETWORK_WIFI
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
A [networkType](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#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](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#change) event.
### networkType
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
Network type value as a constant.
One of the `NETWORK` constants defined in [Titanium.Network](https://titaniumsdk.com/docs/sdk/Titanium.Network.md).
Accepts: `Titanium.Network.NETWORK_LAN`, `Titanium.Network.NETWORK_MOBILE`, `Titanium.Network.NETWORK_NONE`, `Titanium.Network.NETWORK_UNKNOWN`, `Titanium.Network.NETWORK_WIFI`
### networkTypeName
- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
Network type as a String. Returns one of `NONE`, `WIFI`, `LAN`, `MOBILE`, or `UNKNOWN`.
### NOTIFICATION_TYPE_ALERT
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Constant value for an Alert style push notification.
### NOTIFICATION_TYPE_BADGE
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Constant value for a Badge style push notification.
### NOTIFICATION_TYPE_NEWSSTAND
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Constant value for a Newsstand style push notification. Only available on iOS5 and later
### NOTIFICATION_TYPE_SOUND
- Type: Number
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Constant value for a Sound style push notification.
### online
- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only
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.
### PROGRESS_UNKNOWN
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.5.0
- Permission: read-only
Constant value specifying that the progress of a download can not be calculated.
### remoteDeviceUUID
- Type: String
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Remote device UUID if the device is registered with the Apple Push Notification
Service, or null if it is not registered.
### remoteNotificationsEnabled
- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 12.0.0, iPhone 3.3.0, iPad 3.3.0
- Permission: read-only
Indicates whether push notifications have been enabled using
[registerForPushNotifications](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#registerForPushNotifications).
### remoteNotificationTypes
- Type: Array
- Platforms: iPhone, iPad, macOS
- Permission: read-only
Array of push notification type constants enabled for the application.
### TLS_VERSION_1_0
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.6.0, iPhone 1.8.0.1, iPad 1.8.0.1
- Permission: read-only
Constant value specifying TLS version 1.0 for SSL.
### TLS_VERSION_1_1
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.6.0, iPhone 1.8.0.1, iPad 1.8.0.1
- Permission: read-only
Constant value specifying TLS version 1.1 for SSL.
### TLS_VERSION_1_2
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.6.0, iPhone 1.8.0.1, iPad 1.8.0.1
- Permission: read-only
Constant value specifying TLS version 1.2 for SSL.
### TLS_VERSION_1_3
- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 8.3.0
- Requires: Android 10.0+, iOS 12.2+
- Permission: read-only
Constant value specifying TLS version 1.3 for SSL.
## Methods
### addHTTPCookie
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.2.0, iPhone 3.3.0, iPad 3.3.0
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](https://developer.android.com/reference/org/apache/http/impl/cookie/BasicClientCookie.html)
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:
- `cookie` (Titanium.Network.Cookie): The cookie to add
### addSystemCookie
- Platforms: Android
- Since: Titanium SDK 3.2.0
Adds a cookie to the system cookie store.
On Android, [Titanium.UI.WebView](https://titaniumsdk.com/docs/sdk/Titanium.UI.WebView.md) uses the system cookie store. Any existing cookie with the same
domain, path and name will be replaced with the new cookie.
Parameters:
- `cookie` (Titanium.Network.Cookie): The cookie to add
### createBonjourBrowser
- Platforms: iPhone, iPad, macOS
Creates and returns a `BonjourBrowser` object.
Parameters:
- `serviceType` (String): Service to search for, must include the protocol type suffix (._tcp).
- `domain` (String): Bonjour service domain to conduct the search in. Default: ``local.` (The trailing period is intentional.)
`.
- `parameters` (Dictionary, optional): A dictionary object of properties defined in [Titanium.Network.BonjourBrowser](https://titaniumsdk.com/docs/sdk/Titanium.Network.BonjourBrowser.md).
Returns: Titanium.Network.BonjourBrowser
### createBonjourService
- Platforms: iPhone, iPad, macOS
Creates and returns a `BonjourService` object.
Parameters:
- `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. Default: ``local.` (The trailing period is intentional.)
`.
- `parameters` (Dictionary, optional): Dictionary object of properties defined in [Titanium.Network.BonjourService](https://titaniumsdk.com/docs/sdk/Titanium.Network.BonjourService.md).
Returns: Titanium.Network.BonjourService
### createCookie
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.2.0, iPhone 3.3.0, iPad 3.3.0
Creates and returns an instance of [Titanium.Network.Cookie](https://titaniumsdk.com/docs/sdk/Titanium.Network.Cookie.md).
Parameters:
- `parameters` (Dictionary, optional): Properties to set on a new object, including any defined by [Titanium.Network.Cookie](https://titaniumsdk.com/docs/sdk/Titanium.Network.Cookie.md) except those marked not-creation or read-only.
Returns: Titanium.Network.Cookie
### createHTTPClient
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 0.1
Creates and returns an instance of [Titanium.Network.HTTPClient](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md).
Parameters:
- `parameters` (Dictionary, optional): Properties to set on a new object, including any defined by [Titanium.Network.HTTPClient](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md) except those marked not-creation or read-only.
Returns: Titanium.Network.HTTPClient
### createTCPSocket
- Platforms: iPhone, iPad
- Since: Titanium SDK 1.2.0
- DEPRECATED since 1.7.0, removed in 9.0.0. Use [Titanium.Network.Socket.TCP](Titanium.Network.Socket.TCP) where possible.
Creates and returns an instance of [Titanium.Network.TCPSocket](https://titaniumsdk.com/docs/sdk/Titanium.Network.TCPSocket.md).
Parameters:
- `parameters` (Dictionary, optional): Properties to set on a new object, including any defined by [Titanium.Network.TCPSocket](https://titaniumsdk.com/docs/sdk/Titanium.Network.TCPSocket.md) except those marked not-creation or read-only.
Returns: Titanium.Network.TCPSocket
### decodeURIComponent
- Platforms: Android, iPhone, iPad, macOS
Returns a decoded version of a URI encoded value.
Parameters:
- `value` (String): URI encoded input value to be decoded.
Returns: String
### encodeURIComponent
- Platforms: Android, iPhone, iPad, macOS
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:
- `value` (String): Input value to be encoded.
Returns: String
### getHTTPCookies
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.2.0, iPhone 3.3.0, iPad 3.3.0
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:
- `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: Array
### getHTTPCookiesForDomain
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.2.0, iPhone 3.3.0, iPad 3.3.0
Gets all the cookies with the domain matched with the given values from the HTTP client cookie store.
The domain matching follows `RFC6265`.
Parameters:
- `domain` (String): The domain of the cookie to get. It is case-insensitive.
Returns: Array
### getSystemCookies
- Platforms: Android
- Since: Titanium SDK 3.2.0
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](https://titaniumsdk.com/docs/sdk/Titanium.UI.WebView.md) 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](https://titaniumsdk.com/docs/sdk/Titanium.Network.Cookie.md#name) and [value](https://titaniumsdk.com/docs/sdk/Titanium.Network.Cookie.md#value) properties returned.
Parameters:
- `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: Array
### registerForPushNotifications
- Platforms: Android, iPhone, iPad, macOS
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 [Titanium.App.iOS.registerUserNotificationSettings](https://titaniumsdk.com/docs/sdk/Titanium.App.iOS.md#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 `` permission in the `` tag of your tiapp.xml.
Example:
``` js
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:
- `config` (PushNotificationConfig): Dictionary specifying push-notification related options.
### removeAllHTTPCookies
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.2.0, iPhone 3.3.0, iPad 3.3.0
Removes all the cookies from the HTTP client cookie store.
### removeAllSystemCookies
- Platforms: Android
- Since: Titanium SDK 3.2.0
Removes all the cookie from the system client cookie store.
On Android, [Titanium.UI.WebView](https://titaniumsdk.com/docs/sdk/Titanium.UI.WebView.md) uses the system cookie store.
### removeHTTPCookie
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.2.0, iPhone 3.3.0, iPad 3.3.0
Removes the cookie with the domain, path and name exactly the same as the given values from the HTTP client cookie store.
Parameters:
- `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.
### removeHTTPCookiesForDomain
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.2.0, iPhone 3.3.0, iPad 3.3.0
Removes the cookies with the domain matched with the given values from the HTTP client cookie store.
The domain matching follows `RFC6265`.
Parameters:
- `domain` (String): The domain of the cookie to remove. It is case-insensitive.
### removeSystemCookie
- Platforms: Android
- Since: Titanium SDK 3.2.0
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](https://titaniumsdk.com/docs/sdk/Titanium.UI.WebView.md) uses the system cookie store.
Parameters:
- `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.
### unregisterForPushNotifications
- Platforms: Android, iPhone, iPad, macOS
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](https://developer.apple.com/documentation/uikit/uiapplication/1623093-unregisterforremotenotifications)
For example, calling this method would be required if a new version of
your application no longer supports push notifications.
## Events
### change
- Platforms: Android, iPhone, iPad, macOS
Fired when network connectivity changes.
Event properties:
- `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.
## Inherited members
7 members are inherited. Each is documented on the type that declares it.
- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.2/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`
---
- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.