Table of contents
TOC
Collapse the table of content
Expand the table of content

Partner account configuration during setup

Last Updated: 12/12/2016

In Windows 10 Mobile, an OEM or mobile operator may specify one preloaded app to be launched at the end of setup to walk users through an OEM or mobile operator account setup.

Optionally, an OEM or mobile operator may also preload an additional 4 apps that can be subroutined and called from a main app. In this case, the partner specifies one of the apps as the hub app (main app), which will be automatically launched at the end of setup. This app can then invoke other spoke apps (subroutined apps) to complete other tasks.

Partners can use this customization to walk users through the process of setting up an OEM or mobile operator-specific account or to enable a multi-page OOBE setup experience. If partners configure this customization, the All done screen at the end of setup will be replaced with an Almost done screen that contains an introduction to the partner app.

Limitations and restrictions

Partners must meet the following requirements when configuring this customization:

  • An OEM or mobile operator can run up to five (5) apps at the end of OOBE on Windows mobile devices.

    Only one partner, either the mobile operator or OEM, may have an app that launches at the end of OOBE.

  • All the apps must be installed before the end of OOBE on the mobile device. This enables the hub app to invoke the spoke apps.

  • All existing Windows Phone 8.1 and later customizations for launching an app at the end of OOBE remain in place. This includes the existing limitations and timing for unlocking home buttons.

    • The app must be preloaded and conform to all guidelines required of preloaded apps.

    • All text must be fully localized for the display languages that are included on the mobile device.

    • The app must provide a way for users to skip the task(s) and exit the app. For an example of a recommended UI for each account to configure, see the screen Sign in with Microsoft account that is shown during the standard device setup process.

    • The application can use and embed the browser control, but it cannot launch Microsoft Edge.

    • All pages and data necessary for the user to complete or skip the task must be included in the app. A data connection is not guaranteed, but an option to prompt the user to enabled network connections is available. For more information, see the Prompting the user to enable network connections section below.

    • The app must look and function like a wizard, and provide buttons for the user to navigate forward and backward through the steps. The hardware keys—Back, Start, and Search—will not be available to the user.

    • The tasks in the app must not take longer than 5 minutes to complete. After that interval, the OS will resume control and run the final tasks to finish setup, including sending the Welcome SMS and turning on the hardware keys. If the app has not exited by that point, the user can press the Start hardware button to leave the app.

Customization details

Constraints: None

Instructions:

  1. Create the partner account setup app that you want to launch at the end of OOBE.

    See App design considerations and guidelines to learn more about requirements and design considerations you need to consider when writing your app.

  2. Create a customization answer file to preload your app(s) and follow the steps in the section Configure the customization settings.

    <?xml version="1.0" encoding="utf-8" ?>  
    <ImageCustomizations xmlns="http://schemas.microsoft.com/embedded/2004/10/ImageUpdate"  
                         Name="PartnerAccountConfiguration"  
                         Description="Use to specify one preloaded app launched at the end of setup to walk users 
                                      through an OEM or mobile operator account setup. Partners may also preload an
                                      additional 4 apps that may be subroutined and called from the main hub app."  
                         Owner=""  
                         OwnerType="OEM"> 
    
      <Static>  
    
        <!-- Preload up to 5 apps to use for partner account setup. If you do, one app must be the hub app 
             and the rest are spoke apps. -->
        <Applications>
          <Application Source=""
                       License=""
                       ProvXML="" />
          <Application Source=""
                       License=""
                       ProvXML="" />
          <Application Source=""
                       License=""
                       ProvXML="" />
          <Application Source=""
                       License=""
                       ProvXML="" />
          <Application Source=""
                       License=""
                       ProvXML="" />
        </Applications>
    
        <Settings Path="SetupWizard">  
          <!-- Set to the GUID or App ID of the partner setup app -->
          <Setting Name="PartnerSetupAppID" Value="" />   
    
          <!-- Specify the launch parameters for the partner setup app, such as the first page of the wizard -->            
          <Setting Name="PartnerSetupAppParameters" Value="/_default#/accountSetup.xaml" />       
    
          <!-- Set to 1 to prompt the user to user to enable network connections before the app is run 
          <Setting Name="PartnerSetupAppNetworkPrompt" Value="1" /> 
          -->
    
          <!-- For one supported phone language, set the value to the localized partner name, account name, and
               the name you want to appear in the Table of Contents. For multiple language support, use the below 
               settings instead as well as the Localization/MUI settings path for the base DLL and language DLL files. -->
          <Setting Name="PartnerSetupAppPartnerName" Value="" />      
          <Setting Name="PartnerSetupAppTaskName" Value="" />  
          <Setting Name="PartnerSetupAppTOCTaskName" Value="" />      
    
          <!-- For multiple supported phone languages, use these settings and provide the base MUI DLL
          <Setting Name="PartnerSetupAppPartnerName" 
                   Value="@c:\Data\Programs\{00000000-0000-0000-0000-000000000000}\Install\DisplayNames.dll,-101" />      
          <Setting Name="PartnerSetupAppTaskName" 
                   Value="@c:\Data\Programs\{00000000-0000-0000-0000-000000000000}\Install\DisplayNames.dll,-102" /> 
          <Setting Name="PartnerSetupAppTOCTaskName" 
                   Value="@c:\Data\Programs\{00000000-0000-0000-0000-000000000000}\Install\DisplayNames.dll,-103" /> 
          -->   
    
        </Settings>  
    
        <!-- For multiple supported phone langauges, add your base MUI DLL file and specify the 
             language MUI packages (*.dll.mui) 
    
        <Settings Path="Localization/MUI">  
          <Asset Name="BaseDll" Source="" />
    
          <Asset Name="LanguageDll/$(langid)" Source="" />
          <Asset Name="LanguageDll/$(langid)" Source="" />
          <Asset Name="LanguageDll/$(langid)" Source="" />
          <!-- Add as many as you need -->         
        </Settings>  
        -->
    
      </Static>
    
    </ImageCustomizations>
    

Testing steps:

  1. Flash the build containing this customization and relevant display languages to a mobile device.

  2. Verify the Almost done screen displays the localized text as expected.

  3. Launch and complete and partner setup app to verify it works appropriately, is localized, calls any other spoke apps, and that the user can exit instead of completing the setup tasks.

App design considerations and guidelines

When designing your apps, keep the following design considerations in mind:

  • We recommend that you use Universal Windows apps to enable your hub and spoke model.

  • If the app is related to device hardware or the cellular network, you can consider adding it as a settings app. In this case, the app must adhere to the guidelines outlined in Create a partner settings app.

  • When building a shared partner app, be aware that the app might appear in the Windows Store for every mobile device produced by the OEM, every phone ranged by the mobile operator, and might be downloaded by users that have a different mobile operator. To ensure that users do not end up seeing mobile operator configuration options that do not apply to their phone or network, consider these possible mitigations:

    1. Network verification: The app must verify that the phone is on the specified mobile operator’s network before displaying any account setup functionality for that mobile operator. This can be done by checking the MCC and the MNC of the SIM, or by verifying the registry value PhoneMobileOperatorName setting (see Phone metadata in DeviceTargetingInfo for more information).

    2. System settings app: The app can be written as a system settings app. This application will appear on the System screen in Settings, and cannot be pinned to Start. It also will be hidden in the Windows Store so that it cannot be accidentally downloaded. In this case, the app must adhere to guidelines in Create a partner settings app.

  • See Design basics to learn more about how you can design a Universal Windows app that suits a variety of devices with different display sizes and other tips for creating an app with a great UI.

    See Sample app UI for examples on what your partner setup app's UI might look like.

MIDL bindings

MIDL bindings allow an app to be launched through a protocol and package family name. The hub and spoke model only works on Universal Windows apps and you must use Windows.System.Launcher.LaunchUriForResultsAsync.

We recommend that you use the following APIs when implementing your apps:

APIUsecase

Windows.System.Launcher.LaunchUriForResultsAsync

Allows a parent app to launch a child app. The child app must return to the parent app. This achieves the hub and spoke model requirement for this customization (for partners that want to use this model).

When using this API, keep in mind the memory usage for mobile devices. Every time the API is used, another child app is launched while requesting not to terminate the parent app, which means that it must be kept in memory.

Windows.System.Launcher.LaunchUriAsync

Allows forward navigation from App 1 to App 2. The second app is not a child app of the first app.

Configure the customization settings

Preloading the apps and specifying the first page

  1. Preload the apps to the mobile device using the following code example or follow the steps in Preinstallable apps for mobile devices.

        <!-- Preload up to 5 apps to use as the hub and spoke apps -->
        <Applications>
          <Application Source=""
                       License=""
                       ProvXML="" />
          <Application Source=""
                       License=""
                       ProvXML="" />
        </Applications>
    
  2. In the MCSF customization answer file:

    • If your app is a Universal Windows app, set PartnerSetupAppID to the AUMID for your app (or to your hub app if you have subroutined apps).

      If your app is not a Universal Windows app, set PartnerSetupAppID to the GUID or app ID for your app (or to your hub app if you have subroutined apps).

    • Set PartnerSetupAppID to the GUID or app ID for your app (or to your hub app if you have subroutined apps), and set PartnerSetupAppParameters setting to the correct name of the first page of your hub app.

Prompting the user to enable network connections

If the user selects a Custom configuration on the Settings screen in setup, and removes the checkmark from the Allow cellular data usage on your phone option, your app will not have network connectivity even if a valid SIM is installed. To prompt the user to turn the network connection back on before the partner account configuration application is run, set the PartnerSetupAppNetworkPrompt setting to 1.

The values supported by this setting are:

ValueDescription

1 or 'Enable'

Prompt the user to user to enable network connections before the app is run.

0 or 'Disable'

Do not prompt the user to user to enable network connections before the app is run.

Localized strings for partner name, account name, and Table of Contents

Partners must provide three localized strings: partner name, name(s) of the account(s) to configure, and the name to show in the Table of Contents. The strings for the partner name and account name are used to complete the following statement displayed to the user in the screen before the app is launched.

"Almost done..."

"You’re just about done setting up your phone. Next, PartnerSetupAppPartnerName will walk you through setting up PartnerSetupAppTaskName."

  • If only one display language is included on the device, you can set the values for the PartnerSetupAppPartnerName and PartnerSetupAppTaskName settings directly to the desired strings.

    You can also set the value for the PartnerSetupAppTOCTaskName setting directly. This string will be used for the Table of Contents.

    In the above sample MCSF customization answer file, remove the comments in the section "For one supported phone language…" and set the values to the strings you want to use.

  • If you include support for multiple display languages, you must create a resource-only .dll that contains these three strings localized into every included language. For instructions on creating a resource-only .dll and including it in an image, see Create a resource-only .dll for localized strings.

    Note This capability is available only through the MCSF framework and will not work if you use the Windows provisioning framework.

In the above sample customization answer file, remove the comments around the section "For multiple supported phone languages…". The sample shows an installed .dll file named DisplayNames.dll, and that the partner name is string 101 and the account names are string 102. The string for the Table of Contents is string 103. Update these values to match your implementation and update the path to the path of your installed application.

Sample app UI

The following screenshots show what a partner setup app's UI might look like and some of the tasks that the app may walk the user through during account setup.

Screen 1Screen 2Screen 3

sample app ui 1

sample app ui 2

sample app 3

Screen 4Screen 5Screen 6

sample layout 4

sample app screen 5

sample app screen 6

Screen 7

sample app screen 7

Send comments about this topic to Microsoft

© 2017 Microsoft