Customization answer file

A customization answer file is an XML file that you write based on the MCSF schema. OEMs can use the MCSF customization answer file to specify the settings and variants for a custom mobile OS image. The customization answer file allows for a broader integration across the OS by providing OEMs with a single place to define nearly all mobile OS settings.

When creating or working with customization answer files, keep the following design requirements and considerations in mind:

  • If you are using ImgGen.cmd to generate a mobile OS image, you can only specify one customization answer file. For more information, see Building a mobile image using ImgGen.cmd.

  • Depending on what you want to do, you can use the customization answer file to create a package containing your customization(s) or use the answer file as one of the inputs to create an OS image.

  • The values used in the root customization answer file (or the one you specify as the input customization answer file during ImgGen.cmd or CustomizationGen.cmd in Step 6) is used to determine the package owner so it is important to provide values for the following attributes:

    • Name

    • Description

    • Owner

    • OwnerType (in the customization samples this is typically already set to 'OEM').

    • Any files, assets, or other settings specific to the customization

  • Absolute or full paths to file sources, such as imports, assets and data files, are required. This means that whenever you specify the Source attribute value for a file Import, Asset, or DataAsset, the path must be absolute.

  • File source paths may contain $(environment_variables). Note that you can only use environment variables when referencing files. This will not work when configuring Setting values.

  • Using %this_format% in customization answer files is not allowed and results in an error.

  • The source path for Import files may contain the macro, $(CurrentFileDir).

  • Import source files can use environment variables in the file name. However, other source file names cannot use environment variables.

Sample customization answer files

You can use as reference the sample OEM customization answer file located in the %WPDKCONTENTROOT%\Samples\Customization directory. This answer file shows several configured customizations and it imports two answer files that contain real connection settings data for AT&T and T-Mobile.

Sample 1

The following sample customization answer file shows how to:

  • Specify other customization answer files to import from the root answer file.

  • Define Targets or conditions for when a variant can be applied.

  • Define Static settings and data, which are installed for all images, regardless of the variant.

  • Define settings for a Variant, which are applied if the associated target's conditions are met.

<?xml version="1.0" encoding="utf-8" ?>  
<!--  Copyright (c) Microsoft Corporation.  All rights reserved.  -->  

<ImageCustomizations xmlns="http://schemas.microsoft.com/embedded/2004/10/ImageUpdate"  
                     Name="Sample Root Customization File"  
                     Description="Sample customization XML. This XML contains all the valid settings that should be correctly parsed and applied to image."  
                     Owner="ContosoOEM"  
                     OwnerType="OEM">  


 <!-- This root customization answer file imports two other customization answer files. -->
  <Imports>
    <Import Source="C:\Customization\AnswerFiles\SampleCustomizationImport1.xml" />
    <Import Source="C:\Customization\AnswerFiles\SampleCustomizationImport2.xml" />
  </Imports>

  <!-- Targets define the conditions for when a variant can be applied. One target ID must be
       referenced for each variant. -->

  <!-- These examples show the definition for three sample operators. -->
  <!-- In the example below, targets are set up for the variant to use in the root file. -->
  <Targets>  
   <Target Id="SIM_TinyMO">  
      <TargetState>  
        <Condition Name="MNC" Value="26" />  
        <Condition Name="MCC" Value="310" />  
      </TargetState>  
    </Target>  
    <Target Id="SIM_BigMO">  
      <TargetState>  
        <Condition Name="MNC" Value="15" />  
        <Condition Name="MCC" Value="310" />  
      </TargetState>  
    </Target>  
    <Target Id="Known_BigMO">  
      <TargetState>  
        <Condition Name="MNC" Value="55" />  
        <Condition Name="MCC" Value="310" />  
      </TargetState>  
    </Target>  
  </Targets>  


  <!-- These static settings and data will be installed for all images, regardless of the variant. -->
  <Static>
    <DataAssets Type="MapData">
      <DataAsset Source="C:\Customization\TestData\maps\OEMMap_USA.map" />
      <DataAsset Source="C:\Customization\TestData\maps\OEMMap_Canada.map" />
    </DataAssets>

    <Applications>
      <Application Source="C:\Customization\TestData\apps\OEMMOApp.xap"
                   License="C:\Customization\TestData\apps\OEMMOApp_License.xml"
                   ProvXML="C:\Customization\TestData\apps\MPAP_OEMMOApp_01.provxml" />
    </Applications>

    <Settings Path="TestSettingGroup">
      <Setting Name="Level1/MySetting" Value="Blue" />
      <Setting Name="MySettingAsset" Value="Alpha.jpg" />
      <Asset Name="Asset" Source="C:\Customization\MySettingAssets\Alpha.jpg" />
      <Asset Name="Asset" Source="C:\Customization\MySettingAssets\Beta.jpg" />
      <Asset Name="Asset" Source="C:\Customization\MySettingAssets\Delta.jpg" />
    </Settings>

    <Settings Path="TestSettingsGroup2">
      <Setting Name="OEMStaticSetting" Value="OEM Static Setting" />
    </Settings>
  </Static>


  <!-- These settings in the Variant groups will only be applied if the associated target's conditions are met. -->

  <!-- The settings shown here will only be applied for the Known Big MO Variant. -->
  <Variant Name="Known Big MO Variant">  
    <!-- Only one TargetRef can be used for each variant -->
    <TargetRefs>  
      <TargetRef Id="Known_BigMO" />  
    </TargetRefs>  

    <Settings Path="EventSounds">  
      <Asset Name="Ringtones" Source="C:\Resources\Ringtones\KnownBigMO.wma" TargetFileName="BigMO.wma" DisplayName="BigSound" Type="MobileOperator" />
      <Setting Name="DefaultRingtone" Value="BigMO.wma" />  
    </Settings>  

    <Settings Path="LockScreen">  
      <Asset Name="Wallpapers" Source="C:\Resources\Wallpapers\KnownBigMO.jpg" TargetFileName="BigMO.jpg" DisplayName="BigMO" Type="MobileOperator" />
      <Setting Name="DefaultWallpaper" Value="BigMO.jpg" />  
    </Settings>  
  </Variant>  

  <!-- The settings shown here will only be applied for the Tiny MO Variant. -->
  <Variant Name="Tiny MO Variant">  
    <TargetRefs>  
      <TargetRef Id="SIM_TinyMO" />  
    </TargetRefs>  

    <Settings Path="TestSettingsGroup1">  
      <Setting Name="Setting1" Value="Tiny MO Setting 1" />
      <Setting Name="Setting3" Value="Tiny MO Setting 3" />
    </Settings>  

    <Settings Path="EventSounds">  
      <Asset Name="Ringtones" Source="C:\Resources\Ringtones\TinyMO.wma" TargetFileName="TinyMO.wma" DisplayName="TinySound" Type="MobileOperator" />
      <Setting Name="DefaultRingtone" Value="TinyMO.wma" />  
    </Settings>  
  </Variant>  

  <!-- The settings shown here will only be applied for the Big MO Variant. -->
  <Variant Name="Big MO Variant">  
    <TargetRefs>  
      <TargetRef Id="SIM_BigMO" />  
    </TargetRefs>  

    <Settings Path="TestSettingsGroup1">  
      <Setting Name="Setting1" Value="Big MO Setting 1" />
    </Settings>  
  </Variant>  

</ImageCustomizations>

Sample 2

The following sample customization answer file snippet shows how to:

  • Define a Static variant

  • Specify the customizations for a specific mobile operator in a Variant section.

<!-- Variant Section -->

  <!-- Example of a static variant. There are no TargetRefs. -->

  <Static>
    <!-- Asset data to be copied to the device. A small set of approved destinations are allowed.
         Only allowed in the static settings -->
    <DataAssets>
      <DataAsset Source="C:\Customization\Assets\OEMMap_USA.map" Type="MapData" />
    </DataAssets>
  </Static>

  <!-- Simple example of some things to do on a hypothetical TinyMO. Setting the Boot Screen 
       on FirstSIM, and the MMS Gateway whenever the SIM is detected as "Newly Inserted". Ringtones and
       wallpapers are also added. -->

  <Variant Name="TinyMO Settings">
    <TargetRefs>
      <TargetRef Id="SIM_TinyMO" />
    </TargetRefs>

    <Settings Path="Connectivity">
      <Setting Name="MMSGateway" Value="123.tinymo.com" />
    </Settings>

    <Settings Path="EventSounds">
      <Asset Name="Ringtones" Source="C:\Assets\Ringtones\Ringtone1.wma" />
      <Asset Name="Ringtones" Source="C:\Assets\Ringtones\Ringtone2.wma" />
      <Asset Name="Ringtones" Source="C:\Assets\Ringtones\Ringtone3.wma" />
      <Setting Name="DefaultRingtone" Value="Ringtone1.wma" />
    </Settings>

    <Settings Path="LockScreen">
      <Asset Name="Wallpapers" Source="C:\Assets\Wallpapers\Lockscreen1.jpg" />
      <Asset Name="Wallpapers" Source="C:\Assets\Wallpapers\Lockscreen2.png" />
      <Asset Name="Wallpapers" Source="C:\Assets\Wallpapers\Lockscreen3.jpeg" />
      <Setting Name="DefaultWallpaper" Value="Lockscreen2.png" />
    </Settings>

  </Variant>

Customization XML elements

The following table defines all the elements in a customization answer file.

Element Parent Description

Imports

-

Contains the description for other customization answer files to import.

Import

Imports

Specifies the file to import and merge with the customizations in the root file.

If the same setting is set in the imported file, that setting will be overridden by the value specified by the same in the root file.

Targets

-

Defines the conditions for when a variant can be applied.

Target

Targets

One Target Id must be specified for each variant. This can contain multiple sets of TargetState that can cause the target to fire.

A single Condition is defined by a single name/value pair. The name is a runtime configuration condition name such as MNC or an OEM condition that can be defined in CustomTargetState. Multiple Condition can be contained within the TargetState.

Static

-

Contains the description for the static variation.

The settings that are registry based will override values that are set in packages.

DataAssets

Static

Enables the ability to put data files directly onto the data partition without a package. OEMs specify the type of data from an approved list and the image customization process determines the destination for the data based on the type.

In Windows Phone 8.1, the following types of data are supported:

  • MapData – Use to specify map data

  • RetailDemo_Microsoft – Use to add custom demo content to the Microsoft retail mode provisioning app. This data asset is reserved for Microsoft use and the data assets are provided by Microsoft Marketing. Partners should contact Microsoft to reach your Microsoft marketing contact.

  • RetailDemo_OEM – Use to add custom demo content to the OEM retail mode provisioning app.

  • RetailDemo_MO – Use to add custom demo content to the mobile operator retail mode provisioning app.

  • RetailDemo_Apps – Use to add free or trial apps and games to be included in demo phones.

Note that when specifying any retail demo data asset in the customization answer file, the retail mode data asset must point to a directory structure where nested files are placed in a very particular format. For more information, see the Retail Demo Mode Programmers Guide, which will be available in a future documentation release.

Variant

-

These settings in the Variant groups will only be applied if the associated target's conditions are met.

TargetRefs

Variant

A collection of targets that causes the variant to be provisioned.

Currently, only one TargetRef is supported.

Applications

Static, Variant

A collection of applications to be applied statically to the phone, or when a variant is provisioned.

For a static variant, the app is installed into the system partition. For non-static variants, the .xap file of the app is always included in the data partition.

For more information, see Apps: Preloading and storage location.

Settings

Static, Variant

A settings group that is determined by a provided path.

For more information about the settings group, setting elements, and associated attributes, see Managed Centralized Settings Framework (MCSF).

Setting

Settings

A single setting and value that is determined by a name. A Setting can contain assets or data files associated with the setting.

Note

If the policy for a specified setting is not included in a package in the image, the setting will not be included in the image and a warning will be displayed.

Asset

Settings

Indicates a file that needs to be included in the phone image and associated with the Settings to which it belongs.

When specifying an asset, OEMs must provide the Name and Source attributes. The Name determines where the asset is stored on the phones. OEMs can specify multiple files using the same asset name, such as for multiple lock screen backgrounds, ringtones, and so on. The Source must be set to the location of the asset on your machine.

OEMs can use the following optional attributes:

TargetFileName can be used to set the name of the file on the device. If there is no TargetFileName specified, the source name is used.

DisplayName can be used by some settings to display a name such as the ringtone’s display name. The setting determines exactly how this property is used and is a passthrough to a registry value.

Type is a flag that indicates the type of asset, as required by some settings. In Windows Phone 8.1, MO and OEM are supported. If no value is specified, the default value is OEM.

Specifying data values in customization answer files

When creating your customization answer file, certain values must be specified in a specific format. These are as follows:

Type value Value attribute Description

REG_DWORD

Decimal: 1

- or -

Hexadecimal: 0x1

32-bit number presented in either decimal or hexadecimal format.

All hexadecimal values in the customization answer file must be prefixed with 0x. For example, if the hexadecimal value that you need to specify is 1, you must set the Value in the customization answer file to 0x1. These values are in little-endian format where the multibyte value is stored in memory from lowest byte (the "little end") to the highest byte. For example, 0x12345678 is stored as (0x78 0x56 0x34 0x12) in little-endian format.

Options defined in the policy settings files. For example:

<Validate>

<Option Value="0" FriendlyName="Red" />

<Option Value="1" FriendlyName="Green" />

<Option Value="2" FriendlyName="Blue" />

</Validate>

0 or Red

1 or Green

2 or Blue

Use the enumerated value. For example, either the enumerated value 0 or its equivalent friendly name "Red" can be specified.

REG_MULTI_SZ

Red.png;Green.png;Blue.png

Multiple text strings separated by a semicolon ';'.

A ';' is used as the delimeter for REG_MULTI_SZ so this character cannot be used inside the string because it will be parsed as the separator of two strings.

REG_BINARY

E8,03

(which corresponds to 0x03E8 hexadecimal)

Byte array in hexadecimal format, separated by a comma ','.

Do not add the 0x prefix when specifying this type of registry value in the customization answer file.

Targets

When creating a customization answer file, OEMs can define Targets to describe keying for a variant. Targets for variants must be described or pre-declared before being referenced by the variant. OEMs can use the same target in multiple variants to enable reuse. Within a target, if the device meets any of the target states, the settings will be applied (the states are OR'ed together). The conditions within the states are AND'ed together and all of the conditions must be met in order for a state to be true.

In the previous XML sample, a SIM target is defined through MNC/MCC pairs. The following example shows how the SIM targets may be defined:

<Targets>
    <Target Id="SIM_TinyMO">
        <TargetState>
            <Condition Name="MNC" Value="123" />
            <Condition Name="MCC" Value="456" />
        </TargetState>
        <TargetState>
            <Condition Name="MNC" Value="456" />
            <Condition Name="MCC" Value="123" />
        </TargetState>
    </Target>
</Targets>

Extension provisioning keys

OEMs can use custom CSPs as conditions by listing the name/path in the Name attribute and the desired value to pass to the CSP to check against.

Importing other customization answer files

A customization answer file can be used to import other customization answer files that, when merged, form a single set of customizations and variants to be applied to the OS image.

Priority order for imported customization answer files

When importing customization answer files, if there are any settings that are defined twice, the custom image will not build unless a priority within the imported answer files are specified to determine the overwrite order. To specify the overwrite order, the header for customization answer files contain an optional Priority attribute, which determines the order that settings will be overwritten if imported files contain a setting defined more than once. Generally, the highest priority will have its value used for customization package creation. If files have the same priority and define the same setting, the image fails to build.

To add the priority order for the imported answer file, set the Priority attribute within the ImageCustomizations block of the customization answer file to be imported. The following example shows how to do this:

<ImageCustomizations xmlns="http://schemas.microsoft.com/embedded/2004/10/ImageUpdate"
                  Name="Settings Input"
                  Description="Settings for image build"
                  Owner="Contoso"
                  OwnerType="OEM"
                  Priority="2">

Note
When setting Priority, 1 is the highest, and zero (0) and negative numbers are not allowed.

Specifying files to be imported

The following code example shows how you can specify other customization answer files to be imported. The Imports element must be specified in the root customization answer file.

  <Imports>
    <Import Source="C:\Customization\SampleOperators.xml" />
    <Import Source="C:\Customization\SampleBrandCommon.xml" />
  </Imports>

Apps: Preloading and storage location

OEMs can preload apps using the following customization answer file code snippet:

    <Applications>
      <Application Source="C:\Customization\TestData\apps\OEMMOApp.xap"
                   License="C:\Customization\TestData\apps\OEMMOApp_License.xml"
                   ProvXML="C:\Customization\TestData\apps\MPAP_OEMMOApp_01.provxml" />
    </Applications>

Note
The AppPreInstaller is specifically looking for provXML files with the filename pattern MPAP_*_*.provxml so make sure your file names are correctly formatted.

The following table describes where preloaded apps are stored on the device:

First option Alternative option

Default

Main OS

Data

Variant

Data

Main OS

All applications can be uninstalled by the user. When applications are uninstalled, the application files remain on the device, but these are not shown in the application list. During a cold boot, or when the user selects Reset my phone, apps in the Data partition will be removed while apps in the MainOS partition will be reinstalled. Users can also install apps to the SD card. When the phone boots with an SD card, the user is given an option to select the install location.

Collisions and overrides

If there are collisions or overrides, Settings groups are treated as a Condition-Setting Path pair. This means that two settings using the same path but different conditions are considered unique, as are two settings with the same condition but different paths.

When two different files set the same unique Settings group, the following rules are used by the image customization process to resolve collisions or overrides:

  • A file may overwrite a unique item that is defined by any file it imports. For example, the imports sample in the previous section, SampleDevice.customizations.xml, can be used to override the theme color set in SampleBrandCommon.xml.

  • Two files imported by the same file cannot set the same unique item. For example, if SampleOperators.xml and SampleBrandCommon.xml both set the same theme color using the same condition, an error will occur and a message will be displayed to indicate that the value cannot be imported because both files define the same value.

Prepare for Windows mobile development