Variant selection during runtime

After variants are defined and added to the phone image, the correct settings based on the keying on the phone are applied during runtime. This topic provides information about how these settings are applied.

Setting the device language

During boot up, the OS sets the phone language based on the UICC EF LP. The OS uses the UICC MCC to set the initial phone country/region.

For phones that have multiple SIMs, the OS uses the SIM that is associated with Slot 0 to select the initial phone language. OEMs can configure Slot 0 and Slot 1. For more information, see Setting the UICC slot for branding configuration.

If runtime configuration is enabled (see Enabling runtime configuration), the OS sets the language and locale regardless of the SIM-based language detection (SIMBLD) value. If partners do not want to use runtime configuration but want to use SIMBLD, partners must configure the device to use runtime configuration but without setting any specific configuration. This will allow SIMBLD to work but it will not configure any other configuration. The OS will set the language or locale using the runtime configuration implementation without executing the rest of the configuration runtime.

Use SIMBLD to disable languages per ICCID

Note  This feature is available in Windows Phone 8 GDR2, but it might not be available yet in Windows Phone 8.1.

If the SIM LP field is incorrect for some countries/regions, you cannot use SIMBLD. However, SIMBLD cannot be turned off especially for subvariants in a multivariant image. For this scenario, OEMs can create a SimbldIccidTable.xml to enable certain SIMs (based on the ICCID) to disable one or more languages. The SimbldIccidTable.xml file must be stored in the device's %systemdrive%\programs\commonfiles\adc\OEM directory. The runtime configuration engine scans the entire SimbldIccidTable.xml file to match the longest ICCID defined with the ICCID from the SIM and ignores the languages for the matching ICCID.

The following example shows what the SimbldIccidTable.xml can contain.

• The SIM iccid attribute must be set to the ICCID of the SIM that needs one or more languages to be disabled.

• The langlist element contains the list of languages to be disabled. Specify the languages you want to disable by specifying their ISO 639 language code.

    <simbldiccidtable>
        <sim iccid="8901">
            <langlist>
                <iso639 id="jp"/>
            </langlist>
        </sim>
        
        <sim iccid="89010">
            <langlist>
                <iso639 id="sl"/>
                <iso639 id="hr"/>
                <iso639 id="en"/>
            </langlist>
        </sim>
        
        <sim iccid="89320">
            <langlist>
                <iso639 id="sl"/>
                <iso639 id="hr"/>
            </langlist>
        </sim>
        
        <sim iccid="89374">
            <langlist>
                <iso639 id="en"/>
                <iso639 id="de"/>
                <iso639 id="hy"/>
            </langlist>
        </sim>
    </simbldiccidtable>

Selecting the variant

You can select the variant using the values for the keys for the particular phone that runtime configuration is running on. Using the keys, all matches are gathered from the datastore. Keys are applied in the following order, with multiple hits in each group being applied in the first discovered order:

Note  This feature is available in Windows Phone 8 GDR2, but it might not be available yet in Windows Phone 8.1.

In wpblue_gdr2, key handling and ordering of the ProvXML files is improved.

• Key handling

  The UICC handler and extension handler receive keys following the device state.

  • The UICC handler keys come first in the key queues.

  • The extension handler will get keys and sort these keys based on the order defined in the registry.

  The following example shows how keys are handled in wpblue_gdr2.

  UICC 1 2 3 4 … M

  Extension 1 2 3 4 … N

   

  Key queue 1 2 3 4 … M 1 2 3 4 … N

   

• Ordering of ProvXML files

  Each matching ProvXML entry is sorted using the following criteria:

  • Bitwise OR for matching keys

  • Number of matching matchings

  • Order in the index file

Selecting the correct settings through a UI

If on device keying is not sufficient to determine the correct mobile operator settings, users can specify the correct settings through a UI. The UI is defined in the customization answer file and will show up during initial phone setup and during SIM changes.

To pass information to the framework about the UI, OEMs can use the uiname and uiorder conditions and set the value to the name of the UI option:

• uiname must be set to the friendly name to use if the runtime configuration needs the user to resolve multiple matches.

• uiorder is associated with the uiname and used to sort the display options in the UI. Specifying a lower uiorder value will display the option higher in the list. If you set the uiorder value to 0, the option will be auto selected and users will only be able to go to the Cellular settings screen to select other options.

Important  

If the Roaming key is used for roaming state changes, these values must be the same for generic, roaming, and non-roaming configurations related to the same variant.

The following example shows how Contoso and Fabrikam will show up as the two options when the UI picker shows up. In this example, Contoso will appear before Fabrikam in the options list because the uiorder value for Contoso is lower than Fabrikam.

    <Target Id="Contoso">
      <TargetState>
        <Condition Name="MCC" Value="244" /> 
        <Condition Name="MNC" Value="05" />
        <Condition Name="uiname" Value="Contoso" />
        <Condition Name="uiorder" Value="10" />
      </TargetState>        
    </Target>

    <Target Id="Fabrikam">
      <TargetState>
        <Condition Name="MCC" Value="244" /> 
        <Condition Name="MNC" Value="05" />
        <Condition Name="uiname" Value="Fabrikam" />
        <Condition Name="uiorder" Value="15" />
      </TargetState>        
    </Target>

The following example shows the UI where users can choose the correct cellular data and MMS settings.

Users can also change their initial settings selection by going to the Cellular settings screen.

Apps and storage

The runtime configuration engine supports the following types of pre-installed applications:

• Preloaded applications – Installed at variant selection time during boot or SIM swap. The application installers can be stored on the user store or OS partition.

• Automatically downloaded applications – Queued to download through Wi-Fi and install from the Windows Phone Store during boot or SIM swap.

Application installers can be stored to the user store for the preloaded applications. The installer for the variant will be copied over the OS partition to prevent these from being deleted during phone reset and the remaining variant apps will be deleted. This provides a better user experience and allows for preloads without permanently using storage space.

The runtime configuration engine performs the following stages of cleanup to reclaim storage for the user:

• Some time (default of 0 hours) after applying a variant for the user’s primary SIM card and completing initial phone setup, the runtime configuration engine will perform post-variant cleanup. At this point, the phone has been effectively branded and relevant data has been backed up so it is now safe to delete variant data from the user store.

• Some time (default of 72 hours) after completing initial phone setup, if no variant has been applied, the runtime configuration engine will delete all variant data from the user store. No data will be persisted.

You can use the following settings to modify the default values:

You can also pin apps to the Start screen. However, the following conditions apply:

• Only first boot preloaded apps can be pinned to specific tile locations in the Start screen.

• Other apps will be pinned to the bottom of the Start screen if they are configured for pinning.

• The Start layout is also runtime configuration configurable.

Send comments about this topic to Microsoft