Vehicles increasingly rely on connectivity to manage the growing list of use cases requested by both OEMs and vehicle owners, resulting in an increased data footprint and associated costs. Use the per-application network selection (PANS) feature to route the traffic of specified apps on networks paid for by the OEM.
With PANS, you can manage the volume and cost of data usage while simultaneously providing a robust, secure, and connected car experience. PANS:
- Consists of a new API added to
ConnectivityManager
available only to automotive devices. - Provides an updated Wi-Fi suggestion API (see Wi-Fi suggestion API for internet connectivity) to include support for dynamically changing PANS network capabilities.
- Collects supporting metrics.
- Provides a reference app.
Why PANS?
PANS can:
- Dynamically update app-to-network mappings.
- Manage app-level routing without making changes to apps.
- Only OEM-allowed apps can access the mapped OEM networks.
- App developers needn't make any changes to implement this feature.
- User-facing metrics track app-to-network data usage for OEM managed networks.
- Network access is secure and can't be abused through unintended use cases or unauthorized apps.
- Changes to PANS app-to-network mappings are communicated to users.
- The same network configuration is applied across all users.
Core advantages
PANS provides OEMS with these core advantages:
- OEMs can pay for network traffic instead of users:
- System updates can be provided at no cost to the user.
- Network usage of specified apps can be provided at no cost to the user.
- Telemetry and other analytics can be managed at no cost to the user.
- OEMs can ensure critical apps remain connected even without a user-paid data plan. For example, safety-critical features such as maps, assistant (hands-free driving), and system updates continue to function even when a user has no data plan.
- PANS provides additional granularity of control specific to network traffic routing in Android. For example, OEMs can optimally define a logical network topology for the routing of app-level traffic.
Figure 1. PANS framework
Implement PANS
To implement PANS, a new ConnectivityManager
API,
setOemNetworkPreference
, is provided.
This new API maps apps to an OemNetworkPreference
.
This API is available only to automotive devices and is annotated as a
@SystemApi
with a new signature
permission.
Figure 2. Implement PANS
OemNetworkPreference
OemNetworkPreference
is an abstraction over OEM_PAID
and
OEM_PRIVATE
NetworkCapabilities
mapping apps by package name
to a network preference. Network preferences allow for network hierarchies.
For example, mapping an app to the OEM_NETWORK_PREFERENCE_OEM_PAID
preference
results in the following priority of default networks assigned to an app: use an
UNMETERED
network first, if UNMETERED
is not available use an
OEM_PAID
network, and if OEM_PAID
is not available, use the system
default network.
OEM_PAID
Used primarily for apps that can be routed on both OEM and non-OEM networks.OEM_PRIVATE
Used primarily for OEM apps to gain access to a network dedicated to them.
/** * If an unmetered network is available, use it. * Otherwise, if a network with the OEM_PAID capability is available, use it. * Otherwise, use the general default network. */ public static final int OEM_NETWORK_PREFERENCE_OEM_PAID = 1; /** * If an unmetered network is available, use it. * Otherwise, if a network with the OEM_PAID capability is available, use it. * Otherwise, the app doesn't get a default network. */ public static final int OEM_NETWORK_PREFERENCE_OEM_PAID_NO_FALLBACK = 2; /** * Use only NET_CAPABILITY_OEM_PAID networks. */ public static final int OEM_NETWORK_PREFERENCE_OEM_PAID_ONLY = 3; /** * Use only NET_CAPABILITY_OEM_PRIVATE networks. */ public static final int OEM_NETWORK_PREFERENCE_OEM_PRIVATE_ONLY = 4;
Call PANS APIs
To use PANS APIs:
- Use
OemNetworkPreferences
to map an app to a network preference. - Call
setOemNetworkPreference
with theOemNetworkPreferences
object. - Use the
Runnable
interface to listen for API completion.
For example:
// Mapping three packages to two network preferences // Packages have a 1:1 mapping to network preferences OemNetworkPreferences pref = new OemNetworkPreferences.Builder() .addNetworkPreference("first.package.name", OEM_NETWORK_PREFERENCE_OEM_PAID) .addNetworkPreference("second.package.name", OEM_NETWORK_PREFERENCE_OEM_PAID) .addNetworkPreference("third.package.name", OEM_NETWORK_PREFERENCE_OEM_PRIVATE_ONLY) .build(); myConnectivityManager.setOemNetworkPreference(pref, myExecutor, myListener);
Considerations
As you implement PANS, keep the following points in mind:
- Network preferences aren't persisted across boots and needs to be reapplied on each boot.
- To create a preference for an app, it needn't be installed. Therefore, network preferences for uninstalled apps can be set proactively.
- At any given time, an app can only be mapped to a single network preference.
- Network preferences are used to set the default network of an app. This is
the network used when an app hasn't specified what network(s) it wants to use through
one of the specialized APIs. Not only does this cover the vast majority of connectivity needs,
it also allows continued usage of specialized APIs such as the
NetworkRequest
API so as to not break existing app use-cases. For example, when an app only wants to do an operation over an unmetered network, PANS won't force it to use another network.
Configure a network
A network with either the OEM_PAID
or OEM_PRIVATE
capabilities must be available when using a corresponding network preference. Android
provides support for the configuration of capabilities for Ethernet and Wi-Fi networks. For
Ethernet networks, you can use a resource overlay, config_ethernet_interfaces
.
This is set at compile time.
For Wi-Fi, the WifiNetworkSuggestion
API can be used with the new
Android 12 APIs, setOemPaid(Boolean)
and
setOemPrivate(Boolean)
. This can be changed at runtime.
Consider these examples:
- A resource overlay named
config_ethernet_interfaces
specifies:- The name of the interface to configure.
- The desired
NetworkCapabilities
values.<!-- 11 NET_CAPABILITY_NOT_METERED 12 NET_CAPABILITY_INTERNET 14 NET_CAPABILITY_TRUSTED 15 NET_CAPABILITY_NOT_VPN 22 NET_CAPABILITY_OEM_PAID || 26 NET_CAPABILITY_OEM_PRIVATE --> <string-array translatable="false" name="config_ethernet_interfaces"> <item>eth0;11,12,14,15,22;;</item></string-array>
- This
WiFiNetworkSuggestion
can be changed dynamically:ArrayList<WifiNetworkSuggestion> list = new ArrayList<>(); list.add(new WifiNetworkSuggestion.Builder() .setSsid(WifiInfo.sanitizeSsid(ssid)) .setOemPrivate(true) .build()); mWifiManager.addNetworkSuggestions(list);
Restrict access to PANS networks
Tagging a network with either the OEM_PAID
or OEM_PRIVATE
capabilities marks that network as a restricted network. Restricted networks
can only be used by apps that have the
CONNECTIVITY_USE_RESTRICTED_NETWORKS
permission, which is controlled by OEMs.
Apps with this permission can use restricted networks provided the apps explicitly request them. However, these apps won't get restricted networks as their default. Apps mapped through PANS can have restricted OEM networks set as their default and won't need the restricted network permission to use them. When such an app has a restricted OEM network assigned as its default network by PANS, it also has the ability to explicitly request said OEM network if the app chooses to do so.
Review the reference app
A reference app (including code) named NetworkPreferenceApp
is provided
in user-debug automotive builds and demonstrates how to:
- Consume PANS metrics.
- Set PANS policy.
- Set a default policy for the device.
- Clear a policy.
- Apply a policy on boot.
- Use the Driver Distraction API (see Driver Distraction Guidelines).
- Dynamically update Wi-Fi with
OEM_PAID
andOEM_PRIVATE
.
Figure 3. Reference app
Metrics
To facilitate transparency around data usage, metrics are collected and made
available regarding the amount of data transmitted over the
OEM_PAID
and OEM_PRIVATE
network mappings.
Troubleshooting
Most troubleshooting conditions arise from either an app using the wrong network (no network connectivity) or data overages. To enable quick resolutions:
- Connectivity
dumpsys
includes a list of active per-app default networks and their associated apps (mapped from PANS). - Netd
dumpsys
includes UID IP and firewall rules. - Netstats
dumpsys
includes PANS per-app metrics. For example, which apps used which OEM network.
All dumpsys
data is available by creating an Android bugreport.