1 <html devsite> 2 <head> 3 <title>Carrier Configuration</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <p>The Android 6.0 Marshmallow release introduces a capability for privileged 27 applications to provide carrier-specific configuration to the platform. This 28 functionality, based on the <a href="uicc.html">UICC carrier privilege 29 functionality</a> introduced in Android 5.1 (Lollipop MR1), will allow carrier 30 configuration to be moved away from the static configuration overlays and give 31 carriers and OEMs the ability to dynamically provide carrier configuration to 32 the platform through a defined interface.</p> 33 34 <p>A properly signed carrier app can either be preloaded in the system image, 35 installed automatically, or manually installed through an app store. The app 36 will be queried by the platform to provide configuration for settings 37 including:</p> 38 39 <ul> 40 <li>Roaming/Non-roaming networks 41 <li>Visual Voicemail 42 <li>SMS/MMS network settings 43 <li>VoLTE/IMS configurations 44 </ul> 45 46 <p class="note"><strong>Note</strong>: This app must be signed with the 47 certificate that has a matching signature to one on the SIM. See the <a 48 href="#how_privilege_is_granted_to_a_carrier_app">How is privilege granted to a 49 Carrier App</a> section for details.</p> 50 51 <p>The determination of what values to return is entirely up to the Carrier App 52 and can be dynamic based on detailed information passed to the app via the 53 platform. </p> 54 55 <p>The key benefits of this approach are:</p> 56 57 <ul> 58 <li><strong>Dynamic configuration</strong> - Support for concepts like 59 non-MCCMNC derived configuration, for example 60 mobile virtual network operators (MVNOs) or customer opt in to extra services 61 <li><strong>Support for devices sold through any channel</strong> - e.g. an 62 open market phone can be automatically configured with the right 63 settings by downloading an app from an app store. 64 <li><strong>Security</strong> - Privilege to provide this configuration is 65 given only to applications signed by the carrier 66 <li><strong>Defined API</strong> - Previously this configuration was stored 67 mostly in internal XML overlays within the framework and not through a public 68 API. The carrier config API in Android 6.0 is public and well defined. 69 </ul> 70 71 <h2 id=how_it_works>How it works</h2> 72 73 <h3 id=loading_the_config>Loading the config</h3> 74 75 <p>The carrier configuration supplied by this feature is a set of key-value pairs 76 that change various telephony-related behaviors in the platform.</p> 77 78 <p>The set of values for a particular device is determined by querying the 79 following components in order:</p> 80 81 <ol> 82 <li>The Carrier App (although this is technically optional, it is the recommended 83 location for additional configuration beyond what exists in the Android Open 84 Source Project - AOSP) 85 <li>The Platform Config App bundled with the system image 86 <li>Default values, hardcoded into the framework (equivalent to the behavior prior 87 to M) 88 </ol> 89 90 <p class="caution"><strong>Important</strong>: If a value for a particular key 91 is returned at any stage, the first value found takes precedence over the 92 further stages.</p> 93 94 <h4 id=the_platform_config_app>The Platform Config App</h4> 95 96 <p>A generic Platform Config App is bundled with the system image that can supply 97 values for any variables the regular Carrier App does not. The platform config 98 app can be found (in M) in: <code>packages/apps/CarrierConfig</code></p> 99 100 <p>This apps purpose is to provide some per-network configuration when a Carrier 101 App is not installed, and carriers/OEMs should make only minimal changes to it 102 in their own images. Instead carriers should provide the separate Carrier App 103 for carrier customization, allowing updates to be distributed via avenues such 104 as app stores.</p> 105 106 <h4 id=how_privilege_is_granted_to_a_carrier_app>How privilege is granted to a Carrier App</h4> 107 108 <p>The Carrier App in question must be signed with the same certificate found on 109 the SIM card, as documented in <a href="uicc.html">UICC Carrier Privileges</a>.</p> 110 111 <h4 id=what_information_is_passed_to_the_carrier_app>What information is passed to the Carrier App</h4> 112 113 <p>The Carrier App is supplied with the following values, enabling it to make a 114 dynamic decision as to what values to return:</p> 115 116 <ul> 117 <li>MCC 118 <li>MNC 119 <li>SPN 120 <li>IMSI 121 <li>GID1 122 <li>GID2 123 </ul> 124 125 <h4 id=when_loading_the_carrier_config_occurs>When loading the carrier config occurs</h4> 126 127 <p>The building of the list of key value pairs occurs:</p> 128 129 <ul> 130 <li>When the SIM is loaded (boot, or SIM hot swap) 131 <li>When the Carrier app manually triggers a reload 132 <li>When the Carrier app gets updated 133 </ul> 134 135 <p>See the <a 136 href="http://developer.android.com/reference/android/service/carrier/CarrierService.html#onLoadConfig(android.service.carrier.CarrierIdentifier)">android.service.carrier.CarrierService#onLoadConfig()</a> 137 reference for more details.</p> 138 139 <p class="note"><strong>Note</strong>: The platform caches carrier 140 configuration bundles and loads from the cache for SIM state changes. This is 141 to speed up boot and SIM hot swap. It is assumed that without a package update 142 or an explicit <code>notifyConfigChangedForSubId</code>, the config bundle has 143 not been modified.</p> 144 145 <h3 id=using_the_config>Using the config</h3> 146 147 <p>Once the configuration has been built, the values contained within it are used 148 to set various values of system configuration, including:</p> 149 150 <ul> 151 <li>Internal framework telephony settings 152 <li>SDK-returned configuration values, e.g. in SmsManager 153 <li>App settings like VVM connection values in the Dialer 154 </ul> 155 156 <h3 id=configuration_keys>Configuration keys</h3> 157 158 <p>The list of keys is defined as part of the public SDK in <code><a 159 href="http://developer.android.com/reference/android/telephony/CarrierConfigManager.html">android.telephony.CarrierConfigManager</a></code> 160 and cannot change within the same API level. See the table below for a summary of keys.</p> 161 162 <h2 id=how_to_build_your_application>How to build your application</h2> 163 164 <h3 id=create_your_application>Create your application</h3> 165 166 <p>Your application must target the Android 6.0 API level (23).</p> 167 168 <h3 id=declare_a_class_that_overrides_android_service_carrier_carrierservice>Declare a class that overrides android.service.carrier.CarrierService</h3> 169 170 <ol> 171 <li>Override <code>onLoadConfig</code> to return the values you wish to 172 supply based on the <code>service.carrier.CarrierIdentifier</code> object 173 passed. 174 <li>Add logic to call <code>notifyConfigChangedForSubId</code> in scenarios 175 where carrier configuration may change over time (e.g. when the 176 user adds extra services to their account) 177 </ol> 178 179 <p>An example is below:</p> 180 181 <pre class="prettyprint"> 182 public class SampleCarrierConfigService extends CarrierService { 183 184 private static final String TAG = "SampleCarrierConfigService"; 185 186 public SampleCarrierConfigService() { 187 Log.d(TAG, "Service created"); 188 } 189 190 @Override 191 public PersistableBundle onLoadConfig(CarrierIdentifier id) { 192 Log.d(TAG, "Config being fetched"); 193 PersistableBundle config = new PersistableBundle(); 194 config.putBoolean( 195 CarrierConfigManager.KEY_CARRIER_VOLTE_AVAILABLE_BOOL, true); 196 config.putBoolean( 197 CarrierConfigManager.KEY_CARRIER_VOLTE_TTY_SUPPORTED_BOOL, false); 198 config.putInt(CarrierConfigManager.KEY_VOLTE_REPLACEMENT_RAT_INT, 6); 199 // Check CarrierIdentifier and add more config if needed 200 return config; 201 } 202 } 203 </pre> 204 205 206 <p>Please see the <a 207 href="https://developer.android.com/reference/android/service/carrier/CarrierService.html">android.service.carrier.CarrierService</a> reference on developer.android.com for more details.</p> 208 209 <h3 id=name_the_class_in_your_manifest>Name the class in your manifest</h3> 210 211 <p>An example is below:</p> 212 213 <pre class="prettyprint"> 214 <service android:name=".SampleCarrierConfigService" 215 android:label="@string/service_name" 216 android:permission="android.permission.BIND_CARRIER_SERVICES"> 217 <intent-filter> 218 <action android:name="android.service.carrier.ConfigService"/></intent-filter> 219 </service> 220 </pre> 221 222 <h3 id=sign_app_with_same_certificate_on_sim>Sign app with same certificate on SIM</h3> 223 224 <p>See <a href="uicc.html">UICC Carrier Privileges</a> for the requirements.</p> 225 226 <h2 id=testing_your_application>Testing your application</h2> 227 228 <p>Once you have built your configuration application, you can test your code 229 with:</p> 230 231 <ul> 232 <li>A SIM containing a valid certificate signature 233 <li>A device running Android 6.0 and later, for example a Nexus device 234 </ul> 235 236 </body> 237 </html> 238
