Share via

Runtime configuration

  • Article

Runtime configuration provides a generic mechanism for creating a single image that can work for multiple markets and reduce the number of images that OEMs need to create, manage, and test. It enables OEMs to improve the open market end user experience and allows OEMs to more quickly produce MO-specific software variants. Runtime configuration also enables OEMs to dynamically configure language, branding, apps, and network settings during runtime based on the mobile operator and country/region.

A variant is defined by these Microsoft-supported keys: MCC, MNC, and SPN. Windows Phone 8.1 GDR1 also includes support for a Roaming key. If enabled, end users can be prompted to pick from multiple configurations through a UI.

When the OS is determining the correct image and settings to use on the phone, it uses the most specific set of key matches. OEMs can also use triggers based on custom CSPs created by OEMs. OEMs can extend the runtime configuration engine to trigger provisioning based on custom data. For more information on how to do this, see Define extension provisioning keys. Groups of settings, called variants, can be conditionally applied based on the results of configuration service providers. To see more examples of how to define a variant, see Specifying a variant in the customization answer file. As part of the runtime configuration framework, preinstalled applications can also be downloaded from the Windows Phone Store using Wi-Fi.

See the following sections for more information about runtime configuration.

Roaming key

Applies to: Windows Phone 8.1 GDR1

A Roaming key with values of either 0 (non-roaming) or 1 (roaming) is also supported as a new condition in the customization answer file. This key allows OEMs to create configuration sets, or variants, in the customization answer file that are triggered when the roaming state changes. OEMs must explicitly set the Roaming for both the settings that are applied when roaming and the settings that are applied when not roaming. This means that if OEMs marks a certain configuration to be applied when roaming, the non-roaming configuration must also exist or the configuration will never be rolled back to its previous non-roaming values. If using this key, OEMs must also specify all the connection settings needed for the connections that will be marked roaming and non-roaming. The Roaming key also supports the UI picker as long as OEMs use the same UI picker condition for both roaming and non-roaming states. For configurations that don't change when roaming, OEMs do not need to add the Roaming key. OEMs who already have a configuration for a connection with a particular MCC and MNC condition, and changes in the configuration when roaming is not a concern, OEMs do not need to do anything and the existing customization answer file will work.

For a sample customization answer file that uses the Roaming key, see the Using the Roaming key for roaming state changes section in Connectivity configuration.

Supported scenarios and design principles

Runtime configuration provides the flexibility to ship one OS image that can handle the following scenarios:

  • Single operator in a single country/region – Put mobile operator-specific network settings and branding configuration in the Static section of your customization answer file.

  • Branded to a single operator in a single country/region, but includes support for travel SIMs – Put mobile-operator specific network settings and branding configuration in the Static section of the customization answer file. Add variants for network settings that vary by operator and country/region to support travel SIMs. For example, the condition group may include MCC, MNC, and SPN which you can define in the Targets section of the answer file. You can then add the variants in the Variant section of your customization answer file.

  • Customized open market phone – Put OEM-specific branding configuration in the Static section of the customization answer file then add variants for network settings that vary by operator and country/region to support travel SIMs.

  • Distinguishing operators or plans - You can use the MCC/MNC/SPN as conditions to pick the operator and variant, but there are cases where you might need to provide more settings or options. These cases are as follows:

    • Additional properties (such as GID1 or IMSI range) – If you need to distinguish mobile operators based on additional properties, you must extend the set of condition providers. For more information, see Define extension provisioning keys.

    • User selection – For cases where the mobile operator (MVNO_A versus MVNO_B) or plan (3G versus 4G) cannot be distinguished based on the SIM or other device properties, use a UI where users can choose the correct mobile operator or plan settings. For more information, see the section Selecting the correct settings through a UI in Variant selection during runtime.

Enabling runtime configuration

To enable runtime configuration support, see Enabling runtime configuration.

Specifying a variant in the customization answer file

The following example shows a Variant description in a customization answer file. In this example:

  • The settings and configuration for the Contoso Settings variant is being defined.

  • The target for when the variant is applied is based on the conditions for the SIM_Contoso Target. The theoretical conditions for this target are not shown in the example. For more examples on how to define Targets and their Conditions, see Connectivity configuration.

  • The application and connectivity settings are applied during SIM swap. So if a Fabrikam SIM was on the phone and the user later inserts a Contoso SIM, the ContosoApp will be installed and the connectivity setting for the MMSGateway will be applied.

  • The wallpaper settings are only applied if a Contoso SIM is the first SIM inserted into the phone.

<!-- These settings are applied when a Contoso SIM is detected -->

<Variant Name="Contoso Settings">
    <TargetRefs>
        <TargetRef Id="SIM_Contoso" />
    </TargetRefs>

    <Applications>
        <Application Source="C:\Customization\Applications\Contoso\ContosoApp.xap" 
                     License="C:\Customization\Contoso\ContosoApp_License.xml" />
                     ProvXML="C:\Customization\Applications\Contoso\MPAP_ContosoApp.provxml" />
    </Applications>
    
    <Settings Path="Connectivity">
        <Setting Name="MMSGateway" Value="123.Contoso.com" />
    </Settings>

    <Settings Path="Shell\Wallpaper">
      <Asset Name="Wallpapers" Source="C:\Customization\Assets\OEMWallpaper1.jpg" />
      <Asset Name="Wallpapers" Source="C:\Customization\Assets\OEMWallpaper2.jpg" />
      <Asset Name="Wallpapers" Source="C:\Customization\Assets\OEMWallpaper3.jpg" />
      <Setting Name="DefaultWallpaper" Value="C:\Programs\CommonFiles\Wallpapers\OEMWallpaper3.jpg" />
    </Settings>

</Variant>

Dual SIM

For phones that have dual SIM, if there is a single SIM in the phone during first boot, or a SIM is first inserted in the phone, this SIM will be used by the OS for all customizations.

If there are two SIMS in the phone on first boot, or first SIM(s), the one specified by the OEM customization will be used for branding (run once) customizations.

For more information about dual SIM, see Dual SIM. Configuration for certain feature areas, such as MMS and APN, also provide specific guidance or requirements related to dual SIM phones.

Updates

OEMs can update phones over-the-air using image update or OMA DM or OMA CP provisioning. You can use image update for any settings. You can also a Windows Phone Store app to update network settings.

Variant selection during runtime

Troubleshoot runtime configuration

 

 

Send comments about this topic to Microsoft