# Titanium.Network
The top level network module.
# 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
# apiName READONLY
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
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
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
Network type value as a constant.
One of the NETWORK
constants defined in Titanium.Network.
# networkTypeName READONLY
Network type as a String. Returns one of NONE
, WIFI
, LAN
, MOBILE
, or UNKNOWN
.
# online READONLY
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
Remote device UUID if the device is registered with the Apple Push Notification Service, or null if it is not registered.
# remoteNotificationsEnabled READONLY
Indicates whether push notifications have been enabled using registerForPushNotifications.
# remoteNotificationTypes READONLY
Array of push notification type constants enabled for the application.
# Methods
# addEventListener
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
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
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
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
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
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
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
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
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
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
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
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
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
- Type
- 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
- Type
- 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
- Type
- Array<Titanium.Network.Cookie>
# registerForPushNotifications
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
Removes all the cookies from the HTTP client cookie store.
Returns
- Type
- 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
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 |
Returns
- Type
- 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
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
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
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
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
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
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
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
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
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
Constant value for an Alert style push notification.
# NOTIFICATION_TYPE_BADGE
Constant value for a Badge style push notification.
# NOTIFICATION_TYPE_NEWSSTAND
Constant value for a Newsstand style push notification. Only available on iOS5 and later
# NOTIFICATION_TYPE_SOUND
Constant value for a Sound style push notification.
# PROGRESS_UNKNOWN
Constant value specifying that the progress of a download can not be calculated.