Per-application network selection (PANS)

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:

  1. 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.
  2. 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.
  3. 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:

  1. Use OemNetworkPreferences to map an app to a network preference.
  2. Call setOemNetworkPreference with the OemNetworkPreferences object.
  3. 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:

  1. 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>
  2. 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 and OEM_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.