Retele Wi Fi Telef

Contents
Mobile broadband
Overview
Overview of mobile broadband
Mobile broadband WinRT API overview
Overview of mobile broadband Windows Runtime APIs
Overview of mobile broadband Windows Runtime APIs
Connection Profile API
Device Services Extension API
Provisioning API
SIM PIN API
SMS API
Subscriber and Device Information API
USSD API
Common tasks for mobile broadband Windows Runtime APIs
Create a MobileBroadbandAccount object
Create a MobileBroadbandDeviceInformation object
Create a MobileBroadbandNetwork object
Determine if a device is PIN-locked
Determine which mobile broadband network is currently connected
Determine which Windows device is being used to connect to the network
Discover whether the network device radio is turned on
Enumerate available mobile broadband accounts
Establish temporary network connectivity
Get information about the currently registered network
Get the IMEI, ICCID, IMSI and telephone numbers for the mobile broadband
device
Know when network connectivity changes
Open the networks list
Receive notification for device information account changes
Receive notification when mobile broadband accounts are added or removed
Retrieve ConnectionProfile objects for a MobileBroadbandAccount
Unlock a device
Best practices for using Mobile Broadband Windows Runtime API
Best practices for handling account arrival and removal events
Best practices for connecting to the mobile broadband network
Mobile operator hardware overview
Using metadata to configure mobile broadband experiences
Overview of using metadata to configure mobile broadband experiences
Account provisioning
COSA/APN database
Introduction to COSA/APN database
APN schema definition
APN elements
APN elements overview
OperatorList
Operator
HardwareIdList (APN element)
HardwareId (APN element)
ConnectionInfoList
ConnectionInfo
TrustedCertificateList
TrustedCertificate (APN element)
APN example
COSA overview
APN database overview
COSA/APN database submission
Planning your desktop COSA/APN database submission
Desktop COSA/APN database settings
Testing your desktop COSA/APN database submission
Submitting the desktop COSA/APN database update
Service metadata
Service metadata overview
Delivering experiences for MVNOs
Developer guide for creating service metadata
Service identifier ownership updates
Service metadata package schema reference
MobileBroadbandInfo XML schema
MobileBroadbandInfo XML schema overview
MobileBroadbandInfo XML schema definition
MobileBroadbandInfo XML elements
MobileBroadbandInfo XML elements list
MobileBroadbandInfo
NetworkConfiguration
MobileBroadbandProfiles
Purchase
Internet
AllowStandardUserPinUnlock
AllowTethering
ProvisioningEngine element
ProvisioningEngine
TrustedCertificates
TrustedCertificate (MobileBroadbandInfo)
SubjectName
IssuerName
MobileBroadbandInfo XML example
PackageInfo XML schema
PackageInfo XML schema overview
PackageInfo XML schema definition
PackageInfo XML elements
PackageInfo XML elements list
PackageInfo
MetadataKey
ModelIDList
ModelID
HardwareIdList (PackageInfo)
HardwareId (PackageInfo)
Locale
LastModifiedDate
MultipleLocale
PackageStructure
Metadata
Relationships
ExperienceID
LanguageNeutralIdentifier
MetadataBuilderInformation
Application
Version
PackageInfo XML data types
GUIDType
PackageInfo XML Example
ServiceInfo XML schema
ServiceInfo XML schema overview
ServiceInfo XML Schema Definition
ServiceInfo XML elements
ServiceInfo XML elements list
ServiceInfo
ServiceCategoryList
ServiceCategory
ServiceName
ServiceDescription1
ServiceDescription2
ServiceNumber
ServiceProvider
ServiceIconFile
ServiceSpecificExtension
ServiceInfo XML Data Types
GUIDType
ServiceInfo XML Example
SoftwareInfo XML schema
SoftwareInfo XML schema overview
SoftwareInfo XML Schema Definition
SoftwareInfo XML elements
SoftwareInfo XML elements list
SoftwareInfo
DeviceCompanionApplications
Package (SoftwareInfo)
Identity (SoftwareInfo)
Applications
Application
DeviceNotificationHandlers
DeviceNotificationHandler
PrivilegedApplications
Package (SoftwareInfo - priviliged applications)
Identity (SoftwareInfo - priviliged applications)
SoftwareInfo XML Example
WindowsInfo XML schema
WindowsInfo XML schema overview
WindowsInfo XML Schema Definition
WindowsInfo XML elements
WindowsInfo XML elements list
WindowsInfo
ShowDeviceInDisconnectedState
LaunchDeviceStageOnDeviceConnect
LaunchDeviceStageFromExplorer
LaunchApplicationOnDeviceConnect
AutoplayHandler
PackageIdentity
Application
Verb
AutoplayType
EnableAutoPlayForRegisteredApps
DesktopAutoplayHandler
WindowsInfo XML Example
Using mbidgenerator.exe to generate hardware IDs
Mobile operator scenarios
Mobile Plans
Mobile Plans description
Mobile Plans overview
Mobile Plans sytem architecture
Mobile Plans scenarios
Mobile Plans features
Mobile Plans catalog
Mobile operator gateway page
Mobile operator web portal
Callback notifications
eSIM download error handling
Account management
Walled garden
Toast notifications
Mobile Plans onboarding
Onboarding overview
Development
Integration
Launch
Appendix
General appendix
Legacy callback notifications
eSIM management on Windows for mobile operators and OEMs
Creating and configuring Internet Sharing experiences
Developing apps using multiple PDP contexts
Developing SMS apps
Introduction to developing SMS apps
SMS device storage limits
Enumerate SMS devices
Get SMS device information
Read received SMS by using the text-mode interface
Run new SMS received background events
Send SMS by using custom character sets
Send SMS by using the text-mode interface
Calculate characters and segments of a draft SMS
Specify mobile telephone numbers
Windows automatically segments long messages
Windows automatically selects optimal character encoding
Set SMS declarations
Enabling mobile broadband experiences using portable hotspot devices
Introduction to enabling mobile broadband experiences using portable hotspot
devices
Communication channels
Personal hotspot communication channels
Network cost information element
PnP-X for mobile broadband apps
Enabling mobile operator notifications and system events
Introduction to enabling mobile operator notifications and system events
Develop an app to handle the MobileOperatorNotification event
Mobile operator notification event technical details
Mobile operator notification scenarios
Integrating Windows with wireless hotspots
Introduction to integrating Windows with wireless hotspots
Get started with a hotspot authentication app
Review the hotspot authentication sample
Update the hotspot authentication sample
Verify background events
Hotspot authentication methods
Captive portals
WISPr authentication
WISPr authentication overview
Provisioning for hotspot authentication
Handling large numbers of SSIDs
Handling the hotspot authentication event
Hotspot 2.0
Provisioning Windows using a website
Understanding and configuring Windows Connection Manager
UWP mobile broadband apps
UWP mobile broadband apps overview
Mobile broadband app scenarios
Account management
App startup
Help and support
Hot spot authentication
Live tile updates
Notifications
Plan purchase
Premium services
Designing the user experience of a mobile broadband app
Introduction to designing the user experience of a mobile broadband app
Design the landing page of a mobile broadband app
Design branding in a mobile broadband app
Design account balance and usage info in a mobile broadband app
Design messages in a mobile broadband app
Design billing pages in a mobile broadband app
Design purchase flows in a mobile broadband app
Design help and support pages in a mobile broadband app
Design services and goods pages in a mobile broadband app
Integrate a mobile broadband app with other Windows components
Mobile broadband
4/13/2022 • 2 minutes to read • Edit Online
Use the docs in this section to learn more about mobile broadband and how to configure mobile broadband
experiences for your customers.
Overview
Using metadata to configure mobile broadband experiences
Windows 8, Windows 8.1, and Windows 10 simplify mobile broadband connectivity for users, while offering
new opportunities for mobile network operators. Users enjoy a streamlined, consistent connection flow.
Windows 8, Windows 8.1, and Windows 10 reduce your need to develop traditional connection management
apps so development resources can be focused on customer interaction, including account management and
value-added services.
Windows 8, Windows 8.1, and Windows 10 present an opportunity to reimagine and streamline the existing
mobile broadband ecosystem.
Earlier versions of mobile broadband hardware required custom Windows drivers. With the current
Mobile Broadband class driver, certified mobile broadband devices have a consistent experience without
the need to install custom drivers. This streamlining presents an opportunity to provide customers with a
“just works” experience while possibly reducing support overhead.
Customized connection management experiences duplicate Windows functionality and have different UX
models than the rest of Windows. These connection managers have to be deployed and maintained by
the operator and their ISV partners.
The need for a custom driver and for custom connection management software meant that USB-based
mobile broadband devices need to also perform a USB storage function in order to deliver that custom
software to the user’s PC. This dual-mode device concept often requires the user to switch between
storage mode and modem mode, adding an extra task before the user can successfully connect to the
network.
Highlight unique services and capabilities that make your customer experience unique. Windows 8,
Windows 8.1, and Windows 10 provide the opportunity to focus on the customer connection and to
highlight your unique value-add through a UWP mobile broadband app, previously known as a mobile
operator app.
Key scenarios
This section describes key scenarios that are part of the current mobile broadband experience that you can
choose to enable. Consider each of these scenarios in the context of your business models when you plan which
Windows components your app must interact with.
Plan purchase
Connecting an active device
Operator notifications and system events
Providing accurate usage and plan data
Internet sharing
Wi-Fi hotspot authentication
Displaying account information to the user
Enabling other devices and app scenarios
Plan Purchase
A seamless plan purchase experience makes it easier for users to buy connectivity and enables the operator to
accept new customers without the need for support or retail-store intervention. There are two purchase plan
options:
The mobile broadband app and service metadata is already installed on the PC. This could happen for
PCs that have embedded mobile broadband hardware where the OEM has preloaded the mobile
broadband app and service metadata on the Windows image or an alternate Internet connection is
available.
The mobile broadband app and service metadata is not installed on the PC. This could happen when you
plug in a hardware dongle and an alternate Internet connection is not available.
Regardless of the plan purchase option, there are various sub states based on the state of the SIM or CDMA
mobile broadband device. Cold SIMs (no associated plan), warm SIMs (ready to accept a plan), and hot SIMs
(already active with a plan) will likely present a different experience based on how you want to structure the
purchase flow.
Mobile broadband app is already installed or an alternate Internet connection is available
In this case, an embedded device, mobile broadband app, and service metadata is probably already installed on
the PC with a SIM before the user attempts to activate service. Another possibility is that the user does not yet
have the mobile broadband app but has an alternate Internet connection to download the app. The following
steps occur automatically when the SIM is inserted:
1. The mobile broadband service reads the International Mobile Subscriber Identity (IMSI), the Integrated
Circuit Card ID (ICCID) for GSM networks, the provider ID (SID) for CDMA networks, or the provider name
for CDMA networks and generates a set of Hardware IDs (HWIDs).
Note This step is only necessary if the OEM has not inserted the SIM and preloaded the mobile
broadband app and service metadata.
2. When the PC is connected to the Internet, the HWIDs are sent to Windows Metadata and Internet Services
(WMIS). WMIS identifies the operator and returns the appropriate service metadata package.
3. Windows uses the service metadata to identify and retrieve the mobile broadband app from the
Microsoft Store. The app is installed automatically. In Windows 8.1 and Windows 10, the app is not
pinned to the Start screen.
4. Your operator logo and name appear in the Networks list in Windows Connection Manager. The user can
connect to your network.
5. Windows Connection Manager tries to connect by using the network profile configuration information in
the service metadata. The next step depends on the result of the connection:
If the initial connection is successful and Internet connectivity is available, nothing further happens.
The user has previously purchased service and has an active account.
If the initial connection is successful but Internet connectivity is not available, the mobile
broadband app starts and the user is asked to for a purchase plan.
If the initial connection fails and the error code indicates that network service has not yet been
purchased, the mobile broadband app started. The app can determine the appropriate response.
For example, if the error code is due to lack of connectivity, the app may need to direct the user to
complete the purchase by telephone or by connecting to an alternate Internet connection.
If the initial connection fails with another error code, Windows connection manager notifies the
user about the error. The mobile broadband app is not started.
6. When the mobile broadband app opens, you should ensure that the app is written to make a secure
connection to the backend billing infrastructure so that the user can purchase a subscription. This process
is proprietary for each operator and Microsoft is not involved in the purchase process. The app
establishes this connection through a limited mobile broadband connection (that the operator network
needs to enable) or over an alternate Internet connection, such as Wi-Fi.
7. When plan purchase is complete, the mobile broadband app generates a metadata provisioning file that
is passed to the provisioning agent. This configures Windows with information about the plan that the
user has purchased.
Impor tant The steps above also apply to an external device that is attached to the PC with an alternate
Internet connection.
Mobile broadband app is not installed and no alternate Internet connection is available
An external mobile broadband device, such as a hardware dongle, can be inserted into PCs that may not have an
alternate Internet connection available and may not have a mobile broadband app installed. The following steps
describe how a plan purchase experience can be built to work around limitations in this scenario:
1. As soon as the mobile broadband hardware is detected, the Windows Mobile Broadband service reads
the IMSI, the ICCID, the provider ID, or the provider name and generates a set of HWIDs that represent the
each value read from the device. The Windows Mobile Broadband service listens for mobile broadband-
related events.
2. When the user clicks Connect , the HWID values are used to locate the connection settings in the
Windows APN database as follows:
If the initial connection is successful and Internet connectivity is available, nothing further happens.
The user has previously purchased service and has an active account.
If the initial connection is successful but Internet connectivity is not available, the user is taken to
the URL specified in the APN database for this HWID range.
If the initial connection fails, Windows Connection Manager notifies the user about the error. Your
website should assist the user in purchasing a plan.
3. After the user completes the plan purchase, the website generates a metadata provisioning file and
passes it to the provisioning agent. This configures Windows with basic information about the plan that
the user has purchased. Depending on the network structure, one of the following occurs:
The user is granted Internet access on the current connection.
The provisioning file includes instructions to disconnect and reconnect to the same network or a
different network, which will provide Internet access.
At this point, the user is online. Now that an Internet connection is available, Windows detects the mobile
broadband hardware and downloads and installs the service metadata and the mobile broadband app.
4. The HWIDs that are calculated from the SIM or mobile broadband device are sent to WMIS. WMIS
identifies the operator and returns the appropriate service metadata package.
5. Windows uses the service metadata to identify and retrieve the associated mobile broadband app from
the Microsoft Store. The app is installed automatically and registered for background events. In
Windows 8.1 and Windows 10, the app is not automatically pinned to the Start screen. Registering for
background events allows the app to do things such as reacting to local data usage counters, receiving
operator SMS messages, connecting to Wi-Fi hotspots, and handling entitlement checks.
6. When a background event occurs, the app generates a more complete provisioning file, if needed, and
passes it to the provisioning agent. This configures Windows with information about the plan that the
user has purchased.
Connecting an Active Device
When a device with an active mobile broadband plan is attached to a PC, the experience is similar to that for
purchase, except that the attempted connection leads to the Internet. Windows will not start the mobile
broadband app for mobile broadband or connect to the mobile operator’s website. Instead, the app is installed
in the background.
1. When the mobile broadband hardware is detected, the Mobile Broadband service reads the IMSI, the
ICCID, the provider ID, or the provider name and generates HWIDs.
2. When the user clicks Connect , the HWID values are used to locate appropriate connection settings within
the Windows APN database. For an active device, the connection is successful and Internet connectivity is
available.
3. At this point, the user is online. Now that an Internet connection is available, Windows will detect the
mobile broadband hardware and download and install the service metadata and the mobile broadband
app.
Windows 8.1 and Windows 10 can connect to an operator network during Windows Setup if a mobile
broadband device with an active plan is attached to the PC. The mobile broadband network appears in the
Networks list during Windows Setup along with Wi-Fi networks. Similar to the process for connecting an active
device, a HWID is generated based on the detected mobile broadband hardware and is used to locate
appropriate connections settings within the Windows APN database.
Operator Notifications and System Events
In order to keep users informed about their account status, the mobile broadband app needs to perform some
activities even when the user is not interacting with it. These activities include responding to operator SMS or
network-initiated USSD messages, notifying the user that they are approaching their data limit, notifying the
user that their data plan has expired, and notifying the user of their roaming status. Incoming SMS messages are
available to privileged apps that have been granted access to the SMS capabilities on the PC by the service
metadata package.
Some SMS messages come directly from the mobile network operator and should be displayed to the user by
using the mobile broadband app. The mobile broadband app can invoke a toast notification when it receives an
operator SMS message.
For operator messages that are not intended to be seen by the end-user, the mobile broadband app can process
these and act appropriately. The Windows Notification Service provides the most efficient direct-to-app
notification channel, but Windows also supports the use of incoming SMS and Unstructured Supplementary
Service Data (USSD) notifications from the mobile broadband network.
More information about handling SMS messages can be found in Developing SMS apps. More info about
operator notifications can be found in Enabling mobile operator notifications and system events.
1. The service metadata declares that the mobile broadband app wants to access operator notifications. A
private background event is created and the app is registered for operator notification events at the time
that it is installed.
2. When the app applies provisioning metadata, it includes a description of all SMS and USSD messages
that should be considered operator messages.
Upon receipt of an SMS or USSD message, the Mobile Broadband service compares the message to the
description provided in the provisioning metadata. If parsing rules have been included, the Mobile Broadband
service also interprets the message and updates the information about data usage.
If the message is a match, the System Event Broker is notified to invoke the private background event for that
mobile broadband app. If not, the System Event Broker is notified to invoke the public SMS event.
Some examples of what the operator could include in the mobile broadband app for responses to incoming
SMS messages include the following:
Immediately syncing current data usage
Displaying a notification to the user
Updating the app’s live tile
Retrieving and applying updated provisioning metadata
Note Windows 8, Windows 8.1, and Windows 10 do not include an SMS app with the operating system so a
mobile broadband app or a third-party SMS app to which the operator gives privileged access is needed in
order to display SMS messages to the user.
Note Building a mobile broadband app with SMS support is necessary to show notification UI to the end user
when text messages are received, which may be required to conform to regulatory requirements or best
practices in certain markets.
SMS functionality is available to mobile broadband apps, UWP apps that are given privileged access to mobile
network operators, UWP apps that are given privileged access by the PC OEM (if the mobile broadband device is
embedded in the PC), or the mobile broadband device IHV (if the mobile broadband device is removable).
Mobile network operators and the PC OEM (or the mobile broadband device IHV) specify privileged apps
through service metadata. For more information about service metadata, see Using metadata to configure
mobile broadband experiences.
Providing accurate usage and plan data
Windows provides Data Usage and Subscription Manager APIs that the mobile broadband app can use to
describe the user’s data plan. The mobile broadband app can update this API with information about the data
plan size, metered vs. non-metered plan, and an updated data usage value from the operator’s network.
Windows will check the data usage information that has been set for the user by using these APIs and change
the behavior of core features. For example, Windows Update will only auto-download critical updates when the
user is using a metered network. Usage information is also accessible to third-party apps via the Data Usage
and Subscription Manager APIs.
The following is a walkthrough of the various features that the mobile broadband app can choose to utilize in
order to keep the user informed of their data usage.
1. Local data counters estimate that usage on the profile has changed by more than 5 percent of the user’s
data limit since the last update from the operator. This 5 percent increment is hard-coded and the mobile
broadband app can make use of background events to wake itself up and react to each 5 percent
increment.
2. Data Usage and Subscription Manager is a Windows component that does this 5 percent usage
increment tracking. It notifies the System Event Broker to trigger a background event for each 5 percent
increment in the local estimated usage.
3. The System Event Broker invokes the mobile broadband app to handle the background event. (Other
triggers, such as an incoming notification, might cause this to occur.) The mobile broadband app can
choose what to do when it is invoked for this purpose.
4. A best practice is for the app to handle this event by retrieving the most current usage information from
the operator’s billing infrastructure to validate how much usage the user has actually gone through. This
is likely an asynchronous operation over the network and the mobile broadband app needs to be able to
react to delays in getting this information from the operator’s billing infrastructure. If there is a significant
delay in the data usage tracking, the mobile broadband app can query the local data counters to fill the
gap between the current time and the most recent data.
5. When the web query to the operator’s billing infrastructure completes, the mobile broadband app can
apply updated provisioning metadata that describes the most up-to-date usage information available
back to Windows.
6. The app publishes the updated information through the Data Usage and Subscription Manager APIs.
7. Windows components and third-party apps on the PC can access this usage information by using the
Windows.Networking.Connectivity.ConnectionProfile class. Apps can adjust their behavior
accordingly. For example, the app can use a lower quality video stream on metered networks.
Internet sharing
Mobile broadband provides users with connectivity wherever they go. However, not every device has a mobile
broadband device. Windows 8.1 and Windows 10 enable users to share their mobile broadband connectivity
over Wi-Fi with friends and family using different devices.
Customers can turn on Internet Sharing in PC settings. They can also change the SSID, the password for the Wi-
Fi network, and see how many people are sharing the connection.
For customers that want to use the Mobile Broadband connectivity on another one of their devices, Windows
makes it even easier. Simply open Networks list on a WiFi-capable PC running Windows 8.1 or Windows 10,
click the SSID of the sharing device, and then click Connect . Windows will handle all the device configuration
and inter-device communication.
The following is a walkthrough of the various features that you can configure and manage how Internet Sharing
works on Windows 8.1 and Windows 10.
1. You can choose whether or not your customers are able to use Internet Sharing by uploading a service
metadata package that is automatically downloaded and installed on the PC.
2. Using service metadata, you can also select whether the mobile broadband app runs an entitlement
check against the service to see if a specific customer has purchased a data plan that supports tethering.
3. The mobile broadband app registers for a background event to run the entitlement check whenever the
user enables Internet Sharing and instructs Windows on whether or not to allow it.
4. As part of the provisioning metadata, you can specify which PDP context and APN to use for the shared
data traffic, as well as the maximum number of devices that can share the connection at one time.
5. Using the updated local data usage APIs, you can create an experience in your mobile broadband app to
show customers how much data has been used by other devices that shared their mobile broadband
connection.
For more information about Internet Sharing, see Creating and configuring Internet Sharing experiences.
Wi-Fi hotspot authentication
As part of the provisioning metadata, the mobile broadband app can describe the hotspots that a user can
authenticate using their operator-supplied credentials. These may include WISPr 1.0 hotspots or encrypted
hotspots using EAP-SIM, EAP-AKA, or other supported EAP methods.
Windows will then automatically offload data traffic onto these hotspots when in range. You may want to do this
in order to offload network traffic from your cellular data networks to land-line-based Wi-Fi locations. In some
cases, the Wi-Fi hotspot may have increased speeds or better coverage than the cellular data network for that
location.
You can also make a hotspot less preferred than the mobile network, making it available for Windows to use
when the mobile broadband connection is not available but not used for data offload.
Setup
The mobile broadband app generates a provisioning file that contains the SSIDs and authentication
mechanism for WiFi hotspots that user can authenticate. This avoids the user having to manually enter
this information.
The provisioning agent parses the provisioning file and provides the necessary information to Windows
Connection Manager. Windows automatically connects to these networks when they are available.
Credential generation
If the mobile broadband app generates or retrieves WISPr credentials in a proprietary manner during the
connection, the provisioning metadata includes a reference to the app, rather than providing specific credentials.
If specific credentials are included, this phase is skipped.
1. The captive portal website in the Wi-Fi hotspot includes a challenge from the Wireless Internet Service
Provider roaming (WISPr) protocol.
2. If static credentials were not provided, Windows Connection Manager notifies System Event Broker that
hotspot authentication is occurring. Otherwise, Windows Connection Manager proceeds directly to
authentication.
3. For proprietary authentication schemes, the System Event Broker invokes the mobile broadband app to
generate credentials.
4. The app generates credentials using its proprietary mechanisms. These may or may not involve
interaction with network resources, or with the mobile broadband interface. The app ultimately takes one
of the following actions:
Provide Credentials -- The app can generate credentials for this network, and then return them
to Windows Connection Manager. Windows Connection Manager authenticates to the hotspot
using WISPr.
Cancel Connection -- The PC should not be connected to this network. Windows Connection
Manager ends the connection.
Cancel Authentication -- The app has been authenticated by using an alternate method.
Windows Connection Manager will neither authenticate nor disconnect.
Interact with User -- The app is brought to the foreground. This is selected when user
confirmation is needed, such as a pay-per-connection hotspot. The app should ultimately take one
of the previously listed actions after consulting the user.
Authentication
When credentials are supplied by the mobile broadband app (dynamic WISPr credentials) or statically defined as
part of provisioning (static WISPr credentials, EAP credentials), Windows delivers these credentials to the Wi-Fi
hotspot.
The configuration information provided by the mobile broadband app to the connection profile in Windows
Connection Manager determines how credentials are obtained and delivered. The delivery is outlined in the next
steps:
1. When the user is in range of the Wi-Fi hotspot, Windows Connection Manager replies with credentials
that are statically defined by using provisioning metadata. This data can be generated by the mobile
broadband app, or through a trusted website.
2. The Wi-Fi hotspot verifies the credentials with the operator and then permits the PC to access the
Internet.
Displaying account information to the user
The best way for you to interact with your subscribers in Windows 8, Windows 8.1, and Windows 10 is by using
a mobile broadband app. This app is developed by you to meet your key scenarios around subscriber
interaction.
1. Windows determines which MNO or MVNO the subscriber belongs to when a mobile broadband device
is detected on the PC. The operator’s service metadata is matched and downloaded using by WMIS.
2. The service metadata links the mobile broadband app to the corresponding network entry in Windows
Connection Manager.
3. Windows Connection Manager shows the operator’s logo, operator name, and a View my account link.
4. When the user clicks the link, the mobile broadband app is opened. The app can be developed to retrieve
the most up-to-date information available from your billing system.
5. Optionally, the app can query the local data counters for an estimate of usage since the billing system
was last updated. The app can use this data to display a near-real-time approximation of the user’s usage.
6. More scenarios can be developed into the mobile broadband app. For detailed examples and user
experience guidelines of key scenarios the mobile broadband app can enable, see Designing the user
experience of a mobile broadband app.
Enabling other devices and app scenarios
Windows 8, Windows 8.1, and Windows 10 provide a rich set of development tools and a flexible development
platform that you can advantage of by creating apps that highlight the value added services that make them
unique.
Privileged apps
Mobile Broadband APIs and interfaces, including Account Provisioning and SMS, are restricted to mobile
broadband apps. A list of privileged apps that have access to these privileged APIs must be declared in the
service metadata package that is submitted to the Windows Dev Center Dashboard.
Multiple PDP contexts
Windows 8.1 and Windows 10 support multiple PDP contexts to be active at the same time. This allows mobile
operators to provide differentiated scenarios to their customers. For more information about the scenarios that
are enabled by using multiple PDP contexts, see Developing apps using multiple PDP contexts.
Wireline operators
You can use PnP-X to expose non-mobile broadband devices as a UWP device app.
Devices such as DVRs, gateway routers, mobile hotspots, and phones can (while connected to the same Wi-Fi or
LAN network as the Windows 8, Windows 8.1, or Windows 10 PC) use PnP-X to make Windows 8, Windows 8.1,
and Windows 10 aware of their presence. Device metadata is downloaded for those devices based on their
device properties and a UWP device app developed by you is automatically downloaded. You can reference this
app for these devices so that a single mobile broadband app can manage mobile broadband as well as these
additional devices.
How it works
The components that support the key scenarios for mobile broadband in Windows 8, Windows 8.1, and
Windows 10 are discussed in this section. They are divided between those that are part of the Windows
operating system and those that are part of the service metadata or mobile broadband app.
Windows components
The following components are part of Windows 8, Windows 8.1, and Windows 10:
Provisioning Agent
Data Usage and Subscription Manager
Windows Connection Manager
Local Data Counters
Mobile Broadband Service
Mobile Broadband Class Driver
System Event Broker
Windows Metadata and Internet Services
Microsoft Store
Provisioning Agent
The Provisioning Agent provides an interface for you to configure Windows with your network settings. The
Provisioning Agent accepts an XML file that describes the desired configuration.
You can provide the XML file in one of the following ways:
A signed XML file provided by a website to the window.external.msProvisionNetworks function on a
Windows 8, Windows 8.1, or Windows 10 computer running at least Internet Explorer 10 (or another
supporting browser).
An XML file (either signed or unsigned) provided by an app to the
Windows.Networking.NetworkOperators.ProvisioningAgent.ProvisionFromXmlDocumentAsy
nc function.
For more details about the format and content of the provisioning file, see Using metadata to configure mobile
broadband experiences.
Data Usage and Subscription Manager
The Data Usage and Subscription Manager tracks details about the user’s accounts. The stored cost information
about the currently connected network is available to all UWP apps. You can update this information by using
the Provisioning Agent.
If the carrier requests it, the Data Usage and Subscription Manager uses local data counters to trigger a
background event when 5 percent of the data limit has been used. The System Event Broker delivers this
background event and the mobile broadband app can use the event as a trigger to update billable usage.
Windows Connection Manager monitors available networks across Wi-Fi, mobile broadband, and Ethernet. It
makes automatic connect and disconnect decisions based on the available networks. The Provisioning Agent
enables you to define the relative priority between networks that you own. However, the user can manually
connect to any network. Windows Connection Manager uses the user’s manual actions to influence future
automatic connection choices.
Windows Connection Manager also manages post-connect authentication with Wi-Fi hotspots that support
WISPr 1.0. If static credentials have been stored for the Wi-Fi hotspot, Windows Connection Manager will
authenticate automatically. If dynamic credentials are required, Windows Connection Manager triggers a
background event by using System Event Broker. The mobile broadband app should then generate appropriate
credentials and deliver them to Windows Connection Manager in order to complete the authentication process.
For more details, see Integrating Windows with wireless hotspots.
Local Data Counters
Local data counters track the amount of data that is sent and received on a network interface over time. This
information appears to the user in multiple locations:
The App Histor y tab in Task Manager
(Optionally) Windows Connection Manager in the expanded view of the Wi-Fi or mobile broadband
network. Users can decide whether to show or hide this estimate for a particular network. By default, it is
shown for Mobile Broadband networks and hidden for Wi-Fi networks. However, if Windows detects that
a mobile broadband device is installed, it will hide estimated data usage in Windows Connection
Manager for the corresponding Mobile Broadband network. This is because there is an assumption that if
you have created a mobile broadband app, you will want to control the data usage value that is displayed
to the user. The best place to do that is inside the mobile broadband app. Users can choose to override
this behavior and show estimated usage for the network at any time.
Local data counters are also available programmatically by using the following APIs:
The Windows.Networking.Connectivity.ConnectionProfile.GetNetworkUsageAsync function
provides the data usage over a specified time period.
The Windows.Networking.Connectivity.ConnectionProfile.GetConnectivityInter valsAsync
function provides the connect timestamps and durations when a network interface is used.
Local data usage information serves as an estimate and a guide for the user. Windows cannot account for
unbilled traffic or for usage on other devices that share the same data limits. For example, family plans using the
same SIM on different devices. Mobile broadband apps should use local data counters only to approximate
usage since the last sync with your billing system. For data usage that has already been processed, the billing
system should be considered authoritative.
Mobile Broadband Service
The Mobile Broadband service is a Windows service that manages communication between the Mobile
Broadband APIs and a mobile broadband device. The service can interact with any mobile broadband device
whose driver conforms to the Windows Mobile Broadband Driver Model.
The service also reads the SIM of a newly inserted device and initiates the process that retrieves the service
metadata and the mobile broadband app that corresponds to the attached mobile broadband device.
Mobile Broadband Class Driver
The Mobile Broadband class driver reduces the burden on device manufacturers to deliver a custom driver for
their specific mobile broadband device. Any mobile broadband interface that manifests as a USB device and
complies with the USB Implementers Forum (USB-IF) Network Control Model (NCM) 2.0 specification will be
managed by the Mobile Broadband class driver and does not require additional drivers to be downloaded or
installed.
The Mobile Broadband class driver conforms to the Windows Mobile Broadband Driver Model and provides full
functionality to the Mobile Broadband service. It also supports custom extensions, which will be exposed directly
to the mobile broadband app. For more information, see Mobile operator hardware overview.
System Event Broker
The System Event Broker manages background events. Apps, including the mobile broadband app, can register
to receive background events in order to respond to changes in system state. Events that could be of interest to
the mobile broadband app include:
Network status change – Network connected or disconnected or Internet connectivity changed on a
network.
Account status change – End of billing cycle or 5 percent estimated data usage increments.
Wi-Fi hot-spot authentication – Attempting to connect to a public Wi-Fi hotspot and credentials are
needed.
Incoming operator notification – SMS/USSD message that matches certain parsing rules that
describe the SMS/USSD as coming from the operator.
Incoming SMS – SMS message received that does not match operator-defined parsing rules.
Incoming USSD – USSD message received that does not match operator-defined parsing rules.
Developers should be aware that a strict limit is placed on the amount of CPU time that an app may consume
while it is not active. Although these limits are relaxed for some events, apps must always minimize the
resources that they consume while the system is in a low-power state or while another app is running.
Windows Metadata and Internet Services
Windows Metadata and Internet Services (WMIS) is a cloud-based Windows service that delivers customizations
to Windows from third parties that participate in the Windows device ecosystem. For a mobile broadband
device, WMIS delivers the service metadata package. This provides the basic information that Windows needs in
order to retrieve the mobile broadband app from the Microsoft Store, allow connectivity to the network for the
first time, and display appropriate branding elements in Windows Connection Manager.
Microsoft Store
The Microsoft Store is the primary way that UWP apps are delivered to Windows 8, Windows 8.1, and
Windows 10 PCs. For a mobile broadband app, the app package is retrieved from the Microsoft Store whenever
Internet connectivity is available after the device is connected. The app package is automatically installed and
available to the user at that point. In Windows 8.1 and Windows 10, the app is available in All Apps but is not
automatically pinned to the Start screen.
For more information about UWP device apps, see UWP device apps.
Note Although enterprises can side load UWP apps under certain conditions, these will not be covered in this
document.
Operator metadata
Metadata about operators is provided in three different ways for Windows 8 and Windows 10 as described
below. Each of the metadata options targets a different set of customers. Understanding how the three types of
metadata are delivered and what information is used in each will help you better address your customers.
For more information about the operator metadata, see Using metadata to configure mobile broadband
experiences.
Windows APN database
The Windows APN database is present on all Windows 8, Windows 8.1, and Windows 10 PCs. The database is
periodically updated by using Windows Update to help ensure accuracy of the connectivity information. Updates
to the database are doing through servicing requests by you. The APN database provides information to
Windows about how to connect to the network if it encounters a Mobile Broadband device, including the APNs
to which it should attempt a connection and the URL to which the user should be directed if no Internet
connectivity is available.
This information is intended to get customers online within seconds of connecting a mobile broadband device. It
should enable them to purchase service immediately by using a Web browser or get online immediately if they
have already purchased service.
For information on submitting updates to the Windows APN database, see COSA/APN database submission.
Service metadata
Service metadata is delivered to any user after they connects a mobile broadband device. Service metadata is
always automatically downloaded as long as the user has any form of Internet connectivity, including metered
mobile broadband or roaming networks.
This information enables customers to have a richer experience by allowing you to add branding elements for
Windows Connection Manager, referencing a mobile broadband app that is automatically acquired from the
Microsoft Store, and having the most current mobile broadband settings for getting online for purchase or
Internet connectivity. Windows will periodically check that it has the latest service metadata package from
WMIS.
The service metadata package is delivered to customers only when a mobile broadband device from the
specified operator is detected on the PC. Information in this package overrides the content of the APN database,
whenever it’s present. For more information on the service metadata package schema reference, see Service
metadata package schema reference.
For instructions on how to create a service metadata package, see Developer guide for creating service
metadata.
Provisioning metadata
Provisioning metadata is delivered to the PC by either the operator’s website or the mobile broadband app after
the subscriber has purchased service. Provisioning metadata is packaged as an XML file and is processed by the
Provisioning Agent to modify the network settings of the PC.
Provisioning metadata can be specified for each subscriber’s individual requirements. The provisioning
metadata may also be updated with much higher frequency by using the mobile broadband app. Information in
the provisioning metadata overrides the contents of the APN database and the service metadata. This is because
it tends to be the most specific and tailored information about the subscriber.
Overview of mobile broadband Windows Runtime
APIs
The following table lists the APIs for authoring a mobile broadband app.
API DESC RIP T IO N
Connection Profile API Provides information about the connection status (for
example, to the Internet)
Device Services Extension API Enables device-specific extensions, such as SIM Toolkit
and Preferred Roaming List (PRL) download.
Provisioning API Enables you to provision Windows with account

provisioning data and data usage information.
SIM PIN API Enables you to enable, disable, or change the SIM PIN.
SMS API Provides functions that are required to implement an

SMS client.
Subscriber and Device Information API Provides subscriber information for the SIM and device
information for the mobile broadband device.
USSD API Enables you to establish an Unstructured

Supplementary Service Data (USSD) session with a
network (client and network initiated).
The following sections are available in this topic:

Mobile Broadband Account API
Network Account IDs
Mobile Broadband Account API

Because it has methods that can be used to get personally identifiable information about the customer and
change the network settings on mobile broadband devices, the Mobile Broadband Account API is a privileged
API. This means that most UWP apps cannot call its methods without getting an “access denied” error. To be able
to call this API, a UWP app must meet the following criteria:
The app must have a device metadata or service metadata package associated with it, and it must be
listed in the PrivilegedApplications XML element of the SoftwareInfo.xml file inside the package. The
package does not have to be exclusive to the application; it is possible for any particular UWP app to be
listed in the PrivilegedApplications element of several packages. That package must be associated with
the service provider for a mobile broadband device that has been active at least once on the computer, so
that it has been installed.
The application’s appxmanifest file needs a <DeviceCapability> entry for the Mobile Broadband
Account API. You can do this by adding the following XML element as a child of the <Capabilities>
element in the application’s appxmanifest file:
<DeviceCapability Name="BFCD56F7-3943-457F-A312-2E19BB6DC648" />
For more information on the <Capabilities> element, see App Manifest File For Windows 8.
Note Applications that are not UWP apps (for example, Microsoft Win32 services or desktop apps) have
unrestricted access to the Mobile Broadband Account API. This is because these applications can use existing
Win32 and Component Object Model (COM) APIs to get full access to the mobile broadband network. These
APIs cannot be used from UWP apps.
Network Account IDs

A network account ID is a unique identifier for a mobile broadband account. It provides a unified ID that can be
used without needing to know whether the ID comes from a GSM, CDMA, or WiMAX network. Windows
generates network account IDs whenever it encounters a hardware-provided network subscription identifier
that it has not encountered before. The following list identifies the network account ID for each supported
network type:
GSM networks: The SIM’s ICCID is used to differentiate between subscriptions.
CDMA networks: The mobile identification number (MIN) is used.
When Windows encounters one of the preceding network types for the first time, it creates a new network
account ID and maps it to a SHA-256 hash of the hardware-provided subscription identifier, and then stores
both of them in the registry. Conversely, if Windows finds the hash of the hardware-provided subscription
identifier in the registry, it uses the network account ID that’s associated with that hash. Network account IDs
should be globally unique (they are based on GUIDs), but because what is stored is a hash of the hardware-
provided identifier, the network hardware must be present when trying to map a network account ID back to the
ICCID or MIN that it was generated from.
Impor tant Even though getting the ICCID from a network account ID requires access to the computer and the
network device that are used to map them together, network account IDs do uniquely identify individual users.
Therefore, we recommend that you follow your organization’s policies for dealing with personally identifiable
information when you're working with them.
Network account IDs are segregated by mobile network operator (MNO), so that if an end user has both
Provider1 and Provider2 mobile broadband devices and their corresponding mobile broadband apps are
installed, the Provider1 app will not be able to use any Provider2 network account IDs, and vice versa. The
function that returns all network account IDs will return only the IDs of the network accounts for the MNO
whose application is calling the function. An attempt to use a network account ID that belongs to a different
MNO will result in an “access denied” error.
Note Apps that are not UWP apps (for example, Win32 services or desktop apps) have access to all network
accounts regardless of network service provider.
Related topics
Connection Profile API
The connection profile API, which is part of Windows.Networking.Connectivity.NetworkInformation ,

provides connectivity, usage, and data plan information for established network connections. The connection
profiles associated with a given mobile account can be retrieved by using the MobileBroadbandAccount API.
The connection profile API allows your mobile broadband app to query several properties of the network
connection on the mobile broadband interface, including the following:
GetNetworkConnectivityLevel Indicates whether the network is connected and if the network
provides internet connectivity.
GetSignalBars Indicates the current number of signal bars displayed by the Windows UI for the
connection.
GetNetworkUsageAsync Provides bytes sent, bytes received, and connectivity times for a connection
profile.
This API also includes a status change event that notifies the application whenever connectivity on the operator’s
interface has changed. For more info about the NetworkStatusChanged event, see
NetworkStatusChangedEventHandler delegate .
Related topics
List of mobile broadband Windows Runtime APIs
Network Information sample
NetworkStatusChangedEventHandler delegate
Device Services Extension API
Windows-compliant mobile broadband devices project each supported feature as a device service. Examples of
services are IP Connectivity (ability to connect to or disconnect from a mobile broadband network), Phonebook,
SIM Toolkit, SMS, and USSD. Each device service has a corresponding GUID. All control messages and non-IP
packets that are exchanged between the mobile broadband generic driver and the device carry the GUID to
identify the service that is associated with the request. Command identifiers (CIDs) and status indication codes
are defined under a service’s GUID namespace. For example, Phonebook and SIM Toolkit might both share the
same CID code, but they are distinguished by the device service GUID that is exchanged in the request.
Any device services that are not natively implemented by the Windows wireless platform can be accessed by the
Device Services Extension API. This API provides a direct pipe for the independent hardware vendor (IHV)
software to access functionality on the device. This pipe provides a conduit through the WWAN service and
mobile broadband generic driver to the device, as shown in the following diagram:
The Windows wireless platform supports APIs for the following app functions:
Enumerate device services
Open/close device services
Send control commands to a specific device service
Send data to (or receive data from) a specific device service
Register for “unsolicited” device events from a specific device service
Related topics
Provisioning API
By using the Provisioning API, you can provision the Windows-based computer with required connection
profiles for mobile broadband and Wi-Fi, and can configure the cost that is associated with the mobile
broadband profiles. Provisioning information is contained in an XML document, as described in Using metadata
to configure mobile broadband experiences. You typically call this API after subscription purchase or to update
provisioning information on the computer.
You can also call the Provisioning API at any time to update the information that is provided to Windows. This is
usually done when the mobile broadband app retrieves updated cost and plan status from the operator’s server,
but it can also be done when Wi-Fi hotspot networks or the mobile broadband network configuration must be
updated.
For more information about the Provisioning API, see ProvisioningAgent class .
Related topics
SIM PIN API
By using the SIM PIN API, your mobile broadband app can support operations that are related to the SIM PIN
and the Pin Unlock Key (PUK).
For more information about the SIM PIN API, see Mobile Broadband API Interfaces.
Related topics
SMS API
Windows provides the SMS API to receive operator overage and roaming notifications, send and receive user-
to-user messages, and control the messaging configuration.
The SMS API supports the following use cases:
Send new SMS and new operator SMS notifications.
Send and read messages in text mode and Protocol Data Unit (PDU) mode (binary).
Get messages from the message store of the mobile broadband device.
Delete messages from the message store of the mobile broadband device.
Get properties of the mobile broadband device (account phone number, Global System for Mobile
communication [GSM] or Code-Division Multiple Access [CDMA], and similar information).
For more info about the SMS API, see Windows.Devices.Sms namespace .
Related topics
Subscriber and Device Information API
The Subscriber and Device Information API provides the following subscriber and device information to the
mobile broadband app:
Device name Name of the device.
Technology GSM, CDMA, and similar information.
Subscriber and device ID Subscriber and device identification information (IMSI, IMEI, electronic serial
number [ESN], and similar information).
Manufacturer Manufacturer of the device.
Mobile number Mobile number associated with the device.
SIM ID ICCID associated with the SIM.
Device capabilities Device interface capabilities, such as GSM Band Class and CDMA Band Class.
Firmware and hardware version Firmware and hardware version.
For more info about the Subscriber and Device Information API, see
Windows.Networking.NetworkOperators namespace .
Related topics
USSD API
The Windows USSD API is an abstraction of the underlying Unstructured Supplementary Service Data (USSD)
protocol, which hides most of the details to simplify app development. This API enables mobile broadband apps
to send USSD strings to a new or existing session or to cancel an existing session. This API supports notifications
from the network that may or may not require a response. A response is required for a network-initiated USSD
request or when further information is needed after a mobile-initiated operation.
For more info about the USSD API, see Windows.Networking.NetworkOperators namespace .
Related topics
Create a MobileBroadbandAccount object
Because the MobileBroadbandAccount objects represent network accounts, a network account ID is needed
to create such an object. When a mobile broadband app is started from the network list, it receives the network
account ID to use as a parameter to the tile launch contract.
If the app is activated directly from its tile, there are no parameters associated with the tile launch contract, and
you must get the value of the AvailableNetworkAccountIds static property of the
MobileBroadbandAccount class. This returns a read-only collection of strings, in which each string is a single
account ID. If this method returns a collection that has a single string, you don’t need to take any further action.
The following JavaScript code example shows how to do this:
var myNetworkAccountId;
var allNetworkAccountIds =
Windows.Networking.NetworkOperators.MobileBroadbandAccount.availableNetworkAccountIds;
if (allNetworkAccountIds.size == 1)
{
myNetworkAccountId = allNetworkAccountIds[0];
}
If the returned collection contains more than one string, you will need input from end user who is running the
application. One way is to iterate through the collection, creating a MobileBroadbandAccount object for each
account ID in the collection, and then use a property of the object (for example, the telephone number) to
populate a list box control. This control is presented to the end user, and after the user makes a selection, all
other MobileBroadbandAccount objects can be released.
After you have the account ID, call the CreateFromNetworkAccountId static method of class
MobileBroadbandAccount . The following code example shows how to do this by using JavaScript:
var myNetworkAccountId = "{95499FEF-1579-4547-A0BE-FF271ADBBE76}";

var myNetworkAccountObject =
Windows.Networking.NetworkOperators.MobileBroadbandAccount.createFromNetworkAccountId(myNetworkAccountId);
MobileBroadbandAccount.AvailableNetworkAccountIds returns an
empty list
If your app is not trusted, the property returns an empty collection instead of throwing an exception because
users can have accounts from more than one network operator on their computer. The
AvailableNetworkAccountIds property returns only those account IDs that the app’s metadata package is
allowed to see. Because the AvailableNetworkAccountIds property checks that each account ID has a device
associated with it at the time it is retrieved, this property can return an empty collection even if
CreateFromNetworkAccountId does not throw an Access Denied exception.
This can happen if no network hardware is detected, or if the network hardware does not have an accessible
SIM. A simple way to determine the exact reason why the returned collection is empty is to look at the WWAN
logs. After you have collected the logs, search the text log file for entries that contain the text
AvailableNetworkAccountIds .
Create a MobileBroadbandDeviceInformation
object
A MobileBroadbandDeviceInformation object contain a set of properties that you can use to obtain mobile
broadband–specific data about the network device that is associated with a mobile broadband account (for
example, the firmware version). You can obtain these objects from a MobileBroadbandAccount object only.
Note that a single MobileBroadbandAccount object can be associated with multiple
MobileBroadbandDeviceInformation objects, but only one at a time. (This will happen if a single SIM card,
which holds the information that the MNO uses to differentiate user accounts, is used in two different mobile
broadband devices.)
You get MobileBroadbandDeviceInformation objects by getting the CurrentDeviceInformation property
of a MobileBroadbandAccount object. If there is no network device present at the time that the
CurrentDeviceInformation property was read (for example, because it was unplugged or turned off), reading
this property will return NULL. Because this can change at any time (for example, the user can unplug the
device), we recommend that you get a copy of the property, test that for NULL, and use the copy. The following
code example illustrates shows how to do this:
var myDeviceInfo = myNetworkAccountObject.currentDeviceInformation
if (myDeviceInfo == null)
{
// no device present, inform user
}
else
{
// use myDeviceInfo to get the data you need
}
Related topics
Create a MobileBroadbandNetwork object
MobileBroadbandNetwork objects contain a set of properties that you can use to obtain live data about the
network that is associated with a mobile broadband account (for example, the network registration state or the
APN). You can obtain these objects from a MobileBroadbandAccount object only. Note that a single
MobileBroadbandAccount object can be associated with multiple MobileBroadbandNetwork objects, but
only one at a time. (This will happen if a single SIM card, which holds the information that the MNO uses to
differentiate user accounts, is used in two different mobile broadband devices.)
You obtain MobileBroadbandAccount objects by getting the CurrentNetwork property of a
MobileBroadbandAccount object. If there is no active network at the time that the CurrentNetwork
property was read (for example, because the network device was unplugged or turned off, or the radio had no
signal), reading this property will return NULL. Because this can change at any time (for example, the user can
walk into an elevator with the computer, causing the connection to drop), we recommend that you get a copy of
the property, test that for NULL, and use the copy. The following code example illustrates this.
var myNetwork = myNetworkAccountObject.currentNetwork
if (myNetwork == null)
{
// no network, inform user
}
else
{
// use myNetwork to get the data you need
}
Related topics
Determine if a device is PIN-locked
Because the subscription information on a locked device (for example, ICCID or IMEI) might not be available, all
locked devices enumerate an available network account. To know whether an account represents a locked
device, query the NetworkDeviceStatus property of the CurrentDeviceInformation property for the
account. NetworkDeviceStatus .DeviceLocked indicates a PIN lock, whereas
NetworkDeviceStatus .DeviceBlocked indicates a PUK block.
For example:
var account =
Windows.Networking.NetworkOperators.MobileBroadbandAccount.createFromNetworkAccountId(accountId);
if (account.currentDeviceInformation.networkDeviceStatus ==
Windows.Networking.NetworkOperators.NetworkDeviceStatus.DeviceLocked)
{
// the pin is locked
}
Related topics
Determine which mobile broadband network is
currently connected
You can determine which mobile broadband network you’re connected to by retrieving the APN through the
AccessPointName property of the current network object for the account.
For example:
account.currentNetwork.accessPointName
Related topics
Determine which Windows device is being used to
connect to the network
To determine which Windows device is being used to connect to the network, check the Windows device ID for
the network adapter, which is exposed by the DeviceId property of the current network device object for the
account.
For example:
account.currentDeviceInformation.deviceId
Related topics
Discover whether the network device radio is turned
on
If the user starts the mobile broadband app directly from its tile, the mobile broadband device might be turned
off. This will usually happen if the device entered a power-saving mode or the end user turned on airplane mode
(which disables the network devices). If this is the case, getting the CurrentRadioState property of the
MobileBroadbandDeviceInformation object for the network device in question will return
MobileBroadbandRadioState .Off . (Alternatively, if the radio is turned on, the CurrentRadioState property
will return MobileBroadbandRadioState .On .)
Related topics
Enumerate available mobile broadband accounts
There are two methods that you can use to enumerate network accounts: polling or event-based.
Polling The mobile broadband app can poll for available network accounts by using the static
MobileBroadbandAccount.AvailableNetworkAccountIds method. This is ideal if the application
simply needs a snapshot of the accounts and does not need to respond at run time to accounts that are
being added or removed.
Event-based You can use the MobileBroadbandAccountWatcher class to enumerate and then
monitor for changes to mobile broadband accounts. The event-based method is ideal when the
application must respond to changes (that is, return to the account selection page when the currently
selected account is removed). The procedure to use this class is as follows:
1. Instantiate a MobileBroadbandAccountWatcher object.
2. Add event handlers to the AccountAdded , AccountRemoved , and EnumerationCompleted
events.
3. Invoke Start() on the watcher.
The AccountAdded event handlers are invoked for each existing network account. When all of the
existing network accounts are enumerated, the EnumerationCompleted event is raised.
Additional AccountAdded and AccountRemoved events are raised as account availability changes
(that is, when mobile broadband hardware or the SIM is removed).
Impor tant Account watcher objects automatically stop when the app is suspended by Windows, and restart
when the app is resumed. This is done to preserve battery life because resuming a suspended app to process an
event and then putting it back in the suspended state can result in significant disk activity. The Stopped event
occurs when the watcher stops (this happens either right before or right after the app gets its Suspending
event). When the app resumes, all watchers that were running before the app was suspended automatically
restart, thereby triggering a series of AccountAdded events that are followed by an EnumerationCompleted
event (the same way as if the Star t method had been called). This enables the app to get up-to-date with
anything significant that occurred during the time that it was suspended.
MobileBroadbandAccountWatcher objects are independent of each other. This means that you cannot
depend on all watchers reporting the same set of events – as a group, they will report all events. However, any
given watcher might not report any given event, because that event has been consumed by another watcher.
Unless you have good reason, you should use only one account watcher object per app.
Related topics
Establish temporary network connectivity
Telecommunication applications cannot initiate long-term connections. However, if you need temporary
connectivity to a specific network, you can use the Mobile Broadband API as follows:
1. Create an instance of IMbnConnectionManager .
2. Register to the IMbnConnectionEvents connection point.
3. Create an instance of IMbnInterfaceManager .
4. Get an IMbnInterface interface for the device by passing the account device ID into
IMbnInterfaceManager ::GetInterface . (For more info, see Unlock a device.)
5. Obtain an IMbnConnection interface for the device by calling
IMbnConnectionManager ::GetConnection .
6. Establish a connection by calling IMbnConnection::Connect . The connectionMode parameter must be
set to MBN_CONNECTION_MODE_TMP_PROFILE , and the strProfile parameter must be a mobile
broadband profile description.
The results of the connect attempt are returned by using the IMbnConnectionEvents::OnConnectComplete
method. To disconnect when you are finished, invoke the IMbnConnection::Disconnect method. Status is
returned by using IMbnConnectionEvents::OnDisconnectComplete .
Related topics
Get information about the currently registered
network
You can get the data class, service provider ID and name of the network that the mobile broadband device is
currently registered to. To do this, use the RegisteredDataClass , RegisteredProviderId , and
RegisteredProviderName properties of the current network object for the account.
For example:
var myNetwork = myNetworkAccountObject.currentNetwork

if (myNetwork != null && myNetwork.registeredDataClass == DataClasses.LteAdvanced)
{
// user is connected to an LTE network
}
Related topics
Get the IMEI, ICCID, IMSI and telephone numbers
for the mobile broadband device
The following properties are available for the current network device for the account:
P RO P ERT Y O F M O B IL EB RO A DB A N DDEVIC EIN F O RM AT IO N

VA L UE TO USE
IMEI MobileEquipmentId
MEID MobileEquipmentId
IMSI SubscriberId
MIN SubscriberId
IRM SubscriberId
ICCID SimIccId
Telephone Numbers TelephoneNumbers (only available after network

registration)
account.currentDeviceInformation.mobileEquipmentId
Related topics
Know when network connectivity changes
To know when network connectivity changes, use the AccountUpdated event of

MobileBroadbandAccountWatcher :
2. Add an AccountUpdated event handler.
3. Invoke Star t on the watcher.
4. Query the HasNetworkChanged property of the MobileBroadbandAccountUpdatedEventArgs
object in the AccountUpdated event handler.
5. If the network has changed, query the CurrentNetwork property for the current network object.
Related topics
Open the networks list
You can open the networks list by calling the ShowConnectionUI method of the current network object for the
account.
For example:
account.currentNetwork.showConnectionUI()
Related topics
Receive notification for device information account
changes
To receive a notification for device information account changes, use the AccountUpdated event of
MobileBroadbandAccountWatcher as described here:
2. Add an AccountUpdated event handler.
3. Invoke Star t on the watcher.
4. Query the HasDeviceInformationChanged property of the
MobileBroadbandAccountUpdatedEventArgs object in the AccountUpdated event handler.
5. If the device information has changed, query the account
CurrentDeviceInformation.TelephoneNumbers property for the telephone number.
For example:
if (account.currentDeviceInformation.TelephoneNumbers.length > 0)
{
// there is now at least one telephone number
}
Related topics
Receive notification when mobile broadband
accounts are added or removed
For more info on receiving notifications when mobile broadband accounts are added or removed, see the event-
based enumeration method in Enumerate available mobile broadband accounts.
Related topics
Retrieve ConnectionProfile objects for a
MobileBroadbandAccount
A ConnectionProfile object contains a set of properties and methods that you can use to obtain connectivity,
usage, and data plan information for established network connections. The connection profiles associated with a
mobile account can be retrieved by using the MobileBroadbandAccount object. The following code example
illustrates shows how to do this:
Note A list of all ConnectionProfile objects can be retrieved from
Windows.Networking.Connectivity.NetworkInformation.GetConnectionProfiles .
var myConnectionProfileList = myNetworkAccountObject.getConnectionProfiles();
if (myConnectionProfileList.length !== 0)
{
for (var i = 0; i < myConnectionProfileList.length; i++)
{
//Display connection profile properties
var connectivityLevel = myConnectionProfileList[i].getNetworkConnectivityLevel();
}
}
else
{
// No connection profiles are associated with this mobile broadband account.
}
Related topics
Unlock a device
A subset of the mobile broadband API includes the PIN Management API. To unlock a device, do the following:
1. Get the network adapter ID for the account device:
account.currentNetwork.networkAdapter. networkAdapterId
2. Create an IMbnInterfaceManager instance.

3. Advise to the IMbnPinManagerEvents and IMbnPinEvents connection points (these are used for
getting PIN state and unblock/unlock results). For more info, see the Remarks section of
IMbnInterfaceManager .
4. Pass the network adapter ID into IMbnInterfaceManager ::GetInterface to get an IMbnInterface
interface for the device.
5. Get an IMbnPinManager interface for the device by calling IMbnInterface::Quer yInterface .
6. Call IMbnPinManager ::GetPinState to get the PIN state of the device (the state returned by using the
connection point that was registered in step 3).
7. Determine how the device is locked or blocked by using the MBN_PIN_INFO::pinState parameter that
is passed into the event.
8. Get an IMbnPin interface for the appropriate PIN by calling IMbnPinManager ::GetPin .
9. Call either IMbnPin::Enter or IMbnPin::Unblock , based on how the device is locked (see step 7).
10. Listen for Unlock or Unblock results by using IMbnPinEvents registration to know whether the
operation was successful.
Related topics
Best practices for handling account arrival and
removal events
Mobile broadband accounts can be added or removed during the lifetime of the mobile broadband app. This can
be caused by the addition or removal of hardware, PIN unlocking, or SIM swapping. The arrival or removal of an
account is transient in many cases. Proper handling of these events has significant implications on the usability
of the application. The following best practices apply to handling account arrival and removal events:
Do not immediately raise an error dialog when the active account that is being used is removed.
Do not assume that the user has removed the hardware. Hardware might be temporarily unavailable
during sleep/resume of the machine, depending on the behavior of the driver or the bus.
Do not release any started account watcher objects without calling their Stop method first. Account
watchers, like all Windows Runtime (WinRT) objects, are reference counted. Calling Star t increments
their reference count (Stop decrements it). If you release a started account watcher, it will keep triggering
events but you cannot call Stop on the handle that you’ve just released.
Remember that account watcher objects automatically stop when the app gets suspended by Windows,
and restart when the app resumes. This is the same result as if your app had called Stop and Star t , and
results in the same events. Use these events to bring the app up-to-date with anything significant that
occurred during the time that it was suspended.
Related topics
Best practices for connecting to the mobile
broadband network
Active connections to the mobile broadband network can be an unnecessary drain on battery life and account
data quotas. We recommend that you use careful judgment to determine whether a connection is necessary.
Use the following best practices regarding connectivity to the mobile broadband network:
Do not use the provisioning agent’s <Activation> directives. These directives are intended only for
specific circumstances after activation.
Use the Mobile Broadband API to establish temporary connectivity. This API provides connection
operation results and an easy way to disconnect.
Keep the connection lifetime to a minimum.
Use connectivity through Internet-connected interfaces whenever they are available. You can observe
availability by using the NetworkInformation API.
Related topics
You should use this topic to get a high-level understanding of the Windows 8, Windows 8.1, and Windows 10
mobile broadband hardware requirements and recommendations. We recommend the following to provide
your customers with a simplified connection experience, as well as reducing your maintenance and support
costs.
Embedded mobile broadband modules that provide USB interfaces must meet the Windows 8,
Windows 8.1, or Windows 10 hardware certification requirements and be managed by using the mobile
broadband class driver. Your hardware requirements documentation for IHVs should require that mobile
broadband devices pass the Windows 8, Windows 8.1, or Windows 10 device certification.
External USB mobile broadband dongles must support identity morphing. Your hardware requirements
documentation for IHVs should require that external mobile broadband devices pass both the Windows 8
device certification, Windows 8.1, or Windows 10 device certification and pass the Windows 7 logo
certification.
On a Windows 10 computer, the dongle appears as a Windows 10 certified mobile broadband
device and is managed by using the mobile broadband class driver.
On a Windows 8.1 computer, the dongle appears as a Windows 8.1 certified mobile broadband
device and is managed by using the mobile broadband class driver.
On a Windows 8 computer, the dongle appears as a Windows 8 certified mobile broadband device
and is managed by using the mobile broadband class driver.
On a Windows 7 computer, the dongle appears as a mass storage device, allowing the user to
install specific device drivers.
If you require EAP-SIM, USSD, or multiple PDP connections, the IHV must enable it and it must comply
with the Windows 8, Windows 8.1, or Windows 10 hardware certification requirements.
Any additional functionality required by you or the IHV must be implemented using the device services
extension and enabled in Windows 8, Windows 8.1, or Windows 10 by using the mobile broadband class
driver and the Device Services APIs. You should include any additional functionality as part of your
hardware requirement documentation.
Key scenarios
Purchase an external device
An external device is likely to be inserted immediately before the user wants to begin using it.
1. As soon as the device is inserted, it is recognized and managed by the mobile broadband class driver.
2. The Mobile Broadband Service reads the IMSI and generates a set of hashes.
3. When the user clicks Connect , these hashes are used to match connection settings within the COSA/APN
database submission.
If the connection is successful and Internet connectivity is available, nothing further happens. The
user has already purchased service.
If the connection is successful, but Internet connectivity is not available, the web browser opens to
the URL specified in the APN database or your UWP mobile broadband app.
If the connection fails, the user is notified of the error.
4. Your web site or your mobile broadband app helps the user purchase service.
5. After purchase, the device is provisioned by using the provisioning API from a provisioning file. The
provisioning file is passed to the provisioning agent by the web site or the mobile broadband app. The
provisioning file configures Windows with basic information about the plan that the user has purchased.
Depending on the network structure, one of the following occurs:
The user is granted Internet access on the current connection.
The provisioning file includes instructions to disconnect and reconnect to the same network or a
different network, which will provide Internet access.
Connect an external device with an active SIM
When an active device is attached that already had an active SIM, the workflow is similar to when you purchase
an external device, except that the attempted connection will lead to the Internet. You don’t need to direct the
user to your website or mobile broadband app to purchase service.
1. As soon as the device is inserted, it is recognized and managed by the mobile broadband class driver.
2. The Mobile Broadband Service reads the IMSI and generates a set of hashes.
3. When the user clicks Connect , these hashes are used to match connection settings within the COSA/APN
database submission. For a device with an active SIM, the connection is successful and Internet
connectivity is available.
Components
Windows 8, Windows 8.1, or Windows 10 certified mobile broadband devices
To take full advantage of the Windows mobile broadband platform, your mobile broadband device must meet
the Windows 8, Windows 8.1, or Windows 10 hardware certification requirements. For a comprehensive
description of the hardware certification requirements, see Windows Hardware Certification Requirements.
For the end user, the most simplified connection experience is delivered with a USB-based mobile broadband
device. As part of the hardware certification requirements, any mobile broadband device that manifests as a
USB device must comply with the Mobile Broadband Interface Model (MBIM) specification and the MBIM v1.0
Errata. This includes both external USB dongles and embedded modules that provide USB interfaces. For this
class of devices, Windows 8, Windows 8.1, or Windows 10 includes a mobile broadband class driver, which
eliminates the need for additional drivers from the IHV and simplifies the user’s connection experience. Other
hardware that is not USB and driver models can receive Windows 8, Windows 8.1, and Windows 10 certification
and will provide the Microsoft Store mobile broadband app experience, but these are not supported by the
mobile broadband class driver.
Mobile broadband class driver
The mobile broadband class driver reduces the burden on device manufacturers to deliver a custom driver for
their specific mobile broadband device. The mobile broadband class driver manages any USB MBIM-compliant
mobile broadband interface that meets the Windows 8, Windows 8.1, or Windows 10 device certification. When
a certified device is connected, no additional drivers are required and Windows can immediately use the device
to connect to your network. The mobile broadband class driver conforms to the Windows mobile broadband
driver model and provides full functionality to the Windows Mobile Broadband Service. It supports GSM
networks, including HSPA+ and LTE; CDMA networks; and dual-mode networks offering 3G CDMA and 4G LTE. It
also supports operator messages such as SMS and USSD, and EAP-SIM-based authentication.
Note While USSD, EAP-SIM, and multiple PDP contexts are supported by the mobile broadband class driver,
they are optional components of the Windows 8, Windows 8.1, or Windows 10 for desktop editions (Home, Pro,
Enterprise, and Education) hardware certification requirements. Multiple PDP contexts are required for
Windows 10 Mobile for hardware certification, however.
Additional device functionality can be implemented using custom device service extensions, which will be
exposed directly to the mobile broadband app through the WinRT Device Services API.
For more information on the mobile broadband class driver, see Mobile Broadband (MB) Reference.
Device service extension API
One of the distinct advantages to using the Windows platform is the ability to provide new hardware scenarios
that support operator differentiation. The Windows mobile broadband platform is expected to enable
differentiation for operators that can command higher customer loyalty and brand equity. The platform provides
a set of extension points that you can incorporate into your unique experience.
Windows certified mobile broadband devices declare each supported extension point as a “device service”.
Examples of such services include Phonebook, SIM Toolkit, or GPS features. Any device services that are not
natively implemented by the Windows mobile broadband platform can be accessed by using the Device Service
Extension API. You and the IHV define the device services that should be implemented. The IHV’s firmware and
your mobile broadband app must be designed concurrently to enable the desired device services. The USB
Implementers Forum is establishing a registry of device services that are available to IHVs at MBIMRegistry, and
we recommend that you and the IHVs you are working with use this registry to coordinate to ensure consistency
for common device services extensions.
The Device Service Extension API provides a direct way for the mobile broadband app to access functionality on
their mobile broadband device. This provides a conduit through the WWAN service and the mobile broadband
class driver to the device, as illustrated in the following diagram:
Each device service has a corresponding GUID. All control messages and non-IP packets exchanged between the
mobile broadband class driver and the device will carry the GUID to identify the service associated with the
request. Command identifiers (CIDs) and status indication codes are defined under a service’s GUID namespace.
For example, Phonebook and STK could both share the same CID code, but will be distinguished by the device
service GUID exchanged in the request.
Note The COM-based Device Services API is accessible to any desktop application or service. The WinRT
projected Device Services API is available only to a privileged UWP device app that is authorized by a mobile
broadband operator. Developers should carefully consider privacy and security when communicating
information this way.
The Windows wireless platform supports APIs for the following functionality that is available to apps:
Enumerate device services
Open and close device services
Send control commands to a specific device service
Send or receive data to or from a specific device service
Register for unsolicited device events from a specific device
For more information, see IMbnDeviceSer vice interface .
Legacy support and identity morphing
Windows 8, Windows 8.1, and Windows 10 support mobile broadband devices designed for Windows 7.
Whereas the current ecosystem of devices will continue to function on Windows 8, Windows 8.1, and
Windows 10 they will not fully utilize the Windows 8, Windows 8.1, or Windows 10 mobile broadband
platforms.
A summary of mobile broadband device support inWindows 8, Windows RT, Windows 8.1, and Windows RT 8.1
is provided here:
Windows 10 certified devices – These devices pass the mobile broadband experience tests supporting the
Windows 10 Hardware Certification Kit. For these devices, Windows 10 provides the mobile broadband
class driver and advanced power management.
Windows 8 or Windows 8.1 certified devices – These devices pass the mobile broadband experience tests
supporting the Windows 8 or Windows 8.1 Hardware Certification Kit. For these devices, Windows 8 and
Windows 8.1 provide the mobile broadband class driver and advanced power management.
Windows 7 logo’d devices – These devices use third-party IHV drivers based on Windows 7 NDIS 6.20
driver model. Windows 8 and Windows 8.1 provide mobile broadband experience in backward
compatibility mode for these devices and they are limited to Windows 7 functionality.
Windows 8 and Windows 8.1 will continue to support the legacy devices based on modem or Ethernet
interfaces along with a custom connection manager as in earlier versions of Windows. Windows 8 and
Windows 8.1 will not be able to provide mobile broadband experiences as they are not compliant with
the mobile broadband stack. Because the legacy devices are not recognized by the mobile broadband
stack, connectivity over such devices may result in excessive data consumption as they are not managed
by Windows Connection Manager.
Windows RT and Windows RT 8.1 certified devices – These devices pass mobile broadband experience
tests supported by the Windows RT or Windows RT 8.1 Windows Hardware Certification Kit. For these
devices, Windows RT and Windows RT 8.1 provide the mobile broadband class driver and advanced
power management.
Note Windows RT and Windows RT 8.1 systems do not support mobile broadband devices designed for
Windows 7 and earlier versions.
To ensure that Windows 8 and Windows 8.1 certified devices are useful on older platforms, Windows provides
an identity morphing solution that enables the device to exhibit behavior that is appropriate for the operating
system to which it is connected.
Identity morphing
When the device is first connected to a Windows 7 PC, a typical external mobile broadband USB dongle presents
itself as a mass storage device. This does not expose other functionality to prevent these devices from appearing
as non-functional due to missing driver software. The mass storage device contains the IHV-supplied software
that installs the driver package. After the user installs the driver package, the IHV-supplied software must morph
the device to expose the other functions to the user. At this point, the device will appear as a mobile broadband
device and the user can connect to your network.
The native Windows 8, Windows 8.1, and Windows 10 class driver eliminates the need for an external USB
device to expose itself initially as a mass storage device, since no driver installation is necessary. Windows 8,
Windows 8.1, and Windows 10 include the capability to trigger a device’s identity morphing, allowing the device
to immediately appear as a mobile broadband device.
To learn how to develop an identity morphing solution, see IMbnDeviceSer vice interface .]
Firmware update support
Mobile broadband device firmware should be updated by using Windows Update. For info on how this can be
done, see Mobile Broadband Device Firmware Update on Windows 8. Specific configurations for your
experience can be provisioned by using your mobile broadband app.
OMA -DM client support
Windows 8.1 added OMA-DM support for enterprises to manage your devices running Windows in BYOD
(Bring Your Own Device) scenarios. This extends support for these scenarios by adding enterprise-relevant
protocols (MS-MDE, MS-MDM) for use by 3rd-party mobile device management providers and Windows
InTune.
Windows separates OMA-DM support for mobile Network operator configuration from the support for
enterprise BYOD. The OMA-DM client in Windows 8.1 and Windows 10 does not support configuring Mobile
Operator specific settings natively and is not 3rd party extensible to support mobile network operator
requirements. OMA-DM solutions supporting Windows Phone platform are not compatible with the
Windows 8.1 OMA-DM client or the Windows 10 OMA-DM client.
Here are some options to consider when supporting an operator-specific OMA-DM:
If the OMA-DM client is in the network adapter’s firmware:
Typically, mobile broadband device manufacturers may bundle operator-specific OMA-DM client in
their network adapter’s firmware.
The mobile broadband device manufacturer may be able to provide 3rd party OMA-DM client
solutions for integrating in their network adapter firmware if a natively supported solution does
not exist.
Mobile broadband apps should continue to use provisioning metadata when configuring
operating system specific parameters.
OMA-DM client in the mobile broadband app:
If the modules do not support an OMA-DM client in the network adapter’s firmware, you may
want to implement OMA-DM client in your mobile broadband app.
This solution requires operator-specific or device manufacturer-specific custom device service
support for configuring device specific parameters by the mobile broadband app.
Mobile broadband app that include an OMA-DM client should use provisioning metadata when
configuring operating system specific parameters.
APN Management
Default APN management is done by using the local APN database. You may desire to have the APN information
changed for selective users, such as enterprise users. In such cases, either you or the OEM can choose to update
the APN directly on the device by using OMA DM in OTA signaling.
Your device must implement the following:
When pre-provisioned by operator or provisioned through OTA prior to a successful connection by
using the SIM on that system, the device should provide Internet PDP context as a first provisioned
context with the ContextType set to Internet when queried by Windows as defined in MBIM section
10.5.13.5. This ensures that the connection logic uses this APN information when attempting a
connection.
If the SIM has been used to establish a successful connection to the network using an alternative APN on
that system, setting the ContextType to Internet will not work. The only way to force the Window to
establish a connection using the new APN is to delete the specific profile created. The profile can be
deleted by running the following command from an elevated command prompt: netsh mbn delete
profile interface="Mobile Broadband Connection" name="myProfileName"
Note Since this is an optional Windows feature for devices to support, there is no HCK test or automated test
case to validate this scenario on the system. It is our expectation that the operator certification will handle the
validation to confirm that the device conforms to the operator requirements.
For more info about the APN database, see APN database overview.
Network personalization
Certain operators require that mobile broadband-enabled systems be locked to its network or have
requirements to unlock a locked device to allow for service portability. To enable this scenario, we require the
OEM’s and device vendors use MBIM_PIN_TYPE guidance in the MBIM Specification for Subsidy Lock.
The device must report WWAN_READY_INFO :: ReadyState =WwanReadyStateInitialized in this locked
state and should not report WwanReadyStateDeviceLocked .
Note There is no HCK test case to validate that this feature implemented on the device or system works with
Windows. We look towards the OEM and the operator to use specific filters within MBOT to ensure that the final
product can be tested.
Overview of using metadata to configure mobile
broadband experiences
IMPORTANT
Starting in Windows 10, version 1703, the APN database is replaced by a new format called COSA. Windows 8, Windows
8.1, and versions of Windows 10 before 1703 will continue to use the APN database while Windows 10, version 1703 and
later use COSA. For more information about COSA, see COSA overview.
Starting in Windows 10, version 1803, the MBAE app experience is replaced by an MO Overview of UWP app. For more
information about MO Overview of UWP apps, see Overview of UWP mobile broadband apps.
You can provide metadata to customize various aspects of the Windows 8, Windows 8.1, and Windows 10
mobile broadband application experience. These include customizing Windows Connection Manager with
operator branding, integrating the mobile broadband app with Windows Connection Manager, providing
updated information for the Windows APN database, and providing data to provision the PC. Windows 8,
Windows 8.1, and Windows 10 includes three sources of metadata you can use:
Windows APN database The Windows APN database contains pre-provisioned data that is required to
connect to the operator's network for the first time. The database is part of Windows 8, Windows 8.1, and
Windows 10 and is updated by using Windows Overview of update. The Windows APN database is
always available on the PC. For more info about COSA and the APN database, see COSA/APN database.
Ser vice metadata Information required for subscription purchase and operator branding. You provide
this information as part of the service metadata package. It is stored on the Windows Metadata and
Internet Services (WMIS) and downloaded after a mobile broadband device is detected using any
available Internet connection. This metadata can also be preinstalled onto a PC by the OEM, but you must
preinstall the package that was downloaded from the hardware developer section of the Windows Dev
Center - Hardware. For more info about the service metadata, see Service metadata.
Account provisioning metadata Information generated after a subscription purchase, including Wi-Fi
credentials and plan information. This metadata is provided by you to Windows after payment validation
and can be updated by using the provisioning-refresh mechanism. For more info about the account
provisioning metadata, see Account provisioning.
The following diagram shows how the different metadata sources are related and how they are serviced. The
service metadata takes priority over information in the Windows APN database.
Overview of use the links in this section to learn more about the different types of mobile broadband metadata:
COSA/APN database
Service metadata
Provisioning refers to configuring a Windows computer with the information that is required to connect to an
operator network. Provisioning is usually performed after a mobile broadband subscription purchase. Windows
accepts an XML-based provisioning file from the operator. The Provisioning API applies a provisioning XML file
from the operator, either by using a mobile broadband app or through a purchase web site.
The following diagram illustrates the contents and hierarchy of the provisioning XML file.
For more info about the provisioning schema, see CarrierControlSchema schema.
Updating the provisioning metadata

There are several ways you can update the provisioning metadata on a computer.
Mobile broadband app
After the mobile broadband app is installed on the computer, it can retrieve or generate an updated provisioning
file based on any trigger that you implement in the app.
Mobile broadband apps can apply provisioning files by using the
Windows.Networking.NetworkOperator.ProvisioningAgent APIs. If the app is associated with a Network
Account ID, it can use CreateFromNetworkAccountId to provide unsigned metadata. If the app is not
associated with a Network Account ID, it must use the default constructor for ProvisioningAgent and sign the
XML.
A mobile broadband app can use the following triggers to update the provisioning metadata:
Usage After the data limit is initially configured, you can tell Windows to notify the app at every 5%
usage increment. This ensures that the app retrieves the most up-to-date usage information.
Timers A timer can update the provisioning metadata at appropriate time intervals.
Incoming SMS You can send SMS messages that your app understands. This might define a message
that initiates a refresh, or automatically checks for updated usage upon receiving a threshold notification.
Windows Notification Ser vice Any UWP app can register for push notifications and take actions
based on their content. You can use this as a notification channel for provisioning updates.
Large location changes If different parameters apply to users who are in different locales, a change in
location might trigger an app to apply updated settings for the user’s new location.
Time zone changes For large region sizes, a change in the system time zone can be used as a proxy for
location changes. This can be of particular interest on computers that do not have GPS or Mobile
Broadband.
Web-based provisioning
A web site can supply provisioning data by using the window.external.msProvisionNetworks API.
Provisioning files that are supplied to this API must be signed by using an X.509 certificate and XML-DSig.
Certificates can be pre-supplied to the computer by using the APN database, service metadata, or a previous
account provisioning metadata file. If the certificate is already trusted, there is no user interaction. If the
certificate is not previously known to the computer, it must be an EV certificate, and the user is prompted for
consent before the certificate is accepted.
Automatic provisioning refresh
A provisioning file can include a directive for Windows to automatically retrieve an updated provisioning file at a
scheduled interval or in response to a specific SMS message. This method does not require that a mobile
broadband app be installed on the local computer.
Provisioning metadata contents

The provisioning metadata includes the following sections:
Global
Activation
Mobile broadband information
Wi-Fi information
Plan information
Refresh
Signature
Permitted combinations
For more info about these sections, see CarrierControlSchema schema.
Global
The global section is required in every provisioning file. Required elements in this section are as follows:
CarrierId A GUID that uniquely identifies the organization that authored the file. If you are building a
mobile broadband app, you must use the GUID that you specified in the Service Number field of
Ser viceInfo.xml in the service metadata package. For info about the service metadata package schema,
see Service metadata package schema reference.
NOTE
This is the same service number that you provided in the Create a mobile broadband experience wizard on
the Windows Dev Center Dashboard – Hardware. If you are not creating a mobile broadband app, you can
generate a GUID for your organization’s use. In either case, you should always use the same GUID on all
provisioning files that your organization issues.
SubscriberId A string that uniquely identifies the customer in your organization. If you are a mobile
operator, this should be the IMSI or ICCID ranges for GSM operators or the provider ID or provider name
for CDMA operators. If you are not a mobile operator, you can choose any sufficiently unique string.
Activation
Device activation occurs after the activation process is complete on the back end. The PC might need to follow
certain instructions before connecting to the network. The provisioning engine uses the activation instructions
received in the device activation element. If no value is specified, then no client action is required. Available
actions include:
Re-connect Disconnect and connect to the operator network.
Re-register Disconnect and register to the operator network.
Data Data or instructions that you want to send to the device to activate the connection. The Provisioning
Engine passes this data as is to the device. For CDMA, this can include instructions such as *228 to start
an OTA Programming Session and reconnect to the network.
Mobile broadband information
Mobile broadband information contains several elements:
MBNProfiles
Defines subscriber information on the mobile operator network. There are two different profiles that can be
used:
PurchaseProfile : Information that is needed to connect to the operator’s network to purchase a new
subscription.
DefaultProfile Every mobile broadband subscription can have one default profile that is used to connect
to the home network operator. Windows Connection Manager uses this profile for auto-connecting to the
network.
<MBNProfiles>
<DefaultProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WWAN/v1">
<Name>Contoso MBN</Name>
<Description>Contoso Mobile Broadband</Description>
<HomeProviderName>Contoso MBN</HomeProviderName>
<Context>
<AccessString>contoso.com</AccessString>
<UserLogonCred>
<UserName>mbuser</UserName>
<Password>[PLACEHOLDER]</Password>
</UserLogonCred>
</Context>
</DefaultProfile>
</MBNProfiles>
Branding
IMPORTANT
Starting in Windows 10, version 1709, branding fields provisioned by the ProvisioningAgent API have been replaced by
branding fields in the COSA database. Logo has been replaced by Branding Icon in COSA, and Name has been
replaced by Branding Name in COSA.
Logo and Name will no longer be considered when provisioning in Windows 10, version 1709 and later. The
ProvisioningAgent API will not throw an error if they are used, but you should change Branding Icon and Branding
Name in COSA instead.
For more information about Branding Icon and Branding Name , see Desktop COSA/APN database settings (Desktop
COSA only settings).
Branding lets you specify how Windows displays your mobile broadband networks. This information overrides
any service metadata, if present. If no information is provided, the contents of the service metadata package are
used. The branding elements are as follows:
Logo A Base64-encoded .PNG or.BMP file that is embedded in the XML. This logo is applied to your
mobile broadband profiles for display in the Network List.
Name Sets the carrier’s display name for the mobile broadband profiles.
SMS Parsing
You can provision the rules to identify a text message and extract information as part of the provisioning XML
file. You can use SMS messages to update data usage statistics or to initiate a refresh of provisioning
information. These messages can be identified by a combination of the following:
Bearer type (SMS/USSD)
Sender (SMS only)
Regular expression
For more information on SMS notifications, see Enabling mobile operator notifications and system events.
Each rule contains the following information:
Silent If this value is true, the message results in a MobileOperatorNotification event only. If this value is
false, the message results in an SmsMessageReceived event.
Allowed sender Specifies the reserved sender address from which the notification is permitted to
arrive. This number must exactly match the sender number that is received in the SMS message,
including the international format.
Pattern The regular expression to identify and optionally extract data fields from the text message. This
pattern will match all messages from a sender: [^]*
RuleId An identifier for this rule, which is passed to the mobile broadband app as part of the
MobileOperatorNotification event. This identifier enables the app to know which rule caused the SMS to
trigger a MobileOperatorNotification event, and can reduce the app’s need to parse the message again.
Fields and groups Each capturing group in the regular expression pattern is tied to a named field. This
is used to extract and transform the data into a set of usable values. For example, the first match-group
can be tied to the Usage field and the second match-group can be tied to the UsageDataLimit field.
This association indicates that the first value is the current usage information, and the second value is the
maximum allowed usage.
Usage, UsagePercentage, UsageOverage, UsageOveragePercentage : Expresses the current
usage as an absolute number, as a percentage of the data limit, as a number in excess of the data
limit, or as a percentage in excess of the data limit. Absolute values can reference a group that
specifies the unit in which the value is expressed.
UsageTimestamp : The date and time at which the usage field is calculated. This information must
be included if any Usage\ * field is included. The format string contains the following identifiers to
express how the substring should be interpreted:
IDEN T IF IER DESC RIP T IO N
%d Day of month as decimal number (01 – 31)
%H Hour in 24-hour format (00 – 23)
%I Hour in 12-hour format (01 – 12)
%m Month as decimal number (01 – 12)
%M Minute as decimal number (00 – 59)
%S Second as decimal number (00 – 59)
%y Year without century, as decimal number (00 – 99)
%Y Year with century, as decimal number (0000-9999)
%p AM/PM indicator
%#d, %#H, %#I, %#m, %#M, %#S, %#y, %#Y Same as above but with no leading zeros
DataLimit : The absolute number of bytes that the user is allowed to use; this includes a group that
specifies the unit in which the value is expressed.
OverDataLimit, Congested : Modifies flags that are reported to apps to indicate that the user
has exceeded their data limit or that the network is under heavy load.
InboundBandwidth, OutboundBandwidth : If a maximum bandwidth is being imposed by the
network, this specifies the groups that represent the value and the units.
PlanType : Specifies how the user is charged for future usage.
Caution Because SMS messages influence Windows behavior, only trusted SMS messages can be consumed.
Security is maintained by restricting the sender address. This security method assumes that your network’s SMS
Gateway ensures that messages from restricted senders cannot be spoofed.
Wi-Fi information
This section lets you provide any number of Wi-Fi network profiles for Windows to use. The format of the
section is similar to the XML schema that is used by the Windows native WLAN API.
NOTE
One profile can contain multiple SSIDs, if all other settings are the same. If different networks vary in other ways
(authentication method, encryption settings, plan, and so on), you must create additional profiles.
When you specify the WLAN section, you must also specify all profiles that should be configured on the
computer. If those profiles reference a data plan, the plans section must also be included. The behavior that
occurs when this section is processed is as follows:
If the computer has a profile that is no longer specified, it is deleted.
If you specify a profile, it is updated or created.
An empty WLAN section deletes all profiles.
Omitting the WLAN section leaves the WLAN profiles on the machine unchanged.
An additional node in this section is the associated plan. This node enables Windows to associate the WLAN
profile with a plan that is described in the plans section. The plan lets you inform Windows of the metering state
of the network and influence the behavior of Windows during the time that the computer is connected to the
network.
Unencrypted network, no automatic authentication
This profile configures Windows to connect to an open network.
If this network contains a captive portal, the browser is opened upon connection to the network.
If the network does not contain a captive portal, the user is connected with no further action.
<WLANProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WLAN/v1">
<name>Contoso Wi-Fi</name>
<SSIDConfig>
<SSID>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
<authentication>open</authentication>
<encryption>none</encryption>
<useOneX>false</useOneX>
</authEncryption>
</security>
</MSM>
</WLANProfile>
Unencrypted network, WISPr authentication

This profile configures Windows to connect to an open network and uses Wireless Internet Service Provider
roaming (WISPr) authentication:
If the network contains a WISPr-capable captive portal, the specified user name and password is
submitted to the specified authentication server.
If the captive portal is not capable of WISPr, the browser is opened upon connection to the network.
<SSIDConfig>
<SSID>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
</authEncryption>
<HotspotProfile xmlns="http://www.microsoft.com/networking/WLAN/HotspotProfile/v1">
<UserName>WisprUser1</UserName>
<TrustedDomains>
<TrustedDomain>www.contosoportal.com</TrustedDomain>
</TrustedDomains>
</HotspotProfile>
</security>
</MSM>
</WLANProfile>
Encrypted network, EAP-SIM authentication

This profile configures Windows to connect to an encrypted network by using a SIM as the authentication type,
such as a Hotspot 2.0 network. Hotspot 2.0 defines such a network to use WPA2-Enterprise with EAP-SIM
authentication.
<SSIDConfig>
<SSID>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
<authentication>WPA2</authentication>
<encryption>AES</encryption>
<useOneX>true</useOneX>
</authEncryption>
<OneX xmlns="http://www.microsoft.com/networking/OneX/v1">
<EAcomputeronfig>

<EapHostConfig xmlns="http://www.microsoft.com/provisioning/EapHostConfig">
<EapMethod>
<Type>18</Type>
<VendorId>0</VendorId>
<VendorType>0</VendorType>
<AuthorId>311</AuthorId>
</EapMethod>
<Config xmlns="http://www.microsoft.com/provisioning/EapHostConfig">
<EapSim xmlns="http://www.microsoft.com/provisioning/EapSimConnectionPropertiesV1">
<Realm Enabled="true"></Realm>
</EapSim>
</Config>
</EapHostConfig>
</EAcomputeronfig>
</OneX>
</security>
</MSM>
</WLANProfile>
Unencrypted network, app-based authentication

This profile configures Windows to connect to an open network and use WISPr authentication in cooperation
with your mobile broadband app.
If the network contains a captive portal, your app is opened in the background to provide WISPr
credentials. The credentials are then submitted to the specified authentication server.
If the captive portal is not capable of WISPr, the browser is opened upon connection to the network.
<name>Contoso WiFi</name>
<SSIDConfig>
<SSID>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
</authEncryption>
<ExtAuth>
<ExtensionId>YourAppIdGoesHere</ExtensionId>
</ExtAuth>
<TrustedDomains>
<TrustedDomain>www.contosoportal.com</TrustedDomain>
</TrustedDomains>
</HotspotProfile>
</security>
</MSM>
</WLANProfile>
Plan information
Each mobile broadband and hotspot profile references a plan. Multiple profiles can reference the same plan.
Plans are described in a separate top-level section.
The Plan is divided into two sections—Description and Usage. This allows you to initially provide profiles and
descriptions in a larger provisioning file, and then subsequently provide smaller provisioning files that contain
only the customer’s current usage.
This information is used to directly affect the behavior of Windows, and is provided to applications to tailor their
behavior to the network. This information can be made available to third-party applications through network
information APIs.
Description
The elements that generally change with low frequency over a customer’s subscription period, including:
PlanType The type of billing relationship the customer has with the operator:
Unrestricted Usage does not incur additional cost.
Fixed The user is allotted a certain amount of usage for a fixed cost.
Variable The user pays based on usage.
SecurityUpdatesExempt A Boolean value that specifies whether security updates count toward the
customer’s usage.
DataLimitInMegabytes The user’s allotted usage, if PlanType is Fixed .
BillingCycle Defines the plan's starting date and time, its duration, and what happens at the end of the
billing cycle.
BandwidthInKbps The user’s connection speed as allowed by the network; this can reflect the norm for
their plan, or reflect a lower rate that is currently imposed by the carrier due to congestion or excessive
use (maximum of 2 Gbps).
MaxTransferSizeInMegabytes An integer that expresses the size of an individual download that a
compliant application should permit over a metered connection, without explicit user approval of the
connection being used.
UserSMSEnabled Indicates whether the plan includes user-to-user SMS support. If true, Windows will
keep the device attached to the network in Connected Standby even when the mobile broadband
interface is not being used. If false, Windows can power down the mobile broadband interface to
conserve power, thereby resulting in the device not being addressable by the network when the
computer is idle.
Usage
The following elements can change with higher frequency:
UsageInMegabytes The user’s most recent data usage.
OverDataLimit A Boolean value that indicates whether the user has passed the allotted usage, if
PlanType is Fixed .
Congested A Boolean value that indicates whether a lower connection speed than usual is being
imposed due to excessive usage. The Congested flag indicates that the network is currently experiencing
(or expects to experience) heavy load, and lower-priority transfers should be deferred until another time,
if possible. You can use this flag to indicate concepts such as peak hours, or to respond to an overloaded
hotspot.
Refresh
You can push updated settings to the computer as required because of network changes or for technical
support. Windows attempts periodic refreshes by using information that is provided by you or by the
provisioning API. A refresh can be triggered by SMS notifications from the operator. To enable Refresh, you must
provide the following information in the provisioning XML:
TrustedCer tificates A list of certificate thumbprints that have trusted signatures on future provisioning
files.
DelayInDays The (integer) number of days before which a refresh is not attempted.
RefreshURL The HTTPS URL to get the latest copy of the user’s provisioning file.
UserName & Password Optional credentials that are to be presented by using HTTP-Auth when
retrieving the re-provisioning file. This information must be encrypted when stored.
Alternatively, the mobile broadband app can provide a new provisioning file at any time, based on
communication between the app and the operator’s backend.
<RefreshParameters>
<DelayInDays>30</DelayInDays>
<RefreshURL>https://www.contoso.com/refresh</RefreshURL>
<Username>[PLACEHOLDER]</Username>
</RefreshParameters>
Signature
Because provisioning modifies system settings that persist after the user has exited or uninstalled the app, a
stricter measure of verification is required than for most APIs. This verification is provided by a combination of
operator-specific hardware (the SIM), cryptographic signatures, and user confirmation.
Provisioning requirements:
USER C O N F IRM AT IO N
SIM P RESEN T ? SO URC E O F P RO VISIO N IN G SIGN AT URE REQ UIREM EN T REQ UIREM EN T
Yes, MB provider Mobile broadband app None None
Yes, MB provider Operator web site Certificate must: None

- Chain back to trusted root
CA.
- Be associated with mobile
broadband hardware in
APN database or experience
metadata.
No, Wi-Fi provider Mobile broadband appor Certificate must: User is prompted to
web site - Chain back to trusted root confirm the first time the
CA. certificate is used; no
- Be marked for Extended confirmation is required
Validation. thereafter.
Permitted combinations
Although Global is the only first-level node that is required by the schema, certain combinations of other nodes
are typical. This section discusses these typical combinations:
Profiles (WL ANProfiles, MBNProfiles) + Plans including Description and Usage Creates or
updates the full set of profiles, and applies plan information and current usage to each. An error is
returned if a profile references a Plan that is not specified in the same provisioning file, and a warning is
returned if no profile in the provisioning file references a specified Plan.
Plans including Description and (optionally) Usage Updates Plan information for existing profiles
on the computer, but does not modify the profiles on the computer. A warning is returned if no profile on
the computer references a specified Plan.
Plans including Usage only Updates usage information in existing profiles on the computer, but does
not modify the profiles or the description of the Plan that is associated with each profile.
Common Scenarios
Here are some common scenarios that you may need as you create provisioning metadata:
Find the account provisioning schema
Apply provisioning XML to the device
Provision the device to connect automatically to a mobile broadband network
Provision the device to connect automatically to a Wi-Fi network
Provision the device to connect automatically to a WISPr-enabled hotspot
Sending activation to the mobile broadband device
Force the mobile broadband device to reconnect to the network after provisioning completes
Updating data usage statistics for a connection profile
Update data usage by using an SMS message
Find the account provisioning schema
XSD schemas are available under %SYSTEMROOT%\schemas\provisioning on any computer that is
running Windows 8, Windows 8.1, or Windows 10.
Apply provisioning XML to the device
You can apply a provisioning XML file to a device by using a mobile broadband app, a UWP app, or from a web
site.
To provision from a mobile broadband app:
1. Instantiate a ProvisioningAgent instance (by using
Windows.Networking.NetworkOperators.ProvisioningAgent.CreateFromNetworkAccountId ).
2. Call ProvisionFromXmlDocumentAsync , passing in the unsigned provisioning XML document.
The asynchronous operation complete and the results of the provisioning operation are returned.
To provision from a UWP app other than the mobile broadband app:
1. Generate a signed Account Provisioning XML document.
2. Instantiate a ProvisioningAgent instance (by using the default constructor).
3. Call ProvisionFromXmlDocumentAsync , passing in the signed XML document.
The asynchronous operation completes and the results of the provisioning operation are returned.
From a web site:
1. Generate a signed Account Provisioning XML document.
2. Call window.external.msProvisionNetworks , passing in the signed XML document.
The operation completes and the results of the provisioning operation are returned.
Provision the device to connect automatically to a mobile broadband network
You can define a provisioning XML document by using an MBNProfile section.
<?xml version="1.0"?>
<CarrierProvisioning xmlns="http://www.microsoft.com/networking/CarrierControl/v1">
<Global>
<CarrierId>{00000000-1111-2222-3333-444444444444}</CarrierId>
<SubscriberId>1234567890</SubscriberId>
</Global>
<MBNProfiles>
<Name>Profile Name</Name>
<Description>The Description</Description>
<HomeProviderName>Contoso</HomeProviderName>
<Context>
<AccessString>apn</AccessString>
<UserLogonCred>
<UserName>username</UserName>
</UserLogonCred>
</Context>
</DefaultProfile>
</MBNProfiles>
</CarrierProvisioning>
NOTE
The child elements of DefaultProfile are required. See the provisioning XML schema reference for more details.
Provision the device to connect automatically to a Wi-Fi network

You can define a provisioning XML document by using a WlanProfiles section.
<Global>
</Global>
<WLANProfiles>
<name>My Wi-Fi Hotspot</name>
<SSIDConfig>
<SSID>
<name>wifihotspot1</name>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
</authEncryption>
</security>
</MSM>
</WLANProfile>
</WLANProfiles>
The child elements of MSM define how to connect to the network. This includes any necessary EAP
configuration. All child elements of the MSM element in the WLAN_profile Schema are supported. See the
provisioning XML schema reference for more details.
Provision the device to connect automatically to a WISPr-enabled hotspot
You can use either of the following two ways to enable hotspot authentication:
1. Directly declare credentials by using the BasicAuth directive:
<WLANProfiles>
<SSIDConfig>
<SSID>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
</authEncryption>
<BasicAuth>
<UserName>[PLACEHOLDER]</UserName>
</BasicAuth>
<TrustedDomains>
<TrustedDomain>hotspot.contoso.com</TrustedDomain>
</TrustedDomains>
</HotspotProfile>
</security>
</MSM>
</WLANProfile>
</WLANProfiles>
2. Redirect to an app for authentication by using the ExtAuth directive:
<WLANProfiles>
<SSIDConfig>
<SSID>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
</authEncryption>
<ExtAuth>
<ExtensionId>Alice</ExtensionId>
</ExtAuth>
<TrustedDomains>
<TrustedDomain>hotspot.contoso.com</TrustedDomain>
</TrustedDomains>
</HotspotProfile>
</security>
</MSM>
</WLANProfile>
</WLANProfiles>
You should directly define credentials when possible. Redirecting to another app has power and complexity
implications.
Sending activation to the mobile broadband device
An arbitrary binary large object (BLOB) that is contained inside the CarrierSpecificData element can be
Base64-encoded and sent to the device by using the ProvisioningAgent. You can do this by using the
Activation<Ser viceActivatation> directive in the provisioning XML:
<Global>
</Global>
<Activation>
<ServiceActivation xmlns="http://www.microsoft.com/networking/CarrierControl/WWAN/v1">
<CarrierSpecificData>YXJiaXRyYXJ5ZGF0YQ==</CarrierSpecificData>
</ServiceActivation>
</Activation>
This method is equivalent to invoking the IMbnVendorSpecificOperation::SetVendorSpecific method of

the Mobile Broadband API, and passing a SAFEARRAY together with the BLOB contents.
Force the mobile broadband device to reconnect to the network after provisioning completes
There are two ways you can force the mobile broadband device to reconnect to the network after provisioning:
ReregisterToNetwork and ReconnectToNetwork .
You can use the ReregisterToNetwork directive to force re-registration to the mobile broadband network by
turning the mobile broadband radio off and then back on. After the radio comes back on, the adapter is
connected by using the default profile. You should use this directive sparingly, and only if it is necessary to
deregister from the network after account activation.
You can use the ReconnectToNetwork directive when context activation must apply any new security or policy
settings after account activation has completed. This is done by deactivating the PDP context and reactivating
based on the default profile settings for the mobile broadband adapter. If the default profile is updated in the
same provisioning XML, the new profile settings will be used.
Optionally, you can specify these directives by using retry counts/intervals and delayed execution times.
NOTE
If the radio is successfully cycled on in a ReregisterToNetwork but the automatic connection back to the network using
the default profile fails, then subsequent retries do not cycle the radio again.
<Global>
</Global>
<Activation>

<ReregisterToNetwork
xmlns="http://www.microsoft.com/networking/CarrierControl/WWAN/v1"
Delay="PT30S"
RetryCount="3"
RetryInterval="PT1M"
/>
</Activation>
Updating data usage statistics for a connection profile

You can only update usage for profiles that were provisioned by using the ProvisioningAgent by applying a
new account provisioning file that has updated plan information. You can provide a provisioning file that
contains only usage information, or only plan information. Depending on how much of the system configuration
you want to change, the new provisioning file can include the following:
Profiles, plan descriptions, and usage
Plan descriptions and usage (updates existing profiles)
Plan usage (updates existing profiles and plans)
If you apply new profiles and reference plans that are not defined in the XML, the provisioning results include a
warning.
Update data usage by using an SMS message
This is accomplished in one of the following ways:
Specify an operator message, receive an operator notification message, read the message by using the
SMS API, parse the message in the app, and then set the usage by using IProvisionedProfile .
Specify an operator message rule that has a valid combination of usage fields and directly provide the
updated usage in the SMS.
Troubleshooting
If you run into provisioning problems, you can use the following sections to help you figure it out.
Provisioning API results
If provisioning fails, you will receive an exception when you try to perform the provisioning action. Failures that
can cause exceptions include the following:
The provisioning XML does not conform to the CarrierControlSchema schema.
The provisioning XML requires a signature, but is not appropriately signed.
Partial provisioning failures
Portions of the provisioning operation might not succeed because of a variety of reasons. For example, you
might have a reference to Wi-Fi hardware that is not present at the time of provisioning. The provisioning agent
does a best effort attempt to provision everything in the file. When something fails, it is noted in the
provisioning results that are asynchronously returned by using ProvisionFromXmlDocumentAsync .
The results are returned as XML and can be parsed to discover the failure. Elements provide structure to show
what failed, and ErrorCode attributes indicate the reason for the failure as a standard HRESULT.
For example, the following error code indicates that no WLAN profiles were provisioned because the WLAN
service was not active:
<CarrierProvisioningResult>
<WLANProfiles ErrorCode=”80070426”/>
</CarrierProvisioningResult>
If an individual profile could not be applied, it will appear as follows:
<CarrierProvisioningResult>
<WLANProfiles>
<WLANProfile Name=”MyProfile” ErrorCode=”80070005”/>
</WLANProfiles>
</CarrierProvisioningResult>
Event Logs
Events in the Applications and Ser vices Logs\Microsoft\Windows\NetworkProvisioning\Operational
channel can provide detailed feedback about provisioning failures.
PowerShell ProvisioningTestHelper module
You can import the ProvisioningTestHelper module from the Windows 8, Windows 8.1, and Windows 10
SDKs. By using this module, you can generate and install EV certificates, sign an XML file by using the installed
certificate, and validate the XML against the provisioning schema. To import the module into a PowerShell
session, type the following command:
Import-Module "<path_to_sdk>\bin\<arch>\ProvisioningTestHelper.psd1"
Where <path_to_sdk\bin\<arch>> is the install location of the Windows 8, Windows 8.1, or Windows 10 SDK
that corresponds to the architecture of the computer.
After you import this module, the following four PowerShell cmdlets are available:
Install-TestEVCer t Generates a new CA certificate, registers it on your test computer as a trusted EV SSL
provider, and uses it to generate and install an EV certificate for use in signing. You must run this cmdlet
only one time to install the certificates. You can sign any number of files by using the certificates.
Install-TestEVCert -CertName <Certificate Name> -RootCertOutputPath <complete path to the folder to

which the root certificate is to be exported>
The client certificate has the name that is specified in the command and the root certificate has “Root”
appended to it together with the client certificate name. The -CertName parameter is optional. If the –
CertName parameter is not specified, MBAPTestCer t is used.
The -RootCertOutputPath parameter is also optional. It should be used if you want to export the root
certificate to be installed on another computer by using the Install-RootCertFromFile cmdlet.
Install-RootCer tFromFile Applies the test root certificate on a different computer, to test the client
experience on a computer other than the development computer.
Install-RootCertFromFile -CertFile <complete path to the root certificate>
Conver tTo-SignedXml Uses an EV certificate (generated for test, or issued by a third-party provider) to
apply an XML-DSig signature to a provisioning XML file. This signature from a trusted certificate causes
Windows to accept the provisioning file as valid from a mobile broadband app with no affiliated
hardware.
ConvertTo-SignedXml -InputFile <complete path to the input XML file> -OutputFile <complete path to
the output XML file> -CertName <name of the certificate used to sign the xml>
This command will sign the input XML file, put the signature in the XML, and save it to the output XML
file.
Test-ValidProvisioningXml Validates the Provisioning XML (signed or unsigned) against the
provisioning schema.
Test-ValidProvisioningXml -InputFile <complete path to the input XML file>

Introduction to COSA/APN database
This section contains information about both COSA and apndatabase.xml (APN database). COSA is a newer
format used in Windows 10, version 1703 and later, while APN database is used for Windows 8, Windows 8.1,
and versions of Windows 10 before Windows 10, version 1703.
COSA and the APN database are used by Windows networking components, such as the Windows Connection
Manager, to provide a seamless connection experience for end users by supplying and trying available
connection APNs based on the user’s mobile broadband device. COSA and the APN database contain the
information needed to connect to the mobile broadband network, allowing Windows to connect automatically
with minimal user input. They maintain access strings for different mobile network operators, enabling a user’s
connection to the operator’s network prior to acquiring any additional software or metadata. For example, a
user can get connected without having a mobile broadband app installed.
In addition to provisioning information, COSA and APN database also include a URL to the account experience
website. After automatically connecting to the operator’s network, the account experience website opens in the
default browser, where the user can purchase a subscription or one-time access.
The following topics present further information about APNs, COSA, and APN database.
APN elements
COSA overview
COSA/APN database submission
NOTE
The XML document must be saved by using UTF-8 encoding.
The following is a definition of the APN schema.
<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="OperatorList">
<xs:complexType>
<xs:sequence>
<xs:element ref="Operator" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Operator">
<xs:complexType>
<xs:sequence>
<xs:element ref="HardwareIdList"/>
<xs:element ref="ConnectionInfoList"/>
<xs:element ref="TrustedCertificateList" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required"/>
<xs:attribute name="AccountExperienceURL" type="xs:anyURI" use="optional"/>
<xs:attribute name="OperatorGUID" type="GUID" use="optional"/>
</xs:complexType>
</xs:element>
<xs:element name="HardwareIdList">
<xs:complexType>
<xs:sequence>
<xs:element ref="HardwareId" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="HardwareId">
<xs:complexType>
<xs:attribute name="id" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="ConnectionInfoList">
<xs:complexType>
<xs:sequence>
<xs:element ref="ConnectionInfo" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="ConnectionInfo">
<xs:complexType>
<xs:attribute name="AccessString" use="optional">

<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="0"/>
<xs:maxLength value="100"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="Username" use="optional">

<xs:simpleType>
<xs:whiteSpace value="collapse"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="Password" use="optional">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="FriendlyName" use="optional">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="Purchase" type="xs:boolean" use="required"/>
<xs:attribute name="Internet" type="xs:boolean" use="required"/>
<xs:attribute name="AutoConnectOrder" type="xs:positiveInteger" use="optional"/>
<xs:attribute name="Compression" use="optional">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="DISABLE"/>
<xs:enumeration value="ENABLE"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="AuthProtocol" use="optional">
<xs:simpleType>
<xs:enumeration value="NONE"/>
<xs:enumeration value="PAP"/>
<xs:enumeration value="CHAP"/>
<xs:enumeration value="MsCHAPv2"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name="TrustedCertificateList">
<xs:complexType>
<xs:sequence>
<xs:element ref="TrustedCertificate" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="TrustedCertificate">
<xs:complexType>
<xs:attribute name="SubjectName" type="xs:string" use="required"/>
<xs:attribute name="IssuerName" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:simpleType name="GUID">
<xs:pattern value="\{[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}\}"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
APN elements overview
This section describes the XML elements defined by the APN XML schema. The following is a list of these
elements in the order in which they are defined in the XML schema.
OperatorList
Operator
HardwareIdList
HardwareId
ConnectionInfoList
ConnectionInfo
TrustedCertificate
OperatorList
The OperatorList element specifies a list of operators included in the APN database.
Usage
<OperatorList>
child elements
</OperatorList>
Attributes
There are no attributes.
Child elements
EL EM EN T DESC RIP T IO N
Operator Specifies the details of the operator.
Parent elements
There are no parent elements.
XSD
<xs:element name="OperatorList">
<xs:complexType>
<xs:sequence>
<xs:element ref="Operator" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Remarks
The OperatorList element is required.
Operator
The Operator element specifies the details of an operator that is included in the APN database.
Usage
<Operator name=”xs:string” AccountExperienceURL=”xs:anyURI” OperatorGUID=”GUID”>
child elements
</Operator>
Attributes
AT T RIB UT E TYPE REQ UIRED DESC RIP T IO N
Name xs:string Yes The name and

country/region of the
operator.
Example: Contoso
(Argentina)
AccountExperienceURL xs:anyURI No The URL of the

operator’s website used
to configure Mobile
Broadband.
OperatorGUID GUID No A GUID used to identify

the operator.
Child elements
HardwareIdList A list of hardware IDs that are assigned to the operator.
ConnectionInfoList A list of access strings.
TrustedCertificateList A list of trusted certificates used to verify that account

provisioning is provided by a purchase website owned
by the operator.
Parent elements
OperatorList The parent element of the APN XML schema.
XSD
<xs:element name="Operator">
<xs:complexType>
<xs:sequence>
<xs:element ref="HardwareIdList"/>
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required"/>
<xs:attribute name="AccountExperienceURL" type="xs:anyURI" use="optional"/>
<xs:attribute name="OperatorGUID" type="GUID" use="optional"/>
</xs:complexType>
</xs:element>
Remarks
The Operator element is required.
HardwareIdList (APN element)
The HardwareIdList element specifies a list of hardware IDs for the operator.
Usage
<HardwareIdList>
child elements
</Operator>
Attributes
Child elements
HardwareId An operator hardware ID.
Parent elements
Operator Specifies the details for an operator in the APN database.
XSD
<xs:element name="HardwareIdList">
<xs:complexType>
<xs:sequence>
</xs:sequence>
</xs:complexType>
</xs:element>
Remarks
The HardwareIdList element is required.
HardwareId (APN element)
The HardwareId element specifies the HWID for the specified operator.
Usage
<HardwareId>
...insert text here
</HardwareId>
Attributes
Text value
A string that represents an encoded hardware ID. Generating the proper hardware ID values involves a complex
algorithm. We recommend that you use mbidgenerator.exe to generate your hardware IDs.
Child elements
There are no child elements.
Parent elements
HardwareIdList Specifies the list of hardware IDs for an operator.
XSD
<xs:element name="HardwareId">
<xs:complexType>
<xs:attribute name="id" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
Remarks
The HardwareId element must represent one of the following:
GSM networks: IMSI range
GSM networks: ICCID range
CDMA networks: Provider name value
CDMA networks: Provider ID value (also known as SID)
The HardwareId element is required.
ConnectionInfoList
The ConnectionInfoList element specifies a list of connections for the specified operator.
Usage
<ConnectionInfoList>
child elements
</ConnectionInfoList>
Attributes
Child elements
ConnectionInfo An operator hardware ID.
Parent elements
Operator Specifies the details for an operator in the APN database.
XSD
<xs:element name="ConnectionInfoList">
<xs:complexType>
<xs:sequence>
</xs:sequence>
</xs:complexType>
</xs:element>
Remarks
The ConnectionInfoList element is required.
ConnectionInfo
The ConnectionInfo element specifies a list of connections for the specified operator.
Usage
<ConnectionInfoList AccessString=”xs:string” Username=”xs:string” Password=”xs:string”
FriendlyName=”xs:string” Purchase=”xs:Boolean” Internet=”xs:Boolean” AutoConnectOrder=”xs:positiveinteger”
Compression=”xs:token” AutoProtocol=”xs:token”>
Attributes
AccessString xs:string No The name and

country/region of the
operator.
Example: Contoso
(Argentina)
Username xs:string No The username is used

to connect to the
Internet.
Password xs:string No The password used to

connect to the Internet.
FriendlyName xs:string No The value shown in

Windows Connection
Manager in the APN
drop-down box.
Purchase xs:boolean Yes Denotes whether the

access string should be
used for purchase or
Internet.
Internet xs:boolean Yes Denotes whether the

access string should be
used for purchase or
Internet.
AutoConnectOrder xs:positiveinteger No Determines the order in

which Windows tries to
connect to each of the
APNs in the
ConnectionInfoList
element.
Compression xs:token No Specifies if compression

will be used at the data
link for header and data
transfer.
Values: ENABLE or
DISABLE
AuthProtocol xs:token No Specifies the

authentication protocol
used for activating a
PDP context.
Values: NONE, PAP,
CHAP, or MsCHAPv2
Child elements
Parent elements
ConnectionInfoList Specifies the details for an operator in the APN database.
XSD
<xs:element name="ConnectionInfo">
<xs:complexType>
<xs:attribute name="AccessString" use="optional">

<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="Username" use="optional">

<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="Password" use="optional">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="FriendlyName" use="optional">
<xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="Purchase" type="xs:boolean" use="required"/>
<xs:attribute name="Internet" type="xs:boolean" use="required"/>
<xs:attribute name="AutoConnectOrder" type="xs:positiveInteger" use="optional"/>
<xs:attribute name="Compression" use="optional">
<xs:simpleType>
<xs:enumeration value="DISABLE"/>
<xs:enumeration value="ENABLE"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="AuthProtocol" use="optional">
<xs:simpleType>
<xs:enumeration value="NONE"/>
<xs:enumeration value="PAP"/>
<xs:enumeration value="CHAP"/>
<xs:enumeration value="MsCHAPv2"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
Remarks
The ConnectionInfo element is required.
The TrustedCertificateList element specifies a list of trusted certificates for the operator.
Usage
<TrustedCertificateList>
child elements
</TrustedCertificateList>
Attributes
Child elements
TrustedCertificate A certificate trusted by the operator.
Parent elements
OperatorList The parent element of the APN XML schema.
XSD
<xs:element name="TrustedCertificateList">
<xs:complexType>
<xs:sequence>
</xs:sequence>
</xs:complexType>
</xs:element>
Remarks
The TrustedCertificateList element is optional.
TrustedCertificate (APN element)
The TrustedCertificate element specifies a trusted certificate for the specified operator.
Usage
<TrustedCertificate SubjectName=”xs:string” IssuerName=”xs:string”>
</TrustedCertificate>
Attributes
SubjectName xs:string Yes The subject name of the

certificate.
IssuerName xs:string Yes The issuer name of the

certificate.
Child elements
Parent elements
TrustedCertificateList Specifies a list of trusted certificates for the operator.
XSD
<xs:element name="TrustedCertificate">
<xs:complexType>
<xs:attribute name="SubjectName" type="xs:string" use="required"/>
<xs:attribute name="IssuerName" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
Remarks
The TrustedCertificate element is optional.
APN example
The following XML document uses the APN XML schema to specify the APN information for a service:
<?xml version="1.0" encoding="utf-8"?>

<OperatorList
<Operator name="Contoso">
<HardwareIdList>
<HardwareId id="MBAE:0:XSDR^EREDER^F">
</HardwareId>
</HardwareIdList>
<ConnectionInfoList>
<ConnectionInfo AccessString="ContosoAPN" Username="user" Password="pass" FriendlyName="Prepaid
Contoso Mobile Broadband" Internet="Y" Purchase="N" AutoConnectOrder="1"/>
</Operator>
</OperatorList>
COSA overview
COSA, or Country and Operator Settings Asset, is the new format that Mobile Operators (MOs) use in Windows
10, version 1703 and later to provision Windows devices for mobile broadband. The existing APN database
(apndatabase.xml) from Windows 8, Windows 8.1, and versions of Windows 10 before 1703 has been
converted to COSA, which is ingestible by the new provisioning framework. Note that these previous versions
of Windows will continue to use the older APN database for provisioning desktop devices.
For more information about the older APN database, see APN database overview.
To see a list of available settings MOs can configure in desktop COSA, see Desktop COSA/APN database
settings.
FAQ
What are the settings that MOs can specify in COSA?
What events trigger the application of new MO settings?
What SIM information from modems does COSA use?
Is there an algorithm to make the best APN match?
Where is the COSA database stored, and can it be visually inspected like apndatabase.xml?
What happens when a device updates from Windows 10, version 1607 (or earlier) to Windows 10, version
1703? Are custom or manually created APNs migrated? Do they still have priority over the defaults from the
database?
Why does the Set as metered connection setting sometimes change from Off to On ?
What are the settings that MOs can specify in COSA?
The settings are largely the same as what MOs configured in apndatabase.xml, with a few exceptions and new
additions. For details, see the tables in Planning your desktop COSA/APN database submission.
What events trigger the application of new MO settings?
Three events trigger the Windows provisioning engine to look for a change in settings:
1. The insertion or removal of a physical SIM (change in ICCID)
2. Reconfiguration of an eSIM (change in ICCID)
3. When the device boots
What SIM information from modems does COSA use?
For MO/MVNO discovery, Windows tries to make the best match for an available profile in the COSA database
using SPN from the SIM in the modem.
Is there an algorithm to make the best APN match?
In versions of Windows before Windows 10, version 1703, MOs could specify an auto-connect order. Windows
10, version 1703 and later continue to use a round-robin approach through all available APNs, but there is no
longer a specific order that the algorithm uses.
Where is the COSA database stored, and can it be visually inspected like apndatabase.xml?
COSA is in the format of a Windows 10 provisioning package (.ppkg). It is in the
Windows\Provisioning\COSA\Microsoft folder. You can use a third-party tool, such as 7-Zip File Manager
(www.7-Zip.org), to visually inspect its contents.
Note that OEM extensions to COSA, if specified in the device image, are in the COSA\OEM folder. For more
information, see Customize the Country and Operator Settings Asset.
What happens when a device updates from Windows 10, version 1607 or earlier to Windows 10, version 1703
or later? Are custom or manually created APNs migrated? Do they still have priority over the defaults from
the database?
COSA replaces apndatabase.xml after the upgrade. If an APN was provisioned in the previous version, whether
custom, manual, or device-provisioned via the database, it is migrated as a part of the upgrade to version 1703
and the device continues to use it for connectivity without requiring any additional action. Manually provisioned
APNs still have priority over the defaults from the database just as they did in version 1607 and earlier.
Why does the "Set as metered connection" setting sometimes change from Off to On?
Updates to the Windows operating system may include updates for the COSA database. If the database is
updated, the provisioning engine may remove the cellular profiles. When the system restarts after database
updates are installed, the provisioning engine reinstalls the cellular profiles. This operation resets user settings
to their default values. For example, Set as metered connection changes from Off to On . This behavior is by
design.
The APN database, or apndatabase.xml, is the provisioning database that Mobile Operators (MOs) use to
configure mobile broadband experiences for their networks. It is available in Windows 8, Windows 8.1, and
versions of Windows 10 before Windows 10, version 1703.
Starting in Windows 10, version 1703, the APN database is replaced by a new format called COSA. Windows 8,
Windows 8.1, and versions of Windows 10 before version 1703 will continue to use the APN database while
Windows 10, version 1703 and later use COSA.
For more info about COSA, see COSA overview.
To see a list of available settings MOs can configure in the APN database, see Desktop COSA/APN database
settings.
APN database contents

To connect to a mobile broadband network, the user typically provides the following information:
In Global System for Mobile Communications (GSM) networks, an APN such as data.contoso.com .
In CDMA networks, an access string that includes a special dial code such as #777 , or a Network Access
Identifier (NAI) such as ann@contoso.com .
The user’s credentials (username and password) for the network connection.
Specifically, the APN database includes the following data:
Operator identification data
For a GSM network, you can submit database entries for the International Mobile Subscriber
Identity (IMSI) or Integrated Circuit Card Identifier (ICCID) ranges that your network uses. If you are
a mobile virtual network operator (MVNO), you can specify one or more ranges of IMSIs or
subscriber identification module (SIM) ICC IDs that you leased from a mobile network operator
(MNO).
For CDMA networks, you can submit new database entry for each Provider ID or Provider Name.
To better understand how you can identify MVNOs, see Delivering experiences for MVNOs.
List of purchase APNs and access strings
For a GSM network, a list of APNs that have a username and password to purchase the
subscription.
For a CDMA network, a list of NAIs to purchase the subscription.
List of Internet connect APNs and access strings
For a GSM network, a list of APNs that have a username and password to connect to the Internet.
For a CDMA network, a list of NAIs that are used to connect to the Internet.
Account Experience URL URL for a first-time purchase account experience web site.
Cer tificate Data Certificate information for account provisioning metadata. This includes Certificate
Issuer Name and Subject Name, and is used to verify that Account Provisioning that is provided by a
purchase web site comes from the user’s authorized web service.
For more information on the APN database XML schema, see APN database schema reference.
APN database submission and maintenance

If you want to request a new APN or update an existing one, see COSA/APN database submission.
Planning your desktop COSA/APN database
submission
IMPORTANT
Starting in Windows 10, version 1703, the APN database is replaced by a new format called COSA. Windows 8, Windows
8.1, and versions of Windows 10 before version 1703 will continue to use the APN database while Windows 10, version
1703 and later use COSA. For more information about COSA, see COSA overview.
Use the sections in this topic when you are planning to add a new APN to the baseline COSA/APN database that
ships with Windows desktop devices, or update an existing one.
The APN update process

To connect to a mobile broadband network, the user is typically required to provide the following information:
On GSM networks, an Access Point Name (APN) such as "data.contoso.com" is required.
On CDMA networks, an access string that includes a special dial code such as "#777" or a Network Access
Identifier such as somebody@contoso.com is required.
A username and password for the network connection.
COSA and the APN connectivity database are updated by using Windows Update. The figure below shows the
overall submission process.
Complete the APN/COSA update spreadsheet

The APN update spreadsheet is used to gather the required information so Microsoft can update the COSA or
the APN database appropriately. This spreadsheet is included in your submission request to Microsoft. MOs
should send all information to target all devices to Microsoft when submitting an APN update, if applicable.
Use the following link to download the latest APN update spreadsheet: https://go.microsoft.com/fwlink/p/?
linkid=851213
For more info about the settings in the APN update spreadsheet, see Desktop COSA/APN database settings.
Considerations when completing the spreadsheet

APN database considerations
Note the following only when submitting an APN update using apndatabase.xml, for Windows 8, Windows 8.1,
or versions of Windows 10 before Windows 10, version 1703.
The operator identification data is stored in the APN database as encoded Hardware IDs.
For GSM networks, you can have a separate database entry for each unique combination of
MCC/MNC pair. If you are a Mobile Virtual Network Operator (MVNO) and do not have a unique
MCC/MNC pair, you can specify one or more ranges of IMSIs or SIM ICC IDs currently leased from a
Mobile Network Operator (MNO).
For CDMA networks, you can have a new database entry for each Provider ID (also called a SID) or
Provider Name.
Certificate information for account provisioning metadata includes Cer t Issuer Name and Cer t
Subject Name and is used to verify that account provisioning provided by a purchase website comes
from the an authorized web service. If the certificate information stored here matches what the
purchase website presents, Windows will allow that website to push network-specific configuration
information to the PC.
When submitting an APN database update using apndatabase.xml, the following values must be included:
A CDMA Provider name

A CDMA Provider ID (SID)
Certificate information for account provisioning metadata includes Cer t Issuer Name and Cer t
Subject Name and is used to verify that account provisioning provided by a purchase website comes
from an authorized web service. If the certificate information stored here matches what the purchase
website presents, Windows will allow that website to push network-specific configuration information to
the PC.
The auto-connect order must be unique for the Operator and Countr y/Region combination with the
same IMSI, ICCID range, CDMA provider name, or CDMA provider ID value.
For example, if Contoso had four APNs for MCC+MNC value 100 101, it would list each APN entry in a
new row in the spreadsheet and number the auto-connect order starting with 1 up to 4 for each of those
four entries because they share the same IMSI range. If Contoso had another set of APNs for MCC+MNC
value 100 102, it should start the auto-connect ordering at 1 for that set of APNs.
If you don’t provide an auto-connect order, Windows will ask the user to choose an APN, which could
introduce user error. We recommend that the auto-connect order be specified. In this case, the user sees
the Friendly Name of the APN in Windows Connection Manager.
APN database and COSA considerations
Note the following for both COSA and APN database.
Changes provided by the OEM will take precedence over the default COSA/APN database included in
Windows.
The Countr y/Region and the Operator entries in the spreadsheet are used to determine whether this is
an update to an existing APN or a request for a new APN. If the Countr y/Region and the Operator
fields match content that already exists in the APN database, the entries will be deleted and replaced with
the entries that you list in your spreadsheet.
NOTE
Because the previous entries will be deleted, it is important to list all APNs for the Operator and
Countr y/Region combination, including the ones that are not changing.
For example, when the following values are entered in a row in the spreadsheet:
Operator: Contoso
Country/Region: Argentina
All entries currently in the COSA or APN connectivity database that match the following format will be
deleted and replaced with the row in your spreadsheet for that Operator and Countr y/Region
combination:
<Operator name="Contoso (Argentina)">
If the Operator and Countr y/Region entries do not match content that already exists in COSA or the
APN database, a new APN is created.
For example, if the following values are entered in a row in the spreadsheet:
Operator: Contoso
Country/Region: Argentina
If it does not exist in the appropriate connectivity database, a new entry is added after your submission is
accepted that looks like the following:
<Operator name="Contoso (Argentina)">
On each row of the spreadsheet that is submitted, you must specify only one of the following:
An MCC+MNC with a blank IMSI range
An MCC+MNC with a specific IMSI range
An MCC+MNC with a specific ICCID range
An MCC+MNC with a specific GSM provider name
If you have created a website for setting up Mobile Broadband service, it is important to provide the
Account Experience URL and certificate data.
Access strings used for plan purchase (Purchase Flag =Y ) can be one of the following:
For GSM networks, an APN with a specified User Name and Password used for purchasing the
subscription.
For CDMA networks, a Network Access Identifier (NAI) is used for purchasing the subscription.
Access strings used for Internet connectivity (Connect Flag =Y ) can be one of the following:
For GSM networks, an APN with a specified User Name and Password used to connect to the
Internet.
For CDMA networks, a Network Access Identifier (NAI) is used to connect to the Internet.
Once your spreadsheet is complete, you can test the APNs you’ve entered. For the next steps in testing your
APN update, see Testing your desktop COSA/APN database submission.
Desktop COSA/APN database settings
This topic describes the settings available in desktop COSA and the APN database (apndatabase.xml).
For more info about the Desktop COSA/APN database submission process, see Planning your desktop
COSA/APN database submission.
For more info about COSA, see COSA overview.
For more info about the APN database, see APN database overview.
APN database-only settings

The following settings in the spreadsheet apply to the APN database only. These entries will be used if you are
targeting Windows 8, Windows 8.1, or versions of Windows 10 before Windows 10, version 1703.
SET T IN G N A M E DESC RIP T IO N O P T IO N A L O R REQ UIRED N OT ES
CDMA ProviderID A 5-digit number that Optional

should match the CDMA
provider ID (also called SID)
reported by your device.
CDMA ProviderName A string of no more than 36 Optional

characters that should
match the CDMA provider
name reported by your
device. This setting is case
sensitive.
CertIssuerName The Cert Issuer Name of Optional If specified, you must also
your signing certificate used specify the Cert Subject
for operator XML Name and Carrier GUID.
provisioning.
CertSubjectName The Cert Subject Name of Optional If specified, you must also
your signing certificate used specify the Cert Issuer
for operator XML Name and Carrier GUID.
provisioning.
Carrier GUID The self-assigned GUID that Optional If specified, you must also
is used in future operator specify the Cert Subject
XML provisioning packages. Name and Cert Issuer
Name.
GSM ProviderName A string of no more than 36 Optional This setting is only

characters that should supported on Windows 8.1
match the GSM provider and versions of Windows
name reported by your 10 before Windows 10,
device. This setting is case version 1703.
sensitive.
SET T IN G N A M E DESC RIP T IO N O P T IO N A L O R REQ UIRED N OT ES
Purchase A yes or no value describing Required Possible values:

if the APN is provisioning or Y – if the APN is
purchase. provisioning or
purchase
N – if the APN is not
provisioning or
purchase
If Purchase Flag
setting is Y , the
Connect Flag setting
must be N.
Connect A yes or no value describing Required Possible values:

if the APN is provisioning or Y – if the APN is
purchase. provisioning or
purchase
N – if the APN is not
provisioning or
purchase
If Connect Flag
setting is Y , the
Purchase Flag setting
must be N.
APN database and desktop COSA settings

The following entries apply to both APN database and desktop COSA. For COSA, the minimum supported
version of Windows required is indicated in the last column.
M IN IM UM
SUP P O RT ED
O P T IO N A L O R W IN DO W S VERSIO N
SET T IN G N A M E DESC RIP T IO N REQ UIRED N OT ES F O R C O SA
UpdateType Describes whether Required Possible values: Windows 10, version

the APN Database Add – A new 1703
entry is new or entry
modified. Change –
Update an
existing entry
Keep – Do
not change
the entry
Delete –
Delete the
entry
Country/Region The country or Required This entry might Windows 10, version
region for the APN change to match 1703
entry. how Windows refers
to a particular
country or region.
M IN IM UM
SUP P O RT ED
Operator The name of the Required Ensure you use the Windows 10, version
operator. You do not same spelling and 1703
need to include the capitalization each
country or region in time you submit an
this field. update for your APN
entries.
MCC A 3-digit MCC value Optional for ICCID Windows 10, version
used for GSM IMSI ranges. 1703
submissions.
MNC A 2- or 3-digit MNC Optional for ICCID Windows 10, version

value used for GSM ranges. 1703
IMSI submissions.
IMSI Range - Start A 15-digit number Optional The number should Windows 10, version
that includes the end in 00. 1703
MCC+MNC at the If this setting and
start of the number. the IMSIRange
- End setting is
left blank but the
MCC and MNC
entries are
specified, the
entire
MCC+MNC
range is covered.
IMSI Range - End A 15-digit number Optional The number should Windows 10, version
that includes the end in 99. 1703
MCC+MNC at the If this setting and
start of the number. the IMSI Range
- Star t setting is
left blank but the
MCC and MNC
entries are
specified, the
entire
MCC+MNC
range is covered.
ICCID Range - Start A 19- or 20-digit Optional The number should Windows 10, version
number that starts end in 00. 1703
with 89 (the ICCID
issuer identifier
number).
ICCID Range - End A 19- or 20-digit Optional The number should Windows 10, version
number that starts end in 99. 1703
with 89 (the ICCID
issuer identifier
number).
M IN IM UM
SUP P O RT ED
AccountExperienceUR Used by Windows Optional Helps improve the Windows 10, version
L Connection Manager plan acquisition 1703
if the user does not experience.
have an active plan If both AppID
and tries to connect and
to your network. AccountExperienc
eURL are
specified, AppID
receives higher
precedence and
the UX will not
display the
AccountExperienc
eURL.
FriendlyName A name for this APN Optional Appears in the Windows 10, version
entry that is Windows Connection 1703
understandable and Manager in cases
meaningful to where Windows
subscribers. cannot automatically
connect to the
network.
AccessString For GSM networks, Required Windows 10, version

this is an APN such 1703
as data.contoso.com.
For CDMA networks,
this is an access
string that includes a
special dial code such
as #777 or an
Network Access
Identifier such as
example@contoso.co
m.
UserName The user name used Optional Windows 10, version

to connect to your 1703
APN. This setting is
case sensitive.
Password The password used Optional Windows 10, version

to connect to your 1703
APN. This setting is
case sensitive.
M IN IM UM
SUP P O RT ED
AuthProtocol Specifies the Optional Possible values: Windows 10, version

authentication NONE – No 1703
protocol to be used authenticatio
for activating a n protocol is
Packet Data Protocol required
(PDP) context. PAP – PAP
authenticatio
n is required.
CHAP –
CHAP
authenticatio
n is required.
MsCHAPV2
–MSCHAPv2
is
authenticatio
n is required.
This setting is
only supported
on Windows 8.1
and versions of
Windows 10
before Windows
10, version 1703.
Compression Specifies if Optional Possible values: Windows 10, version

compression will be ENABLE – 1703
used at the data link Compression
for header and data is enabled
transfer. DISABLE –
Compression
is not enabled
This setting is
only supported
on Windows 8.1
and versions of
Windows 10
before Windows
10, version 1703.
M IN IM UM
SUP P O RT ED
AutoConnectOrder Windows tries Optional If you have more Windows 10, version
connections to the than one access 1809
APNs provided by string for an
the operator and operator, this setting
marked as “auto- must start with 1.
connect” in APN This is needed for
database or COSA Windows to try
until it successfully several APN entries
connects to the that share either an
mobile network. If all IMSI range, ICCID
auto-connect range, CDMA
attempts fail, provider ID, or
Windows will show a CDMA provider
prompt allowing the name when the user
user to pick an APN tries to connect.
or enter a custom
APN.
Desktop COSA-only settings

The following settings apply to desktop COSA only. These entries will be used if you are targeting Windows 10,
version 1703 and later.
M IN IM UM
O P T IO N A L O R SUP P O RT ED
SET T IN G N A M E DESC RIP T IO N REQ UIRED N OT ES W IN DO W S VERSIO N
SupportDataMarketp A true/false string Optional Before enabling Windows 10, version

lace describing whether a this setting, 1703
profile entry please ensure
supports Mobile that your Mobile
Plans. Operator is part
of the Mobile
Plans program.
If left blank,
defaults to
"false."
SPN An identifier string Optional Helps to identify the Windows 10, version
for the Service MO/MVNO's 1703
Provider Name (SPN) network. If left blank,
defaults to empty
string and does
nothing.
AlwaysOn Describes whether Required If left blank, defaults Windows 10, version
the connection is to "true." 1703
always on or not.
M IN IM UM
PurposeGroups A string specifying Required The following Windows 10, version

the purposes of the purpose values are 1703
connection by a available:
comma-separated list Internet
of GUIDs MMS
representing purpose IMS
values. SUPL
Purchase
Administrati
ve
Application
eSIM
provisioning
If left blank,
defaults to
"Internet."
Optional The following Windows 10, version

optional purpose 1903
group value is
available:
LTE attach
Specifying an LTE
attach APN through
COSA is typically
unnecessary because
the attach info is
usually managed
directly by the
underlying modem's
hardware. However,
in the case where the
modem's hardware
does not have an LTE
attach APN value and
the network is
incapable of
assigning one to the
UE, the MO can
optionally provide
LTE attach
information so that
the UE can LTE attach
without the user
manually entering a
value.
IPType A string specifying Optional Possible values: Windows 10, version

the network protocol IPv4 1703
of the connection. IPv6
IPv4v6
If left blank,
defaults to
"IPv4."
M IN IM UM
BrandingName The mobile Optional If left blank, defaults Windows 10, version
broadband device to empty string and 1709
typically provides the does nothing.
operator name,
which Windows
shows in the
Windows Connection
Manager. You can
override this name
by specifying a
custom name in
metadata.
BrandingIcon A custom logo that Optional Icons must have Windows 10, version
appears in the transparent 1709
Windows Connection backgrounds and
Manager next to smooth edges. It's
your network entry. recommended to test
the icon with both
light and dark
themes. They must
also meet the
following format and
size requirements:
256 x 256:
32-bit +
Alpha
48 x 48: 32-
bit + Alpha
48 x 48: 8-bit
256 color
48 x 48: 4-bit
16 color
32 x 32: 32-
bit + Alpha
32 x 32: 8-bit
256 color
32 x 32: 4-bit
16 color
24 x 24: 32-
bit + Alpha
24 x 24: 8-bit
256 color
24 x 24: 4-bit
16 color
16 x 16: 32-
bit + Alpha
16 x 16: 8-bit
256 color
16 x 16: 4-bit
16 color
M IN IM UM
UseBrandingNameO Determines if the Optional Possible values: Windows 10, version

nRoaming branding should be 0 - Use only 1709
displayed during when
roaming or not connected to
roaming. home
network
1 - Use when
connected to
home
network and
domestic
roaming
2 - Use when
connected to
home
network,
domestic
roaming, and
international
roaming
If left blank,
defaults to 0.
Roaming Specifies the roaming Optional Possible values: Windows 10, version
conditions under 0: Home 1709
which the connection network only
should be activated. 1: All roaming
conditions
(home and
roaming)
2: Home and
domestic
roaming only
3: Domestic
roaming only
4: Non-
domestic
roaming only
5: Roaming
only
If left blank, defaults
to 1 (all roaming
conditions).
M IN IM UM
DataMarketplaceRoa This setting controls Optional This setting works Windows 10, version
mingUIEnabled whether the roaming with the 1709
UI should be shown Suppor tDataMark
for a SIM or eSIM etPlace setting. The
that is part of the possible values are:
Mobile Plans service. 0: The
roaming
indicator will
never be
displayed.
1: The
roaming
indicator is
displayed
when the
device is
roaming in a
foreign
country.
If left blank,
defaults to 1 .
UIName If the target Optional For example, Windows 10, version

condition values ContosoMVNO is 1709
(SPN, MCC, MNC, an MVNO. It doesn't
IMSI Range, ICCID have any unique
Range, etc.) can't values that can be
indicate the unique used to distinguish
entry, then COSA will itself from the main
display this name to MO network,
the end user to Contoso . In this
enable manual case, UIName can
selection of which be used and will be
MO's connection shown in the
value to use. Windows Settings UI,
enabling the user to
manually select which
MO provisioning
settings to use.
UIOrder The index to control Required if UIName If not specified, Windows 10, version
the UIName value's is specified; Optional defaults to 0 . 1709
dropdown list picker otherwise
position.
M IN IM UM
ESIM_PROV A true/false string Impor tant Optional If left blank, Windows 10, version
describing whether unless the MO defaults to 1709
the profile is to be supports an eSIM "false."
considered as an provisioning profile,
eSIM provisioning in which case it is An eSIM
profile. required. provisioning
profile is a single-
purpose profile.
When it is
installed on the
eUICC, it enables
the user's
equipment to
establish a
limited
connection to
the MO's walled
garden in order
to purchase a
regular,
operational eSIM
profile.
M IN IM UM
AppID A string describing Optional In Windows 10, Windows 10, version

the Package Family version 1803 and 1803
Name (PFN) and later, AppID is used
application ID of a to identify MOs with
mobile operator's their companion
UWP companion apps. AppID must
app. be declared in this
format:
PFN!AppId
Note This format
is case sensitive.
To obtain the
PFN and AppId
for your app,
follow these
steps:
1. Acquire the
PFN as
specified on
View App
Identity
Details.
2. Locate the
AppId by
opening your
solution's
AppManifest.
XML file and
querying the
AppXManifest
for the
application ID.
For more info
about UWP
companion apps
for MOs, see
UWP mobile
broadband apps.
M IN IM UM
Hotspot Determines if you Optional Possible values: Windows 10, version

want to permit users Never 1803
to share their mobile Always
broadband EntitlementCh
connection as a eckRequired
personal hotspot.
If left blank,
defaults to
"Always."
The
EntitlementCheck
Required option
enables users to
share their
hotspots with an
entitlement
check, which
requires a
handler for
Windows
notification
events. If this
option is
selected, you
need to develop
an MO UWP
companion app
to handle the
entitlement
check requests.
For more info
about UWP
companion apps
for MOs, see
UWP mobile
broadband apps.
For more info
about the
EntitlementCheck
API, see its UWP
API reference
page.
M IN IM UM
EnableAutoSlotSwitch Determines if you Optional Possible values: Windows 11

want to automatically "false": When
switch slots when a a new SIM is
SIM is inserted. either
inserted or
removed, a
toast is
displayed
asking if the
user wants to
switch slots.
The slot is
switched only
if the user
clicks "yes" on
this toast.
"true": On
SIM insert,
the slot is
switched
automatically
and then a
toast is
displayed
informing the
user that the
slot has been
switched. This
toast doesn’t
take any
button input
from the user.
The SIM
removed
behavior
remains
unchanged.
If not specified,
defaults to
"false".
Testing your desktop COSA/APN database
submission
Before submitting an APN update request to Microsoft, it is important for the MNO or MVNO to validate the
APN entries that they are about to submit. Microsoft does not have access to your network, so it is your
responsibility to ensure the values that are being submitted are valid and work correctly.
Contact your Microsoft TAM

The first step in testing and submitting your APN update is to work with your TAM to open a MS Solve case with
Microsoft Customer Services and Support. This case is for tracking purposes. After a MS Solve case is opened,
provide the following information to the support engineer:
A completed spreadsheet that contains your APN information.
If you do not have a TAM:
Contact Microsoft Customer Services and Support by calling (800) MICROSOFT (642-7676).
Inform the customer service representative that a COSA/APN database update is needed.
Provide the spreadsheet to the support engineer.
If asked, specify Windows 8 or Windows 10 as the product, as appropriate.
NOTE
You will need to provide a credit card to open the incident, but you will not be charged.
Test your submission for desktop COSA

Use this process for Windows 10, version 1703 and later.
After you have submitted your completed spreadsheet that contains your APN information to your TAM,
Microsoft will create a provisioning package (.ppkg) file for you and return it to you so you can install and test
your APN.
For more information about how to install a provisioning package file, see Apply a provisioning package.
Modify the local COSA database (desktop COSA )
Follow these steps to test the updated COSA Provisioning Package (PPKG) you received from Microsoft after
completing your APN information spreadsheet and submitting it to your TAM.
These steps require a script from Microsoft to apply and test the PPKG file. Use the following link to download
the latest version of the script: https://go.microsoft.com/fwlink/p/?linkid=866771.
Apply the test PPKG file
IMPORTANT
Create a backup of the original provisioning package before performing the following actions. The original provisioning
package is located here: %systemroot%\Provisioning\Cosa\Microsoft\Microsoft.Windows.Cosa.Desktop.Client.ppkg .
1. Remove any SIM from the device, if any.
2. Copy the script and the new PPKG file to a local directory.
3. Open an elevated Command Prompt window and change to the directory containing the script.
4. Run the script with this syntax to apply the PPKG:
ApplyCosaProvisioning.BAT -a <full path to the PPKG local directory> .
a. For example:
ApplyCosaProvisioning.BAT -a "C:\FromMicrosoft\Microsoft.Windows.Cosa.Desktop.Client.ppkg"
5. Insert the SIM and await provisioning.
Restore the original PPKG file
WARNING
Once validation of the new PPKG received from Microsoft has completed, always restore it with the following steps.
Restoring back to the original PPKG will ensure that you receive the latest COSA updates via Windows Update.
1. Once validated, remove the SIM from the device.

2. Run the script with this syntax to restore the original PPKG: ApplyCosaProvisioning.BAT -r .
3. Insert the SIM for provisioning to take effect, reading the original PPKG.
Collect logs in case of failure
To collect logs in the event of a failure during the testing process, follow these steps:
1. Remove any SIM from the device.
2. Run the script with this syntax to start netsh logging: ApplyCosaProvisioning.BAT -l .
3. Insert the SIM and wait for provisioning to fail.
4. Follow the tool's prompts to end logging.
5. Send the logs to Microsoft in zipped format.
Test your submission for the APN database (apndatabase.xml)

Use this process for Windows 8, Windows 8.1, and versions of Windows 10 before Windows 10, version 1703.
There are two ways that you can ensure that the APN entries work before submitting them to Microsoft:
Editing APN values for the current profile
Modify the local APN database
Editing APN values for the current profile
A simple way to test that an APN can connect to your network is to edit the current profile and insert the APN to
test into the profile. To perform this test, follow these steps:
NOTE
This test does not simulate the full experience, which is described in the Modify the local APN database section.
1. Insert a SIM into the PC that works with the APN value you want to test.
2. Turn on the PC, log on to Windows, and open Windows Connection Manager. The mobile broadband
connection should appear.
3. Right-click the mobile broadband connection, and then select View connection proper ties .
4. Enter the APN value to test into this dialog box.
5. Save your changes, and then try to connect to the mobile broadband network.
Modify the local APN database
Before you submit an APN update, you should editing the local APN database or creating a new one for testing.
By doing this, you closely simulate the full experience because the APN selection logic that Windows Connection
Manager uses is fully tested.
Modify the local APN connectivity database
1. Copy any existing values from the local APN database file -- View the existing entries in the local
APN database on your PC and copy these entries into a new XML file. If you don’t have any APN entries in
the local copy of the APN database, skip this step and start with a blank XML file.
2. Modify values in the XML file according to the published APN schema – Ensure that your APN
entries follow the APN database schema reference.
3. Generate your hardware IDs – Hardware IDs specify one or more hardware identification strings that
match the SIM characteristics to an APN entry in the database. Each string is specified by a HardwareId
element. We recommend that you use mbidgenerator.exe to generate your hardware IDs. For more
information, see Using mbidgenerator.exe to generate hardware IDs.
4. Validate that the file you generated conforms to the published APN database schema --
Always perform a schema check to ensure that the file you have generated conforms to the APN
database schema reference.
5. Over write the APN connectivity database on the PC with your new database
a. From an elevated command prompt, type cd %systemroot%\system32 and then press ENTER.
b. Type takeown /f .\ApnDatabase.xml and then press ENTER.
c. Type icacls .\ApnDatabase.xml /grant %username%:F and then press ENTER.
d. Copy your customized version of the ApnDatabase.xml file to the directory.
6. Validate that the APN entries exist in the local APN database:
a. Ensure that there are no existing mobile broadband profiles by running the following command:
netsh mb show profiles
b. If a mobile broadband profile exists, type netsh mb profile interface=<Interface name>
name=<Profile name>
c. Ensure that the device doesn’t have a provisioned context by running the following command:
netsh mb show provisionedcontext interface=<Interface name>
Note If the device provides a provisioned context, Windows will use the APN from that
provisioned context instead of the local APN database and you will not able to test your APNs. If
the device has a provisioned context, you need to acquire another device that doesn’t provide a
provisioned context.
d. Open Windows Connection Manager. It will show the Wi-Fi and mobile broadband networks that
are within range.
e. Select the Mobile Network, and then click Connect .
f. If you have multiple APNs that match the SIM properties, Windows Connection Manager will try
each of the matching APNs until a successful connection takes place. If none of the APNs connect,
Windows Connection Manager will either show an error or show a custom APN entry screen,
allowing the user to enter a custom APN.
Note The auto-connect order that you specify in the APN database is used to determine the order
in which APNs are tried.
g. If you have only one APN in the APN database, Windows will automatically connect to the
operator network.
NOTE
You can see which APN was applied to the connection profile by opening Windows Connection Manager, right-clicking the
Mobile Broadband entry for your network, and then clicking Proper ties .
Submitting the desktop COSA/APN database
update
IMPORTANT
The following steps to submit an APN update apply to both desktop COSA, which is used for Windows 10, version 1703
and later, and apndatabase.xml, which is used for Windows 8, Windows 8.1, and versions of Windows 10 before 1703.
Microsoft will convert apndatabase.xml submissions to COSA if you are targeting Windows 10, version 1703 or later.
Now that you’ve tested the APN entries, it’s now time to submit them to Microsoft by following the steps in this
topic.
Fill out the APN testing questionnaire

Once you have tested your APN values, you must fill out the following questionnaire. This will be sent to your
TAM as part of your submission.
The purpose of this questionnaire is to make sure you have completed testing and to help the team at Microsoft
understand how thoroughly you tested the incoming APNs.
Please describe what testing you have done on the APNs that you are submitting.
[describe here]
Have you tested these APN values on your network? Windows cannot test these APNs for you because we do not
have access to your wireless network.
[yes/no]
Do you understand that all the APNs that match the Operator and Country/Region combination will be wiped out
and replaced by the APNs that you have attached to this request?
[yes/no]
Have you attached an Excel sheet to this request?

[yes/no]
Do you certify that you are entitled to submit an update on behalf of this operator?
[yes/no]
Provide your contact information:

[Name]
[Company]
[Job title]
[E-mail from a corporate e- account for the company you are submitting for]
[phone 1]
[phone 2]
Submit COSA/APN database updates to Microsoft

Use the following procedure to submit COSA or APN connectivity database updates to Microsoft.
1. Contact your Microsoft TAM - Using the same MS Solve case described in Testing your desktop
COSA/APN database submission, provide your TAM with a completed APN testing questionnaire to
describe the level of testing that has been done.
2. Microsoft triage process -- Microsoft will review your submission and may contact you if errors are
detected. Microsoft will not do any testing on your mobile network. If no errors are detected in your
submission, it will proceed through the release process.
3. Operator validation -- Since Microsoft cannot test the APNs you provided for your mobile network,
you’ll be asked to do so after a new COSA provisioning package or APN database has been generated.
You’ll be provided a new copy of the COSA .ppkg file or the APN database XML file that you’ll use to
apply to your PCs and test the functionality on your actual network. You’ll go through another test pass,
as described in Testing your desktop COSA/APN database submission. Your Microsoft TAM will provide
you with an installable file that will patch COSA or the APN database on the PC with the updated
database. You’ll be given a specific time period to test the new APN database. Once you have completed
your testing, you’ll be asked to reply back to your Microsoft contact with your sign-off. If you find an issue
or error, there may be a limited opportunity to correct it. If the issue cannot be corrected in time, your
changes will be reverted from the next released update of the APN database. You’ll need to resubmit your
APN connectivity database submission and wait until the next scheduled update.
4. Update is released -- Once you have signed off on the new APN database, it will go through the update
publishing process. Once it is ready, it will appear in Windows Update for users to install. You’ll be
provided a more detailed release timeline after completing your APN database submission.
IMPORTANT
If you do not sign-off within the allotted time period, your changes will be reverted from the next released update of the
APN connectivity database. You’ll need to resubmit your APN submission and wait until the next scheduled update.
Deleting an APN database entry

Deleting an APN entry is considered a special-case operation. If you are only deleting an entry, you do not have
to fill out a spreadsheet. List the entries in the APN connectivity database you want to have deleted by
answering the following questionnaire. Once this is done, send it to your TAM.
NOTE
Deletions take place based on Operator and Countr y/Region combination.
Please describe which operator and region combination you wish to have removed from the APN database.
[Describe here. For example: <Operator name="Contoso (Argentina)">]
Do you understand that all the APNs that match the Operator and Country/Region combination will be wiped
out?
[yes/no]
If you wish to add values to the APN database in addition to this deletion request, have you attached an
Excel sheet and questionnaire for that add request?
[not applicable/yes/no]
Do you certify that you are entitled to submit an update on behalf of this operator?
[yes/no]
Provide your contact information:

[Name]
[Company]
[Job title]
[E-mail from a corporate email account for the company you are submitting for]
[phone 1]
[phone 2]
Service metadata overview
MBAE deprecation warning

IMPORTANT
Starting in Windows 10, version 1803, the MBAE app experience is replaced by an MO UWP app. For more information
about MO UWP apps, see UWP mobile broadband apps.
You can create and submit a service metadata package to create an experience that is deeply integrated with
Windows. When Windows detects mobile broadband hardware that matches the operator’s service metadata
package, it automatically downloads the service metadata and the specified mobile broadband app.
Service metadata contains the information that describes a service, including the following:
The service provider name
One or more service categories
Mobile broadband-specific information
Mobile broadband profiles
Trusted certificates for provisioning XML
DeviceNotificationHandler element
PrivilegedApplications element
The information in the metadata is used to customize aspects of the Windows 8, Windows 8.1, and Windows 10
user experience and provide integration with a mobile broadband app, previously known as a mobile operator
app.
A service metadata package consists of multiple XML documents stored within a .devicemetadata-ms file. Each
document specifies various components of the service’s attributes. These XML documents provide Windows
Connection Manager with customizations that appear to the user, as well as network configuration information.
For reference information about the XML documents in a service metadata package, see Service metadata
package schema reference.
Service metadata contents

The following summary describes some of the most interesting fields that are contained and defined inside a
service metadata package:
Hardware IDs
For a GSM network, you can submit a metadata package that describes the IMSI or ICCID ranges against
which you want your service metadata package to match. If you are an MVNO, you can specify one or
more ranges of IMSIs or SIM ICC IDs that you have leased from an MNO. For a CDMA network, you can
submit a package by using Provider ID (SID/NID) or Provider Name. The hardware IDs correspond to the
HardwareID element in the service metadata package schema. For more information about how to plan
your Hardware Identification (HWID) ranges for MNO and MVNO scenarios, see Delivering experiences
for MVNOs
Ser vice number
The unique ID for the mobile broadband service provider. This GUID is also used to identify the operator
when using Account Provisioning Metadata. If you update the device metadata package, this GUID must
remain the same. The service number corresponds to the ServiceNumber element in the service
metadata package schema.
Operator logo A custom logo that appears in Windows Connection Manager next to your network
entry. (The logo is hidden when the user is on a roaming network.) The operator logo corresponds to the
ServiceIconFile element in the service metadata package schema. For more information about the logo
requirements, see Service Icon Requirements.
IMPORTANT
In Windows 10, version 1709 and later, this field has been replaced by branding through COSA. Fields in COSA for
branding are described on Planning your desktop COSA/APN database submission. If you are targeting versions
of Windows before Windows 10, version 1709, you will still create a metadata package as described in this section.
For more information about COSA, see COSA overview.

A UWP device app that is automatically downloaded and applied to the computer. This app can provide
key experiences such as plan purchase, data usage, and help and support, and can highlight value-added
services.
MB Purchase Profile
Purchase profile that is used for establishing limited connectivity for purchasing a subscription.
If you are a GSM operator who has only one Purchase APN for all subscribers, you can use the service
metadata to provision that to the computer. If you have multiple Purchase APNs, you should use account
provisioning metadata to set the appropriate purchase APN. Or, you can do nothing and use the entries
that are stored in the APN database to provide APN connectivity information.
MB Internet profile
Every mobile broadband subscription can have one default profile that is used to connect to the home
network operator. The Windows Connection Manager uses this profile for auto-connecting to the
network.
If you are a GSM operator who has only one Internet APN for all subscribers, you can use the service
metadata to provision the computer. If you have multiple Internet APNs, you should use account
provisioning metadata to set the appropriate internet APN. Or, you can do nothing and use the entries
that are stored in the APN database to provide APN connectivity information.
Cer tificate data
Certificate information used for provisioning. This includes Certificate Issuer Name and Subject Name.
This information is used to ensure that account provisioning operations that are initiated by a website are
issued by a trusted operator.
Custom operator name
The mobile broadband device typically provides the operator name, which Windows shows in Windows
Connection Manager. You can override this name by specifying a custom name in metadata. This name
displays only if the user is on a home network and is not on a roaming network. A displayed roaming
network name is based on information that is received from the device. This corresponds to the
ServiceProvider element in the service package metadata schema.
IMPORTANT
In Windows 10, Version 1709 and later, this field has been replaced by branding through COSA. Fields in COSA for
branding are described on Planning your desktop COSA/APN database submission. If you are targeting versions
of Windows before Windows 10, Version 1709, you will still create a metadata package as described in this section.
For more information about COSA, see COSA overview.
Device notification handler

In general, an app must be run by the user at least one time before it can register work items with the
System Event broker. However, mobile broadband apps might need to receive important events before
the user can run the app. You can specify the DeviceNotificationHandler element in service metadata,
which Windows will use to register some critical events. For more information about SMS notifications,
see Delivering experiences for MVNOs.
List of privileged apps with access to mobile broadband restricted interfaces
Mobile Broadband APIs and interfaces (including Account Provisioning and SMS) are restricted and
available to mobile broadband apps only. A list of privileged apps that have access to these privileged
APIs can be specified in the service metadata package in the PrivilegedApplications element. Privileged
apps can be debugging or test apps; they are not required to be distributed through the Microsoft Store.
Service Metadata Package Structure

The components of a service metadata package are stored in a compressed cabinet file and must have a file
extension of .devicemetadata-ms . Service metadata packages use this file extension because they use the
same underlying platform as device metadata packages. Before you create the .devicemetadata-ms file, you
must first create a globally unique identifier (GUID) for the metadata package. Then, you must use the following
naming convention when you create the .devicemetadata-ms file: <GUID>.devicemetadata-ms .
Note Although the usual file extension of a cabinet file is .cab , the file extension for a service metadata
package file must be .devicemetadata-ms . This is intended to underscore the fact that end-users must not
decompress or modify these packages.
There are two types of service metadata packages: a single locale service metadata package and a multiple
locale service metadata package.
Single Locale Service Metadata Package
The localizable resources in the service metadata package are the operator name that appears in Windows
Connection Manager and the service icon that appears next to it. If you do not need to localize your name or
change your icon based on locale information from the PC, create a single locale service metadata package.
Regardless of what locale the user is using on their PC, they will get the operator name and service icon defined
in the single locale service metadata package.
A single locale service metadata package must have the following file structure:
Some considerations for a single locale metadata package:
The icon file can have any file name. However, the individual XML documents must be named
PackageInfo.xml , Ser viceInfo.xml , WindowsInfo.xml , and SoftwareInfo.xml .
The name of the MobileBroadbandInfo.xml file is defined in the Ser viceInfo.xml . You should use the
names listed in this document for that file.
The .devicemetadata-ms file cannot include “{“ or “}” in the name. The GUID for each metadata package
file name must be unique. When you create a new or revised service metadata package, you must create
a new GUID, even if the changes are minor.
Windows recognizes service metadata packages with a file extension of .devicemetadata-ms .
Multiple Locale Service Metadata Package Structure
A service metadata package supports multiple locale files in one package. If you support more than one locale
for your service, you can put multiple locale files into one service metadata package.
You can use a multiple local service metadata package if you want to show a localized name for your service in
Windows Connection Manager network list or to show a different logo in Windows Connection Manager for
your network. Windows will display the localized network name and logo based on the system preferred
language, which is usually configured during Windows Setup. Even if the current user’s language is different
from the system preferred language, the icon and network name always will show up in the system preferred
language. If the service metadata package does not include a locale, the language neutral description from the
root of the service metadata package is displayed. For most users their language will match the system
preferred language.
A multiple locale service metadata package must have the following file structure:
Some considerations for a multiple locale metadata package:
Create a locale name folder in each folder and put the XML file or relevant file in the locale name folder.
You still must have the top-level XML file and relevant files, such as the icon file, at the top level of each
folder. This provides a fallback mechanism when the locale is not included in your service metadata
package.
Ensure that all required files and the fields within those files are completely filled out inside each locale-
specific folder that you create. This is in addition to the content in the top level of each folder. For
example, the ServiceNumber element in ServiceInfo.xml must be filled out and duplicated in the top-level
folder and in every locale-specific folder that you create. Failing to do this will cause errors.
The SoftwareInformation XML document does not support multiple locales because you cannot specify
different SoftwareInfo.xml files per locale.
Service metadata submission and maintenance

For more information about how to submit service metadata packages to the Windows Dev Center Dashboard –
Hardware, see Developer guide for creating service metadata.
It is important to keep metadata packages up-to-date in terms of how they are described and which IMSI and
ICCID or CDMA Provider Name or SID values they match. This can require an MNO or MVNO to implement a
new workflow that is part of SIM or device acquisition to track new orders of SIMs and the MNO or MVNO to
which those ICCIDs or IMSIs are being provided.
It is a best practice to avoid making frequent changes to your service metadata by reserving ICCID or IMSI
ranges (or CDMA SIM/Provider name) for the MNO and MVNO in advance, so that when new SIMs (or CDMA
devices) are procured, they are already accounted for in your service metadata package.
If you need to update your service identifiers that are registered on the Windows Dev Center hardware
dashboard, see Service identifier ownership updates.
Metadata updates are silently applied based on internal Windows logic (typically every eight days) when
Windows queries WMIS whether it has any updated metadata updates.
The app should be designed to deal with a previous version of the metadata to which it refers, until the latest
metadata is applied to the system.
Designing the user experience of a mobile broadband app provides guidelines about how to design the user
experience to address common error cases, such as when the device is missing or not recognized.
Delivering experiences for MVNOs

IMPORTANT
This topic provides info on how you can match service metadata to a mobile network operator (MNO) or mobile
virtual network operator (MVNO) so that a mobile broadband app is automatically downloaded when the
mobile broadband device is inserted.
To successfully match service metadata, Windows reads information from the SIM card that is inserted into the
computer. For CDMA networks, the mobile broadband device itself is read. Windows then queries the Windows
Metadata and Internet Services (WMIS) database to download the correct service metadata package. After the
service metadata package is downloaded, Windows downloads the associated mobile broadband app to the
computer.
Use the link from the following list that is appropriate for your network:
Matching on GSM networks
Matching on CDMA networks
For info about the hardware that is required to properly match service metadata to an MNO and MVNO, see
Mobile operator hardware overview.
For info on service metadata, see Service metadata.
For info on the service metadata package schema, see Service metadata package schema reference.
Matching on GSM networks

For a GSM network (3GPP), Windows reads the Integrated Circuit Card Identifier (ICCID) and the International
Mobile Subscriber Identity (IMSI) number from the SIM card. These numbers must be set and retrievable from
the device. If a SIM is PIN-locked and the IMSI information is hidden, Windows does not take action until the SIM
PIN is unlocked. Windows also reads the Home Provider Name from the SIM or mobile broadband device.
If the ICCID, IMSI, and Home Provider Name are available from the device, the ICCID and IMSI are stripped of the
last two digits, encoded by using a hashing algorithm, and sent to WMIS in the form of Hardware IDs (HWIDs) to
match to a service metadata package. The Home Provider Name is checked. If there is no match, the ICCID is
checked. If there is no match, the IMSI is checked. If no matches are found, no service metadata package is
downloaded. Windows checks approximately every eight days to see if new metadata exists for the user’s
mobile broadband SIM.
Managing MVNOs
If you are an MNO who has a single brand for all customers, you can create a metadata package that covers all
the IMSI ranges for your MCC+MNC. For example, if your MCC+MNC is 123 456, you can create a metadata
package that covers 123456000000000 – 123456999999999. This means that any user who inserts a SIM that
is in that range is matched to your experience.
This can get more complicated if one or more MVNOs share that same MCC+MNC value. The following
describes some strategies for dealing with this situation.
Option 1: Segmenting IMSI ranges
With this option, The MNO does not define an ICCID range in the service metadata packages, and instead
segments out IMSI ranges that define the MNO experience and the MVNO experience. When a matching request
comes from client devices, their IMSI values are used to match the correct experience to that SIM.
This method requires that the MNO ensures that the IMSI ranges are kept up-to-date, and that the MVNOs are
assigned future ranges in predictable blocks of IMSI numbers.
If neither the ICCID nor the IMSI matches the request from the client machine, no match is made.
Note IMSI ranges must have a granularity of 100. The start range value must end in 00, and the end range
value must end in 99.
Figure 1 Segmenting IMSI ranges (within an MNO's MCC+MNC) shows an example of client device that request
service metadata from WMIS and how each matching request from the client is matched to an experience.
Figure 1 Segmenting IMSI ranges (in an MNO's MCC+MNC)

Computer #1’s matching request does not match any ICCID values and lands inside the IMSI range that is
defined by the MNO. The MNO service metadata is downloaded to that computer.
Computer #2’s matching request does not match any ICCID values or any IMSI values. No experience is
downloaded.
Computer #3’s matching request does not match any ICCID values and lands inside the IMSI range for
MVNO A. The MVNO service metadata is downloaded to that computer.
Option 2: Segmenting ICCID ranges
With this option, the MNO does not define an IMSI range in the service metadata packages, and instead
segments out ICCID ranges that define the MNO experience and the MVNO experience. When a matching
request comes from client machines, the ICCID values are used to match the correct experience to that SIM.
This method requires that the MNO ensures that the ranges are kept up-to-date and that the MVNOs are
assigned future ranges in predictable blocks of ICCID numbers. If large blocks of ICCIDs are assigned to SIMs
during SIM manufacturing, this can be a desirable matching strategy for the MNO and their MVNOs.
If neither the ICCID nor the IMSI matches the request coming from the client machine, then no match is made.
Figure 2 Segmenting ICCID ranges (within an MNO's ICCID issuer identification number) shows an example of
client computers that request service metadata from WMIS and how each matching request from the client is
matched to an experience.
Figure 2 Segmenting ICCID ranges (in an MNO's ICCID issuer identification number)
Computer #1’s matching request in includes in the ICCID range that is defined by the MNO. The MNO
service metadata is downloaded to that computer.
Computer #2’s matching request does not match any ICCID values or any IMSI values. No experience is
downloaded.
Computer #3’s matching request lands inside the ICCID range that is defined for MVNO A. The MVNO
service metadata is downloaded to that computer.
Option 3: Describing MVNOs with ICCID ranges and MNO together with an IMSI range
An MNO’s entire IMSI-based range can be assigned (that is, everything under their MCC+MNC values). Any
MVNOs can then be assigned a specific ICCID range for their SIMs. This means that unless an ICCID match exists
for that SIM, the SIM gets the MNO experience.
This option requires the MNO or MVNO to ensure that the ICCID ranges are kept up-to-date and that the
MVNOs are assigned future ranges in predictable blocks of ICCID numbers. If large blocks of ICCIDs are
assigned to SIMs during SIM manufacturing, this can be a desirable matching strategy for the MNO and their
MVNOs. This means that the MNO has less maintenance because their package spans all the IMSI-based ranges.
In this scenario, it is very important to ensure that the MVNO keeps their ICCID ranges up to date; otherwise,
customers of the MVNO can be matched to the MNO experience.
Figure 3 Using ICCID to define MVNOs and an all-encompassing IMSI range for the MNO shows an example of
client computers that request service metadata from WMIS and how each matching request from the client is
matched to an experience.
Figure 3 Using ICCID to define MVNOs and an all-encompassing IMSI range for the MNO
defined by the MNO. The MNO service metadata is downloaded on that computer.
Computer #2’s matching request in included in the ICCID range for MVNO B. MVNO B’s service metadata
is downloaded to that computer.
Computer #3’s matching request is included in the ICCID range for MVNO A. MVNO A’s service metadata
defined by the MNO. The MNO service metadata is downloaded on that computer.
Option 4: Segmenting ICCID and IMSI ranges
You can use a mixture of ICCID ranges and IMSI ranges to describe the MNO and MVNO networks.
Note ICCID ranges get first priority for matching.
This is the most complex matching model. To ensure proper matching, the MNO and MVNO must frequently
update their service metadata packages.
Figure 4 Segmenting ICCID and IMSI ranges shows an example of client device that request service metadata
from WMIS, and how each matching request from the client is matched to an experience.
Figure 4 Segmenting ICCID and IMSI ranges

Computer #1’s matching request does not match any ICCID values, but is included in the IMSI range that
is defined by the MNO. The MNO service metadata is downloaded to that computer.
Computer #2’s matching request is included in the ICCID range for MVNO B. MVNO B’s service metadata
Computer #3’s matching request is included in the ICCID range for MVNO A. MVNO A’s service metadata
is defined by the MNO. The MNO service metadata is downloaded to that computer.
is defined by MVNO C. MVNO C’s service metadata is downloaded to that computer.
Option 5: Using Home Provider Name for GSM networks to identify the MNO and MVNO
With this option, the MNO does not define an IMSI or ICCID range in the service metadata packages, and instead
segments out the Home Provider Names that define the MNO experience and the MVNO experience.
For mobile broadband devices that are assigned to MVNOs, make sure that each MVNO device reports a
Provider Name value that uniquely identifies the MVNO. The MNO should have its own Provider Name value
that uniquely identifies it.
When a matching request comes from client machines, the Home Provider Name is used to match the correct
experience to that SIM.
This option is recommended only in the case where IMSI and ICCID cannot be used.
If the Home Provider Name does not match the request coming from the client machine, no match is made.
Note Home Provider Names must be globally unique to ensure that a user gets the correct experience. Service
metadata will only allow a single service metadata package that uses a given Home Provider Name.
Figure 5 Provider Name-based matching for GSM networks shows an example of devices that request service
metadata from the Windows Metadata and Internet Services (WMIS) service, and how each matching request
from the device is matched to an experience.
Figure 5 Provider Name-based matching for GSM networks

Computer #1’s matching request matches the Home Provider Name for the MNO. The MNO service
metadata is downloaded.
Computer #2’s matching request does not match any Provider Name values. No experience is
downloaded.
Computer #3’s matching request matches the Home Provider Name for MVNO A. MVNO A’s service
Computer #4’s matching request matches the Home Provider Name for MVNO B. MVNO B’s service
Option 6: Describing MVNOs with Home Provider Name and MNO together with an IMSI range
An MNO’s entire IMSI-based range can be assigned (that is, everything under their MCC+MNC values). Any
MVNOs can then be assigned a specific Home Provider Name. This means that unless a Home Provider Name
match exists for that device, the device gets the MNO experience.
This option requires the MNO or MVNO to ensure that the Home Provider Name reported from the device does
not change, is globally unique and is kept up-to-date. This option is recommended only in the case where IMSI
and ICCID cannot be used.
Figure 6 Using Home Provider Name to define MVNOs and an all-encompassing IMSI range for the MNO
shows an example of client computers that request service metadata from WMIS and how each matching
request from the client is matched to an experience.
Figure 6 Using Home Provider Name to define MVNOs and an all-encompassing IMSI range for the MNO
Computer #1’s matching request matches the Home Provider Name for MVNO A. The MVNO A service
metadata is downloaded on that computer.
Computer #2’s matching request does not match any Home Provider Name values and lands inside the
IMSI range that is defined by the MNO. The MNO service metadata is downloaded on that computer.
Computer #3’s matching request matches the Home Provider Name for MVNO B. MVNO B’s service
metadata is downloaded to that computer.
Computer #4’s matching request does not match any Home Provider Name values and lands inside the
IMSI range that is defined by the MNO. The MNO service metadata is downloaded on that computer.
Option 7: Alternative matching method
If none of these methods works for the MNO’s network (for example, the MNO cannot keep track of IMSI and
ICCID ranges between the MNO’s and MVNO’s customers), the following alternative is available. It is less ideal
than any of the options described above, but provides a mobile broadband solution for Windows 8,
Windows 8.1, or Windows 10 customers on the network.
Ser vice metadata
This method creates a service metadata package that covers the entire MNO network. This is usually done by
submitting an IMSI range that covers all the MCC+MNC values on the MNO network, and no ICCID ranges.
MVNO ranges are not described. The service metadata package features generic branding and a generic
network name that displays in the Windows Connection Manager. The service metadata then references a
generic app that is automatically downloaded from the Microsoft Store when the MNO’s SIM is detected.
Determining network affiliation
If the user does not already have a plan, the app opens when user tries to connect to the network by using
Windows Connection Manager.
When the app is running, it performs one of the following actions:
Prompts the user to identify the network for which they have a plan from a displayed list of MVNOs and
the MNO network.
Uses web services to send information about the user’s SIM back to the MNO backend so that the
operator can use custom logic to determine the correct network branding for the user.
Customizing the Windows Connection Manager branding
After the user’s mobile broadband data plan affiliation is determined, the mobile broadband app can change the
logo and network name that displays in Windows Connection Manager. This is done by using account
provisioning metadata, which allows the operator app to send XML-based information to Windows that relates
to the specific subscriber’s plan information.
For more information about account provisioning, see Account provisioning.
Ser vice metadata updates
Future service metadata updates (for example, any changes that are submitted to the generic service metadata
package) can overwrite the applied branding on the subscriber’s computer. To avoid this, we recommend that, if
possible, you do not update the service metadata package. Because the metadata package contains generic
branding and covers the entire IMSI range for an MNO, there should not be a frequent need to update the
package for this scenario.
If you must update the service metadata package, make sure that the mobile broadband app can initiate another
account provisioning metadata operation that is based on the backend logic that the operator provides. In this
way, you can specify when the service metadata is updated on the backend, and have the app periodically check
the backend and apply account provisioning metadata information as required.
Note Because service metadata is not versioned, the app cannot query the local copy of metadata to
determine if it has been updated or applied over the customizations that were made by using account
provisioning metadata. There is no way for an app to wake up and react to service metadata updates that are
applied to the computer.
A delay can occur between the time that the service metadata is uploaded through the Windows Dev Center
hardware dashboard, and the time that computers receive the updated metadata.
Branding in the mobile broadband app
The previous steps that are described in this topic lets you rebrand the Windows Connection Manager icon and
network name for the MNO/MVNO’s network. However, there are limited ways in which the app itself can be
rebranded.
You can rebrand the following items in the app:
The app content itself (that is, everything inside the app can be changed for a particular operator). This is
code over which the app has complete control. You might want to change help content, navigation
options, page layouts, colors, and branding inside the app, based on the MNO/MVNO.
The app tile can be dynamically updated to show specific images and layouts that are specific to the
operator. For information about how to dynamically update tile content, see Quickstart: Sending a tile
update.
You cannot rebrand the following items in the app:
Name of the app. You can try to hide the name by changing the tile template, but you cannot change
either the name itself or the icon that represents that app, as it is defined in the app manifest.
App name, information, and the icon in the settings charm.
Description of the app.
SIM reprogramming
If you want to dynamically reprogram SIMs to change the IMSI or the ICCID, you should be aware of the
following ways in which Windows 8, Windows 8.1, and Windows 10 interpret the reprogramming:
Reprogramming requires invalidation of the device’s caching of IMSI and ICCID. There are several ways
this can be done, depending on the operator network and device.
After the SIM is reprogrammed, the device re-reads the SIM information. It can use the hot SIM swap
insertion sequence to let Windows know that it should re-query the new IMSI and ICCID values.
The ICCID must be changed or Windows will not treat the SIM as a new SIM.
If only the IMSI is changed, Windows does not treat the SIM as a new SIM and your service metadata is
not downloaded. The mobile broadband app is not downloaded if a different app has already been
downloaded for this SIM.
To get new service metadata (which results in new branding), and to get a new mobile broadband app to
download the ICCID and the IMSI, you must change both the service data and the mobile broadband app by
using the operator’s reprogramming method.
Matching on CDMA networks

For a CDMA network (3GPP2), Windows reads the SID and the Provider Name values that are reported by the
device to a corresponding service metadata package in WMIS. If no matches are found, no service metadata
package is downloaded. Windows checks approximately every eight days to see if new metadata exists for the
device. If service metadata exists for a SID and a separate service metadata package exists for a Provider Name,
and both values match the SID and Provider Name values that the device is reporting, matching preference is
given to SID. In this case, the Provider Name package is not matched.
Impor tant The Provider Name value is case sensitive and must be an exact match to the Provider Name that
the device reports to Windows. If you want to match by using the Provider Name, you must make sure that you
have specified all spelling and capitalization variations of the Provider Name that CDMA devices report to
Windows in the service metadata package that you submit through the Windows Dev Center hardware
dashboard.
Managing MVNOs
MVNOs on CDMA networks can be identified by using one of following three options.
Option 1: MNO and MVNOs get their own SID values
For mobile broadband devices that are assigned to MVNOs, make sure that each MVNO gets a unique SID. The
MNOs should have their own SID value that is different from each of the MVNOs.
Separate service metadata is created for the MNO and for each of the MVNOs that matches on the unique SID
value that the device reports to Windows.
Figure 7 SID-based matching for CDMA networks shows an example of computers that request service
metadata from WMIS service, and how each matching request from the client gets matched to an experience.
Figure 7 SID-based matching for CDMA networks

Computer #1’s matching request matches the SID for the MNO. The MNO service metadata is
downloaded.
PC #2’s matching request does not match any SID values or any Provider Name values. No experience is
downloaded.
PC #3’s matching request matches a SID value that is defined by another MNO or MVNO.
PC #4’s matching request matches the SID for MVNO B. MVNO B’s service metadata downloaded.
Option 2: MNO and MVNOs get their own provider name values
For mobile broadband devices that are assigned to MVNOs, make sure that each MVNO device reports a
Provider Name value that uniquely identifies the MVNO. The MNO should have its own Provider Name value
that uniquely identifies it.
Separate service metadata is created for the MNO and for each of the MVNOs that matches on the Provider
Name value that the device reports to Windows.
For this option to work, the MNO must make sure that no service metadata is submitted that matches on the
SID that the devices report. If service metadata exists for those SIDs, matches are performed on the SID instead
of the Provider Name, causing this scheme to break. To remove a SID-based metadata package from WMIS, you
must contact Windows Dev Center hardware dashboard support.
Figure 8 Provider Name-based matching for CDMA networks shows an example of devices that request service
metadata from the Windows Metadata and Internet Services (WMIS) service, and how each matching request
from the device is matched to an experience.
Figure 8 Provider Name-based matching for CDMA networks

PC #1’s matching request does not match on the SID, but does match the Provider Name for the MNO.
The MNO service metadata is downloaded.
PC #2’s matching request does not match any SID values or any Provider Name values. No experience is
downloaded.
PC #3’s matching request matches a SID value that is defined by another MNO or MVNO.
PC #4’s matching request does not match on the SID, but does match the Provider Name for MVNO B.
The MVNO B’s service metadata is downloaded.
Option 3: Alternative matching method
If the first two options described here are not acceptable, CDMA operators can use the alternative matching
method described in Option 7: Alternative matching method of the Matching on GSM networks section.
Radios and metadata

You can expect the following matching behaviors, depending on the type of radio.
Single -Mode Single -Subscription Device
The single-mode single subscription device is a GSM-only or CDMA-only device. These are commonly available
devices that provide access to only a GSM or CDMA network.
This device reports either GSM or CDMA mode to Windows. The previously described matching logic applies
and the device is matched to the appropriate service metadata.
Multi-Mode Single -Subscription Device
The multi-mode single subscription device has both GSM and CDMA capabilities. For example, it can connect to
a GSM LTE network or a CDMA network by using a single subscriber subscription for that operator.
This device reports GSM as the primary mode to Windows.
When matching service metadata for this type of device, you can create GSM-based metadata that matches the
GSM properties of the device.
Single -Mode Multi-Subscription Device
The single-mode multi-subscription device can have either GSM or CDMA capabilities active at one time, and it
can work with multiple providers. The user must have a subscription from each provider to use more than one
provider. For example, the Qualcomm Gobi chipset allows the user to connect to various CDMA networks or to a
GSM network.
This device reports the mode to Windows for the active provider. If the device is active with the GSM provider, it
should report that it is in GSM mode. In this case, you should create GSM metadata for matching. The GSM
metadata and mobile operator app can access the device when it is in GSM mode only.
If the device is active with the CDMA provider, it should report that it is in CDMA mode to Windows. In this case,
the operator should create CDMA metadata for matching. The CDMA metadata and mobile broadband app can
access the device only when it is in CDMA mode and active for that CDMA network.
Metadata Maintenance Implications

It is important to keep the following metadata package content up-to-date:
How the packages are described.
The IMSI and/or ICCID or CDMA provider name or SID values against which the packages match.
For more information about mobile broadband metadata see Using metadata to configure mobile broadband
experiences.
Developer guide for creating service metadata

IMPORTANT
This guide walks you through the process of creating a service metadata package on the Windows Dev Center
hardware dashboard, previously known as Sysdev. Service metadata is required to connect a mobile broadband
app to your hardware device. When a user plugs a mobile broadband device into their computer, the associated
service metadata is downloaded and then the mobile broadband app is automatically downloaded.
You can leverage service metadata to create a deeply integrated experience with Windows. Service metadata
packages allow you to include branding information, such as icons and your operator name, configure settings
and permissions for accessing SIM hardware and personal hotspots, and provision mobile broadband apps to
work with your mobile broadband device.
Note
Even though the mobile broadband app is automatically installed, the user must pin it to the Start Screen
manually.
Getting started
To create a successful service metadata package, you must complete the steps included in this section.
Register your company with the Windows Dev Center hardware dashboard
Your company has an active account on the Windows Dev Center hardware dashboard. If your company
does not have an account on the Windows Dev Center hardware dashboard, you can create a new
account and add your user account to you company. For more info, see Administration in the Windows
Dev Center hardware dashboard help.
Your company has a VeriSign code signing certificate to sign the packages.
Service Metadata wizard access and service identifiers registration
MNOs and MVNOs must complete the following steps before you can create a service metadata package:
Request access to the Service Metadata wizard
Register your service identifiers
To complete the steps above, you must send an email to sysdev@microsoft.com with the following info:
The organization name used when you registered for the Windows Dev Center hardware dashboard.
Whether you are a mobile network operator or a mobile virtual network operator.
Your website and justification on why you need to create a service metadata package.
Include the following service identifiers as applicable:
List of GSM Provider IDs
List of GSM Provider Names
List of CDMA SIDs
List of CDMA Provider Names
You should receive an acknowledgement emails with 24 hours that your request was received. However, it could
take up to 5 business days to process the request. If we have conflicts, we’ll send you an email asking for
additional information.
Before you create your service metadata package, ensure that your mobile broadband app has been developed
and associated with the Microsoft Store. This app should provide key experiences, such as plan purchase, data
usage, help and support, as well as highlighting value-added services from the operator. For more info about
creating the mobile broadband app, see the following links:
Note
The mobile broadband app doesn’t have to be published to the Microsoft Store until the service metadata has
been tested and is ready to be published externally. We recommend that the app is published to the Microsoft
Store only after the service metadata package passes preview mode testing.
Creating service metadata packages

Creating a service metadata package starts with the Service Metadata wizard that is available on the Windows
Dev Center hardware dashboard. For more info on the Service Metadata wizard, see Step 2- Create the service
metadata package. You can use the Service Metadata wizard to create a new or edit an existing service metadata
package. As you go through the wizard and fill out the values, the wizard will validate and notify you of any
errors or warnings. This validation includes checking for missing or incorrect fields, service identifier ownership,
mobile broadband app existence in the Microsoft Store, and so on.
When you are on the final confirmation page and ready to submit, you have the option of submitting your
package either in Developer mode or Preview mode.
Developer mode Used during the initial stages when your intent is to simply create service metadata
packages and use it for offline test purposes. In this mode, the package will not be signed and will have to
be manually downloaded and installed to the test machine for validation purposes. This mode can be
viewed as a quick and rapid way to create and verify service metadata packages works with your device.
Preview mode Used when you are confident that the package is authored correctly and is ready for
submission for end to end testing. In this mode, the package will be signed by the Windows Dev Center
hardware dashboard and will automatically get downloaded to test machines, provided your test
machines are provisioned correctly.
When you have completed preview testing, and verified your package works for all scenarios, then you can
publish the package to live.
The following diagram discusses the workflow:
To create a new service metadata package, see Steps for creating a service metadata package.
To edit an existing service metadata package, see Steps for editing a service metadata package.
Steps for creating a service metadata package

Use the following steps to create a service metadata package on the Windows Dev Center hardware dashboard:
1-Gather the required information for the service metadata package
2-Create the service metadata package
3-Insert the store manifest file into the Microsoft Store device app
4-Test the service metadata package
5-Publish the service metadata package
1-Gather the required information for the service metadata package
As you go through the steps in the Service Metadata Wizard in Step 2 of this topic, several pieces of information
stored in the package.appxmanifest file from the mobile broadband app project that you want to associated with
the device is required. Use the following steps to gather the information so that it’s ready for Step 2 of this topic.
Caution
The mobile broadband app must be associated with the Microsoft Store before you gather the values in this
step. When you associate a mobile broadband app, the values in the package manifest file are updated to use
the information from your Microsoft Store developer account. However, the mobile broadband app does not
have to be published to the Microsoft Store. It can stay in your local development environment until you are
ready to publish the service metadata package.
To gather UWP device app information
1. Open the mobile broadband app project by using Visual Studio 2013.
2. In the right hand pane, right click the Package.appxmanifest file, and then click View Code .
3. Gather the following attributes from the package.appxmanifest file:
From the Identity element, the Name attribute will be used for the Package name field in the
Service Metadata Wizard.
From Identity element, the Publisher attribute will be used for the Publisher field in the Service
Metadata Wizard.
From the Applications element, the Id attribute from the Application child element will be used
for the App ID field in the Service Metadata Wizard.
4. Close the package.appxmanifest file.
You can also complete this without using Visual Studio 2013 by doing the following steps:
To gather mobile broadband app information without using Visual Studio 2013
1. Navigate to the package.appxmanifest file for your mobile broadband app.
2. Right-click the file, and then click Open with .
3. Clear the Use this app for all .appxmanifest files check box, click More options , and then click
Notepad .
4. Gather the following attributes from the package.appxmanifest file:
From the Identity element, the Name attribute will be used for the Package name field in the
Service Metadata Wizard.
From Identity element, the Publisher attribute will be used for the Publisher field in the Service
Metadata Wizard.
From the Applications element, the Id attribute from the Application child element will be used
for the App ID field in the Service Metadata Wizard.
5. Save and close the package.appxmanifest file.
2-Create the service metadata package
Service metadata is created by using the Service Metadata Wizard in the Windows Dev Center hardware
dashboard.
To create a ser vice metadata package
1. Navigate to sysdev.microsoft.com.
2. Under the Device metadata heading, click Create mobile broadband experience .
3. On the Ser vice info page, complete the following fields, and then click Next .
Enter the name for your network that is to be used in the Windows network selection
UI – The name of you network that will be displayed to customers in Windows Connection
Manager.
Enter your ser vice number – A GUID that must match the carrier ID field in your provisioning
metadata. You can create a GUID by using Visual Studio 2013. For more information on how to
create a GUID, see Create GUID (guidgen.exe).
Upload your icon that is to be shown in the Windows network selection UI – Click
Browse , and then select the icon that is shown to customers in Windows Connection Manager.
Enter the Windows notification event handler in your app (optional unless entitlement
check is required below) – This is the notification handler that was registered in your mobile
broadband app.
Do you want to allow users to share their mobile broadband connection (personal
hotspot)? – The possible options are Always allow , Allow only with entitlement check
(Windows notification event handler required) , and Never allow . The default option is to
always allow.
Do you want to require system admin privileges to perform PIN unlock on SIMs? – If
you want to require system administrator privileges to PIN unlock a SIM card, click the Yes option.
4. On the Hardware info page, select the information that should be used to identify your experience.
Once a check box is selected, you can add the appropriate network ranges. The ID generated should exist
in the Windows APN database so the right subscriber is identified. For more information about the APN
database, see COSA/APN database submission.
If you are a GSM Provider that uses the International Mobile Subscriber Identity (IMSI), select the
IMSI check box under the GSM heading. In the Provider ID box, enter the GSM service provider
ID. Under the IMSI/ICCID Ranges heading, enter the range, and then click Add .
If you are a GSM provider that uses the integrated circuit card identifier (ICCID), select the SIM ICC
ID check box under the GSM heading. Under the Enter the Provider ID and ICC ID range
heading, enter the range, and then click Add .
If you are a GSM provider that uses the home provider name, select the Home provider name
check box under the GSM heading. Under the Enter the Home Provider Name or enter the
Provider ID (MCC+MNC) heading, enter the provider ID and provider name, and then click Add .
If you are a CDMA provider that uses the SID, select the SID check box under the CDMA heading.
In the Enter the SID box, enter the CDMA SID.
If you are a CDMA provider that uses the provider name, select the Provider name check box
under the CDMA heading. In the Enter Provider Name box, enter the CDMA service provider
name.
Click Next .
5. On the App info page, enter the information you gathered in Step 1 of this topic. If you want to add
additional privileged apps, click Add , and then enter up to 7 more. When all of the privileged apps are
entered, click Next .
6. On the Confirm page, verify that the information is correct. Select the Developer Mode or Preview
Mode option, and then click Submit .
Developer Mode – The package is not signed and it must be manually downloaded and installed
on every computer. Use this option if you want to save the package for offline development.
Preview Mode – The package is signed and automatically downloaded from Microsoft to test
computers with the appropriate registry settings configured. Preview Mode does not check to
ensure that the mobile broadband app is published to the Microsoft Store.
3-Insert the store manifest file into the Microsoft Store device app
A store manifest file must be included with a UWP device app. Use the following steps to download the store
manifest file from your service metadata package and insert it into the mobile broadband app project.
Inser t the store manifest file
1. On the Windows Dev Center hardware dashboard, on the manage experience page for your service
metadata package, click the service metadata package, and then click StoreManifest.xml to download
your store manifest file.
2. Open the mobile broadband app project by using Visual Studio 2013.
3. Right-click the project, click Add , and then click Existing Item .
4. Browse to the store manifest file that you downloaded, and then click Add .
5. Recompile the mobile broadband app and publish it again to the Microsoft Store.
4-Test the service metadata package
To test the service metadata package, you must have the mobile broadband device and the service metadata
package files. The instructions to configure your test system and install the service metadata package depend on
the mode of the package.
Test a service metadata package in developer mode
You must manually download the package and install it in the right location for the scenarios to work correctly.
Your developer mode package will need to be accessed from two different entry points depending on whether
you authored a new package or an existing package.
If you created a new package, in the Windows Dev Center hardware dashboard, click Manage experiences ,
and then click Unassociated Dev Packages (the first entry in the Manage experiences table). The following
figure shows an example:
If you edited an existing service metadata package that is already associated with an experience, select the
experience from the Manage experiences table, and you will see the developer mode package in the
Metadata packages table. Click Download MBAE Zip Package Edit to download it.
After you’ve download the service metadata package, you must enable test signing because the service
metadata package is not signed. To enable test signing, run bcdedit –set testsigning on from an elevated
command prompt and then restart your computer.
After test signing is enabled, copy the *.devicemetadata-ms file from the service metadata package to the
following location: %ProgramData%\Microsoft\Windows\DeviceMetadataStore\ culture, where culture is
the current culture code for your computer.
Test a service metadata package in preview mode
If the service metadata package is in preview mode, you must create the PreviewKey registry entry on your test
computer. For more info about configuring the PreviewKey registry entry, see Creating a Preview Package.
Note
You do not have to enable test signing to test a service metadata package that is in preview mode.
After the PreviewKey registry entry is created, plug in your mobile broadband device and ensure that it shows in
the Networks list. If it does not, see the Troubleshooting section for more info.
Clear the existing service metadata
When service metadata is installed on a PC, the values contained in the metadata are stored in many different
places, including the registry, metadata cache, metadata store, WWAN profiles and dev node. This can make it
challenging to repeat multiple tests with the same, or different, metadata packages. To ensure that the service
metadata is installed correctly, you should clear any existing service metadata. You can clear existing service
metadata by setting up your test computer to run a PowerShell script that removes all traces. First, you must set
up the environment on your test computer:
Note
This will not work on a Windows RT device. Use the steps in the procedure named “To clear service metadata on
a device running Windows RT”.
To set up the environment for clearing ser vice metadata
1. Download psexec.exe (https://go.microsoft.com/fwlink/p/?linkid=330071), and then extract it to a folder.
2. Download and install the Windows Driver Kit Windows 8.1 (https://go.microsoft.com/fwlink/?
LinkId=330072).
3. Navigate to where the WDK files are installed. The default location is C:\Program Files
(x86)\Windows Kits\8.1\Tools . If your test computer is running x86, copy devcon.exe from the x86
folder into the same folder as psexec.exe. If your test computer is running x64, copy devcon.exe from the
x64 folder.
4. Save the following script as MetadataRemovalScript.ps1 in the same folder as Devcon.exe and PsExec.exe.
Note
In the Save as type box, make sure to select All files (*.*) before saving the file.
# DEVICE SHOULD BE CONNECTED TO MACHINE
Write-Host "Launching devcon to remove MBAE software device nodes devcon.exe remove @SWD\MBAE\*"
$DevconParameters = ' remove @SWD\MBAE\* '
try
{
Start-Process devcon.exe -ArgumentList $DevconParameters
}
catch
{
$Error[0] # Dump details about the last error
Write-Host "Error running devcon.exe " $DevconParameters
exit
}
Write-Host "Removing MB Profiles"

$mbprcmd = "mbn sh pr i=*"
$mddelprcmd = "mbn del pr i=* name="
$cmdout = $mbprcmd | netsh | Out-String
$tokens = $cmdout.Split( [String[]] ("`r`n"), [StringSplitOptions]::RemoveEmptyEntries)
if($tokens.Length -gt 3)
{
for($i=3;$i -lt $tokens.Length-1;$i++)
{
$x = $mddelprcmd + '"' + $tokens[$i].trim() +'"'
Write-Host "Deleting Profile Cmd :" $x
$x | netsh
}
}
Write-Host ""
Write-Host "Disabling ALL Mobile Broadband Adapters"
$MBAdapters = Get-Netadapter -Name "Mobile Broadband*"
foreach($MBAdapter in $MBAdapters)
{
Write-Host "Disabling MB Adapter :"$MBAdapter.Name
Disable-NetAdapter -Name $MBAdapter.Name -Confirm:$false
}
Write-Host "Stopping Device Setup Manager Service"

Stop-Service DsmSvc
Write-Host "Removing MBAE metadata packages in store"

#Find Package Ids
$MBAEPackageRegKeyHive = "HKLM:\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts\Accounts\"
if(Test-Path $MBAEPackageRegKeyHive)
{
$DevMetadataStorePath = join-path -Path $Env:ProgramData -ChildPath
"Microsoft\Windows\DeviceMetadataStore"
$PackageIds = Get-ChildItem $MBAEPackageRegKeyHive | ForEach-Object {Get-ItemProperty $_.pspath} |

where-object {$_.MetadataPackageId} | Foreach-Object {$_.MetadataPackageId}
foreach($PackageId in $PackageIds)
{
$PackageStoreFile = $PackageId + ".devicemetadata-ms"
$PackageStorePath = Get-ChildItem $DevMetadataStorePath -Recurse -Filter $PackageStoreFile
if($PackageStorePath -ne $null)
{
Write-Host "Deleting Device Metadata Store @" $PackageStorePath.FullName
Remove-Item -Force $PackageStorePath.FullName
}
}
}
Write-Host "Removing all metadata from cache"

$DevMetadataCachePath = join-path -Path $Env:ProgramData -ChildPath
"Microsoft\Windows\DeviceMetadataCache\*"
if(Test-Path $DevMetadataCachePath)
{
Write-Host "Delete All Metadata Packages under "$DevMetadataCachePath
Remove-Item -Recurse -Force $DevMetadataCachePath
}
Write-Host "Cleanup MBAE registry keys"

$MBAERegKeyPath = "HKLM:\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts\*"
if(Test-Path $MBAERegKeyPath)
{
Write-Host "Found MBAE reg keys - deleting"
Remove-Item -Path $MBAERegKeyPath -Recurse
}
Write-Host "Enabling all MB Adapters, press any key to continue"

$keypress = $host.UI.RawUI.ReadKey("NoEcho,IncludeKeyUp")
$MBAdapters = Get-Netadapter -Name "Mobile Broadband*"
foreach($MBAdapter in $MBAdapters)
{
Write-Host "Enabling MB Adapter :"$MBAdapter.Name
Enable-NetAdapter -Name $MBAdapter.Name -Confirm:$false
}
Write-Host "END of Script"
# DEVICE SHOULD BE CONNECTED TO MACHINE
Write-Host "Launching devcon to remove MBAE software device nodes devcon.exe remove @SWD\MBAE\*"
$DevconParameters = ' remove @SWD\MBAE\* '
try
{
}
catch
{
$Error[0] # Dump details about the last error
Write-Host "Error running devcon.exe " $DevconParameters
exit
}
Write-Host "Removing MB Profiles"

$mbprcmd = "mbn sh pr i=*"
$mddelprcmd = "mbn del pr i=* name="
$cmdout = $mbprcmd | netsh | Out-String
$tokens = $cmdout.Split( [String[]] ("`r`n"), [StringSplitOptions]::RemoveEmptyEntries)
if($tokens.Length -gt 3)
{
for($i=3;$i -lt $tokens.Length-1;$i++)
{
$x = $mddelprcmd + '"' + $tokens[$i].trim() +'"'
Write-Host "Deleting Profile Cmd :" $x
$x | netsh
}
}
Write-Host ""
Write-Host "Please remove the MB device from the system and press any key to continue"
$keypress = $host.UI.RawUI.ReadKey("NoEcho,IncludeKeyDown")
Write-Host "Removing MBAE metadata packages in cache and store"

#Find Package Ids
$MBAEPackageRegKeyHive = "HKLM:\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts\Accounts\"
if(Test-Path $MBAEPackageRegKeyHive)
{
$DevMetadataCachePath = join-path -Path $Env:ProgramData -ChildPath
"Microsoft\Windows\DeviceMetadataCache"
$DevMetadataStorePath = join-path -Path $Env:ProgramData -ChildPath
"Microsoft\Windows\DeviceMetadataStore"
$PackageIds = Get-ChildItem $MBAEPackageRegKeyHive | ForEach-Object {Get-ItemProperty $_.pspath} |

where-object {$_.MetadataPackageId} | Foreach-Object {$_.MetadataPackageId}
foreach($PackageId in $PackageIds)
{
$PackageCacheFolder = Get-ChildItem $DevMetadataCachePath -Recurse -Filter $PackageId
if($PackageCacheFolder -ne $null)
{
Write-Host "Deleting Device Metadata Cache @" $PackageCacheFolder.FullName
Remove-Item -Recurse -Force $PackageCacheFolder.FullName
}
$PackageStoreFile = $PackageId + ".devicemetadata-ms"
$PackageStorePath = Get-ChildItem $DevMetadataStorePath -Recurse -Filter $PackageStoreFile
if($PackageStorePath -ne $null)
{
Write-Host "Deleting Device Metadata Store @" $PackageStorePath.FullName
Remove-Item -Force $PackageStorePath.FullName
}
}
}
Write-Host "Cleanup MBAE registry keys"

$MBAERegKeyPath = "HKLM:\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts\*"
if(Test-Path $MBAERegKeyPath)
{
Write-Host "Found MBAE reg keys - deleting"
Remove-Item -Path $MBAERegKeyPath -Recurse
}
Write-Host "END"
After the environment is set up, run the following steps each time that you want to clear any existing service
metadata:
To clear the ser vice metadata
1. Ensure that the mobile broadband device is plugged into your test computer.
2. From an elevated command prompt, navigate to the folder where you extracted psexec.exe, and then run
psexec /s /i powershell
3. In the PowerShell command prompt, navigate to the folder where you extracted psexec.exe.
4. Type set-executionpolicy unrestricted and then press Enter.
5. Type Y and then Enter.
6. Type .\MetadataRemovalScript.ps1 and then press Enter.
7. When prompted, remove the mobile broadband device, and then press Enter.
8. Repeat these steps each time you want to clear the service metadata from your test computer.
To clear ser vice metadata on a device running Windows RT
1. Remove the software device nodes.
a. In Device Manager, click View , and then click Show hidden devices .
b. Expand Software devices.
c. Right-click the following device nodes, and then click Uninstall :
Windows.Devices.Sms.SmsDevice and
Windows.Networking/NetworkOperators.MobileBroadbandAccount
2. Remove all mobile broadband profiles from all interfaces.
a. From an elevated command prompt, type netsh mbn sho pro i=\ *
b. For each of the profiles, type netsh mbn delete profile name = “The profile name here”
i=\ * and then press Enter.
3. Disable all mobile broadband adapters.
a. In Device Manager, expand Network adapters .
b. Right-click each mobile broadband device, and then click Disable .
4. From an elevated command prompt, stop the DSM service by typing sc stop dsmsvc and then press
Enter.
5. Remove your service metadata packages from the device metadata store by deleting any folder that
contains your service metadata package from
%ProgramData%\Microsoft\Windows\DeviceMetadataStore . You can identify service metadata
packages by looking for the MobileBroadbandInfo.xml file.
6. Delete all WWAN SVC MBAE registry entries.
a. In Registry Editor, delete the following registry entry and all child entries:
HKEY_LOCAL_MACHINE\Software\Microsoft\WwanSvc\MobileBroadbandAccounts.
b. If you don’t have access to delete the registry entry, you must give yourself Full Control
permissions.
7. Enable all mobile broadband adapters.
a. In Device Manager, expand Network adapters .
b. Right-click each mobile broadband device, and then click Enable .
5-Publish the service metadata package
Once you have confirmed that the service metadata package works correctly, the final step is to release the
package. You can release the package by selecting the package attached to the specific experience by clicking the
Release button, as shown below.
Steps for editing a service metadata package

You can edit a service metadata package by using the Manage Experiences page of the Windows Dev Center
hardware dashboard.
Troubleshooting
Open the networks list and look for your mobile broadband network. If the network is listed by using the name
and icon that you used in the service metadata package Ser viceInfo.xml file, the package is correctly parsed. If
you are updating a service metadata package that has the same name and icon, or if the name or icon has not
appeared in the list after about approximately one minute, you should perform additional steps, as discussed
here:
Force a metadata refresh
Check the metadata cache
Check the registry
Check the WWAN Logs
Force a metadata refresh
Some parts of the metadata and mobile broadband app systems rely on network access, which can fail and
leave the computer in an inconsistent state. If this happens, you can encounter a situation where service
metadata is not installed or the mobile broadband app is not installed. The system periodically tries to remedy
the situation, but to conserve power, retries are fairly infrequent ( just a few times a day). Instead of waiting for
the next retry, you can manually force a refresh to happen immediately. To do this, perform the following steps:
1. Open the desktop Control Panel .
2. Open Devices and Printers .
3. From the View menu, click Refresh , or press the F5 key. This action causes metadata to be reparsed and
background events to be re-registered.
Impor tant
If a service metadata package has already been successfully parsed, the system will treat this refresh as a
metadata update. In this case, your metadata package must have a different GUID in its filename and an updated
timestamp in the LastModifiedDate element of PackageInfo.xml .
Check the metadata cache
If a metadata refresh did not fix the problem, make sure that the service metadata package is valid and that it
has the correct Hardware IDs. To do this, perform the following steps:
1. Navigate to %programdata%\Microsoft\Windows\DeviceMetadataCache\dmrccache\ culture,
where culture is the culture code for the current culture of your test computer (for example, en-us or es-
es ).
2. Look for a folder that has the same name as your metadata package (without the .devicemetadata-ms
extension). If this directory does not exist, it can mean one of four things:
The service metadata package is corrupt.
The service metadata package does not have the correct Hardware IDs.
The mobile broadband device is not in a state where metadata can be downloaded, or you plugged
in the device before you copied the service metadata package.
A problem occurred when checking the digital signature on the metadata package. This is usually
caused by not having test signing enabled on your test computer.
If you’re sure that the package is not corrupted and that you first plugged in the mobile broadband device after
you copied the service metadata package, check the IMSI ranges. It’s very easy to type in too many or too few 0s
or 9s. If the problem persists after confirming or correcting these items, you must look at the registry.
Check the registry
Warning
You should not edit registry data that does not belong to your application unless it is absolutely necessary. If
there is an error in the registry, your system might not function properly. Do not, under any circumstances,
delete the MobileBroadbandAccounts registry key. Windows will not re-create it and you will break the
feature.
Perform the following steps to check the registry:
1. Open Registry Editor.
2. Go to HKLM\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts .
3. Inside this registry key, look for three other keys: Accounts , NetworkInterfaceBindings , and Data .
These keys do not exist by default; they are automatically created the first time that a mobile broadband
device is inserted, turned on, or connected.
4. If the Accounts or NetworkInterfaceBindings keys do not exist and you have already plugged in or
turned on your mobile broadband adapter, check the WWAN logs.
5. If some or all of these keys exist, expand the Accounts key in the Tree view. One or more registry keys
that have names similar to GUIDs should exist inside it. The registry tree entries should be similar to the
registry tree that is displayed below:
If the registry key looks similar to the above figure (the value names will vary slightly depending on
whether the account is on a GSM or CDMA network), and if you do not see the icon in the networks list,
you should look at the event logs.
If the Registry entries are similar to the next figure, it means that the mobile broadband adapter was
inserted before the service metadata package was copied into the device metadata store, the service
metadata package is corrupted, or the Hardware IDs are incorrect. To remedy a situation where you
plugged in or turned on the device before copying the metadata package into the metadata store,
perform the steps in Force a metadata refresh. Otherwise, follow the steps in Check the WWAN Logs.
Check the WWAN Logs

If there are no Accounts or NetworkInterfaceBindings registry keys under
HKLM\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts , or if there are entries that are not
fully populated, you must look at the WWAN logs. The following steps will reset the computer to a known state:
1. Unplug or turn off your mobile broadband device (if the device is embedded, disable it in the Device
Manager ).
2. Delete the following registry keys:
HKLM\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts\Accounts
HKLM\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts\NetworkInterfaceBi
ndings
Warning
Do not, under any circumstances, delete the
HKLM\SOFTWARE\Microsoft\WwanSvc\MobileBroadbandAccounts\ registry key. Windows will
not re-create it and you will break the feature.
There are two types of entries that are of interest in the logs: account management WWAN service entries log
entries, and parser task entries. The first type can help debug issues that are caused by problems with the
networking hardware, and the second type can help debug metadata parsing issues.
Account management WWAN service entries log entries for a network that is successfully processed are similar
to the following:
[0]02CC.0CD0::2012-01-04 09:22:26.567 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Account updater

started for network interface {7a0a0dce-0a51-471a-8c16-6e767cd0b861.
[0]02CC.0CD0::2012-01-04 09:22:26.567 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Getting home
provider ID from hardware device for network interface {7A0A0DCE-0A51-471A-8C16-6E767CD0B861}. Provider ID
is "234567".
[0]02CC.0CD0::2012-01-04 09:22:26.567 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Getting home
provider name from hardware device for network interface {7A0A0DCE-0A51-471A-8C16-6E767CD0B861}. Provider
name is "MS GSM".
[0]02CC.0CD0::2012-01-04 09:22:26.586 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Network
identity not recognized, assigning new network account ID.
[0]02CC.0CD0::2012-01-04 09:22:26.597 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Devnode
create/update started.
[0]02CC.0CD0::2012-01-04 09:22:26.617 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Devnode
create/update finished.
[0]02CC.0CD0::2012-01-04 09:22:26.617 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Data store
[0]02CC.0CD0::2012-01-04 09:22:26.707 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Data store
[0]02CC.0CD0::2012-01-04 09:22:26.707 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Account updater
finished for network interface {7a0a0dce-0a51-471a-8c16-6e767cd0b861}.
You can find these entries by searching the log for Account Management . In this case, the most important
entries are Data store create/update star ted and Data store create/update finished . If these entries exist
and have no error messages, the hardware is behaving correctly. (The data store that is referred to here contains
the registry keys that are discussed in Check the registry.)
By contrast, on a device where the SIM is removed, the entries typically look like the following:
[0]02CC.03E4::2012-01-04 09:29:50.309 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Account updater

started for network interface {7a0a0dce-0a51-471a-8c16-6e767cd0b861}.
[0]02CC.03E4::2012-01-04 09:29:50.309 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Detected
removal of SIM from device bound to network interface {7A0A0DCE-0A51-471A-8C16-6E767CD0B861}.
[0]02CC.03E4::2012-01-04 09:29:50.309 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Devnode
[0]02CC.03E4::2012-01-04 09:29:50.309 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Devnode
[0]02CC.03E4::2012-01-04 09:29:50.309 [Microsoft-Windows-WWAN-SVC-EVENTS]Account Management: Account updater
finished for network interface {7a0a0dce-0a51-471a-8c16-6e767cd0b861}.
Note
In the latter example, there are no entries for Data store create/update star ted or Data store
create/update finished . Because information stored in the SIM is critical to the account management process,
a device that does not have a SIM will not have the necessary associated metadata.
If the hardware was successfully processed, but your logo or name do not display in the networks list, there
might be a problem with the metadata package. This can be investigated by using the parser task entries in the
log. To find these entries, search for Parser-Task . Log entries for a successful parse typically look like the
following:
[0]0DA8.0A2C::2012-01-04 09:22:32.007 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Parser task

started.
[0]0DA8.0A2C::2012-01-04 09:22:32.030 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Parsing
metadata for device container with id "{972238E7-36F4-11E1-BC81-00155DE96B01}" for culture "en-US".
[0]0DA8.0A2C::2012-01-04 09:22:32.297 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Starting
parse of mobile broadband service information file.
[0]0DA8.0A2C::2012-01-04 09:22:32.297 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Metadata
package contains no data for culture "en-US". Using fallback data.
[0]0DA8.0A2C::2012-01-04 09:22:32.356 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Finished
update of stored network account information.
[0]0DA8.0A2C::2012-01-04 09:22:32.377 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]The mobile
broadband account now contains service provider information.
[0]0DA8.0A2C::2012-01-04 09:22:32.378 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Applying
WWAN profiles for service provider Contoso GSM.
creation and/or update of WWAN profiles.
[0]02CC.0CD0::2012-01-04 09:22:32.512 [Microsoft-Windows-WWAN-SVC-EVENTS]WWAN Service event: Profile Update
Notification received
[0]02CC.0CD0::2012-01-04 09:22:32.519 [Microsoft-Windows-WWAN-SVC-EVENTS]WWAN Service event: Complete
Scanning
[0]02CC.0CD0::2012-01-04 09:22:32.519 [Microsoft-Windows-WWAN-SVC-EVENTS]WWAN Service event: WWAN Interface
information
creation and/or update of WWAN profiles.
[0]0DA8.0A2C::2012-01-04 09:22:32.659 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]WWAN
profiles applied successfully for service provider Contoso GSM.
[0]0DA8.0A2C::2012-01-04 09:22:32.659 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Adding
trusted provisioning certificates for service provider Contoso GSM.
setting of trusted certificates for network provisioning.
setting of trusted certificates for network provisioning.
[0]0DA8.0A2C::2012-01-04 09:22:33.016 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Trusted
provisioning certificates added successfully for service provider Contoso GSM.
[0]0DA8.0A2C::2012-01-04 09:22:33.017 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Parser task
finished.
[0]0DA8.0A2C::2012-01-04 09:22:33.017 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-
Task]MbaeParserTask completed successfully.
These logs show that the MobileBroadbandInfo.xml file was correctly parsed, that the parser task applied the
WWAN profiles (together with the WWAN service logging that successfully updated the profiles), and that the
parser task set the trusted provisioning certificates mentioned in MobileBroadbandInfo.xml .
If any part of the process failed, that failure is logged. For example, if the digital signature check fails on the
service provider icon file, log entries typically look like the following:
[0]0F24.0C70::2012-01-04 10:09:49.271 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Parser task
started.
[0]0F24.0C70::2012-01-04 10:09:49.288 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Parsing
metadata for device container with id "{97223B34-36F4-11E1-BC81-00155DE96B01}" for culture "en-US".
[0]0F24.0C70::2012-01-04 10:09:49.483 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Starting
[0]0F24.0C70::2012-01-04 10:09:49.483 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Metadata
package contains no data for culture "en-US". Using fallback data.
[0]0F24.0C70::2012-01-04 10:09:49.547 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Finished
[0]0F24.0C70::2012-01-04 10:09:49.547 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Starting
[0]0F24.0C70::2012-01-04 10:09:49.688 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Digital
signature verification failed for file "c:\programdata\microsoft\windows\devicemetadatacache\dmrccache\en-
us\B68264FF-E4D1-49B1-AB5F-2B9C1C16EF5D\ServiceInformation\ContosoBroadband.ico".
[0]0F24.0C70::2012-01-04 10:09:49.690 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Finished
[0]0F24.0C70::2012-01-04 10:09:49.692 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task]Parser task
finished.
[0]0F24.0C70::2012-01-04 10:09:49.692 [Microsoft-Windows-Mobile-Broadband-Experience-Parser-
Task]MbaeParserTask did not complete successfully. Error is 0x80070306: One or more errors occurred while
processing the request.
Because it is normal for the parser task to run more than one time, you might see more than one set of
[Microsoft-Windows-Mobile-Broadband-Experience-Parser-Task] log entries. In this case, the sets of entries are
typically the same - if they are not the same, it can indicate an intermittent problem.
Additional resources
Use the following links to learn more about mobile broadband in Windows 8.1 and Windows 10:
Service metadata
Service identifier ownership updates

IMPORTANT
Service Identifiers are a set of fields that are encoded in mobile broadband devices (SIM cards for GSM and
modem for CDMA) and are used to uniquely identify the device. The service identifier is used by Windows 8,
Windows 8.1, and Windows 10 to download the service metadata package for that device. Before you create
your service metadata packages, you must register your service identifiers with the Windows Dev Center
hardware dashboard. For info on registering new service identifiers, see Developer guide for creating service
metadata.
Depending on the technology, service identifiers can consist of the following:
GSM
Provider ID The combination of mobile country code and mobile network code, which is a 5 or 6
digit number.
Provider Name The name flashed on to the device when the firmware is provisioned.
CDMA
SID The System Identifier (SID) of a CDMA network.
Provider Name The name flashed on to the device when the firmware is provisioned.
If the ownership of an IMSI changes, the new operator must send an email to sysdev@microsoft.com with the
following info:
Organization name used by the operator during the Windows Dev Center hardware dashboard
registration process
Name of the old mobile operator that owned the IMSI
List of GSM Provider IDs affected by the ownership change
You should receive an acknowledgement emails with 24 hours that your request was received. However, it could
take up to 5 business days to process the request. If we have conflicts, we’ll send you an email asking for
additional information.
MobileBroadbandInfo XML schema overview

IMPORTANT
A service metadata package contains one MobileBroadbandInfo.xml document, which contains information that
is specific to mobile broadband networks.
The data within the MobileBroadbandInfo.xml document is formatted based on the MobileBroadbandInfo XML
schema, which is described in this section.
Note The XML document must be saved by using UTF-8 encoding.
For the complete definition of the MobileBroadbandInfo XML schema, see MobileBroadbandInfo XML schema
definition.
For information about the elements that are defined by the MobileBroadbandInfo XML schema, see
MobileBroadbandInfo XML elements.
For an example of XML data in the format that is defined by the MobileBroadbandInfo XML schema, see
MobileBroadbandInfo XML example.
MobileBroadbandInfo XML schema definition

IMPORTANT
The following is the namespace of the MobileBroadbandInfo XML schema:
http://schemas.microsoft.com/windows/2010/12/DeviceMetadata/MobileBroadbandInfo
The following is a definition of the MobileBroadbandInfo schema.
<?xml version="1.0" encoding ="UTF-8" ?>
<xs:schema
targetNamespace="http://schemas.microsoft.com/windows/2010/12/DeviceMetadata/MobileBroadbandInfo"
xmlns:tns="http://schemas.microsoft.com/windows/2010/12/DeviceMetadata/MobileBroadbandInfo"
xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" blockDefault="#all">


<xs:element name="MobileBroadbandInfo" type="tns:MobileBroadbandInfoType"/>


<xs:simpleType name="TetheringAllowedType">
<xs:enumeration value="Never"/>
<xs:enumeration value="Always"/>
<xs:enumeration value="EntitlementCheckRequired"/>
</xs:restriction>
</xs:simpleType>


<xs:complexType name="MobileBroadbandInfoType">
<xs:sequence>
<xs:element name="NetworkConfiguration" type="tns:NetworkConfigType" minOccurs="0"/>
<xs:element name="ProvisioningEngine" type="tns:ProvisioningEngineType" minOccurs="0"/>
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>


<xs:complexType name="NetworkConfigType">
<xs:sequence>
<xs:element name="MobileBroadbandProfiles" type="tns:MobileBroadbandProfilesType" minOccurs="0"/>
<xs:element name="AllowStandardUserPinUnlock" type="xs:boolean" minOccurs="0"/>
<xs:element name="AllowTethering" type="tns:TetheringAllowedType" minOccurs="0"/>
</xs:sequence>
</xs:complexType>


<xs:complexType name="MobileBroadbandProfilesType">
<xs:sequence>
<xs:element name="Purchase" type="tns:FileType" minOccurs="0"/>
<xs:element name="Internet" type="tns:FileType" minOccurs="0"/>
</xs:sequence>
</xs:complexType>



<xs:simpleType name="FileType">
<xs:whiteSpace value="preserve"/>
<xs:pattern value="[\p{L}\p{N}\.\-_ ]+" /> 
</xs:restriction>
</xs:simpleType>


<xs:complexType name="ProvisioningEngineType">
<xs:sequence>
<xs:element name="TrustedCertificates" type="tns:TrustedCertificateListType" minOccurs="0"/>
</xs:sequence>
</xs:complexType>


<xs:complexType name="TrustedCertificateListType">
<xs:sequence>
<xs:element name="TrustedCertificate" type="tns:TrustedCertificateType" minOccurs="0"
maxOccurs="256"/>
</xs:sequence>
</xs:complexType>


<xs:complexType name="TrustedCertificateType">
<xs:sequence>
<xs:element name="SubjectName" type="xs:string" />
<xs:element name="IssuerName" type="xs:string" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:schema>
MobileBroadbandInfo XML elements list

IMPORTANT
This section describes the XML elements defined by the MobileBroadbandInfo XML schema. The following is a
list of these elements in the order in which they are defined in the XML schema.
MobileBroadbandInfo
Purchase
Internet
AllowTethering
ProvisioningEngine
TrustedCertificates
TrustedCertificate
SubjectName
IssuerName
MobileBroadbandInfo

IMPORTANT
The MobileBroadbandInfo element is the parent element of the MobileBroadbandInfo XML schema.
Usage
<MobileBroadbandInfo>
child elements
</MobileBroadbandInfo>
Attributes
Child elements
NetworkConfiguration The NetworkConfiguration element specifies the

purchase and Internet mobile broadband profiles to be
used.
ProvisioningEngine The ProvisioningEngine element specifies trusted

certificate values for Subject Name and Issuer Name.
Parent elements
XSD
<xs:element name="MobileBroadbandInfo" type="tns:MobileBroadbandInfoType" />
<xs:complexType name="MobileBroadbandInfoType">
<xs:sequence>
<xs:element name="NetworkConfiguration" type="tns:NetworkConfigType" minOccurs="0" />
<xs:element name="ProvisioningEngine" type="tns:ProvisioningEngineType" minOccurs="0" />
</xs:sequence>
</xs:complexType>
Remarks
The MobileBroadbandInfo element is required.

IMPORTANT
The NetworkConfiguration element specifies the purchase and Internet mobile broadband profiles to be used.
The files that are referenced in this element should be included in the Ser viceInformation directory. These
files help in getting users connected to the operator network. It also specifies whether standard users should be
allowed to perform PIN unlock operations on their Mobile Broadband SIMs.
Usage
<NetworkConfiguration>
child elements
</NetworkConfiguration>
Attributes
Child elements
MobileBroadbandProfiles Specifies the purchase and Internet mobile broadband

profiles to be used.
AllowStandardUserPinUnlock Specifies whether standard users should be allowed to

perform PIN unlock operations on their Mobile
Broadband SIMs.
Parent elements
MobileBroadbandInfo The MobileBroadbandInfo element is the parent element

of the MobileBroadbandInfo XML schema.
XSD
<xs:element name="NetworkConfiguration" type="tns:NetworkConfigType" minOccurs="0" />
<xs:complexType name="NetworkConfigType">
<xs:sequence>
<xs:element name="MobileBroadbandProfiles" type="tns:MobileBroadbandProfilesType" minOccurs="0" />
<xs:element name="AllowStandardUserPinUnlock" type="xs:boolean" minOccurs="0" />
</xs:sequence>
</xs:complexType>
Remarks
In order to set a plan purchase APN or an Internet connection APN, the mobile network operator (MNO)
should specify the XML profiles that correspond to these states as part of this element.
The child elements in this element are optional. If these are not specified, the APN values from the APN
database included with Windows are used to help the user get connected.
Typically, only users in the Administrators security group are allowed to perform PIN unlock operations
on their Mobile Broadband SIMs. However, setting the AllowStandardUserPinUnlock element to true
allows the mobile operator to specify whether standard users are allowed to perform this function.

IMPORTANT
The MobileBroadbandProfiles element specifies the purchase and Internet mobile broadband profile files to use.
Usage
<MobileBroadbandProfiles>
child elements
</MobileBroadbandProfiles>
Attributes
Child elements
Purchase Specifies the purchase mobile broadband profile file to

use.
Internet Specifies the Internet mobile broadband profile file to

use.
Parent elements
NetworkConfiguration Specifies the purchase and Internet mobile broadband

profiles to be used or whether standard user can
perform PIN unlock operations.
XSD
<xs:element name="MobileBroadbandProfiles" type="tns:MobileBroadbandProfilesType" minOccurs="0" />
<xs:complexType name="MobileBroadbandProfilesType">
<xs:sequence>
<xs:element name="Purchase" type="tns:FileType" minOccurs="0" />
<xs:element name="Internet" type="tns:FileType" minOccurs="0" />
</xs:sequence>
</xs:complexType>
Remarks
The MobileBroadbandProfiles element is optional.
Purchase

IMPORTANT
The Purchase element specifies the purchase mobile broadband profile file to use.
Usage
<Purchase>
child element
</Purchase>
Attributes
Text value
The name of a file in the ServiceInformation directory.
Child elements
Parent elements

profile files to use
XSD
<xs:pattern value="[\p{L}\p{N}\.\-_ ]+"/>
</xs:restriction>
</xs:simpleType>
Remarks
The Purchase element is optional.
Internet

IMPORTANT
The Internet element specifies the purchase mobile broadband profile file to use.
Usage
<Internet>
child element
</Internet>
Attributes
Text value
The name of a file in the ServiceInformation directory.
Child elements
Parent elements

profile files to use
XSD
<xs:element name="Internet" type="tns:FileType" minOccurs="0"/>
<xs:pattern value="[\p{L}\p{N}\.\-_ ]+"/>
</xs:restriction>
</xs:simpleType>
Remarks
The Internet element is optional.

IMPORTANT
IMPORTANT
Starting in Windows 10, version 1507, this element has been deprecated and may not be supported in future versions of
Windows.
The AllowStandardUserPinUnlock element specifies if standard users are allowed to perform PIN unlock
operations.
Usage
<AllowStandardUserPinUnlock>
text
</ AllowStandardUserPinUnlock >
Attributes
Text value
A Boolean value where true allows standard users to perform PIN unlock operations and false does not.
Child elements
Parent elements

XSD
<xs:element name="AllowStandardUserPinUnlock" type="xs:boolean" minOccurs="0" />
Remarks
The AllowStandardUserPinUnlock element is optional.
AllowTethering

IMPORTANT
The AllowTethering element specifies whether the user is always allowed, never allowed, or allowed after an
entitlement check to use Internet sharing.
Note If this element is configured to allow after an entitlement check, you must specify a
DeviceNotificationHandler in your app that will handle the entitlement check.
Usage
<AllowTethering>
text
</AllowTethering>
Attributes
Text value
A string indicating whether Internet sharing is always allowed, never allowed, or allowed after an entitlement
check.
Child elements
Parent elements

XSD
<xs:element name="name="AllowTethering" type="tns:TetheringAllowedType" minOccurs="0" />
<xs:simpleType name="TetheringAllowedType">
<xs:enumeration value="Never"/>
<xs:enumeration value="Always"/>
<xs:enumeration value="EntitlementCheckRequired"/>
</xs:restriction>
</xs:simpleType>
Remarks
This element is only applicable to Windows 8.1 and Windows 10.
The AllowTethering element is optional.
ProvisioningEngine

IMPORTANT
The ProvisioningEngine element specifies the trusted certificates. This allows operators to provision the PC with
packages that are signed with a trusted certificate.
For more information about provisioning, see Account provisioning.
Usage
<ProvisioningEngine>
child element
</ProvisioningEngine>
Attributes
Child elements
TrustedCertificates Specifies the trusted certificates.
Parent elements
MobileBroadbandInfo The MobileBroadbandInfo element is the parent element

of the MobileBroadbandInfo XML schema.
XSD
<xs:element name="ProvisioningEngine" type="tns:ProvisioningEngineType" minOccurs="0" />
<xs:complexType name="ProvisioningEngineType">
<xs:sequence>
<xs:element name="TrustedCertificates" type="tns:TrustedCertificateListType" minOccurs="0" />
</xs:sequence>
</xs:complexType>
Remarks
Windows 8, Windows 8.1, and Windows 10 allow mobile network operators to provide packages to make
updates to the user’s mobile broadband network settings called provisioning packages.
To ensure those provisioning packages come from the mobile network operator, Windows verifies that
the Issuer Name and Subject Name from the certificate that is used to sign the provisioning package
match what is described in the service metadata package.
The ProvisioningEngine element is optional.
TrustedCertificates

IMPORTANT
The TrustedCertificates element specifies a list of trusted certificates.
Usage
<TrustedCertificates>
child elements
</TrustedCertificates>
Attributes
Child elements
TrustedCertificate Specifies the trusted certificate.
Parent elements
ProvisioningEngine Specifies the trusted certificates.
XSD
<xs:element name="TrustedCertificates" type="tns:TrustedCertificateListType" minOccurs="0" />
<xs:complexType name="TrustedCertificateListType">
<xs:sequence>
<xs:element name="TrustedCertificate" type="tns:TrustedCertificateType" minOccurs="0" maxOccurs="256" />
</xs:sequence>
</xs:complexType>
Remarks
The TrustedCertificates element is optional.
TrustedCertificate (MobileBroadbandInfo)

IMPORTANT
The TrustedCertificate element specifies the Subject Name and Issuer name of a trusted certificate.
Usage
<TrustedCertificate>
child elements
Attributes
Child elements
SubjectName The Subject Name of the trusted certificate.
IssuerName The Issuer Name of the trusted certificate.
Parent elements
TrustedCertificates Specifies the trusted certificates.
XSD
<xs:element name="TrustedCertificate" type="tns:TrustedCertificateType" minOccurs="0" maxOccurs="256" />
<xs:complexType name="TrustedCertificateType">
<xs:sequence>
</xs:sequence>
</xs:complexType>
Remarks
The TrustedCertificate element is optional.
SubjectName

IMPORTANT
The SubjectName element specifies the Subject Name of a trusted certificate.
Usage
<SubjectName>
text
</SubjectName>
Attributes
Text value
A string with the Subject Name of the certificate.
Child elements
Parent elements
TrustedCertificate Specifies a trusted certificate.
XSD
Remarks
The SubjectName element is optional.
IssuerName

IMPORTANT
The IssuerName element specifies the Issuer Name of a trusted certificate.
Usage
<IssuerName>
text
</IssuerName>
Attributes
Text value
A string with the Issuer Name of the certificate.
Child elements
Parent elements
TrustedCertificate Specifies a trusted certificate.
XSD
Remarks
The IssuerName element is optional.
MobileBroadbandInfo XML example

IMPORTANT
The following XML document uses the MobileBroadbandInfo XML schema to specify the mobile broadband
specific information for the service:

<MobileBroadbandInfo
xmlns="http://schemas.microsoft.com/windows/2010/12/DeviceMetadata/MobileBroadbandInfo">
<NetworkConfiguration>
<MobileBroadbandProfiles>
<Purchase>PurchaseProfile.xml</Purchase>
<Internet>OperatingProfile.xml</Internet>
</MobileBroadbandProfiles>
<AllowStandardUserPinUnlock>true</AllowStandardUserPinUnlock>
</NetworkConfiguration>
<ProvisioningEngine>
<TrustedCertificates>
<TrustedCertificate>
<SubjectName>CN=Contoso, OU=Contosodev, O=Contoso, C=US</SubjectName>
<IssuerName>CN= Contoso SA Root CA, OU=Contosodev, O=Contoso, C=US</IssuerName>
</TrustedCertificates>
</ProvisioningEngine>
</MobileBroadbandInfo>
PackageInfo XML schema overview

IMPORTANT
A metadata package contains one PackageInfo.xml document, which has information that the operating system
uses to install the metadata package and reference its contents.
The data in the PackageInfo.xml document is formatted based on the PackageInfo XML schema, which is
described in this section.
For the complete definition of the PackageInfo XML schema, see PackageInfo XML schema definition.
For information about the elements that are defined by the PackageInfo XML schema, see PackageInfo XML
elements.
For information about the data types that are defined by the PackageInfo XML schema, see PackageInfo XML
data types.
For an example of XML data in the format that is defined by the PackageInfo XML schema, see PackageInfo XML
Example.
PackageInfo XML schema definition

IMPORTANT
The following is the namespace of the PackageInfo XML schema:
http://schemas.microsoft.com/windows/DeviceMetadata/PackageInfo/2007/11/
http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2
The following is a definition of the PackageInfo schema.

<xs:schema targetNamespace="http://schemas.microsoft.com/windows/DeviceMetadata/PackageInfo/2007/11/"
xmlns:v2=http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2
xmlns:tns="http://schemas.microsoft.com/windows/DeviceMetadata/PackageInfo/2007/11/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
blockDefault="#all">
<xs:import namespace="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2"
schemaLocation="PackageInfov2.xsd" />
<xs:element name="PackageInfo" type="tns:PackageInfoType" />
<xs:complexType name="PackageInfoType">
<xs:sequence>
<xs:element name="MetadataKey" type="tns:MetadataKeyType" />
<xs:element name="PackageStructure" type="tns:PackageStructureType" />
<xs:element name="Relationships" type="tns:RelationshipsType" minOccurs="0" />
<xs:element name="MetadataBuilderInformation" type="tns:MetadataBuilderInformationType" minOccurs="0"
/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="MetadataKeyType">
<xs:sequence>
<xs:choice>
<xs:sequence>
<xs:element name="HardwareIDList" type="tns:HardwareIDListType" />
<xs:element name="ModelIDList" type="tns:ModelIDListType" minOccurs="0" />
</xs:sequence>
<xs:element name="ModelIDList" type="tns:ModelIDListType" />
</xs:choice>
<xs:element name="Locale" type="tns:LocaleType" />
<xs:element name="LastModifiedDate" type="xs:dateTime" />
<xs:element ref="v2:MultipleLocale" minOccurs="0" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="ModelIDListType">
<xs:sequence>
<xs:element name="ModelID" type="tns:GUIDType" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:simpleType name="GUIDType">
<xs:pattern value= "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="HardwareIDListType">
<xs:sequence>
<xs:element name="HardwareID" type="tns:HardwareIDType" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:simpleType name="HardwareIDType">
<xs:minLength value="1" />
<xs:maxLength value="207" />
<xs:pattern value="^([a-zA-Z0-9!#$%&()*+\-./:;<=>?@[\\\]^_`{|}~])*$" />
</xs:restriction>
</xs:simpleType>
<xs:complexType name="LocaleType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="default" type="xs:boolean" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="PackageStructureType">
<xs:sequence>
<xs:element name="Metadata" type="tns:MetadataType" minOccurs="2" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="MetadataType">
<xs:simpleContent>
<xs:attribute name="MetadataID" type="xs:anyURI" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="RelationshipsType">
<xs:sequence>
<xs:element name="ExperienceID" type="tns:GUIDType" minOccurs="0" />
<xs:element name="LanguageNeutralIdentifier" type="tns:GUIDType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"
</xs:sequence>
</xs:complexType>
<xs:complexType name="MetadataBuilderInformationType">
<xs:sequence>
<xs:element name="Application" type="tns:ApplicationType" />
<xs:element name="Version" type="tns:VersionType" />
</xs:sequence>
</xs:complexType>
<xs:simpleType name="ApplicationType">
</xs:restriction>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="VersionType">
</xs:restriction>
</xs:simpleType>
</xs:schema>
The following is the PackageInfo v2 XML schema metadata (packageinfov2.xsd):
<xs:schema targetNamespace="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2"
xmlns:tns="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2"
<xs:element name="MultipleLocale" type ="xs:boolean" />
</xs:schema>
PackageInfo XML elements list

IMPORTANT
This section describes the XML elements defined by the PackageInfo XML schema. The following is a list of these
PackageInfo
MetadataKey
ModelIDList
ModelID
HardwareIDList
HardwareID
Locale
LastModifiedDate
MultipleLocale
PackageStructure
Metadata
Relationships
ExperienceID
Application
Version
PackageInfo

IMPORTANT
The PackageInfo element is the parent element of the PackageInfo XML schema. The child elements of the
PackageInfo element specify the attributes of the service metadata package.
Usage
<PackageInfo>
child elements
</PackageInfo>
Attributes
Child elements
MetadataBuilderInformation The MetadataBuilderInformation element specifies

information about the application that created the
service metadata package.
MetadataKey The MetadataKey element specifies the attributes of the

service metadata package. These include the following:
The identifier for each hardware function
supported by the device.
The language-specific locale for the text strings
within the package.
PackageStructure The PackageStructure element specifies the XML

schemas which are referenced by the service metadata
package.
Relationships The Relationships element, through its child elements,

specifies data that is used to track a service metadata
package within the device metadata cache.
Parent elements
XSD
<xs:element name="PackageInfo" type="tns:PackageInfoType" />
<xs:complexType name="PackageInfoType">
<xs:sequence>
<xs:element name="MetadataBuilderInformation" type="tns:MetadataBuilderInformationType" minOccurs="0" />
<xs:any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The PackageInfo element must contain one instance of the MetadataKey, PackageStructure, and Relationships
elements.
MetadataKey

IMPORTANT
The MetadataKey element specifies the attributes of the service metadata package. These include the following:
The identifier for each hardware function supported by the device.
The language-specific locale for the text strings within the package.
Usage
<MetadataKey>
child elements
</MetadataKey>
Attributes
Child elements
HardwareIDList The HardwareIDList element specifies one or more hardware

identification strings for the device.
LastModifiedDate The LastModifiedDate element specifies the time stamp on

which the service metadata package was last changed.
Locale The Locale element specifies the localized version of the

ModelIDList The ModelIDList element specifies the GUID of each device

type or model that is specified within the service metadata
package.
MultipleLocale The MultipleLocale element specifies whether the service

metadata package supports multiple locales.
Parent elements
PackageInfo The PackageInfo element is the parent element of the

PackageInfo XML schema. The child elements of the
PackageInfo element specify the attributes of the device
metadata package.
XSD
<xs:complexType name="MetadataKeyType">
<xs:sequence>
<xs:choice>
<xs:sequence>
</xs:sequence>
<xs:element name="ModelIDList" type="tns:ModelIDListType" />
</xs:choice>
<xs:element ref="v2:MultipleLocale" minOccurs="0" />
</xs:sequence>
</xs:complexType>
The following is the PackageInfov2 XML schema metadata:
<xs:schema targetNamespace="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2"
xmlns:tns="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2"
</xs:schema>
Remarks
The child elements of the MetadataKey element specify the metadata that the operating system uses to do the
following:
Search the device metadata store for a service metadata package based on either a device's ModelID or
HardwareID value. If more than one metadata packages match the device's Model or Hardware ID, the
operating system also compares the Locale value within the metadata package to the current language
setting on the user's computer.
Update the device metadata store with the service metadata package if a package has a more recent
LastModifiedDate value than an existing package within the device metadata store.
The MetadataKey element must contain:
One instance of the Locale and LastModifiedDate elements.
One instance of either the HardwareIDList or ModelIDList elements. The MetadataKey element can
contain one instance of both elements.
The MetadataKey element is required.
ModelIDList

IMPORTANT
The ModelIDList element specifies one or more GUIDs. Each GUID is specified through a ModelID element, and
identifies a physical device specified within the device metadata package.
Caution The ModelIDList and ModelID elements are not supported for service metadata packages. You must
use the HardwareIDList and HardwareID elements instead.
Usage
<ModelIDList>
child elements
</ModelIDList>
Attributes
Child elements
ModelID The ModelID element specifies the GUID of a physical

device.
Parent elements

device metadata package. These include the following:
within the package.
XSD
<xs:sequence>
<xs:element name="ModelID" type="tns:GUIDType" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
Remarks
The ModelIDList element is required only if the HardwareIDList element is not specified in the MetadataKey
element. If it is specified, the ModelIDList element must contain one or more ModelID elements. If your device
metadata package supports multiple device models or model IDs, you can specify a ModelID element for each
device model.
If the PackageInfo XML data contains both of the HardwareIDList and ModelIDList elements, the operating
system uses the following rules when it determines whether a device is specified by a device metadata package:
If the device has a model ID, the operating system does not search for a match in the HardwareIDList
element. For more information about model IDs, see ModelID.
Otherwise, the operating searches the HardwareIDList element for a match of the device's hardware ID.
ModelID

IMPORTANT
The ModelID element specifies the GUID of a physical device.

Usage
<ModelID>
text
</ModelID>
Attributes
Text value
A value formatted as a GUIDType XML simple type.
Child elements
Parent elements
ModelIDList The ModelIDList element specifies the GUID of each

hardware model supported by the device specified
within the device metadata package.
XSD
Remarks
The ModelID element specifies a model ID for a hardware model supported by a device. Each model ID is
specified through a GUID.
Model IDs are based on the business definition or SKU of the physical device. Each model ID must be unique for
all makes and models of the physical device.
The following list describes the differences between hardware and model IDs for a physical device:
Hardware IDs, specified through the HardwareID element, identify a hardware function based on a bus-
specific value. Hardware IDs could map device drivers to device instances. For example, two devices with
the same hardware ID share a functional interface that is used by the same driver.
Model IDs, specified through the ModelID element, enable the OEM or independent hardware vendor
(IHV) to uniquely identify the physical device independent of bus or interface technologies. For example,
two devices with different model IDs may have the same hardware IDs for their components.
Hardware IDs map device metadata packages to device instances on a specific bus or interface.
Model IDs map device metadata packages to physical devices, regardless of how the device is connected
to the computer.
HardwareIdList (PackageInfo)

IMPORTANT
The HardwareIDList element specifies one or more hardware identification strings for the service metadata
package. Each string is specified by a HardwareID element.
Usage
<HardwareIDList>
child elements
</HardwareIDList>
Attributes
Text value
Must contain one or more HardwareID elements.
Child elements
HardwareID The HardwareID elements represent the mobile network

operator.
Parent elements

within the package.
XSD
<xs:complexType name="HardwareIDListType">
<xs:sequence>
</xs:sequence>
</xs:complexType>
Remarks
The HardwareIDList element is required.
HardwareId (PackageInfo)

IMPORTANT
For service metadata packages, the HardwareID values represent the mobile network operator in the form of the
following:
GSM networks: IMSI value
GSM networks: ICCID value
CDMA networks: Provider name value
CDMA networks: Provider ID value (also known as a SID)
Usage
<HardwareID>
text
</HardwareID>
Attributes
Text value
Generating the proper hardware ID values as part of metadata creation involves a complex algorithm. You
should generate hardware ID values by using MBIDGenerator.exe included in the Windows Driver Kit (WDK).
Child elements
Parent elements
HardwareIDList The HardwareIDList element specifies one or more

hardware identification strings for the service metadata
package.
XSD
<xs:simpleType name="HardwareIDType">
<xs:pattern value="^([a-zA-Z0-9!#$%&()*+\-./:;<=>?@[\\\]^_`{|}~])*$" />
</xs:restriction>
</xs:simpleType>
Remarks
Hardware IDs that are included in PackageInfo.xml must have the “DOID:” prefix added to them. For
example: DOID:MBAE:0:hashednumber1
More than one HardwareID element can be used to specify a service.
For GSM IMSI or ICCID ranges, the start range value must end in 00 and the end range value must end in
99. For privacy reasons, matching occurs in blocks of 100 for IMSI and ICCID values.
The HardwareID element is required.
Locale

IMPORTANT
The Locale element specifies the locale of the service metadata package. A service metadata package can specify
single or multiple locales. To use multiple locales, you must set the MultipleLocale element to true .
Usage
<Locale
default = "xs:boolean">
text
</Locale>
Attributes
default xs:boolean Yes Must be true (1) or

false (0). If the default
attribute is set to true,
the operating system
uses this device
metadata package as
the default for the
current locale of the
computer.
Child elements
Parent elements

within the package.
XSD
<xs:complexType name="LocaleType">
<xs:simpleContent>
<xs:attribute name="default" type="xs:boolean" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
Remarks
The Locale element can be <Language>-<Region> (such as EN-US) or <Language> (such as EN). If the
<Language> is set, the package applies to all <Language> locales. For example, EN applies to EN-US and
EN-BR.
To specify the metadata package as the default for the current locale of the computer, set the default
attribute to true (1).
Note Only one metadata package for a service should set the default attribute to true (1). Otherwise,
the operating system randomly selects a metadata package for the service.
When the operating system selects a service metadata package to display, it uses the Locale element in
the following way:
1. The operating system retrieves the system preferred language and region. This is typically
configured during Windows Setup.
2. If the Locale element of a service metadata package matches the system preferred language and
region, the operating system selects the package for the service and uses the icon and
Ser viceProvider value (from ServiceInfo.xml) that matches that language and region.
3. If the services metadata package does not have a Locale element that matches the system
preferred language, the operating system will apply the language neutral icon and
Ser viceProvider value (from ServiceInfo.xml) that is stored in the root of the service metadata
package.
The Locale element is required.
LastModifiedDate

IMPORTANT
The LastModifiedDate element specifies the timestamp on which the service metadata package was last
changed. Based on this information, the operating system selects and loads the most recent service metadata
package version.
Usage
<LastModifiedDate>
text
</LastModifiedDate>
Attributes
Text value
The timestamp value is represented in the Universal Time Coordinated (UTC) format.
Child elements
Parent elements

within the package.
XSD
Remarks
The value of the LastModifiedDate element must represent the actual time that the metadata package
was last changed.
Each time you submit your service metadata package to the Windows Hardware Dev Center Dashboard
for distribution through Windows Metadata and Internet Services (WMIS), the LastModifiedDate element
is updated after your package is validated.
The LastModifiedDate element is required.
MultipleLocale

IMPORTANT
The MultipleLocale element specifies if the service metadata package supports multiple locales or not.
Usage
<MultipleLocale>
text
</MultipleLocale>
Attributes
Text value
A boolean value that is true if the service metadata package supports multiple locales.
Child elements
Parent elements

within the package.
XSD
Remarks
To support multiple locales in the service metadata package , Set the MultipleLocale element to true . This
element is not supported on Windows 7. If this element is not specified, the default value is true.
If there is both a single locale service metadata package and a multiple-locale service metadata package
on a user's computer, Windows uses the multiple-locale service metadata package, if all other ranking
values are the same.
PackageStructure

IMPORTANT
The PackageStructure element specifies the XML schemas that are referenced by the service metadata package.
Each XML schema is specified through the Metadata element.
Usage
<PackageStructure>
text
child elements
</PackageStructure>
Attributes
Text value
Four or more Metadata elements are required.
Child elements
Metadata The Metadata element specifies the XML schemas that

are referenced through the device metadata package.
Parent elements

metadata package.
XSD
<xs:sequence>
</xs:sequence>
</xs:complexType>
Remarks
A minimum of four instances of the Metadata element must be specified within the PackageStructure element.
Each instance must specify one of the required XML schemas that are used to create a service metadata
package:
MobileBroadbandInfo XML schema
The PackageStructure element is required.
Metadata

IMPORTANT
The Metadata element specifies the namespaces of the XML schemas that are referenced in the service metadata
package.
Usage
<Metadata
MetadataID = "xs:anyURI">
text
</Metadata>
Attributes
MetadataID xs:anyURI Yes Specifies the namespace of

an XML schema that is
referenced within the
Text value
The Uniform Resource Identifier (URI) of the namespace of a service metadata XML schema. The XML schema
must be one of the schemas referenced within the services metadata package.
Child elements
Parent elements
PackageStructure The PackageStructure element specifies the XML schemas

which are referenced by the service metadata package.
XSD
<xs:sequence>
</xs:sequence>
</xs:complexType>
<xs:complexType name="MetadataType">
<xs:simpleContent>
<xs:attribute name="MetadataID" type="xs:anyURI" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
Remarks
In the PackageInfo element, a minimum of two instances of the Metadata element must be specified. Each
instance must specify the namespace of one of the following required XML schemas that are used to create a
service metadata package:
WindowsInfo XML schema
The easiest approach is to copy the following example above into your Packageinfo.xml file. If any of the folders
specified above are not included in the service metadata package, make sure to remove the Metadata element
from the PackageStructure element.
<PackageStructure>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/DeviceMetadata/PackageInfo/2007/11">PackageInfo.xml</Metada
ta>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo">ServiceInformation</Met
adata>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/">WindowsInformation</Me
tadata>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/SoftwareInfo">SoftwareInformation</M
etadata>
</PackageStructure>
The SoftwareInformation folder and service metadata packages are not supported on devices running Windows
7.
Each folder name can be changed to an arbitrary name as long as the name is set in this metadata element. The
following example shows how to use “WindowsInfo” as a folder name:
<Metadata
MetadataID="http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/">WindowsInfo</Metadata>
Relationships

IMPORTANT
The Relationships element specifies data that is used to track a device metadata package within the device
metadata cache.
Usage
<Relationships>
text
child elements
</Relationships>
Attributes
Text value
If the Relationships element is specified, it must specify the ExperienceID element or the
LanguageNeutralIdentifier element, or both.
Child elements
ExperienceID The ExperienceID element specifies a GUID that is

managed by the Windows Dev Center Dashboard. This
GUID is used to group one or more metadata packages
for the same device identifiers independent of the
packages’ locale.
LanguageNeutralIdentifier The LanguageNeutralIdentifier element specifies a GUID

that identifies the device metadata package independent
of its locale.
Parent elements
PackageInfo The PackageInfo element specifies the attributes of the

XSD
<xs:complexType name="RelationshipsType">
<xs:sequence>
<xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"
</xs:sequence>
</xs:complexType>
Remarks
The child elements of the Relationships element (ExperienceID and LanguageNeutralIdentifier) provide separate
search keys that the operating system uses to query device metadata packages that are installed within the
device metadata cache.
ExperienceID

IMPORTANT
The ExperienceID element specifies a GUID representing the device experience. This GUID is used to group one
or more metadata packages for the same device identifiers independent of the packages’ locale.
In Windows 8, Windows 8.1, and Windows 10 it is also used to link the device metadata to a device app that can
be automatically acquired when the device is first connected. A device app specifies one or more ExperienceID
elements in a StoreManifest.XML file in the app submission package. Each of these ExperienceID GUIDs
corresponds to the ExperienceID element of a device metadata package. After the StoreManifest.xml file has
been submitted, the device app can then be distributed to one or more device models, if the ExperienceID in a
device’s metadata is also specified in the device apps StoreManifest file.
Usage
<ExperienceID>
text
</ExperienceID>
Attributes
Text value
A value formatted as a GUIDType XML simple type.
Child elements
Parent elements
Relationships The Relationships element specifies data that is used to

track a device metadata package within the device
metadata cache.
XSD
Remarks
In Windows 8.1 and Windows 10, the ExperienceID is created by the Service Metadata Wizard on the Windows
Dev Center Dashboard.
In Windows 8 the ExperienceID can be specified by the service metadata developer, or automatically generated
and added to the service metadata using the Device Metadata Authoring Wizard. If the ExperienceID is not
specified in the service metadata package, the Windows Dev Center Dashboard creates a GUID and updates the
ExperienceID element within the metadata package when the mobile network operator or mobile virtual
network operator submits the service metadata package.

IMPORTANT
The LanguageNeutralIdentifier element specifies a GUID, which identifies the service metadata package
independent of its locale. The LanguageNeutralIdentifier element lets the same GUID be used to identify one or
more localized versions of a service metadata package for the same service.
Usage
<LanguageNeutralIdentifier>
text
</LanguageNeutralIdentifier>
Attributes
Child elements
Parent elements
Relationships The Relationships element specifies data that is used to

track a device metadata package within the device
metadata cache.
XSD
Remarks
The LanguageNeutralIdentifier element allows the same GUID to be used in one or more localized versions of a
device metadata package for the same device.
For example, If you release a device for three locales (such as EN-US, JA-JP, and AR-SA), you can create separate
metadata packages for the device for each locale. By using a common GUID for the LanguageNeutralIdentifier
elements in these packages, you can easily search for the device's metadata package by browsing its
PackageInfo XML document.
Impor tant The LanguageNeutralIdentifier element is not used by any component of the operating system. It is
reserved for use by the OEM, independent hardware vendor (IHV), and independent software vendor (ISV).]
The LanguageNeutralIdentifier element is optional.

IMPORTANT
The MetadataBuilderInformation element specifies information about the application that created the device
metadata package.
Usage
<MetadataBuilderInformation>
text
child elements
</MetadataBuilderInformation>
Attributes
Text value
A string that contains between 1 and 256 printable characters inclusive.
Child elements
Application The Application element specifies the name of the

application software that created the service metadata
package.
Version The Version element specifies the version of the

application software that created the service metadata
package.
Parent elements

metadata package.
XSD
<xs:element name="MetadataBuilderInformation" type="tns:MetadataBuilderInformationType" minOccurs="0" />
<xs:complexType name="MetadataBuilderInformationType">
<xs:sequence>
</xs:sequence>
</xs:complexType>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
Remarks
The MetadataBuilderInformation element is not used by any component of the operating system. It is reserved
for use by the OEM, IHV, and ISV.
Application

IMPORTANT
The Application element specifies the name of the application software that created the device metadata
package.
Usage
<Application>
text
</Application>
Attributes
Text value
A string that contains between 1 and 256 characters inclusive.
Child elements
Parent elements
MetadataBuilderInformation The MetadataBuilderInformation element specifies the

application that created the service metadata package.
XSD
</xs:restriction>
</xs:simpleType>
Remarks
The Application element is not used by the Windows 7 operating system. It is reserved for use by OEMs and
developers.
Version

IMPORTANT
The Version element specifies the version of the application software that created the service metadata package.
Usage
<Version>
text
</Version>
Attributes
Child elements
Parent elements
MetadataBuilderInformation The MetadataBuilderInformation element specifies the

application that created the service metadata package.
XSD
</xs:restriction>
</xs:simpleType>
Remarks
The Version element is not used by the Windows 7 operating system. It is reserved for use by the OEM and
developers.
GUIDType (PackageInfo)

IMPORTANT
The GUIDType XML simple type specifies a GUID.
<xs:pattern value="[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" />
</xs:restriction>
</xs:simpleType>
Patterns
The GUIDType simple type is a xs:string that is restricted by the following pattern:
[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
Remarks
The GUIDType XML simple type specifies a GUID that uniquely identifies components within the device metadata
package, such as the device's ExperienceID, LanguageNeutralIdentifier, and ModelID values.
PackageInfo XML Example

IMPORTANT
The following XML document uses the PackageInfo XML schema to specify the components of a vendor’s
metadata package.
The package is for a service that has the following hardware ID:
MBAE:0:L9@E}}DT2.*F65MQA57Y+L
NOTE
Hardware IDs that are included in PackageInfo.xml must have the “DOID:” prefix added to them.
The package is also for the EN-US locale, which the document sets as the default locale for the components of
the metadata package.
<PackageInfo xmlns=http://schemas.microsoft.com/windows/DeviceMetadata/PackageInfo/2007/11/
xmlns:v2=” http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/PackageInfov2”>
<MetadataKey>
<HardwareIDList>
<HardwareID>DOID:MBAE:0:L9@E}}DT2.*F65MQA57Y+L</HardwareID>
</HardwareIDList>
<Locale default="true">EN-US</Locale>
<LastModifiedDate>2008-01-24T00:00:00Z</LastModifiedDate>
<v2:MultipleLocale>true</v2:MultipleLocale>
</MetadataKey>
<PackageStructure>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/DeviceMetadata/PackageInfo/2007/11">PackageInfo.xml</Metada
ta>
<Metadata
MetadataID="http://schemas.microsoft.com/windows/DeviceMetadata/ServiceInfo/2007/11/">ServiceInformation</Me
tadata>
<Metadata
MetadataID=”http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/”>WindowsInformation</Me
tadata>
</PackageStructure>
</PackageInfo>
ServiceInfo XML schema overview

IMPORTANT
A service metadata package contains one ServiceInfo.xml document, which contains detailed information about
the service that Windows Connection Manager displays to the user.
The data in the ServiceInfo.xml document is formatted based on the ServiceInfo XML schema, which is described
in this section.
For the complete definition of the ServiceInfo XML schema, see ServiceInfo XML Schema Definition.
For information about the elements that are defined by the ServiceInfo XML schema, see ServiceInfo XML
Elements.
For information about the data types that are defined by the ServiceInfo XML schema, see ServiceInfo XML Data
Types.
For an example of XML data in the format that is defined by the ServiceInfo XML schema, see ServiceInfo XML
Example.
ServiceInfo XML Schema Definition

IMPORTANT
The following is the namespace of the ServiceInfo XML schema:
http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo
The following is a definition of the ServiceInfo schema.

<xs:schema targetNamespace="http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo"
xmlns:tns="http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo"
<xs:element name="ServiceInfo" type="tns:ServiceInfoType" />
<xs:complexType name="ServiceInfoType">
<xs:sequence>
<xs:element name="ServiceCategoryList" type="tns:ServiceCategoryListType" />
<xs:element name="ServiceName" type="tns:ServiceNameType" minOccurs="0" />
<xs:element name="ServiceDescription1" type="tns:ServiceDescriptionType" minOccurs="0" />
<xs:element name="ServiceNumber" type ="tns:ServiceNumberType" />
<xs:element name="ServiceProvider" type="tns:ProviderNameType" />
<xs:element name="ServiceIconFile" type="tns:ServiceIconFileType" minOccurs="0" />
<xs:element name="ServiceSpecificExtension" type="tns:ServiceSpecificExtensionType" minOccurs="0" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="ServiceCategoryListType">
<xs:sequence>
<xs:element name="ServiceCategory" type="tns:ServiceCategoryType" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:simpleType name="ServiceCategoryType">
<xs:union memberTypes="tns:ServiceCategoryTypeEnumeration xs:string" />
</xs:simpleType>
<xs:simpleType name="ServiceCategoryTypeEnumeration">
<xs:restriction base="xs:string" >
<xs:enumeration value="Network" />
<xs:enumeration value="Network.MobileBroadband" />
<xs:enumeration value="Other" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceNameType">
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceNumberType">
<xs:union memberTypes="tns:GUIDType xs:string" />
</xs:simpleType>
<xs:simpleType name="ProviderNameType">
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceDescriptionType">
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ServiceIconFileType">
<xs:pattern value=".+\.ico" />
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="ServiceSpecificExtensionType">
<xs:simpleContent>
<xs:attribute name="namespace" type="xs:anyURI" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:schema>
ServiceInfo XML elements list

IMPORTANT
This section describes the XML elements defined by the ServiceInfo XML schema. The following is a list of these
ServiceInfo
ServiceCategoryList
ServiceCategory
ServiceName
ServiceDescription1
ServiceDescription2
ServiceNumber
ServiceProvider
ServiceIconFile
ServiceInfo

IMPORTANT
The ServiceInfo element is the parent element of the ServiceInfo XML schema.
Usage
<ServiceInfo>
child elements
</ServiceInfo>
Attributes
Child elements
ServiceCategoryList Specifies one or more functional categories that apply to

the service.
ServiceName Not used.
ServiceDescription1 Specifies descriptive information about the service. This

is applied to the description field of the wireless wide
area network (WWAN) connection profile. It is not
displayed in the user interface to the end user.
ServiceDescription2 Not used.
ServiceNumber This is a self-generated GUID that identifies the operator

that is submitting this package.
ServiceProvider This appears in Windows Connection Manager as the

home network display name.
ServiceIconFile Specifies the name of the service icon file in the service
metadata package.
Note
This is listed as optional in the schema. However, it is
required in order to pass validation when the package
is submitted to the Windows Dev Center Dashboard.
ServiceSpecificExtension References the location of the file that is specific to this

ServiceCategory. For Windows 8, Windows 8.1, or
Windows 10 for desktop editions (Home, Pro, Enterprise,
and Education) service metadata packages, this is the
location of MobileBroadbandInfo.xml.
Parent elements
XSD
<xs:sequence>
</xs:sequence>
</xs:complexType>
Remarks
The ServiceInfo element must contain one instance of the ServiceCategoryList, ServiceNumber, ServiceProvider,
and ServiceSpecificExtension elements.
The ServiceInfo element is required.
ServiceCategoryList

IMPORTANT
The ServiceCategoryList element specifies one or more functional categories that apply to the service. Each
functional category is specified through a ServiceCategory element.
Usage
<ServiceCategorylist>
child element
</ServiceCategorylist>
Attributes
Text value
Must contain one ServiceCategory element.
Child elements
ServiceCategory Specifies one or more functional categories that apply to

the service.
Parent elements
ServiceInfo The ServiceInfo element is the parent element of the

ServiceInfo XML schema.
XSD
<xs:sequence>
</xs:sequence>
</xs:complexType>
Remarks
The following discusses the use of the ServiceCategoryList elements in a service metadata package:
The first ServiceCategory element in the ServiceCategoryList element specifies the service’s primary
functional category. The primary functional category should match how the service is advertised,
packaged, sold, and ultimately identified by users.
Because a service is defined only by its primary functional category, you should specify only one instance
of the ServiceCategory element in the ServiceCategoryList element.
The ServiceCategory for service metadata packages must be one of the following:
Network.MobileBroadband
Network.MobileBroadband.CDMA
Network.MobileBroadband.GSM
The ServiceCategoryList element is required.
ServiceCategory

IMPORTANT
The ServiceCategory element specifies the functional category that applies to the service.
Usage
<ServiceCategory>
text
</ServiceCategory>
Attributes
Text value
Must contain one ServiceCategory element.
Child elements
Parent elements
ServiceCategoryList The ServiceCategoryList element specifies the functional

categories that apply to the service.
XSD
<xs:union memberTypes="tns:ServiceCategoryTypeEnumeration xs:string"/>
</xs:simpleType>
<xs:enumeration value="Network"/>
<xs:enumeration value="Network.MobileBroadband"/>
<xs:enumeration value="Other"/>
</xs:restriction>
</xs:simpleType>
Remarks
The following discusses the use of the ServiceCategoryList elements in a service metadata package:
The first ServiceCategory element in the ServiceCategoryList element specifies the service’s primary
functional category. The primary functional category should match how the service is advertised,
packaged, sold, and ultimately identified by users.
Because a service is defined only by its primary functional category, you should specify only one instance
of the ServiceCategory element in the ServiceCategoryList element.
The ServiceCategory for service metadata packages must be one of the following:
Network.MobileBroadband
Network.MobileBroadband.CDMA
Network.MobileBroadband.GSM
The ServiceCategory element is required.
ServiceName

IMPORTANT
The ServiceName element is not currently used.
Usage
<ServiceName>
text
</ServiceName>
Attributes
Text value
A string that is less than 200 characters in length.
Child elements
Parent elements

XSD
</xs:restriction>
</xs:simpleType>
Remarks
The ServiceName element is not currently used.
ServiceDescription1

IMPORTANT
The ServiceDescription1 element specifies descriptive information about the service. This is applied to the
description field of the wireless wide area network (WWAN) connection profile. It is not displayed in the user
interface to the end user and should be left blank.
Usage
<ServiceDescription1>
text
</ServiceDescription1>
Attributes
Text value
Child elements
Parent elements

XSD
<xs:element name="ServiceDescription1" type="tns:ServiceDescriptionType" minOccurs="0"/>
</xs:restriction>
</xs:simpleType>
Remarks
The ServiceDescription1 element does not appear to the end user in any user interface.
The ServiceDescription1 element is optional and should be left blank.
ServiceDescription2

IMPORTANT
The ServiceDescription2 element is not currently used.
Usage
<ServiceDescription2>
text
</ServiceDescription2>
Attributes
Text value
Child elements
Parent elements

XSD
<xs:element name="ServiceDescription2" type="tns:ServiceDescriptionType" minOccurs="0"/>
</xs:restriction>
</xs:simpleType>
Remarks
The ServiceDescription2 is not currently used.
ServiceNumber

IMPORTANT
The ServiceNumber element specifies the unique self-generated GUID that represents the mobile operator. This
GUID must be present and is checked when account provisioning metadata is applied to a PC to ensure a match
with the GUID value declared in the Carrier ID identified in that file. The account provisioning metadata is
generated by the mobile broadband app or an operator website. Account provisioning metadata is described in
Account provisioning.
Usage
<ServiceNumber>
text
</ServiceNumber>
Attributes
Text value
A string of GUIDType.
Child elements
Parent elements

XSD
</xs:simpleType>
Remarks
The ServiceNumber element is required.
ServiceProvider

IMPORTANT
IMPORTANT
branding are described on Planning your desktop COSA/APN database submission. If you are targeting versions of
Windows before Windows 10, version 1709, you will still create a metadata package as described in this section. For more
information about COSA, see COSA overview.
The ServiceProvider element specifies the name of the service provider. It is shown in Windows Connection
Manger to display the home provider network name. If the user is on a roaming network the roaming network
name is displayed instead.
Usage
<ServiceProvider>
text
</ServiceProvider>
Attributes
Text value
A string of up to 20 printable characters.
Child elements
Parent elements

XSD
<xs:element name="ServiceProvider" type="tns:ProviderNameType"/>
</xs:restriction>
</xs:simpleType>
Remarks
The ServiceProvider element is not shown in Windows Connection Manager when the user is roaming.
The ServiceProvider element is required.
ServiceIconFile

IMPORTANT
IMPORTANT
branding are described on Planning your desktop COSA/APN database submission. If you are targeting versions of
Windows before Windows 10, Version 1709, you will still create a metadata package as described in this section. For more
information about COSA, see COSA overview.
The ServiceIconFile element specifies the name of the service icon file in the service metadata package. The
service icon file is used to display the logo of the mobile network operator (MNO) or mobile virtual network
operator (MVNO) in Windows Connection Manager.
Usage
<ServiceProvider>
text
</ServiceProvider>
Attributes
Text value
The name of an icon file with an .ICO extension.
Child elements
Parent elements

XSD
<xs:element name="ServiceIconFile" type="tns:ServiceIconFileType" minOccurs="0"/>
<xs:pattern value=".+\.ico"/>
</xs:restriction>
</xs:simpleType>
Remarks
The required icon file sizes are as follows:
256x256:32bit+Alpha(compressed) 24x24:32bit+Alpha
48x48:32bit+Alpha 24x24:8bit256
48x48:8bit256 24x24:4bit16
48x48:4bit16 16x16:32bit+Alpha
32x32:32bit+Alpha 16x16:8bit256
32x32:8bit256 16x16:4bit16
32x32:4bit16
The ServiceIconFile element is marked as optional in the schema. However, service metadata packages that are
submitted to the Windows Dev Center Dashboard without the ServiceIconFile element will be rejected.

IMPORTANT
The ServiceSpecificExtension element specifies the relative location of the MobileBroadbandInfo.xml file.
Usage
<ServiceSpecificExtension
name = “xs:anyURI”>
text
</ServiceSpecificExtension>
Attributes
namespace xs:anyURI Yes The URI of the

namespace that is used
for the
MobileBroadbandInfo.x
ml file.
Text value
The name of the XML file that contains the MobileBroadbandInfo schema.
Child elements
Parent elements

XSD
<xs:simpleContent>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
Remarks
The ServiceSpecificExtension element is required.
GUIDType (ServiceInfo)

IMPORTANT
The GUIDType XML simple type specifies a GUID.
</xs:restriction>
</xs:simpleType>
Patterns
The GUIDType simple type is a xs:string that is restricted by the following pattern:
[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
ServiceInfo XML Example

IMPORTANT
The following XML document uses the ServiceInfo XML schema to specify the attributes of the Contoso Wireless
service:
<DeviceInfo xmls="http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo">
<ServiceCategoryList>
<ServiceCategory>Network.MobileBroadband </ServiceCategory>
</ServiceCategoryList>
<ServiceName> </ServiceName>
<ServiceDescription1>Fabrikam Wireless 3G network</ServiceDescription1>
<ServiceDescription2></ServiceDescription2>
<ServiceNumber>D4A5C6D5-8135-4A0D-9B9D-016F5D7D9F45 </ServiceNumber>
<ServiceProvider>Contoso Wireless</ServiceProvider>
<ServiceIcon>Contoso.ico</ServiceIcon>
<ServiceSpecificExtension
namespace="http://schemas.microsoft.com/windows/2010/12/DeviceMetadata/MobileBroadbandInfo">MobileBroadbandI
nfo.xml</ServiceSpecificExtension>
</ServiceInfo>
SoftwareInfo XML schema overview

IMPORTANT
A metadata package contains one SoftwareInfo.xml document, which contains information that the operating
system downloads a UWP app. This information results in privileged access for apps.
The data within the Softwareinfo.xml document is formatted based on the SoftwareInfo XML Schema, which is
For the complete definition of the SoftwareInfo XML schema, see SoftwareInfo XML Schema Definition.
For information about the elements that are defined by the SoftwareInfo XML schema, see SoftwareInfo XML
Schema Definition.
For an example of XML data in the format that is defined by the SoftwareInfo XML schema, see SoftwareInfo
XML Example.
SoftwareInfo XML Schema Definition

IMPORTANT
The following is the namespace of the SoftwareInfo XML schema:
http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/SoftwareInfo
The following is a definition of the SoftwareInfo schema.

<xs:schema targetNamespace="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/SoftwareInfo"
xmlns:tns="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/SoftwareInfo"
<xs:element name="SoftwareInfo" type="tns:SoftwareInfoType" />


<xs:complexType name="SoftwareInfoType">
<xs:choice>
<xs:sequence>
<xs:element name="DeviceCompanionApplications" type="tns:DeviceCompanionApplicationsType" />
<xs:element name="PrivilegedApplications" type="tns:PrivilegedApplicationsType" minOccurs="0" />
</xs:sequence>
<xs:element name="PrivilegedApplications" type="tns:PrivilegedApplicationsType" />
</xs:choice>
</xs:complexType>


<xs:complexType name="DeviceCompanionApplicationsType">
<xs:sequence>
<xs:element name="Package" type="tns:PackageType" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>


<xs:complexType name="PrivilegedApplicationsType">
<xs:choice>
<xs:element name="AnyApplication" type="tns:AnyApplicationType" />
<xs:element name="Package" type="tns:PackageForPrivilegedApplications" maxOccurs="unbounded" />
</xs:choice>
</xs:complexType>


<xs:complexType name="PackageType">
<xs:sequence>
<xs:element name="Identity" type="tns:IdentityType" />
<xs:element name="Applications" type="tns:ApplicationsType" />
</xs:sequence>
</xs:complexType>


<xs:complexType name="IdentityType">
<xs:attribute name="Name" type="tns:PackageNameType" use="required"/>
<xs:attribute name="Publisher" type="tns:PublisherType" use="required"/>
</xs:complexType>
<xs:simpleType name="PackageNameType">
<xs:restriction base="tns:AsciiIdentifierType">
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="PublisherType">
<xs:restriction base="tns:DistinguishedNameType">
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="DistinguishedNameType">
<xs:restriction base="tns:NonEmptyStringType">
<xs:pattern value="(CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-9]*)(\.(0|[1-9]
[0-9]*))+))=(([^,+="<>#;])+|".*")(, ((CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9]
[0-9]*)(\.(0|[1-9][0-9]*))+))=(([^,+="<>#;])+|".*")))*"/>
</xs:restriction>
</xs:simpleType>


<xs:complexType name="ApplicationsType">
<xs:sequence>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ApplicationType">
<xs:sequence>
<xs:element name="DeviceNotificationHandlers" type="tns:DeviceNotificationHandlersType" minOccurs="0"
/>
</xs:sequence>
<xs:attribute name="Id" type="tns:ApplicationIdType" use="required"/>
</xs:complexType>
<xs:simpleType name="ApplicationIdType">
<xs:restriction base="tns:AsciiWindowsIdType">
</xs:restriction>
</xs:simpleType>


<xs:complexType name="DeviceNotificationHandlersType">
<xs:sequence>
<xs:element name="DeviceNotificationHandler" type="tns:DeviceNotificationHandlerType"
</xs:sequence>
</xs:complexType>


<xs:complexType name="DeviceNotificationHandlerType">
<xs:attribute name="EventID" type="xs:string" use="required"/>
<xs:attribute name="EventAsset" type="xs:string" use="required"/>
</xs:complexType>



<xs:complexType name ="AnyApplicationType"/>
<xs:complexType name="PackageForPrivilegedApplications">
<xs:sequence>
<xs:element name="Identity" type="tns:IdentityForPrivilegedApplicationsType" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="IdentityForPrivilegedApplicationsType">
<xs:attribute name="AccessCustomDriver" type="xs:boolean" />
</xs:complexType>
<xs:simpleType name="AsciiIdentifierType">
<xs:restriction base="tns:AllowedAsciiCharSetType">
<xs:pattern value="[^_ ]+"/>
</xs:restriction>
</xs:simpleType>


<xs:simpleType name="AllowedAsciiCharSetType">
<xs:pattern value="[-_. A-Za-z0-9]+"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="NonEmptyStringType">
<xs:pattern value="[^\s]|([^\s].*[^\s])"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AsciiWindowsIdType">
<xs:pattern value="([A-Za-z][A-Za-z0-9]*)(\.[A-Za-z][A-Za-z0-9]*)*"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="UnicodeIdentifierType">
<xs:restriction base="tns:UnicodeIdentifierCharSetType" />
</xs:simpleType>
<xs:simpleType name="UnicodeIdentifierCharSetType">
<xs:restriction base="tns:AllowedUnicodeCharSetType">
<xs:pattern value="[^!#$%'()\*\+,/:;=\?@\[\\\]^_`\|]+" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AllowedUnicodeCharSetType">
<xs:restriction base="tns:UnicodeNoPrivateUseOrNonCharacterCodePointsType">
<xs:pattern value="[^"&<>\u0000-\u0020\u007F\u0080-\u009F\u00A0\u00AD\u0340-
\u0341\u034F\u06DD\u070F\u1680\u1806\u180B-\u180E\u2000-\u200F\u2028-\u202F\u205F\u2060-\u2063\u206A-
\u206F\u2FF0-\u2FFB\u3000\uD800-\uDFFF\uFEFF\p{IsVariationSelectors}]+"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="UnicodeNoPrivateUseOrNonCharacterCodePointsType">
<xs:pattern value="[^\uE000-\uF8FF\uFDD0-\uFDEF\uFFF9-\uFFFF\p{IsPrivateUse}]+"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
<xs:schema targetNamespace="http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo"
xmlns:tns="http://schemas.microsoft.com/windows/2010/05/DeviceMetadata/ServiceInfo"
<xs:sequence>
</xs:sequence>
</xs:complexType>
<xs:sequence>
</xs:sequence>
</xs:complexType>
<xs:union memberTypes="tns:ServiceCategoryTypeEnumeration xs:string" />
</xs:simpleType>
<xs:restriction base="xs:string" >
<xs:enumeration value="Network" />
<xs:enumeration value="Network.MobileBroadband" />
<xs:enumeration value="Other" />
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
<xs:pattern value=".+\.ico" />
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
<xs:simpleContent>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:schema>
SoftwareInfo XML elements list

IMPORTANT
This section describes the XML elements defined by the SoftwareInfo XML schema. The following is a list of
these elements in the order in which they are defined in the XML schema.
SoftwareInfo
Package
Identity
Applications
Application
Package
Identity
SoftwareInfo

IMPORTANT
The SoftwareInfo element is the parent element of the SoftwareInfo XML schema.
Usage
<SoftwareInfo>
child elements
</SoftwareInfo>
Attributes
Child elements
DeviceCompanionApplications Specifies the app that will be downloaded when the

operator’s Mobile Broadband hardware is detected on
the PC.
PrivilegedApplications Specifies the app that will be allowed to access privileged

Mobile Broadband interfaces.
Parent elements
XSD
<xs:element name="SoftwareInfo" type="tns:SoftwareInfoType" />
<xs:complexType name="SoftwareInfoType">
<xs:choice>
<xs:sequence>
</xs:sequence>
<xs:element name="PrivilegedApplications" type="tns:PrivilegedApplicationsType" />
</xs:choice>
</xs:complexType>
Remarks
The SoftwareInfo element is required.

IMPORTANT
The DeviceCompanionApplications element specifies the app that will be downloaded when the operator’s
mobile broadband hardware is detected on the PC.
Usage
<DeviceCompanionApplications>
child elements
</DeviceCompanionApplications>
Attributes
Child elements
Package Specifies the package that will be used for the Microsoft
Store device app.
Parent elements
SoftwareInfo The parent element of the SoftwareInfo XML schema.
XSD
<xs:complexType name="DeviceCompanionApplicationsType">
<xs:sequence>
</xs:sequence>
</xs:complexType>
Remarks
When you specify the DeviceCompanionApplications element, the specified app will be downloaded
when Windows detects the operator’s mobile broadband hardware.
The structure for the package Identity and Application element are identical with the application manifest
structure.
For Windows 8, Windows 8.1, and Windows 10, you can specify only one package and one application ID.
The second package or application ID will be ignored if you specify it.
The DeviceCompanionApplications element is optional.
Package (SoftwareInfo)

IMPORTANT
The Package element specifies the app that will be downloaded when the operator’s mobile broadband
hardware is detected on the PC.
Usage
<Package>
child elements
</Package>
Attributes
Child elements
Identity The publisher identify of the app.
Applications The app that will be download when the Mobile

Broadband hardware device is detected.
Parent elements
XSD
<xs:complexType name="PackageType">
<xs:sequence>
</xs:sequence>
</xs:complexType>
Remarks
The Package element is optional.
Identity (SoftwareInfo)

IMPORTANT
The Identity element specifies the publisher identity and application manifest name of the app.
Usage
<Identity Name=”tns:AsciiIdentifierType” Publisher=”tns:DistinguishedNameType” />
Attributes
Name tns:AsciiIdentifierType Yes The name of the app as

specified in the app
manifest file.
Publisher tns:DistinguishedName Yes The publisher identity

Type of the app.
Child elements
Parent elements
DeviceCompanionApplications Specifies the app that will be downloaded when the

the PC.
XSD
<xs:complexType name="IdentityType">
</xs:complexType>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
<xs:pattern value="(CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-9]*)(\.(0|[1-9][0-
9]*))+))=(([^,+="<>#;])+|".*")(, ((CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-
9]*)(\.(0|[1-9][0-9]*))+))=(([^,+="<>#;])+|".*")))*"/>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
Remarks
The Identity element is optional.
Applications

IMPORTANT
The Applications element specifies the apps that are associated with the Mobile Broadband hardware device.
Usage
<Applications>
Child element
</Applications>
Attributes
Child elements
Application Specifies the app that will be downloaded when the

the PC.
Parent elements
Package Specifies the app that will be downloaded when the

the PC.
XSD
<xs:complexType name="ApplicationsType">
<xs:sequence>
</xs:sequence>
</xs:complexType>
Remarks
The Applications element is optional.
Application (SoftwareInfo)

IMPORTANT
The Application element specifies the associated device notification handler.
Usage
<Application Id=”tns:ApplicationIdType”>
Child element
</Application>
Attributes
Id tns:ApplicationIdType Yes The ID of the

application.
Child elements
DeviceNotificationHandlers Specifies a list of device notification handlers.
Parent elements
Applications Specifies the app that will be downloaded when the

the PC.
XSD
<xs:element name="Application" type="tns:ApplicationType"/>
<xs:sequence>
<xs:element name="DeviceNotificationHandlers" type="tns:DeviceNotificationHandlersType" minOccurs="0" />
</xs:sequence>
</xs:complexType>
Remarks
The Application element is optional.

IMPORTANT
The DeviceNotificationHandlers element specifies the device notification handlers.
Usage
<DeviceNotificationHandlers>
Child element
</DeviceNotificationHandlers>
Attributes
Child elements
DeviceNotificationHandler Specifies a device notification handler.
Parent elements
Application Specifies the app that will be downloaded when the

the PC.
XSD
<xs:element name="DeviceNotificationHandlers" type="tns:DeviceNotificationHandlersType" minOccurs="0" />
<xs:complexType name="DeviceNotificationHandlersType">
<xs:sequence>
<xs:element name="DeviceNotificationHandler" type="tns:DeviceNotificationHandlerType"
</xs:sequence>
</xs:complexType>
Remarks
The DeviceNotificationHandlers element is optional.

IMPORTANT
The DeviceNotificationHandler element specifies a device notification handler. A device notification handler
allows you to run code in response to events, such as mobile network operator administrative SMS or USSD
notifications, even if the Microsoft Store app is not running. For more information about implementing a
notification handler, see the Mobile Operator Notifications white paper.
Usage
<DeviceNotificationHandler EventID=”xs:string” EventAsset=”xs:string”/>
Attributes
EventID xs:string Yes The event ID for the

device notification
handler.
EventAsset xs:string Yes The event asset for the

device notification
handler.
Child elements
Parent elements
DeviceNotificationHandlers Specifies the device notification handlers.
XSD
<xs:element name="DeviceNotificationHandler" type="tns:DeviceNotificationHandlerType" maxOccurs="unbounded"
/>
<xs:complexType name="DeviceNotificationHandlerType">
<xs:attribute name="EventID" type="xs:string" use="required"/>
<xs:attribute name="EventAsset" type="xs:string" use="required"/>
</xs:complexType>
Remarks
When you specify the DeviceNotificationHandler in the Application element, the system calls the event
handler and invokes the event when the device changes to the state.
The EventID attribute is the SMSEventHandler for the SMS device case.
The EventAsset attribute is the same value that you specify in the app manifest as an extension of
Windows.BackgroundTasks.
The DeviceNotificationHandler element is optional.

IMPORTANT
The PrivilegedApplications element specifies the app that will be allowed to access privileged Mobile Broadband
interfaces.
Usage
<PrivilegedApplications>
Child elements
</PrivilegedApplications>
Attributes
Child elements
Package The app that should have access to the privileged

Parent elements
XSD
<xs:complexType name="PrivilegedApplicationsType">
<xs:choice>
<xs:element name="AnyApplication" type="tns:AnyApplicationType" />
</xs:choice>
</xs:complexType>
Remarks
The PrivilegedApplications element allows a specified app to access the Mobile Broadband and SMS APIs
with privileged access rights.
The structure for the package Identity is identical with the <Identity> element in the application manifest
structure. You should copy the elements from the application manifest.
To specify multiple packages, list multiple Package elements in the PrivilegedApplications element.
The Package Name, Publisher, and Application ID must match the information in package.appxmanifest
for the Microsoft Store app. The publisher also must match the publisher certificate that is installed on the
PC.
For the Microsoft Store app that is listed under the DeviceCompanionApplications element to have access
to privileged Mobile Broadband interfaces including SMS, that app also must be specified under the
PrivilegedApplications element.
When you are submitting your service metadata package to the Windows Dev Center Dashboard, you
cannot declare more than 2 privileged apps. One of apps must be the app ID for the Microsoft Store
device app that will be automatically downloaded. The second privileged app is not automatically
downloaded, but will access to the privileged Mobile Broadband APIs if the app is installed.
The PrivilegedApplications element is optional.
Package (SoftwareInfo - priviliged applications)

IMPORTANT
The Package element specifies an app that should have access to the privileged Mobile Broadband interfaces.
Usage
<Package>
child element
</Package>
Attributes
Child elements
Identity The publisher identify of the app.
Parent elements
PrivilegedApplications The apps that should have access to the privileged

XSD
<xs:complexType name="PackageForPrivilegedApplications">
<xs:sequence>
</xs:sequence>
</xs:complexType>
Remarks
The Package element is optional.
Identity (SoftwareInfo - priviliged applications)

IMPORTANT
The Identity element specifies the publisher identity and application manifest name of the app.
Usage
<Identity Name=”tns:AsciiIdentifierType” Publisher=”tns:DistinguishedNameType”
AccessCustomDriver=”xs:boolean” />
Attributes
Name tns:AsciiIdentifierType Yes The name of the app as

specified in the app
manifest file.
Publisher tns:DistinguishedName Yes The publisher identity

Type of the app.
AccessCustomDriver xs:boolean No If the app should have

access to a custom
driver, set this value to
true .
Child elements
Parent elements
Package Specifies the app that should have access to the

privileged Mobile Broadband interfaces.
XSD
<xs:complexType name="IdentityForPrivilegedApplicationsType">
<xs:attribute name="AccessCustomDriver" type="xs:boolean" />
</xs:complexType>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
<xs:pattern value="(CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-9]*)(\.(0|[1-9][0-
9]*))+))=(([^,+="<>#;])+|".*")(, ((CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-
9]*)(\.(0|[1-9][0-9]*))+))=(([^,+="<>#;])+|".*")))*"/>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
Remarks
The Identity element is optional.
SoftwareInfo XML Example

IMPORTANT
The following XML document uses the ServiceInfo XML schema to specify the attributes of the Contoso Wireless
service:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<SoftwareInfo xmlns="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/SoftwareInfo">
<Package>
<Identity Name="64022CONTOSO.ContosoDeviceApp" Publisher="CN=05558413-FFF6-4AA5-8176-AD43036533FA" />
<Applications>
<Application Id="DeviceAppForPrinters">
<DeviceNotificationHandler EventID="NotificationHandler" EventAsset="Fabrikam.OperatorApp.
NotificationHandler" />
</Application>
</Applications>
</Package>
<Package>
<Identity Name="64022CONTOSO.ContosoDeviceApp" Publisher="CN=05558413-FFF6-4AA5-8176-AD43036533FA"
AccessCustomDriver="false" />
</Package>
</PrivilegedApplications>
</SoftwareInfo>
WindowsInfo XML schema overview

IMPORTANT
A metadata package contains one WindowsInfo.xml document. This contains information that the operating
system uses to define display actions for the service specified within the metadata package.
The data within the Windowsinfo.xml document is formatted based on the WindowsInfo XML schema, which is
For the complete definition of the WindowsInfo XML schema, see WindowsInfo XML Schema Definition.
For information about the elements that are defined by the WindowsInfo XML schema, see WindowsInfo XML
Elements.
For an example of XML data in the format that is defined by the WindowsInfo XML schema, see WindowsInfo
XML Example.
WindowsInfo XML Schema Definition

IMPORTANT
The following are the namespaces of the WindowsInfo XML schema:
http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/
http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/WindowsInfov2
The following is a definition of the WindowsInfo XML schema:
<xs:schema targetNamespace="http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/"
xmlns:tns="http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/"
xmlns:v2="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/WindowsInfov2"
<xs:element name="WindowsInfo" type="tns:WindowsInfoType" />
<xs:complexType name="WindowsInfoType">
<xs:sequence>
<xs:element name="ShowDeviceInDisconnectedState" type="xs:boolean" default="false" />
<xs:element name="LaunchDeviceStageOnDeviceConnect" type="xs:boolean" default="false" minOccurs="0" />
<xs:element name="LaunchDeviceStageFromExplorer" type="xs:boolean" default="false" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:schema>
The following is a definition of the WindowsInfov2 XML schema:
<xs:schema targetNamespace="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/WindowsInfov2"
xmlns:tns="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/WindowsInfov2"
<xs:element name="LaunchApplicationOnDeviceConnect" type ="tns:LaunchApplicationOnDeviceConnectType" />

<xs:element name="WindowsHardwareLogoCertified" type="tns:WindowsHardwareLogoCertifiedType" />
<xs:element name="EnableAutoPlayForRegisteredApps" type="xs:boolean" default="false" />


<xs:complexType name="LaunchApplicationOnDeviceConnectType">
<xs:choice>
<xs:element name="AutoplayHandler" type="tns:AutoplayHandlerType" />
<xs:element name="DesktopAutoplayHandler" type="xs:string" />
<xs:any namespace="##other" processContents="lax" />
</xs:choice>
</xs:complexType>


<xs:complexType name="AutoplayHandlerType">
<xs:sequence>
<xs:element name="PackageIdentity" type="tns:PackageIdentityType" />
<xs:element name="Verb" type="tns:VerbType" />
<xs:element name="AutoplayType" type="tns:AutoplayTypeType" />
</xs:sequence>
</xs:complexType>


<xs:complexType name="PackageIdentityType">
<xs:attribute name="Name" type="tns:PackageNameType" use="required" />
<xs:attribute name="Publisher" type="tns:PublisherType" use="required" />
</xs:complexType>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
<xs:pattern value="(CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9][0-9]*)(\.(0|[1-9]
[0-9]*))+))=(([^,+="<>#;])+|".*")(, ((CN|L|O|OU|E|C|S|STREET|T|G|I|SN|DC|SERIALNUMBER|(OID\.(0|[1-9]
[0-9]*)(\.(0|[1-9][0-9]*))+))=(([^,+="<>#;])+|".*")))*"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AutoplayTypeType">
<xs:enumeration value="Device" />
<xs:enumeration value="Content" />
</xs:restriction>
</xs:simpleType>


</xs:complexType>
</xs:restriction>
</xs:simpleType>


<xs:simpleType name="VerbType">
<xs:pattern value="[^ ]+"/>
</xs:restriction>
</xs:simpleType>


<xs:complexType name="WindowsHardwareLogoCertifiedType">
</xs:complexType>


</xs:restriction>
</xs:simpleType>
<xs:simpleType name="AsciiWindowsIdType">
<xs:pattern value="([A-Za-z][A-Za-z0-9]*)(\.[A-Za-z][A-Za-z0-9]*)*"/>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
</xs:schema>
WindowsInfo XML elements list

IMPORTANT
This section describes the XML elements defined by the WindowsInfo XML schema. The following is a list of
these elements in the order in which they are defined in the XML schema.
WindowsInfo
AutoplayHandler
PackageIdentity
Application
Verb
AutoplayType
WindowsInfo

IMPORTANT
The WindowsInfo element is the parent element of the WindowsInfo XML schema.
Usage
<WindowsInfo>
child elements
</WindowsInfo>
Attributes
Child elements
ShowDeviceInDisconnectedState This value should be set to false because it does not

apply to service metadata packages in Windows 8,
Windows 8.1, and Windows 10.
LaunchDeviceStageOnDeviceConnect This value should be set to false because it does not

LaunchDeviceStageFromExplorer This value should be set to false because it does not

Parent elements
XSD
<xs:element name="WindowsInfo" type="tns:WindowsInfoType" />
<xs:complexType name="WindowsInfoType">
<xs:sequence>
<xs:element name="LaunchDeviceStageOnDeviceConnect" type="xs:boolean" default="false" minOccurs="0" />
<xs:element name="LaunchDeviceStageFromExplorer" type="xs:boolean" default="false" minOccurs="0" />
<xs:element ref="v2:LaunchApplicationOnDeviceConnect" minOccurs="0" />
<xs:element ref="v2:WindowsHardwareLogoCertified" minOccurs="0" />
</xs:sequence>
</xs:complexType>
Remarks
The WindowsInfo element is required.

IMPORTANT
The ShowDeviceInDisconnectedState element should be set to false because it does not apply to service
metadata packages in Windows 8, Windows 8.1, and Windows 10.
Usage
<ShowDeviceInDisconnectedState>
text
</ShowDeviceInDisconnectedState>
Attributes
Text value
Should be set to false because it does not apply to service metadata packages in Windows 8, Windows 8.1, and
Windows 10.
Child elements
Parent elements
WindowsInfo The parent element of the WindowsInfo XML schema.
XSD
Remarks
The ShowDeviceInDisconnectedState element is required.

IMPORTANT
The LaunchDeviceStageOnDeviceConnect element should be set to false because it does not apply to service
Usage
<LaunchDeviceStageOnDeviceConnect>
text
</LaunchDeviceStageOnDeviceConnect>
Attributes
Text value
Windows 10.
Child elements
Parent elements
XSD
<xs:element name="LaunchDeviceStageOnDeviceConnect" type="xs:boolean" default="false" />
Remarks
The LaunchDeviceStageOnDeviceConnect element is optional.

IMPORTANT
The LaunchDeviceStageFromExplorer element should be set to false because it does not apply to service
Usage
<LaunchDeviceStageFromExplorer>
text
</LaunchDeviceStageFromExplorer>
Attributes
Text value
Windows 10.
Child elements
Parent elements
XSD
<xs:element name="LaunchDeviceStageFromExplorer" type="xs:boolean" default="false" />
Remarks
The LaunchDeviceStageFromExplorer element is optional.

IMPORTANT
The LaunchApplicationOnDeviceConnect element specifies an app that should appear as the recommended
AutoPlay action when a user plugs in the device.
Usage
<LaunchApplicationOnDeviceConnect>
child elements
</LaunchApplicationOnDeviceConnect>
Attributes
Child elements
AutoplayHandler Specifies a UWP device app that should appear as the

recommended AutoPlay action when a user plugs in a
device.
DesktopAutoplayHandler Specifies a desktop app that should appear as the

device.
Parent elements
XSD
<xs:element name="LaunchApplicationOnDeviceConnect" type ="tns:LaunchApplicationOnDeviceConnectType" />
<xs:complexType name="LaunchApplicationOnDeviceConnectType">
<xs:choice>
<xs:any namespace="##other" processContents="lax" />
</xs:choice>
</xs:complexType>
Remarks
You must specify either a UWP device app or a desktop app. Use AutoplayHandler if you will specify a UWP
device app, and use DesktopAutoplayHandler if you specify a desktop application.
The LaunchApplicationOnDeviceConnect element is optional.
AutoplayHandler

IMPORTANT
The AutoplayHandler element specifies a UWP device app that should appear as the recommended AutoPlay
action when a user plugs in a device.
Usage
<AutoplayHandler>
child elements
</AutoplayHandler>
Attributes
Child elements
PackageIdentity Specifies the package identity (name and publisher) for

the app.
Application Specifies the application ID for the app.
Verb Specifies the verb that the app registers.
AutoplayType Specifies whether the AutoPlay event is a device event or

a content event. AutoPlay determines the type of device
and raises either a Device event for non-volume devices,
or a Content event for volume devices.
EnableAutoPlayForRegisteredApps Specifies whether AutoPlay is enabled for registered

apps.
Parent elements
LaunchApplicationOnDeviceConnect Specifies an app that should appear as the

recommended AutoPlay action when a user plugs in the
device.
XSD
<xs:complexType name="AutoplayHandlerType">
<xs:sequence>
<xs:element name="EnableAutoPlayForRegisteredApps" type ="xs:boolean" default="false" minOccurs="0" />
</xs:sequence>
</xs:complexType>
Remarks
The structure for the PackageIdentity and Application elements are identical with the Application Manifest
structure, so copy the elements from the application's manifest.
In addition to including the AutoplayHandler element in the device metadata, the specified UWP device
app must also register for the AutoPlay event by adding a Declaration in its application manifest for the
event. AutoPlay recognizes the declaration for the app and then includes it in the list of possible actions
that a user can take to respond to that event.
Only the package listed in the DeviceCompanionApplications value in the SoftwareInfo.xml file will be
downloaded as part of the device installation. If the LaunchApplicationOnDeviceConnect element value is
from a different package, Windows does not know whether it will actually be on the user’s device. If the
recommended application is not on the user’s device, users will not be presented with the choice.
Even if the application is the same as the DeviceCompanionApplications entry, it may not always appear
in the AutoPlay list. If the user is not connected to the Internet or otherwise fails to download the
companion application, it will not appear in the list. However, when the user gets the application, they will
be presented with a “New Option Available” AutoPlay dialog box the next time they connect their device.
The AutoplayHandler element is optional.
PackageIdentity

IMPORTANT
The PackageIdentity element specifies a UWP device app that should appear as the recommended AutoPlay
action when a user plugs in a device.
Usage
<PackageIdentity Name=”tns:PackageNameType” Publisher=”tns:PublisherType” />
Attributes
Name tns:PackageNameType Yes Copy this element from

the Name attribute of
the app manifest's
Identity element,
described in Remarks.
Publisher tns:PublisherType Yes Copy this element from

the Publisher attribute
of the app manifest's
Identity element,
described in Remarks.
Child elements
Parent elements

device.
XSD
<xs:complexType name="PackageIdentityType">
<xs:attribute name="Name" type="tns:PackageNameType" use="required" />
<xs:attribute name="Publisher" type="tns:PublisherType" use="required" />
</xs:complexType>
</xs:restriction>
</xs:simpleType>
</xs:restriction>
</xs:simpleType>
Remarks
Copy the Name and Publisher attributes from the application manifest's <Identity> element after the app has
been associated with the Microsoft Store, because the process of associating your app will update the app
manifest.
Here is an example of how the <Identity> element may look inside an app manifest.
<Identity Name="64022FABRIKAM.FabrikamDeviceApp" Publisher="CN=05558413-FFF6-4AA5-8176-AD43036533FA"

Version="1.0.0.0" />
The PackageIdentity element is optional.

Application (WindowsInfo)

IMPORTANT
The Application element specifies the application ID for the app.
Usage
<Application Id=”tns:ApplicationIdType” />
Attributes
Id tns:ApplicationIdType Yes The application ID.

Copy this value from
the app manifest, as
described in Remarks..
Child elements
Parent elements

device.
XSD
</xs:complexType>
</xs:restriction>
</xs:simpleType>
Remarks
The structure for the Application element correspond to the structure of the <Application> element in an app
manifest. Copy the value of the Id value from the Id attribute in the app manifest.
Here is an example of how the <Applications> element may be structured inside an app manifest:
<Applications>
<Application Id="DeviceAppForPrinters" Executable="$targetnametoken$.exe"
EntryPoint="DeviceAppForPrinters.App">
</Application>
</Applications>
The Application element is optional.

Verb

IMPORTANT
The Verb element specifies the Verb that the application registers.
Usage
<Verb />
Attributes
Child elements
Parent elements

device.
XSD
<xs:simpleType name="VerbType">
<xs:pattern value="[^ ]+"/>
</xs:restriction>
</xs:simpleType>
Remarks
The Verb element is optional.
AutoplayType

IMPORTANT
The AutoplayType element specifies whether the AutoPlay event is a device event or a content event. AutoPlay
determines the type of device and raises either a Device event for non-volume devices, or a Content event for
volume devices.
Usage
<AutoplayType>
type
</AutoplayType>
Attributes
Text value
A string that has either the value "Device" or the value "Content".
Child elements
Parent elements

device.
XSD
<xs:simpleType name="AutoplayTypeType">
<xs:enumeration value="Device" />
<xs:enumeration value="Content" />
</xs:restriction>
</xs:simpleType>
Remarks
The AutoplayType element is optional.

IMPORTANT
The EnableAutoPlayForRegisteredApps element specifies whether AutoPlay is enabled for registered apps.
Usage
<EnableAutoPlayForRegisteredApps>
text
</EnableAutoPlayForRegisteredApps>
Attributes
Text value
A Boolean value of either “true” or “false”.
Child elements
Parent elements
XSD
<xs:element name="EnableAutoPlayForRegisteredApps" type ="xs:boolean" default="false"/>
Remarks
This element is only applicable on Windows 8.1 and Windows 10.
The EnableAutoPlayForRegisteredApps element is optional.

IMPORTANT
The DesktopAutoplayHandler element specifies a desktop app that should appear as the recommended
AutoPlay action when the device is connected and no default action is set. The AutoPlay event is raised
whenever a user plugs in a device.
Usage
<DesktopAutoplayHandler>
text
</DesktopAutoplayHandler>
Attributes
Text value
String indicating the desktop app that handles the AutoPlay event.
Child elements
Parent elements
XSD
Remarks
You specify the desktop AutoPlay Handler string in the DesktopAutoplayHandler element when you set the
desktop app. You can retrieve the string from the handler subkey name that is registered under the following
registry key:
HKLM\Software\Microsoft\Windows\CurrentVersion\Explorer\AutoplayHandlers\Handlers
The DesktopAutoplayHandler element is optional.

WindowsInfo XML Example

IMPORTANT
The following XML document uses the WindowsInfo XML schema to specify the display actions for the service
that is specified within a metadata package:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<WindowsInfo xmlns="http://schemas.microsoft.com/windows/DeviceMetadata/WindowsInfo/2007/11/"
xmlns:v2="http://schemas.microsoft.com/windows/2010/08/DeviceMetadata/WindowsInfov2">
<ShowDeviceInDisconnectedState>false</ShowDeviceInDisconnectedState>
</WindowsInfo>
Using mbidgenerator.exe to generate hardware IDs

IMPORTANT
To generate hardware ID values for your service metadata package, you can use the MBIDGenerator.exe
command-line tool, which is part of the SDK in Windows 8.1 and Windows 10.
Note In Windows 8 MBIDGenerator.exe was included in the WDK.
Input
MBIDGenerator.exe accepts the following parameters:
MBIDGenerator.exe [/Test] <input file> [<output file>]
Note The Test parameter provides non-hashed output and should not be used for generating hardware IDs for
submission to the Windows Dev Center Dashboard.
Output
The output from the MBIDGenerator.exe is through a standard command-line output display. Optionally, you can
specify a path and file name for the output file. Errors are always reported back to the command prompt.
The output values appear in the following way:
<HardwareIDList>
<HardwareID>MBAE:0:hashednumber1</HardwareID>
</HardwareIDList>
You can take the output from MBIDGenerator.exe and insert it into the PackageInfo XML schema of your service
metadata package.
Mobile Plans overview
Purpose
Mobile Plans is an application in Windows 10 that helps end users to connect their Windows device to cellular
networks through mobile operators. The purpose of Mobile Plans is to:
Provide a consistent and simplified user experience for activation of cellular-enabled PCs.
Enable a new channel for cellular activation through adoption of eSIM
Increase adoption of cellular services on Windows PCs through a direct relationship between customers and
mobile operators
Mobile Plans is supported in Windows 10, version 1803 and later.
Customer journey
The typical Mobile Plans customer journey is composed of the following steps:
ST EP DESC RIP T IO N
Discovery The user sees one of several entry points in the Windows UI
and launches the Mobile Plans app. There are multiple entry
points available in the Windows Shell that are tailored to
various scenarios.
Browse & Welcome After the Mobile Plans app launches, the user chooses their
mobile operator and sees the operator Gateway page. The
Gateway page invokes the mobile operator web portal which
hosts the next step. Note that some entry points take the
user directly to the operator Gateway page.
Activation & Checkout The mobile operator web portal walks the user through sign
in, activation and checkout
Fulfillment Upon completion of the activation step, the user will be

provisioned for data. This step could include download and
activation of an eSIM profile.
Usage The user enjoys the benefits of an always connected PC, and
is able to see available balance directly in the Windows UI.
They can easily return to the mobile operator web portal to
manage their account and purchase additional data as
needed.
User experience
The following sections illustrate the Mobile Plans user experience.
Launching the app
The Mobile Plans app can be launched from a number of different entry points. The most common entry point is
the network flyout, as this is where users typically manage their active network interfaces in Windows 10. The
cellular interface can be expanded to show status of the cellular network. In the example below, the device has
no SIM profile activated, so the user sees a call to action to “Connect with a data plan.” Selecting this link will
launch the Mobile Plans app.
See the Mobile Plans account management topic for more details on behavior of the network flyout.
The app can also be launched from a toast notification. Selecting the “Get connected” button will launch the
Mobile Plans app.
See the Mobile Plans toast notifications topic for more details on the behavior of toast notifications.
The Mobile Plans app can also be launched from the Settings app, or from the Start menu.
Select provider page
Once the app has launched, the user has the option to choose their mobile operator. The app displays a list of
available mobile operators based on the user’s current location.
See the Mobile Plans operator catalog topic for more information on this page.
Mobile operator gateway page

If the user has chosen a mobile operator, the app shows that operator’s gateway page. This page is hosted by the
Mobile Plans app. The user can select the button to continue.
See the Mobile Plans gateway page topic for more details on the behavior and customization of the Gateway
page.
Once the user has selected the button to continue, the app will load the mobile operator’s web portal. The web
content is displayed in a browser control hosted by the app, and the user can use web navigation to browse the
portal.
See the mobile operator web portal topic for an in-depth description of the mobile operator web portal.
Fulfillment
After completing the signup flow on the web portal, the mobile operator can trigger fulfillment based upon the
type of signup. This could include download and installation of a new eSIM profile, or it could be the addition of
new balance to an active account. Once the fulfillment step is complete, the web portal can invoke a popup to let
the user know the process is complete.
See the Mobile Plans callback notifications topic for more information on this step.
Mobile Plans system architecture
This page provides an overview of the major components of the Mobile Plans system architecture. Together,
these comprise the Mobile Plans program. Not every mobile operator deployment will require every
component listed here.
The Mobile Plans system architecture made up of the following 5 major components:
Mobile Plans App
This is the Universal Windows Platform (UWP) app that is preinstalled by Microsoft on all cellular-enabled
Windows 10 devices. The Mobile Plans app is the primary client environment running on the user's device for
hosting the end user experience. The Mobile Plans app can also run in the background to trigger certain events
(e.g. showing a toast notification).
Mobile Plans Service
The Mobile Plans service is the cloud-based service layer which provides data to the Mobile Plans app. It also
provides an authenticated interface to the Mobile Operator API.
Mobile Operator Web Portal
This is the web-based runtime environment hosted by the mobile operator. The mobile operator web portal is
experienced by the user via web navigation, and is rendered in situ within the Mobile Plans app.
Mobile Operator API
This is the programmatic interface hosted by the mobile operator for exposing user data to the Mobile Plans,
which can be fetched at runtime to update content presented to the user. An example of user data fetched at
runtime would be a user's prepaid balance.
Mobile Operator SM -DP+
This is the service responsible for creation and delivery of a mobile operator's eSIM profile to the Windows 10
device.
Functional overview
The following diagram shows a high-level overview of how the components described above are used in a
typical flow to successfully activate a subscription and install an eSIM profile. Note that other flows are possible
as well.
1. The Mobile Plans app is launched on the Windows 10 device, and retrieves basic functional data from the
Mobile Plans service.
2. The Mobile Plans app invokes the mobile operator web portal, and passes relevant parameters which can be
used by the portal to determine which user experience to present.
3. Upon completion of the activation flow within the mobile operator web portal, the mobile operator requests
an eSIM profile from the SM-DP+ server. The corresponding eSIM activation code is returned to the mobile
operator web portal.
4. The mobile operator web portal returns the eSIM profile activation code to the Mobile Plans app.
5. The Mobile Plans app passes the activation code to the Windows LPA, which contacts the SM-DP+ server to
retrieve the eSIM profile.
6. The eSIM profile is downloaded and installed to the Windows 10 device eSIM, and is activated. Upon
activation, the Windows 10 device registers on the mobile operator network.
7. The user opens the Windows network flyout, which invokes a request to the Mobile Plans service to fetch the
available balance.
8. The Mobile Plans service makes a Get Balance request to the Mobile Operator API, which returns the
available balance to be displayed to the user.
Mobile Plans scenarios
Overview
This topic provides guidance about most common scenarios that mobile operators will enable with Mobile
Plans. Note that this is not an exhaustive list of supported scenarios. It is probable that your specific use case
could be achieved via a combination of solutions. Please speak with your Microsoft contact to discuss your
requirements further.
Install an eSIM profile on a Windows 10 device

This section describes the steps a mobile operator should take to download, install and activate an eSIM profile
on a Windows 10 device. Depending upon constrainsts of the mobile operator's eSIM platform and network
backend, there are multiple methods used to fulfill the profile and network connectivity at the conclusion of the
activation flow.
1. Develop the mobile operator web portal that will take the user through the sign in and activation steps.
2. Implement one of the supported callback methods to return control back to the Mobile Plans app for
download of the eSIM profile:
a. Inline profile download and connectivity - This callback method should be used when the profile is
already available to be released by the SM-DP+ server, AND the profile will enable the device to
register on the cellular network immediately upon profile activation. This method enables profile
delivery and network connection as part of the same end user flow.
b. Asynchronous connectivity. This callback method should be used when the eSIM profile is already
available for release by the SM-DP+ server, however the device needs to wait some time before
attempting to register on the cellular network.
c. Delayed profile download. This callback method should be used when the profile is not available to be
released by the SM-DP+ server, and can only be downloaded after a period of time. It is expected that
the device will be able to register on the cellular network once the profile is downloaded and installed.
3. Ensure proper handling of profile download errors.
4. Implement the basic account management experience for users to manage and maintain their account.
Activate a warm SIM in a Windows device

This section describes the steps to allow users to activate a warm phsycial SIM in a Windows device. The term
'warm' refers to a SIM which has been preactivated and can connect to the mobile operator network, but has
not been associated with an active subscription.
1. Implement the mobile operator web portal that will walk the user through the sign in and activation steps.
2. Implement the callback method for adding balance.
3. Implement the enhanced account management experience.
a. Implement the GetBalance method as part of the mobile operator API.
b. Implement the Walled Garden so users can navigate to the mobile operator web portal even if they
don't have an active balance.
Add balance to a current subscription

This section describes the steps invovled in adding balance for an existing customer subscription. This is useful
when a mobile operator is selling prepaid data plans that must be topped off when the balance runs out.
1. Develop the mobile operator web portal.
2. Implement the callback method for adding balance.
3. Implement the enhanced account management experience.
a. Implement the GetBalance method as part of the mobile operator API, allowing the user's balance to
be shown in the Windows network flyout.
b. Implement the Walled Garden so users can navigate to the mobile operator web portal even if they
don't have balance remaining.
Cancelling a transaction
This section describes the callback method used to notify the Mobile Plans app when a transaction is cancelled
while the user is browsing the mobile operator web portal. This applies to all the previous scenarios in this topic.
Implement the callback method for canceling purchase flow.
Mobile Plans operator catalog
Overview
The Mobile Plans app enables users to see and choose from a list of mobile operators. This article defines the
principles applied in the display of mobile operators on the Select Providers page.
NOTE
The Select Providers page is only available on eSIM-enabled Windows 10 PCs. Since legacy physical UICCs do not allow
the mobile operator's SIM profile to be changed, the Select Provider page is not available when there is no active eSIM on
the device.
List of mobile operators

Users have the ability to see the list of mobile operators which are enabled in Mobile Plans to sell data plans
in a given country.
The physical location of the device is used to determine the country. When the device is connected via
cellular, the network ID is used to determine the country. If the device is connected via Wi-Fi, the country is
determined by reverse IP.
The list of mobile operators that is shown to users is shorted alphabetically by the mobile operator's brand
name.
Mobile operator branding

Mobile operators shown in the catalog must use the brand name and marks that are commonly associated
with their cellular services in the countries where they operate. This is so that users have a clear
understanding of who the service provider is.
Mobile operator brand names which include brand elements associated with a Windows PC OEM will be
shown to those OEM devices only. This is to prevent showing an OEM brand element to a user on a different
OEM device. The mobile operator or OEM must supply the make and model of the devices (as found in the
Windows System Info dialog) on which their OEM-branded mobile operator will be made available.
Device filtering
If a device (including the modem and/or eSIM hardware or firwmare) is found to be incompatible with a
mobile operator's nework, the mobile operator can request to be filtered from the list of mobile operators
shown on that device. This is to prevent an end user from attempting to acquire a data plan from an operator
which cannot be used on their device. The make and model of the device (as found in the Windows System
Info dialog), or the eID of the eSIM, must be supplied by the mobile operator to enable the filtering.
Mobile Plans gateway page
Overview
The Mobile Plans app hosts a Gateway page for every mobile operator enabled in the catalog. The Gateway
page is shown to the end user as part of the Welcome step. It contains basic brand elements for the mobile
operator, as well as several links and a privacy disclaimer. The Gateway page also includes a button to invoke the
mobile operator web portal.
Enhanced Gateway page

This is an optional feature supported in Mobile Plans app version 5.1902.331.0 or above.
The Gateway page can be customized by the mobile operator by specifying the content and style of the page.
This ensures they can highlight their offerings and unique brand value.
Enhanced Gateway page content
The enhanced Gateway page is specified using a template with predefined elements. The highlighted elements
are definable by the mobile operator.
Enhanced Gateway page templates
Custom content shown on the enhanced Gateway page is defined using a JSON file with the following elements:
{ // Root object
"promotionTemplates": [
{ // PromotionTemplate
"id": 0,
"backgroundColor": "0x000000FF", // Black
"bodyFontColor": "0xFFFFFFFF", // White
"bodyText": "Stay connected from virtually anywhere.",
"buttonColor": "0x00B0F0FF", // Light Blue
"buttonFontColor": "0xFFFFFFFF", // White
"buttonText": "Get started",
"hyperlinkFontColor": "0x00B0F0FF", //Light Blue
"images": [
{ // Image
"uri": "https://picsum.photos/id/1/740/480",
"width": 740,
"height": 480,
}
]
}
]
}
The following table describes each JSON element in the previous example.
JSO N EL EM EN T F IEL D N A M E DESC RIP T IO N EXA M P L E
Root object promotionTemplates List of templates to be used N/A

for the enhanced Gateway
page. One or more
templates can be defined
for each mobile operator.
PromotionTemplate id Unique string identifier for 123

each template. The default
value when only one
template is defined should
be "0"
backgroundColor Color of the Gateway page 0x000000FF

background. This field is a
hexadecimal string in the
format of 0xRRGGBBAA . If
undefined, white is used as
the default.
bodyFontColor Color for the body text. This 0xFFFFFFFF

is a hexadecimal string in
the format of 0xRRGGBBAA .
If undefined, black is used
as the default.
bodyText The localized body text for Stay connected from

the client's language. Note virtually anywhere.
that the Disclaimer text
cannot be changed.
buttonColor Color of the "Continue" 0x00B0F0FF

button that launches the
mobile operator web portal.
This field is a hexadecimal
string in the format of
0xRRGGBBAA . If undefined,
the user-selected system
highlight color is used as
the default.
buttonFontColor Color for the text on the 0xFFFFFFFF

"Continue" button. This field
is a hexadecimal string in
the format of 0xRRGGBBAA .
If undefined, white is used
as the default.
buttonText The localized text for the Get started

"Continue" button.
JSO N EL EM EN T F IEL D N A M E DESC RIP T IO N EXA M P L E
hyperlinkFontColor Color of the hyperlinks. This 0x00B0F0FF

field is a hexadecimal string
in the format of
0xRRGGBBAA . If undefined,
the user-selected system
highlight color is used as
the default.
images Images to use for the https://picsum.photos/id/1/

template. Different sizes are 740/480
supported. If multiple sizes
are included, the Mobile
Plans app uses the
optimum size for the screen
resolution. Maximum image
size is 1200 x 600 pixels, file
format png.
Sample enhanced Gateway page
Using multiple Gateway page templates

Mobile operators have the option to define more than one Gateway page template. If this is done, the Mobile
Plans service will call the Mobile Operator API at runtime to request an ID for the template which should be
shown to the user.
Since the request includes identifiers for the profile and device, the mobile operator can define multiple
templates for different user segments. This could be used for A/B testing, or for showing one template to new
users inviting them to signup, and a different template for returning users purchasing additional balance.
Gateway page templates can also be combined with Mobile Plans notifications to create highly targeted
campgains.
NOTE
If the device does not have an active profile for the mobile operator, the request will not be made and the template ID "0"
will be used by default.
The Get Offers request returns the template ID to be shown to the user.
GetOffers API specification

The GetOffers API is called prior to showing the mobile operator Gateway page. The Mobile Plans service is a
proxy for this request.
GET https://{offerUri}sims/{simmri}/offers?limit=1&imei=1234
{offerUri} is the OfferUri value onboarded as part of the mobile operator's service configuration.
The endpoint has two query parameters:
limit, which is required and specifies the number of offers to return.
imei, which is optional and specifies the client’s IMEI.
The response is a JSON object with a single property named offers that contains a list of offers. The number of
offers in this list is at most limit from the request. Each offer in this list is an object with a single property
gatewayId, which must identify an existing gateway in the mobile operator’s service configuration.
The following is an example interaction using this endpoint:
GET https://moendpoint.com/v1/sims/iccid:8988247000100003319/offers?limit=1&imei=1234
X-MS-DM-TransactionId: "MSFT-12345678-1234-1234-1234-123456789abc"
HTTP/1.1 200 OK
Content-type: application/json
{
"offers" : [
{
"gatewayId": "0"
}
]
}
Standard Gateway page

The standard Gateway page is shown to the end when there is no enhanced Gateway page defined. The
standard Gateway page can also be shown as a downgraded experiend when there is a problem loading content
for a mobile operator's enhanced Gateway page.
The standard Gateway page uses a basic template which cannot be customized by the mobile operator.
Overview
This topic describes the web portal that enables mobile operators to provide connectivity solutions directly to
Windows users through a curated web experience hosted in the Mobile Plans app. Mobile operators must create
their web experiences following these design principles to ensure users have a high quality experience while
navigating their portal. The mobile operator web portal is used for all scenarios supported in the Mobile Plans
solution and is hence one of the most important components in the program.
For more information about web portal flow and reference design, see Web portal flow and reference design.
Web Portal interface for eSIM-enabled devices

The Mobile Plans app uses the WebView control to host and present the mobile operator web portal experience.
The portal is invoked by the app calling the mobile operator-hosted service endpoints directly, and returned
content is rendered directly within the control
When starting the WebView , several parameters are passed to the portal as part of the invocation. If there is at
least one eSIM profile associated with the mobile operator, the iccids are passed to the portal as well.
The following example shows these launch parameters for eSIM-enabled devices, embedded in the call to
MyWebView.Navigate() .
MyWebView.ScriptNotify += MyWebView_ScriptNotify;
List<Uri> allowedUris = new List<Uri>();
allowedUris.AddRange(AllowedNotifyUris);
MyWebView.AllowedScriptNotifyUris = allowedUris;
MyWebView.Navigate(“https://moportal.com?
market=US&location=US&transactionId=%2F7RBTuSJt02OZbX8.4&eid=89033023422130000000000199055797&imei=001102000
315468&iccids=8988247000101867183,8988247000103824828”);
In order to provide backwards compatibility with app updates, the portal must disregard any additional
parameters that might also be passed in the requst. This ensures flexibility and ability to introduce new features
in the app without disrupting the mobile operator's integration.
The following table describes the launch parameters available for eSIM.
PA RA M ET ER N A M E DESC RIP T IO N EXA M P L E
eid The eSIM Identifier. This is sent only if eid=

an eSIM is present. 89033024010400000100000000009136
iccids Optional parameter. Specifies the list of iccids=8988247000100003319,

ICCIDs from the available profile on an 988247000100003555
eSIM only. If there are no ICCIDs
matching the MO available on the
eSIM, this parameter is not sent.
imei The device's IMEI number. imei=001201234567890
location The user’s current physical location location=us

with country-level granularity.
transactionId The Transaction ID used for debugging transactionId=waoigFfX00yGH3Vb.1

the session. Providers should log this
and send it in the notification payload.
Maximum size is 64 characters.
market The two-letter ISO code of the region market=us

settings in the PC.
The user’s language preference is sent using the Accept-Language header, described in the following table.
H EA DER N A M E DESC RIP T IO N EXA M P L E
Accept-Language The user’s current language settings. Accept-Language: en-us

The MO portal should render the
contents in the specified language if
possible. For more information, see
RFC 7231, section 5.3.5: Accept-
Language.
Web Portal interface for physical SIMs

The interface for invoking the mobile operator portal using legacy physical UICC is the same as for eSIM.
However, the parameters passed to the portal are different.
MyWebView.Navigate(“https://moportal.com?
iccid=8988247000100003319&imei=001102000311608&market=us&transactionId=waoigFfX00yGH3Vb.1&location=us”);
The following table describes the launch parameters available for a physical SIM.
iccid Required parameter for a physical SIM. iccid=8988247000100003319

Specifies the ICCID on the physical sim.
imei The device's IMEI number. imei=001201234567890
location The user’s current physical location location=us

with country-level granularity.
transactionId The Transaction ID used for debugging transactionId=waoigFfX00yGH3Vb.1

the session. Providers should log this
and send it in the notification payload.
Maximum size is 64 characters.
market The two-letter ISO code of the region market=us

settings in the PC.
The user’s language preference is sent using the Accept-Language header, described in the following table.
Accept-Language The user’s current language settings. Accept-Language: en-us

The MO portal should render the
contents in the specified language if
possible. For more information, see
RFC 7231, section 5.3.5: Accept-
Language.
Web portal design policies

To ensure the best user experience on Windows, mobile operators are encouraged to follow the policies and
guidelines in this section when developing their web portal.
Business functions
P O L IC Y REQ UIRED O R REC O M M EN DED
The web portal experience must meet all applicable legal and Required
regulatory requirements in the countries offered. Any
content displayed in the web portal must comply with all
applicable laws.
Products offered through the web portal experience must be Required

an offer for network connectivity.
Network connectivity products offered through the web Required

portal experience must include clear descriptions of the
offering and terms. Any specific terms of service must be
available for users to review from within the web portal
experience.
Customer support contact information must be accessible to Required

users from within the web portal experience.
The mobile operator's privacy policy must be available for Required

users to review from within the web portal experience.
The account management experience provided by the Required

mobile operator must enable users to take actions on their
current data plans, such as canceling a subscription.
Users must receive an order confirmation after successfully Recommended

completing a plan purchase or activation from within the
web portal experience.
Security
The web portal experience must not deliver or install any 3rd Required
party-owned or branded apps or modules.
Before users exit the mobile operator’s web portal Required

experience, users must be securely logged out from the web
portal.
The portal URI and all requests or notifications sent to and Required
from the web portal must use the secure HTTPS protocol.
All web portal resources and references must use the secure Required
HTTPS protocol.
Advertising
The web portal must not display, or make available for Required
download, any advertisements, sponsored content, videos,
sound files, animations, or otherwise large media files or
images.
Capabilities
The required minimum functionality for the web portal Required

experience is to enable a user to purchase a data plan using
an account registered with the mobile operator.
The web portal must start up promptly and remain Required

responsive to user input until the user exits the web portal
experience.
Once invoked, the web portal must have and retain user Required
focus until either:
The activation flow has completed and the focus has
been returned by the web portal back to the Mobile
Plans app,
OR
The user has cancelled the flow and returned to the
Mobile Plans app.
The web portal must not display any pop-up windows, open Required
any additional windows, or redirect the user to any other
websites or apps, except as required to complete the
activation flow.
The web portal must handle all legitimate errors and Required
exceptions, such as rejection of payment method, backend
failure, etc. After the error or exception is handled, the web
portal must remain responsive for users to exit and return to
the Mobile Plans app.
If users run into an error that can be fixed with user actions, Recommended
it is recommended to display mobile operator customer
support information with the error message.
Usability
The default frame size for the web portal is 800x600. Mobile Required
operators should adopt responsive web design so that
content on their web portal can be auto-adjusted to fit into
the web control frame when users resize the Mobile Plans
app for larger and smaller screens.
Load times and data consumption for loading the web Required
portal experience should be optimized.
The web portal experience should be simple and easy Required

navigate with necessary on-screen guidelines.
User interface elements on the web portal should provide a Required

cohesive experience integrated with the Mobile Plans app,
not confusing users or reminding the users that this is an
embedded web control. For example, there should be no
close/max/min button within the web portal.
Layout of pages within the web portal should be clean and Required
easy to navigate. Users can navigate backward and forward
through pages in the web portal with UI elements within the
portal experience. For more information, see Web portal flow
and reference design.
The web portal must be functional within the WebView Required

Control frame and, once invoked, it must not interfere with
users’ interaction with the Mobile Plans app at any time.
The web portal must not be cluttered with too many images, Required
banners, lengthy text, external links, etc.
An on-screen cancel button within the web experience Recommended

should be available for users to exit the flow when applicable.
Mobile operators can choose the color scheme and fonts Recommended
that best represent their brand. Care should be taken to
ensure all visual elements work well together and reinforce
the brand.
Localization
The web portal should be able to receive and understand Required

users’ locale setting passed by the Mobile Plans app to
display content in the user's preferred language.
Mobile operators may localize their web portal in the Recommended

languages they wish to support.
The experience provided by the web portal should be Recommended

reasonably similar in all languages that it supports, although
data plan availability may vary from region to region.
Accessibility
The web portal should provide accessibility to disabled users Recommended

and adhere to the accessibility guidelines applicable in the
jurisdictions where the mobile operator provides service.
Mobile Plans callback notifications
Overview
Once a user finishes the activation flow in the mobile operator web portal, the portal must provide a signal to let
the Mobile Plans app know that the flow has completed. This is done by issuing a notification to the app that
includes the result of the user interaction with the web portal.
Transactions that the web portal supports include, but are not limited to, the following:
Issuing a new eSIM profile (using an activation code).
Associating the device with a new or existing subscription.
Purchasing a new data plan (either postpaid or prepaid).
Purchasing additional data for to an prepaid plan.
Canceling a subscription.
NOTE
The callback notification must be returned from the host defined in the mobile operator's Service configuration.
Inline profile download and connectivity

The callback method should be used when performing an eSIM profile download in the background while
keeping the user in the mobile operator web portal. This enables the portal to show additional content, such as
an account management page, after the profile download is completed. Additionally, it is expected that the
profile will enable the device to register on the cellular network immediately upon activation, with no time delay
required.
The following diagram shows the call flow for an inline profile download callback:
This is a revised version of the legacy Inline profile delivery callback, which can be found in the Appendix for
documentation purposes. It is recommended that mobile operators use the revised callback method above.
MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData, activationCode )
PA RA M ET ER N A M E TYPE DESC RIP T IO N
purchaseMetadata Object This object contains metadata about

the user's purchase. This includes
details about the user account, the
purchase method or instrument,
details if the user is adding a new line,
and the name of the plan that the user
purchased. These are used for business
reporting.
activationCode String The activation code to be used to

download an eSIM profile
RET URN VA L UE T Y P E DESC RIP T IO N
MobilePlansOperationContext An object with identifiers to which match to this unique

download operation.
The eSIM profile download will begin upon receipt of the callback notificaiton. Control is returned to the web
portal immediately after the call. UI will be displayed to show the profile download progress as popup element
rendered on top of the web portal. The web portal can continue to be navigated during this process.
The following Javascript function shows an example of the API to inform the application that a profile download
should begin:
var purchaseMetaData = MobilePlans.createPurchaseMetaData();
purchaseMetaData.userAccount = MobilePlansUserAccount.new;
purchaseMetaData.purchaseInstrument = MobilePlansPurchaseInstrument.new;
purchaseMetaData.lineType = MobilePlansLineType.new;
purchaseMetaData.modirectStatus = MobilePlansMoDirectStatus.complete;
purchaseMetaData.planName = "My Plan";
MobilePlansInlineOperations.registrationChangedScript = "onRegistrationChanged";
MobilePlansInlineOperations.profileActivationCompleteScript = "onActivationComplete";
MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData , "1$smdp.address$matchingID");
See purchase metadata properties for details about the puchaseMetadata object.
Listening for network registration changes
To listen for network registration changes, the MobilePlansInlineProfileDownload.registrationChangedScript
must be set to a string that is the name of a Javascript function that takes a string for the registrationArgs .
The registration args are a string that represents a JSON object.
ProfileRegistrationCompleteArgs
P RO P ERT Y N A M E TYPE DESC RIP T IO N
networkRegistrationState String A string representing the current

network registration state. The values
of this property can be seen in
MobilePlansNetworkRegistrationState
.
iccid String The ICCID for which the network

registration state has changed.
MobilePlansNetworkRegistrationState
none String No connectivity.
deregistered String The device is not registered and is not

searching for a network provider.
searching String The device is not registered and is

searching for a network provider.
home String The device is on a home network

provider.
roaming String The device is on a roaming network

provider.
partner String The device is on a roaming partner

network provider.
denied String The device was denied registration.
The following Javascript example shows how to implement a listener for network registration changed events.
function onRegistrationChanged(registrationArgs) {
var registrationObj = JSON.parse(registrationArgs);
if(registrationObj.networkRegistrationState == MobilePlansNetworkRegistrationState.home ||
registrationObj.networkRegistrationState == MobilePlansNetworkRegistrationState.roaming ||
registrationObj.networkRegistrationState == MobilePlansNetworkRegistrationState.partner)
{
Log('Registration Successful!');
}
}
Listening for profile activation

To listen for profile activation events, the MobilePlansInlineProfileDownload.profileActivationCompleteScript
must be set to a string that is the name of a Javascript function that takes a string for the activationArgs .
The activationArgs is a string that represents a JSON object.
ProfileActivationCompleteArgs
activationResult String The result of the activation. The values

of this property can be seen in
MobilePlansActivationError .
iccid String The ICCID of the profile that was

activated.
MobilePlansActivationError
success String Indicates that an operation was

successful.
notAuthorized String Indicates that the operation was not

authorized.
notFound String Indicates that the specified eSIM

profile was not found.
policyViolation String Indicates that the operation violates

policy.
insufficientSpaceOnCard String Indicates that there is not enough

storage space on the card to complete
the operation.
serverFailure String Indicates that a server failure occurred

during the operation.
serverNotReachable String Indicates that the server could not be

reached during the operation.
timeoutWaitingForUserConsent String Indicates that user consent was not

granted within the timeout period of
the operation.
incorrectConfirmationCode String Indicates that the wrong confirmation

code was supplied during the
operation.
confirmationCodeMaxRetriesExceeded String Indicates that the wrong confirmation

code was supplied during the
operation, and that no more retries are
permitted.
cardRemoved String Indicates that the SIM card has been

removed.
cardBusy String Indicates that the SIM card is busy.
other String Indicates a status that is not

accounted for by a more specific
status.
cardGeneralFailure String Indicates that a card error occurred

that prevented the download, install,
or other operation from completing
successfully.
confirmationCodeMissing String Indicates that a confirmation code is

needed to download the eSIM profile.
invalidMatchingId String Indicates that the matching ID from

the activation code or discovered
event was refused.
noEligibleProfileForThisDevice String Indicates that an eSIM profile

compatible with this device could not
be found. For example, a profile was
found that requires LTE support, but
the device only supports 3G.
operationAborted String Indicates that the operation aborted.
eidMismatch String Indicates that an eSIM profile on the

mobile operator server is already
allocated for a different eSIM EID than
the one the device has.
profileNotAvailableForNewBinding String Indicates that the user is trying to

download an eSIM profile that has
already been claimed or downloaded.
profileNotReleasedByOperator String Indicates that the eSIM profile is

available, but it is not yet marked as
released for download by the mobile
operator. Only released profiles can be
downloaded, so the MO needs to
mark the profile as released.
operationProhibitedByProfileClass String Indicates that the operation is not

allowed for the eSIM profile class.
profileNotPresent String Indicates that an eSIM profile could

not be found.
noCorrespondingRequest String Indicates that no corresponding

request could be found.
unknownError String Indicates that LPA returned an error

that is unknown.
lpaInitializationError String Indicates that an error occurred when

trying to initialize LPA.
modemNotFound String Indicates that no cellular modem was

found on the device.
localSettingsAccessFailed String Indicates that accessing app local

settings failed.
invalidJson String Indicates that the MO portal has

provided invalid JSON when calling the
Mobile Plans app.
invalidActivationCode String Indicates that the MO portal has given

invalid activation code.
invalidIccid String Indicates that the MO portal has given

an invalid ICCID.
The following Javascript example shows how to implement a listener for the profile activation event.
function onActivationComplete(activationArgs) {
var activationObj = JSON.parse(activationArgs);
if(activationObj.activationResult == MobilePlansActivationError.success)
Log('Activation Success');
}
Delayed eSIM profile download and activation

The following diagram shows the call flow for how the Mobile Plans app supports the delayed download and
activation of an eSIM profile. This should be used when the eSIM profile is not available to be released by the
SM-DP+ server, and can only be downloaded after a period of time. It is expected that the device will be able to
register on the cellular network once the profile is downloaded and activated.
MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData, activationCode, downloadDelay)

purchased. All these are used for
reporting.
activationCode String The activation code or SM-DP+

address where the profile is located
downloadDelay uint The number of minutes to wait before

attempting to download the eSIM
profile

download operation.
Control is returned to the mobile operator Portal immediately after the call. UI will be displayed to inform the
user that a profile will be installed later. After the downloadDelay minutes has occurred, a notification will be
shown to the user, inviting them to begin the process of downloading the profile.
The following Javascript function shows an example of the API to inform the application that a profile download
with delay should begin
MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData , "1$smdp.address$matchingID", 15);
See listening for network registration changes section above.
See listening for profile activation section above.
Cancel eSIM profile download

This applies for the deferred eSIM profile download scenario, but it could be used for future use cases as well.
The following diagram shows the high level flow for how the Mobile Plans program supports a cancellation of
an eSIM profile download without control leaving the MODirect portal.
MobilePlansInlineOperations.notifyOperationCancel(MobilePlansOperationContext)
operationContext Object This object contains information that

uniquely identifies a previous
operation
This operation can be canceled before the user sees a toast notification informing them that download is ready
to begin.
The following Javascript function shows an example of the API to cancel an asynchronous action.
var op = MobilePlansInlineOperations.notifyProfileDownload(purchaseMetaData ,
"1$smdp.address$matchingID", 15);
MobilePlansInlineOperations.notifyOperationCancel(op);
Asynchronous connectivity
The following diagram shows the high level flow for how the Mobile Plans app supports delayed connectivity.
This callback method should be used when the eSIM profile is already available for release by the SM-DP+
server, however the device needs to wait some time before attempting to register on the cellular network.
After the user successfully completes the activation flow, the web portal informs the Mobile Plans app that it
should trigger the delayed connectivity flow using the MobilePlans.notifyPurchaseWithProfileDownload API.
MobilePlans.notifyPurchaseWithProfileDownload

reporting.
activationCode String The activation code for downloading

the eSIM profile. The ICCID for the
profile is inferred from the profile
metadata.
networkRegistrationInterval Unsigned integer The time needed for the mobile

operator to provision connectivity to
the user. The Mobile Plans app
attempts to register to the network
within the specified time interval, in
minutes. Note This time is rounded to
the nearest 15 minute interval. For
example, if this is set as 5 minutes, the
application tries to re-register to the
network after approximately 15
minutes (but it might take longer). if
set to "0" the device will attempt to
register immediately.
The following Javascript function shows an example of the API to inform the application that the user purchase
requires a delayed provisioning of connectivity.
function finishPurchaseWithDownload() {
var metadata = MobilePlans.createPurchaseMetaData();
metadata.userAccount = MobilePlansUserAccount.new;
metadata.purchaseInstrument = MobilePlansPurchaseInstrument.new;
metadata.moDirectStatus = MobilePlansMoDirectStatus.complete;
metadata.line = MobilePlansLineType.new;
metadata.planName = "2GB Monthly";
MobilePlans.notifyPurchaseWithProfileDownload(metadata, "1$smdp.address$matchingID", 15);
}
Adding balance
When a user completes a purchase in the web portal by adding more balance to an existing account, the web
portal should invoke the MobilePlansInlineOperations.notifyBalanceAddition API return control back to the
Mobile Plans app. This could be used for physical SIM or eSIM profile which are already installed in the device.
The following diagram shows the high level flow for how the Mobile Plans app supports adding balance.
MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData)

reporting.

download operation.
When the mobile operator would like to add balance to a given account, the web portal should call the
MobilePlansInlineOperations.notifyBalanceAddition API.
The following Javascript function shows an example of the API to inform the application that a balance addition
has been made.
function NotifyMobilePlans() {
MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData);
}
Adding balance and activate eSIM profile

When a user completes a purcahse in the web portal by adding more data to an existing account, the web portal
should invoke the MobilePlansInlineOperations.notifyBalanceAddition API return control back to the Mobile
Plans app. This could be used for an eSIM profile which is already installed on the device. The ICCID parameter
indicates which eSIM profile should be activated.
The following diagram shows the call flow for how the Mobile Plans app supports adding balance with iccid
information.
MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData, iccid)

reporting.
iccid String The ICCID which should be made

active after the balance addition

download operation.
Balance addition can also be made to a non active profile if the ICCID of the profile is known. Using the
MobilePlansInlineOperations.notifyBalanceAddition with an ICCID will inform the app of the balance addition as
well as switch the active profile to the profile corresponding to the provided ICCID.
The following Javascript function shows an example of the API to inform the application that a balance addition
has been made.
MobilePlansInlineOperations.notifyBalanceAddition(purchaseMetaData, "8900000000000000001");
}
Canceling purchase flow

If a user cancels the activation flow in the web portal, the portal must invoke the
MobilePlans.notifyCancelledPurchase API to return control back to the Mobile Plans app.
MobilePlans.notifyCancelledPurchase

reporting.
The following Javascript function shows an example of the API to inform the application that the user has
canceled a purchase.
function finishPurchaseWithCancellation() {
metadata.purchaseInstrument = MobilePlansPurchaseInstrument.new;
metadata.moDirectStatus = MobilePlansMoDirectStatus.cancelled;
metadata.line = MobilePlansLineType.bailed;
metadata.planName = "";
MobilePlans.notifyCancelledPurchase(metadata);
}
Purchase Metadata Properties details

The following table describes the details used in the purchase metadata.
P RO P ERT Y N A M E TYPE DESC RIP T IO N EXA M P L E

userAccount String Possible values: "userAccount":"New"

New: Indicates that
a new user account
was created by the
user.
Existing: Indicates
that the user logged
on with an existing
user account.
Bailed: Indicates that
the user ended the
purchase flow at this
step.
None: Indicates that
the user didn’t reach
this step.
purchaseInstrument String Possible values: "purchaseInstrument":"New

New: Indicates that "
a new user account
was created by the
user.
Existing: Indicates
on with an existing
user account.
the user ended the
step.
this step.
line String Possible values: "line":New"

New: Indicates that
a SIM card was
added by the user
account.
Existing: Indicates
that the user
transferred an
existing line to the
device.
the user ended the
step.
this step.
moDirectStatus String Possible values: "moDirectStatus":"Complete

Complete: Indicates "
that the user
completed the
purchase
successfully.
ServiceError:
Indicates that the
user was unable to
complete the
purchase due to an
MO service error.
InvalidSIM: Indicates
that the ICCID
passed to the portal
was incorrect.
LogOnFailed:
indicates that the
user failed to log in
to the MO portal.
PurchaseFailed:
Indicates that the
purchase failed due
to a billing error.
ClientError: Indicates
that invalid
arguments were
passed to the portal.
BillingError: Indicates
that there was an error
with the user billing.
planName String For a successful transaction, "planName":"2GB Monthly"

this field must not be
empty and must provide a
descriptive plan name. For
an unsuccessful transaction,
this field must be an empty
string.
Legacy callback notifications

Please refer to the specific page where all legacy callbacks are documented.
Mobile Plans eSIM profile download error handling
Overview
The Mobile Plans app has a built-in retry solution that attempts to repair situations where the eSIM profile
download does not complete successfully. However, in some scenarios, intervention from the mobile operator is
necessary to ensure that the eSIM is installed on the device. Mobile operators can support eSIM error handling
in their web portal to delight their consumers.
Handling eSIM download errors

The Mobile Plans app has a feature that passes error codes to the MO portal once the user re-enters the portal.
The following example shows how the app passes relevant paremeters.
GET https://moportal.com/?
market=US&location=US&transactionId=HADRdRhKI0S5bN4n.1&eid=89033023422130000000000199272786&imei=00110200022
4082 HTTP/1.1
X-MP-LPAError-Codes: ServerFailure,ServerNotReachable
X-MP-LPAError-TimeStamps: 5/18/2018 11:17:23 PM,5/18/2018 11:27:33 PM
X-MP-LPAError-ICCIDs: 8988247000101997790
The Mobile Plans app adds three headers, described in the following table.
X-MP-LPAError-Codes This field provides the error code that X-MP-LPAError-Codes:

has been captured in the LPA. If there ServerFailure,ServerNotReachable
are multiple errors, the error codes are
passed in a comma-separated list.
For a list of possible error codes,
see the ESimOperationStatus
enum.
X-MP-LPAError-TimeStamps This field provides the timestamp of X-MP-LPAError-TimeStamps:

when the error occurred. The format of 5/18/2018 11:17:23 PM,5/18/2018
the timestamp is Date Time UTC offset. 11:27:33 PM
If there are multiple errors, the
timestamps are passed as a comma-
separated list.
X-MP-LPAError-ICCIDs This field provides the ICCID of the X-MP-LPAError-ICCIDs:

eSIM profile that the user attempted 8988247000101997790
to download and install. This ICCID
was passed back to the Mobile Plans
app when control handoff occurred.
Only one ICCID is passed.
Mobile operators might choose not to support handling errors passed by the Mobile Plans app, but we
recommend doing so because it enhances the user experience.
The following image shows an example of the error message that is displayed to the user:
Mobile Operator account management in Windows
10
This topic describes the mobile operator account management experience provided by Windows, which can be
extended with Mobile Plans.
Basic account management experience

This section describes the options to configure what the View my account link shows in the Windows
Connection Manager, also known as also known as the network flyout.
The View my account link could be configured to:
Launch a web browser and open a defined web page.
Launch the Mobile Plans app and open the mobile operator web portal.
Once you have decided on one of these options, please request a COSA database update to implement the right
behavior. For more info, please see Planning your desktop COSA/APN database submission.
The following settings apply for the above options:
AccountExperienceURL. This parameter defines the web page.
AppID. This parameter defines which app is launched. To use the Mobile Plans app, configure
Microsoft.OneConnect_8wekyb3d8bbwe!App.
The following image shows an example of the network flyout:
Enhanced account management experience

By implementing the enhanced account management experience, you can offer these benefits to your
customers:
Customers can see how much data is available, and the amount of time left until their subscription expires, in
the network flyout.
Customers can top up their prepaid subscriptions over mobile connectivity, even when they run out of
prepaid balance or their subscriptions has expired.
You can manage your network flyout offering based on customer's subscription status.
These experiences build on top of the basic account management experience, which is the default experience in
the device network flyout.
Network flyout user experience
Depending on the information that is received from GetBalance API calls, the network flyout behaves differently,
which enhances the user experience.
The network flyout has the following elements:
1. Connect with a data plan. This launches the Mobile Plans app.
2. View my account. Behaves based on the basic account management experience.
3. Balance information. Shows the balance available, which is provided in your GetBalance response.
The following image shows these network flyout elements. Connect with a data plan corresponds with A, View
my account corresponds with B, and Balance information corresponds with C.
To provide the right information in the network flyout, MOs provide Type and Balance (dataRemainingMB and
timeRemaining) information as defined in the GetBalance API section.
The following table provides a reference between the GetBalance response type and what is displayed in the
network flyout.
GET B A L A N C E RESP O N SE T Y P E N ET W O RK F LY O UT SH O W S. . .
MODIRECT "View my account" only with no balance information
MODIRECTPAYG "View my account" and balance information
NONE "Connect with a data plan"
NOTSUPPORTED "View my account" only
GetBalance API
IMPORTANT
Please request a Windows COSA update to enable Get Balance in Windows.
The GetBalance API queries current subscription status, controls whether the Mobile Plans experience is
available on the device, and shows remaining data and time in the network flyout for prepaid subscriptions. The
following diagram shows the high-level flow for the GetBalance API.
Resource model
Communication between the Mobile Plans service and the Mobile Operator API involves manipulating the
resources in the following diagram. Explanations for each resource are in the tables following the diagram.
SIM resource
NOTE
The SIM resource does not currently support “create,” “read,” “update,” or “delete” operations.
JSO N P RO P ERT Y TYPE DESC RIP T IO N
Iccid String The ICCID of the profile that has been

created.
Balance resource
id String Mobile operator internal id, to track

the transaction
Type Enum Possible values:

MODIRECT: Indicates if the
user balance is MO Direct.
MODIRECTPAYG: Indicates if
the user balance is MO Direct
PAYG.
NONE: Indicates the user has
no balance. When the
remaining balance is 0 but the
plan has not expired, we expect
to receive "NONE" so that the
user can purchase data plans.
NOTSUPPORTED: Indicates the
SIM is not supported by the
Mobile Plans experience.
"NOTSUPPORTED" is used
when the SIM should not be in
the*Mobile Plans supported
range. We will turn off the
Mobile Plans experience in the
network flyout and return a
generic error message in the
Mobile Plans app when we
receive this type.
dataRemainingInMB Double The data remaining in the current user

plan, in MB.
timeRemaining String The time duration specified in ISO

8601.
Headers
The following headers may be included in every request from the Mobile Plans service to the mobile provider’s
endpoint.
H EA DER N A M E VA L UE DESC RIP T IO N
X-MS-DM-TransactionId String The TransactionId to uniquely identify

this request/response interaction
between the Mobile Plans service and
the MO service.
Authorization (optional) String A basic authentication string optionally

provided by the MO.
Error codes
The table below defines the error codes that should be used in the HTTP response.
ERRO R C O DE DESC RIP T IO N
HTTP 200 (OK) The operation completed successfully. This code should also
be used to indicate if the user has 0 balance in the specified
location, which should be done using dataRemainingInMB=0
and timeRemaining=”PT0S” with HTTP 200.
ERRO R C O DE DESC RIP T IO N
HTTP 201 (Created) Indicates that the operation completed successfully and the
resource was created successfully.
HTTP 400 (Bad Request) Used for an invalid query parameter, invalid header, or
invalid payload. In the response body, the parameter that is
incorrect should be indicated. For example, if an invalid
fieldsTemplate is specified, this error code must be returned
with details in the response body.
HTTP 401 (Unauthorized) Authentication credentials were incorrect or invalid. This can
occur when the basic auth credentials passed are incorrect.
HTTP 403 (Forbidden) The client certificate is untrusted or invalid. If the client
certificate included as a part of MTLS is invalid, HTTP 403
should be returned.
HTTP 404 (Not Found) The MO service should return this error when the resource
doesn’t exist. This can occur when an incorrect ICCID is sent.
This should not be used to indicate that the user doesn’t
have a balance in the specified location, which is indicated
with HTTP 200 (OK).
HTTP 409 (Conflict) Used if a TransactionId is repeated.
HTTP 429 (Too many requests) Used by the MO service to indicate that the Mobile Plans
service is sending too many requests within the specified
amount of time. In the response, the MO service must use
the Retry-After header to indicate the time after which the
Mobile Plans service should retry for the resource. In the
response body, optional details can be provided.
HTTP 500 (Internal Error) Something unexpected happened on the MO service. The
MO service should include the cause of error whenever
possible so that it can be used for further debugging as
needed.
GetBalance API specification

The GetBalance API is called when network flyout is displayed in the Windows device. The Mobile Plans service
is a proxy for this communication.
This call is done with an HTTP request, where moBaseUrl is the endpoint of the MO-hosted service and sim id is
the ICCID:
GET https://{moBaseUrl}/sims/{sim id}/balances?fieldsTemplate=basic&limit=1&location=US HTTP/1.1
Query parameters:
Q UERY PA RA M ET ER N A M E VA L UE DESC RIP T IO N
location String Optional. The location where the user

balance is being queried. If not
specified, all active balances are
expected. Note The location
parameter is case-sensitive.
Q UERY PA RA M ET ER N A M E VA L UE DESC RIP T IO N
limit Integer Optional. The maximum count of

balances to be returned. If not
specified, all balances should be
returned.
fieldsTemplate Enum Specifies the list of fields that must be

returned in the resource.
Possible values:
Basic: type,
dataRemainingInMB, and
timeRemaining in the Balance
resource must be returned.
Full: All properties in the
Balance resource must be
returned.
The following series of examples show the call flow for the GetBalance API.
Example 1: Returning the first balance that is available for the user in US
GET https://moendpoint.com/v1/sims/iccid: 8988247000100003319/balances?

fieldsTemplate=basic&limit=1&location=us HTTP/1.1
X-MS-DM-TransactionId: “MSFT-12345678-1234-1234-1234-123456789abc”
HTTP response:
HTTP/1.1 200 OK
X-MS-DM-TransactionId: “12345”
{
“balances”: [
{
“id”: “23445”,
“type”: “MODIRECTPAYG”,
“dataRemaininginMB”: 123.0,
“timeRemaining”: “P23DT23H”
}
]
}
If successful, this method will return the balance of the user.

Response JSON:
DATA TYPE DESC RIP T IO N
Balances Collection A collection of Balances.
Example 2: The expected response for a SIM that is in the COSA ICCID range but should not be supported by Mobile Plans
HTTP request:
GET https://{moBaseUrl}/sims/{sim id}/balances?fieldsTemplate=basic&limit=1&location=US

HTTP/1.1
Response JSON:
HTTP/1.1 200 OK
X-MS-DM-TransactionId: “12345”
{
“balances”: [
{
“id”: “23445”,
“type”: “NOTSUPPORTED”,
“dataRemaininginMB”: 0.0,
“timeRemaining”: “PT0S”
}
]
}
Authentication
Communication between the Mobile Plans service and the Mobile Operator API must be authenticated using the
Mutual Transport Layer Security (MTLS). Microsoft provides a certificate for you to use to validate the identity of
the requester to moBaseUrl .
Microsoft provides the certificate during the onboarding process.
How to enable Get Balance in Windows COSA
It is required to configure the following settings in the Windows COSA database to enable the Get Balance
support on Windows devices.
The following COSA settings are required:
SupportDataMarketplace (must be set to “Yes”)
DataMarketplaceRoamingUIEnabled
SIM ICCID range (ICCID Range – Start and ICCID Range – End)
For more info about all supported fields, see the Desktop COSA-only settings on Desktop COSA/APN database
settings.
Download the COSA/APN update spreadsheet.
Mobile Plans walled garden
The Mobile Plans Walled Garden is key to supporting customers when they run out of data. It enables them to
reach the MO Direct portal even when there is no alternative internet connection such as Wi-Fi. This will enable
consumers to purchase additional data plans and manage their subscriptions.
NOTE
The Mobile Plans architecture does not support IP ranges for Walled Garden endpoints. Host names must be used for
allowlisting.
The MO Direct web portal and GetBalance API endpoint must also be part of this Walled Garden.
Walled Garden endpoints

There are only a small number of required endpoints that are always accessible to end users. The following table
defines the endpoints required for Walled Garden.
URL HT T P/HT T PS
service.datamart.windows.com https
dogfood.datamart.windows.com https
windows.policies.live.net https
ctldl.windowsupdate.com http
cdp1.public-trust.com http
ocsp.omniroot.com http
vassg142.ocsp.omniroot.com http
vassg142.crl.omniroot.com http
mscrl.microsoft.com http
crl.microsoft.com http
www.msftconnecttest.com http
crl3.digicert.com http
Ocsp.digicert.com http
login.live.com http + https

URL HT T P/HT T PS
storagetos.datamart.windows.com http + https
mps.datamart.windows.com http + https
mps-service.datamart.windows.com http + https
staging.datamart.windows.com http + https
mps-staging.datamart.windows.com http + https

Mobile Plans notifications
Overview
This topic describes toast notifications in Mobile Plans that can be customized by the mobile operator with text
and images to communicate with end users. Mobile Plans notifications are based on the toast notifications
framework in Windows 10.
NOTE
Please reach out your Microsoft contact before planning to use this feature.
The Mobile Plans app supports the showing of 2 different types of toast notifications: SMS-triggered and app-
triggered.
SMS-triggered notifications
Mobile operators can trigger a notification to be shown on a user's device by sending an SMS to the device. The
body of the SMS includes a string identifier which will route the message to the Mobile Plans app, and trigger
showing of the notification. Clicking on the <accept> button will launch the Mobile Plans app and show the
mobile operator's Gateway page.
Because the mobile operator triggers the notification via SMS, the device must have the active profile and be
registered on the cellular network with ability to receive the SMS. The device must also have data access to the
Mobile Plans service for requesting the notification content.
SMS -triggered notification content
The notification content can be customized by the mobile operator using a template with predefined elements.
The highlighted elements below are definable by the mobile operator.
F IEL D N A M E DESC RIP T IO N EXA M P L E

Notification type Several pre-defined types of SMS- Low Balance, Zero Balance, New Offer,
notifications are supported. Each type Trial Offer, Trial Ending, Trial Ended
behaves the same. Only the strings
shown for the <accept> and
<decline> buttons change
depending on the type.
Title One line call to action "You're almost out of data"
Body Short message highlighting the "There's less than 5MB left for your
offering value to the end user current data plan. Take action now to
make sure you stay connected."
Image A lifestyle oriented photo with the PC https://picsum.photos/id/1/364/180

as the centerpiece. Image dimensions
are 364x180 pixels at 100% scaling.
Logo This is part of the assets that are

provided during onboarding
Sample SMS -triggered notification
Using multiple notification templates

Mobile operators have the option to define more than one SMS-notification template. If this is done, the Mobile
Plans service will call the Mobile Operator API at runtime to request an ID for the template which should be
used for the notification.
Since the request includes identifiers for the active profile on the device, the mobile operator can define multiple
templates for different user segments, or for A/B testing. SMS-notifications can also be combined with enhanced
Gateway pages shown in the Mobile Plans app to create highly targeted campaings.
The Get Notifications request returns the template ID to be used for the notification shown to the user.
GetNotifications API specification
The GetOffers API is called upon receipt of the SMS message by the Mobile Plans application. The Mobile Plans
service is a proxy for this request.
GET https://{notificationUri}sims/{simmri}/notifications
{notificationUri} is the NotificationUri value onboarded as part of the mobile operator's service configuration.
The endpoint has three query parameters:
limit, which is required and specifies the number of notifications to return.
imei, which is optional and specifies the client’s IMEI.
notificationType, which is required and specifies the type of notifications to return. The notificationType
parameter is always one of the enumerated strings accepted by the Mobile Plans’ GET Notifications Request.
The response is a JSON object with a single property named notifications that contains a list of notifications. The
number of notifications in this list is at most limit from the request. Each notification in this list is an object with
a single property, notificationId, which must identify an existing notification in the mobile operator’s service
configuration.
The following is an example interaction using this endpoint:
GET https://moendpoint.com/v1/sims/iccid:8988247000100003319/notifications?
notificationType=lowBalance&limit=1&imei=1234
HTTP/1.1 200 OK
{
"notifications": [
{
"notificationId": 1,
"notificationType": "lowBalance"
}
]
}
App-triggered notifications
Mobile operators in some markets also have the ability to show a promotional notification on eSIM-enabled
Windows 10 PCs that do not have an eSIM profile installed. The promotional notification is triggered by the app
shortly after the user completes setup of the device in the out of box experience. Clicking on the <accept>
button will launch the Mobile Plans app and show the mobile operator's Gateway page.
App-triggered notification content
The promotional notification content can be customized by the mobile operator using a template with
predefined elements. The highlighted elements below are definable by the mobile operator.
Title One line call to action "Activate your free trial"
Body Short message highlighting the "Get 30GB FREE data, so you can stay
offering value to the end user connected from anywhere."
Image A lifestyle oriented photo with the PC https://picsum.photos/id/1/360/234

as the centerpiece. Image dimensions
are 360x243 pixels at 100% scaling.
Logo This is part of the assets that are

provided during onboarding
The Notifications Visualizer app can be used to mockup and test notification content.
Sample App-triggered notification
Mobile Plans onboarding overview
Project overview
Mobile Plans onboarding is a project composed of four phases:
P H A SE DESC RIP T IO N
Feasibility The mobile operator assesses the Mobile Plans solution to

determine feasibility and scope of the project. There are
several approaches and scenarios available which should be
evaluated against business needs. The operator will review
available documentation, work with their designated
Microsoft contact to address questions as needed, align on
the timeframe, and commit to begin the work.
Development The mobile operator implements the component parts of

their solution, according to the scenarios defined above.
Windows and Mobile Plans configurations are also enabled
as needed during this phase.
Integration The mobile operator is enabled in Mobile Plans to run end-

to-end validation in a staging environment. The integration
topic provides more details on this phase.
Rollout & Launch The mobile operator is enabled commercially and made
available to end users in the production environment. The
launch topic provides more details on this phase.
Project schedule
A typical project schedule is divided into the following phases, with milestones defining the exit/entrance criteria
for each phase. The actual length of the devlopment phase will depend on multiple factors including the scope
of the project.
Project plan
This sample project plan has been developed to illustrate the tasks required for each phase of work. Some tasks
are for mobile operators, while others are joint tasks to be done in coordination with Microsoft.
Mobile Plans service configuration
This topic describes how to build a foundation on Windows connected devices that support Mobile Plans. It
details how to configure your eSIM profiles to ensure the best consumer experience, as well as how to provide
service configuration information that ensures that the Mobile Plans experience is properly rendered on
Windows devices.
eSIM profile configuration requirements

You must prepare eSIM profiles that meet the following requirements:
The eSIM profile must not be PIN locked.
The eSIM profile must not be deleted from your SM-DP+ server until you receive confirmation that the
profile download has been completed successfully. The activation code can be reused to retry downloading
the same profile when previous attempts to download have failed.
The eSIM profile must not have the “Do not delete” or “Do not deactivate” policies set.
The activation code must not include any prefixes such as “LPA:”.
The activation code is available immediately after the MO Direct flow.
The activation code must not require a "Confirmation Code".
eSIM profile testing
It is expected that the mobile operator perform a validation to ensure that their eSIM profiles can be installed on
different Windows devices. For this, it is recommended to source some eSIM-capable devices and use the
Windows Settings app to download, install, and activate profiles.
Service configuration
The Mobile Plans service must ingest some configuration information to support a mobile operator. To start the
configuration process, please send an email to Mobile Plans Implementation Support.
Minimum configuration information
1. The brand name you would like to use for your products.
2. The branding logo. Required resolution is 300x300 pixels. Image should also be full bleed with no
transparency.
3. The list of countries where your solution is supported. Please use ISO 3166 code to create the list (comma
separated).
4. Your MO Direct portal URI (localization is not supported). This should be an https address. Port numbers are
not supported.
5. A notification URI. This is the host address from where the Javascript callbacks (callback notifications) are
going to be run. This should be an https address. Port numbers are not supported.
6. The ICCID range or ranges that you want to want to associate with Mobile Plans.
The following image shows an example for the standard gateway page in the Mobile Plans app. The “A”
annotation corresponds to the branding logo you submit, and the “B” annotation corresponds to the brand
name.
Mobile Plans Integration
Overview
This topic describes what steps are needed to integrate and validate the mobile operator implementation of the
Mobile Plans solution.
Mobile Plans service environments

There are two Mobile Plans service environments, Staging and Production. The integration and validation will be
performed in the staging environment, while the production environment is only used for commercial launch.
Validation
This section describes testing and validation that you must do to ensure that you are ready to move into the
Integration phase.
Mobile Operator web portal
Validate that you can run 50 end-to-end user cases that you defined. For example:
Install an eSIM profile.
Activate a warm SIM.
Add balance to your subscription.
Canceling a transaction.
Walled Garden
When the user has no balance, ensure that the user can access Walled Garden sites defined in Walled Garden.
Getting Balance
1. When the user is in the Walled Garden state, the balance returned must be zero.
2. As the user consumes data, the balance returned must decrement to reflect the data remaining.
3. As the allotted time lapses after the Create Order API has been invoked, the time remaining must decrement
to reflect the time remaining.
Test with expired MTLS certificate
1. Validate MO APIs without the MTLS certificate. Expected Status: 401 Unauthorized.
2. Validate with an expired MTLS certificate. Expected Status: 401 Unauthorized.
GetBalance negative tests
1. Validate with an invalid SIM. Expected Status: 404 Not Found.
2. Validate with unknown location or bad location string/number. Expected Status: 400 (Bad Request).
3. Validate with filter limit as a negative number and exceeding the limit of an INT. Expected Status: 400 - Bad
Request. Expected Status 200 OK for filter limit (integer).
4. Validate a call to GetBalance without any location (or empty location), fieldTemplate, limit, and many more
combinations of parameters. Expected Status: 400 (Bad Request) with any bad parameter’s value. Expected
Status 200 – OK.
GetBalance API load test
Before the GetBalance API is enabled in production, both Mobile Plans services and mobile operator services
should be tested to see if they can handle the projected load. The mobile operator is expected to run a load test.
Once that has passed, Mobile Plans executes a load test. The mobile operator should provide a list of 1000
ICCIDs that are temporally used in the load test.
This test configuration is generated from projected traffic of 10,000 SIMs. The Peak RPS is calculated based on 3
times this traffic projection.
Load tests will be executed from 25 test agents.
Load tests will execute for:
1 hour with 1000 different users (#ICCIDs) with 3 RPS (Peak).
The load distribution cross APIs would be as follows:
API LO A D DIST RIB UT IO N EXP EC T ED RP S P EA K RP S
GetBalance 96% 1 3
During test runs, the expected success rate is: 99.9% and average latency: 400ms . On achieving this success
rate, the MO API will be ready to enable in the Mobile Plans production service.
Mobile Plans launch
This section describes the work needed to successfully launch Mobile Plans with your mobile operator, including
Web service API monitoring, running an end-to-end scenario, and the review escalation process.
Before launch
You (the mobile operator) and Microsoft will review that all outstanding issues are properly addressed before
moving to go live. This is important to fully migrate to a production environment.
Launch validation
On the agreed-upon launch date, Microsoft will move the mobile operator portal to production. The mobile
operator is responsible for performing end-to-end validation immediately and reporting back any potential
issues to Microsoft. This will enable providing support to address the issues accordingly.
Mobile operatosr are ultimately responsible for accepting the live, in-production service.
After Launch
API monitoring
The Mobile Plans service monitors the availability of the Web service API (mobile operator portal) by using
Xping to ping the portal twice per minute, making sure it is accessible.
The Mobile Plans service monitors the availability of the GetBalance API using the defined protocol, twice per
minute, making sure it is accessible. For this monitoring the mobile operator should provide an ICCID that will
be continually used.
Escalation process
Microsoft has established a two-way live site escalation process for mobile operators and Microsoft to work
together on any customer-facing production incidents. A live site issue is any event that is not part of the
standard operation of the either your service or Microsoft’s service, and causes (or might cause) an interruption
or a reduction in quality of the Mobile Plans experience. Key scenarios in the Mobile Plans experience are:
Ensuring that the Mobile Plans app can reach your MO Direct portal via Walled Garden or a Wi-Fi or Ethernet
connection.
Ensuring users can always consume purchased data.
The goal of this process is that both mobile operators and Microsoft agree to the following:
1. Monitor and escalate live site incidents following the process described in this topic.
2. Prior to escalation of an incident, assign the correct priority using the guidelines described in this topic.
3. Provide responses on all incidents in accordance with the maximum allowed response times associated to
the incident priority as described in this topic.
Live site performance SLAs
The following table provides detailed descriptions for live site performance SLAs, including service availability
and expected API response times for key APIs integrated with the Mobile Plans service.
IN C L UDED IN
M O B IL E P L A N S
IM PA C T IN C A SE MO API
SERVIC E N A M E DESC RIP T IO N O F IN C IDEN T M O N ITO RIN G? AVA IL A B IL IT Y L AT EN C Y
Core Network Services that Users will not be No. 99.90% N/A
Services provide the able to connect Mobile
(PGW, capability to: to the internet operators
Online Access using their are
Charging the cellular data responsible
System, internet plan. for
internet for a user monitoring
access, GRX with data their own
access, etc.) allowance Core
. Network
Access Services.
Walled
Garden
even with
no data
allowance
.
MO Direct portal A web portal Users will not be Yes 99.90% 400ms
that users can able to engage
access for the with the MO
MO Direct Direct experience
scenario. to sign up data
plans.
xDR CDR: Call Impacts No. N/A N/A

(CDR, SDR, details Microsoft Mobile
TDR) record internal business operators
SDR: intelligence are
Subscripti reporting and responsible
on details sharing insights for
record with mobile monitoring
TDR: operators their own
Transactio xDR services.
n details
record
Incident escalation
Escalation to mobile operators
If a service interruption is detected by Microsoft, the incident is triaged and processed based on the following
severity.
EXP EC T ED
SEVERIT Y B USIN ESS IM PA C T T H RESH O L D RESO L UT IO N T IM E UP DAT E C A DEN C E
1 Outage/Disaster : Partner Failure 8 hours Once partner contact

Issue with high Percentage = 100% is made, email
impact, affecting all OR Global Failure updates should be
traffic to a single Percentage > 5% provided every 2
partner, or a hours
moderate or greater
amount of overall
global traffic.
EXP EC T ED
SEVERIT Y B USIN ESS IM PA C T T H RESH O L D RESO L UT IO N T IM E UP DAT E C A DEN C E
2 Ser vice Partner Failure 24 hours Once partner contact

Disruption: Issue Percentage = 75% is made, email
with medium impact, OR Global Failure updates should be
affecting a high Percentage = 1% to provided every 6
amount of user traffic 5% hours
for a single partner,
but still a low
amount of overall
global traffic.
3 Standard Partner Failure Best effort Once partner contact

Escalation: Issue Percentage = 25% - is made, emails
with low-to-medium 75% OR Global updates should be
impact, affecting Failure Percentage < provided as needed
moderate amount of 1% OR 12
user traffic for a consecutive xPing
single partner, but a tests to MO’s Get
very low amount of Balance endpoints fail
overall global traffic. (MPS makes one
xPing call per 5
minutes)
Escalation to Microsoft
If you detect a service interruption, you can escalate to the Mobile Plans Services team. Service interruptions
include, but are not limited to, core Mobile Plans scenarios being down for more than 30 minutes, or mobile
operators’ services receiving an abnormally high number of calls from Mobile Plans services.
For incidents during staging / onboarding, escalate to Mobile Plans Implementation Support. For incidents post
onboarding, escalate to Mobile Plans Operations support.
Services outage
Microsoft communication of services outage to mobile operators
Microsoft will inform mobile operators of any Microsoft network Mobile Plans service outages via email no
more than 30 minutes after we first become aware of such an outage.
Mobile operator communication of services outage to Microsoft
You must inform Microsoft of any Core Network Services outages via email no more than 30 minutes after you
first become aware of such outages. Mobile Plans Operations support
Pl an n ed m ai n t en an c e
Regularly scheduled or routine maintenance of the services operated by mobile operators or the Microsoft
Mobile Plans team that have or may have end user impact must be communicated beforehand through the
channels defined in this section.
Co m m u n i c at i o n o f pl an n ed m ai n t en an c e t o m o bi l e o per at o r s
The Microsoft Mobile Plans team will communicate planned maintenance to mobile operators no later than five
business days prior to the event. Once the maintenance is completed, a notification is sent to mobile operators.
C o m m u n i c a t i o n o f p l a n n e d m a i n t e n a n c e t o M i c r o so ft
Regularly scheduled or routine maintenance of the mobile operator’s Core Network Services must be
communicated via email to Microsoft no later than five business days prior to the event to Mobile Plans
Operations support.
R e q u e st i n g b u g fi x e s
Repor ting a bug – Each team can report a bug via email to Mobile Plans Operations support, and work with
their counterparts to get a bug logged.
Customer Support
Mobile operators are solely responsible for any customer support issues.
Mobile Plans general appendix
Web portal flow and reference design

This reference design is a template that you can alter to best represent your brand and products. This reference
design shows the recommended UX design with navigation elements, branding locations, and website
functionalities.
MO Direct reference site walkthrough
1. The user clicks on the "Continue" button:
This dialog is prompted by Mobile Plans app.

2. The user enters the MO Direct portal and signs in with their MO account:
Page layout is consistent throughout all pages. For example, logo and branding elements are in top
left, and navigation elements are on the bottom.
The sign-in page can link to signing up for a new account.
“Forgot password” is optional. Note that the user is in the Walled Garden, and only the Mobile Plans
app can access the internet. If you want to support password reset through the MO Direct portal,
make sure that users can reset it within two or three steps without launching a browser or email app
on the device.
3. The user picks an option:
Present the most important content, available services, at the center of the page.
Logo and branding elements are in the top left corner.
Navigation buttons are in the bottom right corner.
Use large tiles for available options, with a title and short description of the service category.
Both the “Next” and “Cancel” buttons are available for users to navigate forward or exit. The MO Direct
expected data service categories might include prepaid plans, recurring monthly plans, and attaching
a new device to an existing plan.
4. The user submits the order:
Page layout is consistent throughout all pages. For example, logo and branding elements are in top
left, and navigation elements are on the bottom.
The Terms of Service link must be visible on the web page.
The order confirmation page lists key information for users to review before submitting the order,
including details on data service, payment method, amount of payment, etc.
5. If the user cancels the MO Direct flow at any time:
A confirmation dialog to leave the MO Direct experience is prompted by Mobile Plans app.
6. An order is completed:
This shows an example of transaction confirmation, which is part of the mobile operator portal.
Once the order is processed successfully and, in this case, after clicking “Continue,” the notification
should be posted to the Mobile Plans app with the purchase result, eSIM activation code, and other
information required in the API. The user will be automatically redirected to the Mobile Plans app PDP
(product details page).
If the transaction is for a physical SIM card or the active eSIM profile is in place, you should be
activating the plan in the backend.
If the transaction requires a new profile to be downloaded, move on to the next step.
7. Downloading an eSIM profile (if applicable):
The eSIM profile is being downloaded.

8. The MO Direct plan is activated:
The device is connected.
The user has an active MO Direct account.
Hyperlink experience
If there is a hyperlink pointing to a new page in your MO Direct portal and the user clicks on it, the web view
control will render that page in the same window. Users must click on the back button in the Mobile Plans app to
return to the previous page.
Alternatively, you might use a hyperlink to launch a dialog within the context of the WebView control.
Back Button experience
The back button on the menu bar of the Mobile Plans app will navigate users to the previous page just like in a
web browser.
IMPORTANT
Build your MO Direct portal as if you are building a shopping cart experience if you would like the user to return to the
previous state without losing any data they had entered.
Error while loading the MO Direct experience

When there are any unhandled errors or exceptions on the MO Direct portal that cause the Mobile Plans app to
fail to load the MO Direct experience, the following error is displayed:
High level integration schedule
The following table provides a high-level overview of the Mobile Plans project integration schedule.
P H A SE A C T IVIT IES O W N ER T IM E EST IM AT E
Implementation eSIM profile installable on a MO

Windows device. Test using
SMDP+ used for Staging
Environment and
Production Environment.
Provide the onboarding MO

checklist document,
including Staging
Environment service
configuration
Enable the mobile operator MSFT Configuration updates

Staging Environment in the occur on the 1st and 3rd
Mobile Plans Staging Friday of every month
Environment
Submit COSA database MO About 3 months

update
MO Direct portal
development start
GetBalance API
development start
Integration Enable Walled Garden MO
Validate COSA update MO
MO Direct portal MO
development complete
GetBalance API MO
development complete
MO development complete MO
- code complete
(checkpoint)
Validate GetBalance API MO

functionality
End-to-end experience is MO
functional in MO Staging
Environment (checkpoint)
Update Service MO
Configuration document to
reflect Production
Environment settings (if not
provided previously)
Provide ICCIDs to be used MO

for GetBalance load test
Enable mobile operator MSFT Configuration updates

Production Environment occur on the 1st and 3rd
environment in Mobile Friday of every month
Plans Staging Environment
End-to-end experience is MO
functional in MO
Production Environment
(checkpoint)
Validaton Exit criteria test cases MO

complete
Verify test case results MSFT
Test sign-off (checkpoint) MSFT
Rollout GetBalance API load test MSFT and MO 1 week
Monitoring and escalation MSFT 1 week

paths in place
Customer support in place MSFT and MO
Commercial agreement MO
completed
COSA update available in MSFT

Windows
Go/No-Go (final checkpoint) MSFT and MO
Configure MO Production MSFT

Environment environment
in Mobile Plans Production
Environment
Launch MSFT and MO Launch date and time must

be agreed upon to ensure
that local validation
happens
Mobile Plans legacy callback notifications
NOTE
This page documents Mobile Plans legacy callback notifications. Please use this as reference only and do not implement
this code going forward.
Inline profile delivery

The following diagram shows the high level flow for how the Mobile Plans program supports downloading a
profile without control leaving the MODirect portal.
When the MO Direct portal is ready for a profile download, install, and activation to occur, the portal should call
MobilePlansInlineProfile.notifyInlineProfileDownload .
MobilePlansInlineProfile.notifyInlineProfileDownload

reporting.
activationCode String The activation code for downloading

the eSIM profile. The ICCID for the
profile is inferred from the profile
metadata.
The following Javascript function shows an example of the API to inform the application that an inline profile
download should start.
MobilePlansInlineProfileDownload.registrationChangedScript = "onRegistrationChanged";
MobilePlansInlineProfileDownload.profileActivationCompleteScript = "onActivationComplete";
MobilePlansInlineProfileDownload.notifyInlineProfileDownload(purchaseMetaData ,
"1$smdp.address$matchingID");
}
Adding balance (Legacy)

When a user completes a purchase in the MO Direct portal by adding more data to their account (no profile
download needed because the user used the current profile on the eSIM), the MO portal should invoke the
MobilePlans.notifyBalanceAddition API return control back to the Mobile Plans app.
MobilePlans.notifyBalanceAddition

reporting.
iccid String The ICCID to which data is assigned. If

this ICCID is not active, the Mobile
Plans app activates the corresponding
profile.
The following Javascript function shows an example of the API to inform the application that the user has
completed a purchase using a profile already available, but not necessarily active, on the eSIM.
function finishPurchaseWithBalanceAddition() {
metadata.purchaseInstrument = MobilePlansPurchaseInstrument.none;
metadata.moDirectStatus = MobilePlansMoDirectStatus.complete;
metadata.line = MobilePlansLineType.new;
metadata.planName = "2GB Monthly";
MobilePlans.notifyBalanceAddition(metadata, "89000000000000000000");
}
Other Legacy callback notifications

The notification to the Mobile Plans app should be sent using JavaScript with the following syntax:
DataMart.notifyPurchaseResult(notificationPayload);
An example of the notification payload for an eSIM is as follows:
let notificationPayload = new Object();

notificationPayload.ver = '1';
notificationPayload.purchaseResult = "
{\"userAccount\":\"New\",\"purchaseInstrument\":\"New\",\"line\":\"New\",\"moDirectStatus\":\"Complete\",\"p
lanName\":\"MyPlan\"}";
notificationPayload.success = true;
notificationPayload.transactionId = 'MSFT_ecf5a4d6-024c-46c3-8fcd-2c1f0deed572';
notificationPayload.activationCode = '1$trl.prod.ondemandconnectivity.com$JO46UQDI07IKQDGG';
notificationPayload.iccid = '8988247000101997790';
DataMart.notifyPurchaseResult(JSON.stringify(notificationPayload));
An example of the notification payload for a physical SIM is as follows:

{\"userAccount\":\"New\",\"purchaseInstrument\":\"New\",\"line\":\"New\",\"moDirectStatus\":\"Complete\",\"p
lanName\":\"MyPlan\"}";
notificationPayload.success = true;
notificationPayload.iccid = '8988247000101997790';
An example of the notification payload for an eSIM where the user abandoned the MO portal without a
successful transaction is as follows. To implement all cases that apply to your specific implementation, see the
table that follows the example.
{\"userAccount\":\"Bailed\",\"purchaseInstrument\":\"None\",\"line\":\"None\",\"moDirectStatus\":\"None\",\"
planName\":\"\"}";
notificationPayload.success = false;
notificationPayload.activationCode = '';
notificationPayload.iccid = '';
The MO Portal URI from which the notification is sent must be in the secure https protocol. You can specify the
host but not necessarily the full path, which leaves some flexibility for the future.
The following table describes each field in the JSON payload of the notification:
JSO N F IEL D TYPE DESC RIP T IO N EXA M P L E
success Boolean True if the user purchased “success”:true

an MO Direct plan.
iccid String For an eSIM, this indicates iccid:”8988247000100297655”

the ICCID that the client
must use for consuming the
MO Direct plan purchased.
activationCode String The activation code to “ActivationCode”

retrieve the eSIM profile.
transactionId String The Transaction ID that the transctionId=

MO portal received as a rRi8OzhI3EiR02nm.2.0.1
query parameter when the
portal was launched.
purchaseResult String Contains the details of the

user interaction with the
MO portal.
userAccount Enum This field is required. “userAccount”:”New”

Possible values:
New: Indicates that
a new user account
was created by the
user.
Existing: Indicates
on with an existing
user account.
the user ended the
step.
this step.
purchaseInstrument Enum This field is required. “purchaseInstrument”:”New”

Possible values:
New: Indicates that
the user used a new
method of payment.
Existing: Indicates
that the user used
an existing payment
method that was on
file.
the user ended the
step.
this step.
line Enum This field is required. “line”:”New”

Possible values:
New: Indicates that
a SIM card was
added by the user
account.
Existing: Indicates
that the transferred
an existing line to
the device.
the user ended the
step.
this step.
moDirectStatus Enum This field is required. “moDirectStatus”:”Complete”

Possible values:
Complete: Indicates
that the user
completed the
purchase
successfully.
ServiceError:
Indicates that the
user was unable to
complete the
purchase due to an
MO service error.
InvalidSIM: Indicates
that the ICCID
passed to the portal
was incorrect.
LogOnFailed:
Indicates that the
user failed to log in
to the MO portal.
PurchaseFailed:
Indicates that the
purchase failed due
to a billing error.
ClientError: Indicates
that invalid
arguments were
passed to the portal.
the user ended the
transaction without
a specific error.
planName String For a successful transaction, “planName”:”prepaid_3GperMonth”

this field must not be
empty and must provide a
descriptive plan name. For
an unsuccessful transaction,
this field must be an empty
string.
eSIM management on Windows for mobile
operators and OEMs
Mobile operators and OEMs

If you are a mobile operator or OEM and would like to support eSIM management on Windows, follow these
steps:
1. Conduct a Hardware Lab Kit (HLK) test run. This ensures modem hardware compatibility with Windows 10
eSIM support. OEMs and ODMs must ensure execution of the following HLK eSIM tests:
a. Basic eSIM support test cases:
Win6_4.MB.CDMA.Data.TestLowLevelUiccAccess
Win6_4.MB.GSM.Data.TestLowLevelUiccAccess
b. For Windows 10 devices with both a removable SIM slot and a soldered eUICC:
Win6_4.MB.CDMA.Data.TestSlot and/or Win6_4.MB.GSM.Data.TestSlot
Win6_4.MB.CDMA.Data.TestDeviceCapsEx and/or Win6_4.MB.GSM.Data.TestDeviceCapsEx
Windows provides the capability for Mobile Device Management providers to manage eSIM profiles in
enterprise use cases. However, Windows does not limit how ecosystem partners might want to offer this to their
own partners and/or customers. As such, the eSIM profile management capability can be supported by
integrating with the Windows OMA-DM. This makes it possible to remotely manage the eSIM profiles according
to company policies.
If you would like to integrate and work with only one MDM provider, contact that provider directly. If you would
like to offer eSIM management to customers using different MDM providers, contact an orchestrator provider.
Orchestrator providers act as a proxy that handles MDM onboarding as well as mobile operator onboarding.
Their role is to make the process as painless and scalable as possible for all parties. Potential orchestrator
providers you could contact include:
HPE’s Device Entitlement Gateway
IDEMIA’s The Smart Connect - Hub
eSIM management for other audiences

If you are an MDM provider and would like to support eSIM management on Windows, see How Mobile Device
Management Providers support eSIM Management on Windows.
If you are an end user in an organization and would like to use an eSIM for a cellular data connection on your
organization-provided device, see Use an eSIM to get a cellular data connection on your Windows 10 PC.
Creating and configuring Internet Sharing
experiences
Internet Sharing, commonly referred to as tethering, has been added in Windows 8.1 to enable users to share
their mobile broadband network connection with one or more other devices that are not mobile broadband-
capable. Traditional tethering mechanisms include Bluetooth and USB. However, Wi-Fi can provide the fast and
easy mobile broadband connection sharing mechanism, such as personal hotspots, mobile hotspots, and so on,
since it requires little configuration, enables high-speed data transmission, and relies on the familiar Wi-Fi
connection process.
Windows 8.1 and Windows 10 extend the Internet sharing capability further by enabling customers to turn on
and connect to PCs that have Internet Sharing configured, known as a tethering access point, just as if it was a
standard Wi-Fi network.
Turn on Internet Sharing

Internet Sharing can be turned on by using the Settings charm on the mobile broadband-capable device. Once
Internet Sharing is turned on, any device that can connect to a Wi-Fi network can connect to it.
To turn on Internet Sharing
1. From the Settings charm, click Change PC settings , and then click Network .
2. Under the Mobile Broadband heading, click the network name.
3. On the Mobile Broadband page, enable Internet Sharing for the network. If the mobile broadband
network is disconnected, the device will automatically connect to the mobile broadband network before
setting up the Wi-Fi network.
4. If you have created the necessary service metadata package, the PC triggers an event telling the
Microsoft Store mobile broadband app to run an entitlement check. The PC waits for the mobile
broadband app to respond before Internet Sharing is turned on. For more info on creating service
metadata packages, see Developer guide for creating service metadata.
5. After the mobile broadband network is turned on and any required entitlement checks have passed, the
mobile broadband connection is shared by using a private Wi-Fi network that uses Wi-Fi Direct
Autonomous Group Owner mode with a customized network name. This ensures that any Wi-Fi device
can connect to the network.
Note The icon for the mobile broadband network is automatically updated throughout Windows to help
customers remember that the network is being shared by other people.
6. After Internet Sharing is turned on, from the Mobile Broadband page, click Edit to change the network
name and password.
The Wi-Fi network must use WPA2-PSK.
The network name is set to a default of <Device Name> <4 digits>. The default network name is
optimized to ensure that the name is recognizable to the user by being short enough to fully fit in
the Networks list and unique enough to distinguish among multiple devices.
The password is set to a default of 12 random digits.
The password must be at least 8 characters in length.
The Wi-Fi network will restart when the network name or password is changed.
When Internet Sharing is turned on, the following things happen:
The network on the client device is automatically set as a metered connection to reduce unnecessary
bandwidth consumption on the mobile broadband network. This is done by using a Windows 8 vendor-
specific information element in the Wi-Fi beacon/probe response frame that defines the network cost. In
Windows 8.1 another vendor-specific information element in the Wi-Fi beacon/probe response frame
was added that notifies the client device if the network is a tethering network. This addition affects both
Windows 8.1 and Windows 10.
When Internet Sharing is turned on, the PC cannot go into Connected Standby or sleep to ensure that
client devices do not lose their internet connection.
You can see how much data has been used by client devices by using the mobile broadband app.
After the last client device has disconnected from the tethered network, Internet Sharing will wait for five
minutes. If no other client devices connect, Internet Sharing is turned off and the PC returns to the normal
power state.
Enterprise administrators can disable Internet Sharing by using Group Policy.
Connect to a tethered network

You can connect to a tethered network using a Wi-Fi device in the same way you connect to any other Wi-Fi
network. However, if a user connects to a tethered network with the same Microsoft account credentials on both
devices running Windows 8.1 or Windows 10, the following things happen:
If Internet Sharing is not turned on when the Windows 8.1 or Windows 10 device connects, the two
devices create a Bluetooth connection and Internet Sharing is turned on.
The connection is automatically configured (network name and SSID) by automatically retrieving the
credentials from the tethered network.
Note Users can also connect to a tethering access point if they have paired their devices by using Bluetooth.
Configure Internet Sharing

Some mobile network operators (MNOs) or mobile virtual network operators (MVNOs) do not support Internet
Sharing on their network, or they require an entitlement check prior to setting up Internet Sharing. Windows
provides the necessary controls to ensure that Windows devices comply with network policies.
To do this in Windows 8, Windows 8.1, or Windows 10 prior to version 1803, you must author a service
metadata package and configure the AllowTethering element in the schema (Service metadata package schema
reference). For more info about creating a service metadata package, see Developer guide for creating service
metadata. There are three options:
Allow Internet Sharing for all customers. (default value if not specified in the service metadata package)
Block Internet Sharing for all customers
Allow Internet Sharing for customers after an entitlement check
To do this in Windows 10, version 1803 and later, you must set the Hotspot setting in the COSA database to the
appropriate value.
If you decide that an entitlement check is not required, no additional information or capabilities are needed. If an
entitlement check is required, you must also provide a background notification event handler that is part of your
UWP mobile broadband app. In Windows 10, version 1803 and later, use the methods in the
TetheringEntitlementCheckTriggerDetails class to handle Windows notification events for checking tethering
entitlement. For earlier versions of Windows, use the NetworkOperatorNotificationEventDetails class. For
more info on creating the background notification event handler, see Enabling mobile operator notifications and
system events.
MOs and MVNOs have different requirements on what PDP context should be used for Internet Sharing.
Windows has updated the existing provisioning XML schema to enable you to provision the system with the
correct Internet Sharing PDP context information. For more information about multiple PDP contexts, see
Developing apps using multiple PDP contexts.
You can also configure the maximum number of concurrent connected client devices is 10. You can change this
number to anything between 3 and 10 by using Account provisioning.
To help ensure that your users don’t accidentally run over their data, you can show data usage statistics to your
customers for shared and non-shared traffic in your mobile broadband app by using the
GetNetworkUsageAsync method of the ConnectionProfile class.
Create a custom Internet Sharing app

For most operators, the Windows user interface will provide the best experience for Internet Sharing. However,
in order to create a consistent experience across all their devices and hardware, you may choose to include your
own Internet Sharing user experience in your mobile broadband app or other app that has been given privileged
access to the mobile broadband device. Windows provides several new APIs in the
Windows.Networking.NetworkOperators namespace to enable your app to do the following:
Ensure the system is capable of Internet Sharing
Turn on and off Internet Sharing
Query and configure the Wi-Fi SSID and passphrase for the network
Run an entitlement check
Query the number of connected devices, as well as the maximum number of connected devices allowed
Receive and react to notifications about a change in the Internet Sharing status or number of connected
devices
Developing apps using multiple PDP contexts
A Packet Data Protocol (PDP) context offers a packet data connection over which a device and the mobile
network can exchange IP packets. As per 3GPP standards, a device can have more than one PDP context
activated at a time. In Windows 8.1 and Windows 10, multiple PDP contexts are supported and enables apps to
communicate over special PDP contexts to the mobile networks along with the internet PDP context that was
supported in Windows 8. You can use this feature to create differentiated experiences and innovative services on
Windows. You can also partner with app developers to develop great quality VOIP and video streaming
experiences for their customers.
Here’s a figure that shows how multiple PDP context works in Windows 8.1 and Windows 10:
Use the following sections in this topic to learn more about multiple PDP contexts:
Key scenarios
Mobile broadband apps
Mobile broadband devices
Key scenarios
You can use multiple PDP contexts to enable premium services.
Differentiated Billing – You can vary the data or billing restrictions by using multiple PDP contexts. For
example, Contoso is a mobile operator that developed a data backup app for their customers. As a mobile
operator, Contoso could create multiple PDP contexts and let premium subscribers use the app for free.
All other subscribers are charged separately to use it.
Rich Communication Ser vices – A global initiative created by the GSM Association to provide rich
communication services, such as an enhanced phonebook, enhanced messaging, and enriched calling.
Rich Communication Services provide interoperability across mobile operators and offers new ways to
use existing assets and capabilities to deliver high quality and innovative communication services.
Sponsored Connectivity – This allows users to a specific type of content without it going against their
monthly data usage. The content provider makes an arrangement to reimburse the mobile operator by
paying them directly, doing a revenue-sharing deal, or some other business arrangement.
Personal Hotspot – Some mobile operators charge different rates when the connection is being used as
a personal hotspot. You can use multiple PDP contexts to differentiate between the two.
Mobile broadband apps

UWP mobile broadband apps can take advantage of multiple PDP contexts to activate a special PDP context and
specify rules to route data traffic. These apps can create rules for specific destinations or for all data traffic.
When the mobile broadband app needs to exchange data with the network, it checks the available and
connected networks. If the mobile broadband app has a special rule for any of these networks, it uses the
Connection Manager API to open a special PDP context. If this connection is successful, the PDP context provides
routing rules for this connection and transfers the data using networking APIs. The mobile broadband app
should repeat this if it receives the NetworkStatusChanged event to see whether any connections have
changed and whether it needs to open a PDP context for the new connection.
Networking APIs
For sending data by using a special PDP context, the Microsoft Store app must use different logic based on
networking APIs that it uses for transferring data.
HTTP-based APIs
HTTP-based APIs, such as XMLHTTPRequest , IXHR2, Windows.Web.Syndication , and
Windows.Web.AtomPub , and APIs based on the Windows HTTP protocol, such as JQuery and
Windows.Web.Http , do not have the ability to bind to a specific interface. For these APIs, Windows handles the
routing of data to a special PDP context by using policies. Once the special PDP context is activated, the app can
specify routing rules based on destination and special PDP context. The destination can be domain name or IP
address, such as video.fabrikam.com, .contoso.com, or 123.23.34.333. After specifying the routing rules, if the
app uses any of the above HTTP APIs to transfer the data, Windows will send the data to the special PDP context
based on routing rules. Once the app has finished transferring data, it should disconnect the special PDP context
and remove the route policy.
NOTE
Background Transfer APIs and HTTP Client(C#) APIs cannot use a route policy.
Socket-based APIs
Socket-based APIs available in the Windows.Networking.Sockets namespace, such as TCP, UDP, and stream
sockets, provide a mechanism to bind to a specific interface. When an app uses the socket APIs, it should bind to
specific interface for routing data to the special PDP context. Once the special PDP context is activated, the
AcquireConnectionAsync API provides the interface information to the app. It can use this information to
bind to a specific interface and start transferring the data.
Multiple PDP content API info

Windows 8.1 and Windows 10 have added the following APIs to support multiple PDP contexts:
CellularApnContext This class contains properties used to specify an access point on a network. An
CellularApnContext object is passed with an AcquireConnectionAsync call to establish a connection
to a specific access point.
ConnectivityManager ::AcquireConnectionAsync This API activates a new connection for a specified
Access Point Name (APN) or PDP context. This asynchronous method allows an app to request a
connection to a specific APN or PDP context with the appropriate configuration information. After the
special APN is activated, it appears as a new virtual interface to Windows and apps.
ConnectivityManager ::AddHttpRoutePolicy This method adds a policy to be used by the HTTP stack
traffic for routing data to a special PDP context. The app can specify the policy based on destinations, such
as domain name and IP address, and special PDP context profile. The Windows HTTP stack uses the policy
for routing the data to the special PDP context once the app has created the policy.
ConnectivityManager ::RemoveHttpRoutePolicy This method removes a previously added HTTP
route policy.
The following code shows how to use these APIs for an HTTP-based data transfer:
var connectivity = Windows.Networking.Connectivity;
var currentRoutePolicy = null;
var currentConnectionSession = null;
// Create PDP context/APN data

var apnContext = new connectivity.CellularApnContext();
apnContext.accessName = "myAPN.com";
apnContext.userName = "APNusername"
apnContext.password = "[PLACEHOLDER]";
apnContext.isCompressionEnabled = false;
apnContext.authenticationType = connectivity.CellularApnAuthenticationType.none;
// Request a connection to Windows

connectivity.ConnectivityManager.acquireConnectionAsync(apnContext).done(onConnectionSucceeded,
onConnectionFailed);
// On successful Activation of APN, Windows returns a ConnectionSession object that encapsulates the new
connection profile
function onConnectionSucceeded(result
{
// keep the connectionSession in scope
currentConnectionSession= result;
// create a route policy for the new connection

currentRoutePolicy = new connectivity.routePolicy(currentConnectionSession.ConnectionProfile, new
hostName("video.mydomain.com"),Windows.Networking.DomainNameType.suffix);
// indicate the new route policy to the Http stack

connectivity.connectivityManager.addHttpRoutePolicy(currentRoutePolicy);
// Backend data interaction with appropriate HTTP APIs (IXHR, Open IFrame etc.)
// After completing the data transfer remove the Route Policy

connectivity.connectivityManager.removeHttpRoutePolicy(currentRoutePolicy);
currentRoutePolicy = null;
// Disconnect the PDP Context to free up resources

currentConnectionSession.close();
}
The following code shows you how to use these APIs for a socket-based data transfer:
// Connect to Special PDP Context
// Create PDP Context/APN Data

// Create PDP context/APN data

apnContext.accessName = "myAPN.com";
// Request the connection to Windows

connectivity.ConnectivityManager.acquireConnectionAsync(apnContext).done(onConnectionSucceeded,
// On successful activation of an APN, Windows returns a ConnectionSession object that encapsulates the new
connection profile
function onConnectionSucceeded(result) {

currentConnectionSession = result;
var socket = new Windows.Networking.Sockets.StreamSocket();

var hostName = new Windows.Networking.HostName("www.contoso.com");
var portNumber = "1234";
// Bind the socket to new Special PDP Context Connection

socket.connectAsync(hostName, portNumber, SocketProtectionLevel.PlainSocket,
currentConnectionSession.connectionProfile.networkAdapter).done(onSocketConnectionSucceeded,
onSocketConnectionFailed);
function onSocketConnectionSucceeded(result)
{
// Start transferring data using socket APIs
// Closing the sockets

socket.close();

Your app must handle NetworkStatusChanged event to handle any network transitions on the special PDP
context connection.
Scenario: Premium mobile broadband app provides free data access using special APN
In this scenario, the mobile broadband app provides free data access using a special PDP context. The app either
uses a connected network, such as a Wi-Fi network, if it is free or it uses a special APN if connected to a specific
operator network. The following sample code illustrates how an app can use the multiple PDP context APIs for
transferring data on a special PDP context if no free networks are connected.
// Reference the namespace

// Current route policy

function onLoad()
{
// Register for network status change
connectivity.networkInformation.addEventListener("networkstatuschanged", OnNetworkStatusChange);
// Process the current status
handleNetworkChange();
}
// Handle newtork status changes

function onNetworkStatusChange()
{
HandleNetworkChange();
}
// On network status change:

// if there is no connectionPolicy, evaluate a new one
// if there is a current connectionPolicy ==> verify it is still valid
// evaluate a new one if the current connectionPolicy is not valid
function handleNetworkChange()
{
if (isCurrentPolicyStillValid())
{
//the current policy is still valid.
return;
}
// No policy or current policy is not good anymore

// cleanup any previous configuration
if (currentRoutePolicy)
{
connectivity.ConnectivityManager.removeHttpRoutePolicy(currentRoutePolicy);
}
// if a different APN was connected, disconnect it to free up resources

if (connectionConnectionSession != null)
{
connectionConnectionSession.close();
connectionConnectionSession = null;
}
// evaluate connection policy

startEvaluateConnectionPolicy();
}
// evaluate if the current connectionPolicy is still valid

function isCurrentPolicyStillValid()
{
if (null != currentRoutePolicy)
{
// a policy is currently in place, let's verify if it is still valid
var currentProfile = currentRoutePolicy.connectionProfile();
if (NetworkConnectivityLevel.none != currentProfile.GetNetworkConnectivityLevel())
{
// current policy is still good. bail out
return true;
}
}
return false;
}
// starts the evaluation of a new connection policy

function startEvaluateConnectionPolicy()
{
// first try to get a free network if it is available
var queryFilter = new connectivity.connectionProfileFilter();
queryFilter.networkCostType = connectivity.networkCostType.unrestricted;
queryFilter.isConnected = true;
connectivity.networkInformation.findConnectionProfilesAsync(queryFilter).done(onSuccess, onFailure);
}
// Succesfully retrieved at least one free connection profile

function onSuccess(results)
{
if(results.count > 0)
{
// Enfore the route to the http stack
enforceHttpRoutePolicy(results[0]);
// Backend data interaction with appropriate APIs(Open IFrame etc.)
}
else
{
onFailure();
}
}
// there are no free networks available at this time

function onFailure()
{
// create a request to connect a specific APN on the network
// no free network available, connect
apnContext.accessPointName = "myAPN.com";
//
// request the connection to Windows
connectivity.connectivityManager.acquireConnectionAsync(apnContext).done(onConnectionSucceeded,
}
// on success Windows returns a ConnectionSession object that encapsulates the new connection profile
function onConnectionSucceeded(result)
{
enforceHttpRoutePolicy(currentConnectionSession.ConnectionProfile,new
// Windows was not able to connect the specified APN

function onConnectionFailed()
{
// display error message and just wait for Network Status Change event to try again
}
// utility function to enforce a route policy

function enforceHttpRoutePolicy(connectionProfile,targetSuffix)
{
// Keep the route request global so we can close it later
currentRoutePolicy= new connectivity.routePolicy(connectionProfile, targetSuffix);
// Indicate the new route policy to the Http stack
}
// cleanup on shutdown
function onShutdown()
{
{
// Remove the route policy from HttpStack
// If a different APN was connected, disconnect it to free up resources

if(currentConnectionSession!= null)
{
}
}
Scenario: Mobile broadband app requires special PDP Context for subscription purchase and provisioning
In this scenario, the mobile broadband app requires a special PDP context for subscription purchase and
provisioning. This app will activate a special PDP context regardless of the connected network.
function onLoad()
{
// Register for network status change
connectivity.networkInformation.addEventListener("networkstatuschanged", OnNetworkStatusChange);
// Process the current status
handleNetworkChange();
}
function onNetworkStatusChange()
{
HandleNetworkChange();
}
// Create the PDP Context/APN Data

apnContext.providerId = "23545";
apnContext.accessPointName = "myAPN.com";
// Request the connection to Windows

connectivity.connectivityManager.acquireConnectionAsync(apnContext).done(onConnectionSucceeded,
// On successful connection to PDP Context, Windows returns a ConnectionSession object that incapsulate
the new connection profile
function onConnectionSucceeded(result)
{

currentRoutePolicy = new connectivity.routePolicy(currentConnectionSession.ConnectionProfile, new
// indicate the new route policy to the Http stack

// After completing the data transfer remove the Route Policy


function handleNetworkChange()
{
// App behavior to handle network
var currentProfile = currentRoutePolicy.connectionProfile();
if (NetworkConnectivityLevel.none != currentProfile.GetNetworkConnectivityLevel())
{
// The special PDP Context is disconnected, app should handle this. It can request another connection to
special PDP Context or it can show error to the user.
}
}
Considerations for mobile broadband apps
Mobile broadband apps can get local data usage information for each PDP context and influence Windows with
policies for special PDP contexts.
Local data usage
In Windows 8, you provide an ongoing subscription-based relationship with users through your mobile
broadband app which has the ability to show current data usage. Users can view their current data usage and
understand their billing cycle or session end date to make an appropriate decision. To reduce the load on the
network as much as possible, you should check the data usage with the network periodically. Windows provides
a local Data Usage API that you can use to combine with data usage to show the current data usage to user.
A special PDP context provides you the ability to differentiate data access charges to certain apps or services.
Each different PDP context is treated as a different profile for local data usage counters. The mobile broadband
app can query the local data usage for each PDP context for a particular duration, similar to how the internet
PDP context worked in Windows 8. You can use this information to show appropriate data usage experience to
the user.
The following sample code demonstrates how you can use the networking APIs to read local data usage for all
PDP contexts:
// Get the network account ID.

IReadOnlyList<string> networkAccIds =
Windows.Networking.NetworkOperators.MobileBroadbandAccount.AvailableNetworkAccountIds;
if (networkAccIds.Count == 0)
{
rootPage.NotifyUser("No network account ID found", NotifyType.ErrorMessage);
return;
}
// For the sake of simplicity, assume we want to use the first account.
// Refer to the MobileBroadbandAccount API's how to select a specific account ID.
string networkAccountId = networkAccIds[0];
// Create mobile broadband object for specified network account ID

var mobileBroadbandAccount =
Windows.Networking.NetworkOperators.MobileBroadbandAccount.CreateFromNetworkAccountId(networkAccountId);
// Get all connection profiles associated with this network account ID

var connectionProfiles = mobileBroadbandAccount.GetConnectionProfiles();
// Collect local usages for last one hour

DateTime endTime = DateTime.Now;
TimeSpan timeDiff = TimeSpan.FromHours(1);
DateTime startTime = endTime.Subtract(timeDiff);
string message = string.Empty;
foreach (var connectionProfile in connectionProfiles)

{
// Display local usages for each connection profiles
DataUsage localUsage = connectionProfile.GetLocalUsage(startTime, endTime);
message += "Connection Profile Name: " + connectionProfile.ProfileName + "\n\n";
message += "Local Data Usage from " + startTime.ToString() + " to " + endTime.ToString() + ":\n";
message += " Bytes Sent : " + localUsage.BytesSent + "\n";
message += " Bytes Received : " + localUsage.BytesReceived + "\n\n";
}
// Print the message string
Policies
Some operators have indicated that special PDP contexts have limited bandwidth. Apps that activate the special
PDP context but do not have access to use the special PDP context can create a denial of service attack. You
should restrict the usage of special APNs to specific apps with a business relationship. You are able to provide
Windows a list of UWP apps with special APN names. Windows will use that information to limit the access to
special APNs. If you do not provide a list, Windows assumes that the special PDP context is open for all apps.
NOTE
This is just to avoid extra traffic on special PDP contexts. You cannot rely on this as a security mechanism for restricting
apps to special PDP contexts. If you would like to restrict access to special PDP contexts, you must implement some
authentication or security mechanism on your network. For example, you could use a filter that allows only certain IP
addresses for a specific PDP context.
Some mobile networks do not support multiple PDP contexts. You can provision whether your network
supports multiple PDP context or not. If your network doesn’t support multiple PDP contexts, Windows should
not allow apps to create on-demand connections on special APNs. By default, Windows assumes you support
multiple PDP contexts.
The following sample XML file demonstrates how to use Windows provisioning metadata to provide an allowed
app list for special PDP contexts:
<Global>


</Global>
<Extensions>
<Extensions_v2 xmlns="http://www.microsoft.com/networking/CarrierControl/v2">
<AdditionalPDPContexts>
<MultiplePDPContextPolicies MultiplePDPContextSupport="true">
<PDPContextPolicy>

<Name>Contoso1</Name>
<Context>

<AccessString>Contoso.Contoso1</AccessString>

<UserLogonCred>
<UserName>user1</UserName>
</UserLogonCred>
</Context>
<AppIDList>

<AppID>Contoso.Sample1.CS_dsarewaj</AppID>
<AppID>Contoso.Sample2.CPP_dsarewaj</AppID>
</AppIDList>
</PDPContextPolicy>
<PDPContextPolicy>
<Name>Contoso2</Name>
<Context>
<AccessString>Contoso.Contoso2</AccessString>
UserLogonCred. -->
<UserLogonCred>
<UserName>user2</UserName>
</UserLogonCred>
</Context>
<AppIDList>

<AppID>Contoso.Sample3.CS_dsarewaj</AppID>
<AppID>Contoso.Sample4.CPP_dsarewaj</AppID>
</AppIDList>
</PDPContextPolicy>
</MultiplePDPContextPolicies>
</AdditionalPDPContexts>
</Extensions_v2>
</Extensions>
Audio and video streaming

Audio streaming apps can play audio or video streams using a special PDP context. Similar to HTTP APIs, your
app can use the following logic to play audio or video by using the <audio> or <video> tag.
You can use video frameworks based on the WinInet APIs.
InstantGo
InstantGo provides an instant on, instant off user experience that users have come to expect on their phone. And
just like on the phone, InstantGo enables the system to stay fresh, up-to-date, and reachable whenever a suitable
network is available. InstantGo on low-power PCs platforms must meet specific Windows Certification
requirements.
The following scenarios are supported in InstantGo:
Updating live tiles with fresh content
Receiving email
Downloading files from, or uploading them to, a website
Sharing content, such as photos on a website
Receiving instant messages
Receiving VoIP calls
Communicating in real-time
Playing background audio and music
For more info on InstantGo, see Introduction to InstantGo.
Your mobile broadband app can use a special PDP context for enabling some of these InstantGo scenarios. You
need to use following logic to reconnect to the special PDP context if it is disconnected because it is out of
coverage. When the device enters the Connected Standby power state, Windows will disconnect all the
connections to special PDP contexts after 10 minutes and your app has to request the connection again.
Audio streaming in background

Audio streaming apps can audio in background and in the Connected Standby power state by using a special
PDP context. For more info on how to play audio in the background, see How to How to play audio in the
background.
Real-time communication apps
Real-time communication apps, such as VoIP or chat apps, can receive a wake up trigger on a special PDP
context. The wake up trigger allows your app to be triggered at all times including when the system is in the
Connected Standby power state.
To enable this scenario, the mobile broadband device should support wake up filters on special PDP context, as
stated in the Mobile Broadband Interface Model (MBIM) specification.
Mobile broadband devices

To support multiple PDP contexts, the firmware of the mobile broadband Device must support multiple PDP
contexts, as defined in the MBIM specification. It must also pass any Windows Hardware Certification Kit tests
specific to multiple PDP contexts.
Since this feature is operator specific, it is optional for mobile broadband devices. If you need this feature, you
must add multiple PDP context functionality in the operator requirements with the following:
The device firmware should support multiple IP data streams as detailed in section 10.5.12.1 of the MBIM
specification. This includes supporting all the control implementation of CIDs and IP data streams for full
support of multiple PDP contexts.
The device firmware must support multiple dual bearer (IPv4 & IPv6) PDP contexts for use by Windows.
This includes 1 for internet connectivity and additional PDP contexts for mobile broadband apps,
according to your requirements.
This does not require device-managed PDP contexts that the firmware may use for SMS and other
administrative contexts.
The device firmware should be able to leverage a host operating system request gracefully for a PDP
context that is already device-managed internally in its firmware.
The device firmware should continue to abstract SMS PDP contexts and route them through the SMS
CIDs regardless of the bearer used underneath.
Introduction to developing SMS apps
Windows 8, Windows 8.1, and Windows 10 provide a Short Message Service (SMS) text messaging platform for
mobile network operators, mobile broadband adapter IHVs, OEMs, and their partnered software vendor’s app
with SMS access into a UWP app.
Note A mobile broadband app requires SMS support to show notifications to the end user when text
messages are received. SMS might also be required to conform to regulatory requirements or best practices in
certain markets.
The Mobile Broadband SMS platform provides the following functionality:
Send and read SMS data in text-mode or PDU-mode (binary)
Filter for data cap overage, roaming, and other administrative SMS operator notifications
New SMS received background event
Read and delete messages from the mobile broadband device message store
Get properties of the mobile broadband device
SMS API access prompt
The sections in this topic include:
Mobile broadband SMS supported devices
Access to mobile broadband SMS
SMS notifications filtering
Developing your SMS app
Mobile broadband SMS supported devices

Here’s an overview diagram on how the SMS works with a mobile broadband connection:
Basic requirements
The computer must be running Windows 8, Windows 8.1, or Windows 10, a mobile broadband device,
and active service from a mobile network operator.
The device should be hardware certified for Windows 8, Windows 8.1, or Windows 10 with the SMS
send/receive capabilities set.
Both internal and external devices are supported.
Global System for Mobile Communications (GSM)- and Code division multiple access (CDMA)-based
devices are both supported.
Additional guidance for a better user experience
An SMS message can be sent or received by an app when the device is in a network coverage area for the
supported operator. Devices must be registered to the network service provider, but do not need to be
connected to data services to send or receive messages.
Sending or receiving SMS data while on a roaming network is subject to additional fees based on the
mobile network operator (MNO) policy.
Devices cannot send or receive SMS data if the device is PIN locked.
Access to mobile broadband SMS

UWP app access to SMS
Access to mobile broadband SMS functionality is available in the following ways:
Mobile network operators can provide users with SMS functionality by using a mobile broadband app.
Mobile broadband adapter IHVs who build open market mobile broadband adapters can enable a mobile
broadband app to access SMS.
OEMs who build computers that have embedded mobile broadband adapters can enable a mobile
broadband app to access SMS.
UWP apps can be given privileged access to SMS by a mobile operator, mobile broadband adapter IHV, or
OEM.
Access to SMS is specified in service metadata or device metadata. Device metadata package is a set of XML files
that create the link between a particular device and its UWP device app. The link is based on the HardwareId of
IHV mobile broadband adapter, or computer hardware IDs of the computer device container for OEMs who build
computers that have embedded mobile broadband adapters.
For more information about service metadata, see Service metadata.
For mobile network operators and mobile broadband adapters IHVs, Windows 8, Windows 8.1, and Windows 10
automatically download and install the mobile broadband app from the Microsoft Store when users connect
their device for the first time. In Windows 8.1 and Windows 10 the mobile broadband app is added to the All
Apps view.
Mobile broadband apps and IHV apps have simultaneous access SMS for a single mobile broadband device. If
both a mobile broadband app and an IHV or OEM UWP app are installed and both show a notifications user
interface when a new SMS is received, the users see two notification UIs. The user can turn off notifications or
uninstall one of the apps.
User consent to SMS access
Mobile broadband apps must obtain user consent to use SMS because sending messages from the user's device
can cause the user to be charged for sending or receiving messages by their cellular service provider.
Users running Windows 8, Windows 8.1, or Windows 10 can control access to SMS capability at an app level by
using the Settings charm.
Note Together with user consent, the app must also have access granted by the device by adding the app
name in the device or service metadata.
SMS notifications filtering

The Mobile Broadband SMS platform filters newly received SMS data into two types: administrative SMS
notifications from a mobile network operator (MNO), and general SMS messages. Administrative SMS
notifications that are received from an MNO are only accessible to a mobile broadband app, and are hidden
from general SMS client apps.
MNOs specify custom filtering rules for administrative SMS notifications in the Windows Provisioning platform.
If no message filtering rules are specified, the SMS platform classifies all SMS messages as general SMS
messages that are available to any app.
For more information about notification filtering, see Enabling mobile operator notifications and system events.
Developing your SMS app

You can write JavaScript, C#, or C++ apps that use the Windows.Devices.Sms API to send, read, and delete
messages.
Note The Windows 7 Mobile Broadband SMS API provided only a low-level modem interface for SMS.
Windows 8, Windows 8.1, and Windows 10 provide an alternate text-mode interface that is suitable for general
app development.
SMS client apps should use SMS device storage as a message queue. Total SMS storage on devices varies, but
device storage is commonly limited to 30 messages.
The Mobile Broadband SMS platform is designed to maintain the ability to receive new incoming SMS messages
by freeing up SMS device storage space while minimizing deletion of user data.
Devices can’t receive new SMS messages if SMS storage becomes full. Windows automatically deletes old SMS
messages from device storage to ensure the ability to receive new incoming SMS data, such as important
mobile network operator notifications.
We recommend the following:
SMS client apps should use local app storage to maintain message history instead of relying on device
SMS storage.
SMS client apps should not delete messages on read. SMS client apps should let Windows automatically
delete old messages when device storage gets full.
Related topics
Developing SMS apps
The Mobile Broadband SMS platform provides the ability to get the first SMS-capable mobile broadband device,
or to get a list of all SMS-capable mobile broadband devices. The following sample code shows instantiating an
SMS object with the default SMS device and with a specific device.
Note In apps that use C# or C++ in Windows 8, Windows 8.1, or Windows 10, the first use of the SmsDevice
object to call GetDefaultAsync or FromIdAsync should be on the STA thread. Calls from an MTA thread can
result in undefined behavior.
JavaScript code example to use the default SMS device
var smsDevice = new Windows.Devices.Sms.SmsDevice.getDefault();
try
{
var smsDeviceOperation = Windows.Devices.Sms.SmsDevice.getDefaultAsync();
smsDeviceOperation.done(smsDeviceReceived, errorCallback);
}
catch (err)
{
// handle error
}
JavaScript code example to enumerate all SMS devices
Windows.Devices.Enumeration.DeviceInformation.findAllAsync(Windows.Devices.Sms.SmsDevice.getDeviceSelector()
).then(function (smsdevices)
{
if (smsdevices.length > 0)
{
// for simplicity we choose the first device
var smsDeviceId = smsdevices[0].Id;
var smsDeviceOperation = Windows.Devices.Sms.SmsDevice.fromIdAsync(smsNotificationDetails.deviceId);
smsDeviceOperation.done(function (smsDeviceResult)
{
smsDevice = smsDeviceResult;
}, errorCallback);
}
}
Detect SMS device access errors

You can detect if enumerating the SMS device failed because the app does not have access to SMS. This can
happen if the user explicitly denies access to the app or if the device metadata has not granted access to the app.
JavaScript code example to detect SMS device access errors
Windows.Devices.Enumeration.DeviceInformation.findAllAsync(Windows.Devices.Sms.SmsDevice.getDeviceSelector()
).then(function (smsdevices)
{
if (smsdevices.length > 0)
{
// for simplicity we choose the first device
var smsDeviceId = smsdevices[0].Id.slice(startIndex,endIndex + 1);
var smsDeviceOperation = Windows.Devices.Sms.SmsDevice.fromIdAsync(smsNotificationDetails.deviceId);
smsDeviceOperation.done(function (smsDeviceResult)
{
smsDevice = smsDeviceResult;
}, errorCallback);
// detect if SMS access is denied due to user not granting app consent to use SMS or if metadata is
missing or invalid.
function errorCallback(error)
{
WinJS.log(error.name + " : " + error.description, "sample", "error");
// If the error was caused due to access being denied to this app
// then the HResult is set to E_ACCESSDENIED (0x80007005)
// var hResult = hex(error.number);
function hex(nmb)
{
if (nmb >= 0)
{
return nmb.toString(16);
}
else
{
return (nmb + 0x100000000).toString(16);
}
}
Related topics
Developing SMS apps
The Mobile Broadband SMS platform provides information about the mobile broadband device, including
account phone number, status, and cellular class.
JavaScript code example for getting an SMS device mobile number
var mobileNumber = smsDevice.accountPhoneNumber;
Related topics
Developing SMS apps
Read received SMS by using the text-mode
interface
You can choose between using the text-mode read interface, which is suitable for simple plain text SMS
messages, or the PDU-mode mode read interface, which is suitable for advanced control of decoding SMS
messages.
Received messages are stored in encoded format on mobile broadband devices. The Mobile Broadband SMS
platform supports decoding received messages to plain text. The character sets that are supported for decoding
received messages are the same as the character sets supported for encoding messages sent.
The following table lists the character encodings supported by the text-mode API:
C H A RA C T ER L IM IT F O R
C H A RA C T ER L IM IT F O R M ULT I- PA RT SM S
N ET W O RK T Y P E C H A RA C T ER SET S SIN GL E SM S SEGM EN T SEGM EN T S
GSM GSM 7-bit default 160 142

alphabet and GSM 7-
bit default alphabet
extension table
CDMA 7-bit ASCII 160 (can vary by

network)
CDMA Unicode 70 (can vary by

network)
JavaScript code example for reading received SMS messages using the text-mode interface
try
{
if (smsDevice!= null)
{
var messageStore = smsDevice.messageStore;
var messageID = id('whichMessage').value;
var getSmsMessageOperation = messageStore.getMessageAsync(messageID);
getSmsMessageOperation.operation.completed = function ()
{
result = getSmsMessageOperation.operation.getResults();
var readableMessage = new Windows.Devices.Sms.SmsTextMessage.fromBinaryMessage(result);
id('fromWho').innerHTML = readableMessage.from;
id('fromMessageBody').innerHTML = readableMessage.body;
console.log("Successfully retrieved message " + messageID + " from message store.");
}
getSmsMessageOperation.operation.start();
}
else
{
console.log("No SMS Device Found");
}
}
catch (err)
{
console.log("SMS did not set up: " + err);
}
Note SMS client apps can use the decoded segmentation information that is provided by Windows to
concatenate multiple segments of a long message and reconstruct the full message. For more info about
segmented SMS messages, see Windows automatically segments long messages.
Related topics
Developing SMS apps
The Mobile Broadband SMS platform provides separate system events for new SMS data that is received,
depending on whether it’s an administrative SMS notification from a mobile network operator or a general SMS
message. The background system event for a new administrative SMS notification that is received from a mobile
network operator is only accessible by a mobile broadband app.
Apps must have already received user consent to use SMS to read new received SMS messages in a background
tasks. Apps cannot read the contents of a new received SMS message from a background task if they are
accessing SMS for the first time, because the app cannot trigger the system SMS device consent prompt from a
background task.
The following code examples demonstrate a background task that is designed to run when a new SMS message
is received.
C# background task code
namespace SmsBackgroundSample
{
public sealed class SmsBackgroundTask : IBackgroundTask
{
// The Run method is the entry point of a background task.
public void Run(IBackgroundTaskInstance taskInstance)

{
// Associate a cancellation handler with the background task.
taskInstance.Canceled += new BackgroundTaskCanceledEventHandler(OnCanceled);
ManualResetEvent manualEventWaiter = new ManualResetEvent(false);

manualEventWaiter.Reset();
// Do the background task activity.
DisplayToastAsync(taskInstance, manualEventWaiter);
// Wait until the async operation is done. We need to do this else the background process will exit.
manualEventWaiter.WaitOne(5000);
Debug.Print("Background " + taskInstance.Task.Name + (" process ran"));
async void DisplayToastAsync(IBackgroundTaskInstance taskInstance, ManualResetEvent manualEventWaiter)

{
SmsReceivedEventDetails smsDetails = (SmsReceivedEventDetails)taskInstance.TriggerDetails;
SmsBinaryMessage smsEncodedmsg = (SmsBinaryMessage) smsDetails.BinaryMessageMessage;
SmsTextMessage smsTextMessage = Windows.Devices.Sms.SmsTextMessage.FromBinaryMessage(smsEncodedmsg);
XmlDocument toastXml = ToastNotificationManager.GetTemplateContent(ToastTemplateType.ToastText02);

XmlNodeList stringElements = toastXml.GetElementsByTagName("text");
stringElements.Item(0).AppendChild(toastXml.CreateTextNode(smsTextMessage.From));
stringElements.Item(1).AppendChild(toastXml.CreateTextNode(smsTextMessage.Body));
ToastNotification notification = new ToastNotification(toastXml);

ToastNotificationManager.CreateToastNotifier().Show(notification);
manualEventWaiter.Set();
}
JavaScript app code to register background task
var triggerAway = new

Windows.ApplicationModel.Background.SystemTrigger(Windows.ApplicationModel.Background.SystemTriggerType.smsR
eceived, false);
var builderAway = new Windows.ApplicationModel.Background.BackgroundTaskBuilder();
builderAway.setTrigger(triggerAway);
builderAway.taskEntryPoint = "HelloWorldBackground.BackgroundTask1";
builderAway.name = "Sms";
var taskAway = builderAway.register();

taskAway.addEventListener("progress", new ProgressHandler(taskAway).onProgress);
taskAway.addEventListener("completed", new CompleteHandler(taskAway).onCompleted);
Related topics
Developing SMS apps
If you need access to raw message protocol data units (PDU) to achieve scenarios that are not supported by the
text-mode interface, Windows 8, Windows 8.1, and Windows 10 enable PDU-mode sending and reading
received SMS messages.
You might need to use the PDU-mode SMS interface in the following cases:
To send or read received SMS by using a National Language Single Shift Table or National Language
Locking Shift Table as defined in 3GPP TS 23.038.
To send multi-part SMS using different character sets for each segment.
JavaScript code example to send SMS messages by using the PDU-mode interface
function smsDevicePDUSend()
{
if (smsDevice !== null)
{
// Defines a binary message
var smsMessage = new Windows.Devices.Sms.SmsBinaryMessage();
var messsagePdu = “0011000B914152828377F90000AA0CC8F71D14969741F977FD07”;
var messagePduByteArray = hexToByteArray(messsagePdu);
smsMessage.setData(messagePduByteArray);
if (smsDevice.cellularClass === Windows.Devices.Sms.CellularClass.gsm)

{
smsMessage.format = Windows.Devices.Sms.SmsDataFormat.gsmSubmit;
}
else
{
smsMessage.format = Windows.Devices.Sms.SmsDataFormat.cdmaSubmit;
}
var sendSmsMessageOperation = smsDevice.sendMessageAsync(smsMessage);
sendSmsMessageOperation.done(function (reply) {
WinJS.log("Sent message in PDU format", "sample", "status");
}, errorCallback);
}
// Used to convert hex PDU to byte array for sending SMS using PDU //mode
function hexToByteArray(hexString)
{
var result = [];
var hexByte = "";
var decByte = 0;
for (var i = 0; i < hexString.length; i = i + 2) {
hexByte = hexString.substring(i, i + 2);
decByte = parseInt(hexByte, 16);
result.push(decByte);
}
return result;
}
JavaScript code example to read received SMS messages by using the PDU-mode interface
function smsDeviceRead()
{
try
{
if (smsDevice !== null)
{
var messageStore = smsDevice.messageStore;
var messageID = “1” // select a Message Id to read
// Check for a valid ID number

if (isNaN(messageID) || messageID < 1 || messageID > messageStore.maxMessages)
{
WinJS.log("Invalid ID number", "sample", "error");
return;
}
var getSmsMessageOperation = messageStore.getMessageAsync(messageID);
// Display message when get is completed

getSmsMessageOperation.done(smsMessageReadSuccess, errorCallback);
}
}
catch (err) {
// handle error
}
}
function smsMessageReadSuccess(smsMessage)
{
try
{
if (smsMessage instanceof SmsBinaryMessage) {
var format = smsMessage.format;
var pduData = smsMessage.getData(); // byte array
}
catch (err)
{
WinJS.log("SMS did not set up: " + err, "sample", "error");
}
}
Related topics
Developing SMS apps
Calculate characters and segments of a draft SMS
The Mobile Broadband SMS platform provides a function to estimate the number of characters remaining and
number of segments used (in a multi-part messages) during the composition of an SMS message.
Note The number of characters in each segment is not constant, and it varies based on the text string in the
message body and the network type. On GSM networks, a single SMS message supports up to 160 7-bit
characters or 70 16-bit characters. A message that spans multiple segments supports 142 7-bit characters in
each segment due to additional header information.
Providing an accurate estimate on the number of segments that are used while composing an SMS message
promotes user confidence, because users are typically charged per SMS message that is sent.
JavaScript code example
var smsMessage = new Windows.Devices.Sms.SmsTextMessage();

smsMessage.body = id('messageText').value; // Set message body text to text of messageText HTML element
var messageLength = smsDevice.calculateLength(smsMessage);
id('remainingCharsCount').innerText = messageLength.charactersPerSegment -
messageLength.characterCountLastSegment;
id('messageSegmentsCount').innerText = messageLength.segmentCount;
Related topics
Specify mobile telephone numbers
Telephone numbers must be specified in ITU E.164 format. SMS clients are encouraged to store telephone
numbers in ITU E.164 international format and use a library to convert ITU E.164-format telephone numbers
into a regional, common written format.
The following table is an example:
REGIO N IT U E. 164 IN T ERN AT IO N A L C O M M O N W RIT T EN F O RM AT
United States of America +15551234567 (555) 123-4567
SMS short codes

SMS short codes that have short phone numbers that are four to six digits long and are typically used to
communicate with automated mobile network operator services are supported.
Related topics
Windows automatically segments long messages
The Mobile Broadband SMS platform automatically segments long messages that are sent on GSM networks
into separate segments that fit in the supported maximum character limit based on message contents.
Segmentation information (that is, part 1 of 2) is encoded in SMS User Data Header (UDH), to enable the
receiving SMS client to combine segments into a single message. All segments of a multi-part SMS are encoded
by using the same character set.
Mobile network operators charge users per message segment. SMS platform automatically creates a maximum
of 10 segments and truncates text above the limit.
Related topics
Windows automatically selects optimal character
encoding
Windows 8, Windows 8.1, and Windows 10 choose the optimal character encoding to use when it sends a SMS
message, based on the most efficient encoding that is supported by the message contents. SMS is encoded in a
7-bit character set, unless it contains at least one invalid character, in which case the whole message is encoded
in Unicode.
JavaScript code example for sending SMS messages using text-mode

interface
try
{
if (smsDevice != null)
{
// defines a text message
var smsMessage = new Windows.Devices.Sms.SmsTextMessage();
smsMessage.to = id("phoneNumber").value;
smsMessage.body = id("messageText").value + "\n\nSent via Windows 8 SMS API";
var sendSmsMessageOperation = smsDevice.sendMessageAsync(smsMessage);
console.log("Sending message...");
sendSmsMessageOperation.then(function (reply)
{
console.log("Text message sent.");
});
}
else
{
console.log("No SMS device found");
}
} catch (err) {
console.log("SMS exception: " + err);
}
Optionally, you can override the optimal encoding functionality and specify which character set to use.
Windows 8, Windows 8.1, and Windows 10 support common character sets for mobile broadband network
adapters that are compatible with GSM (3GPP) and CDMA (3GPP2) networks.
The following table lists the character encodings supported by the text-mode API:
C H A RA C T ER L IM IT F O R
C H A RA C T ER L IM IT F O R M ULT I- PA RT SM S
N ET W O RK T Y P E C H A RA C T ER SET S SIN GL E SM S SEGM EN T SEGM EN T S
GSM GSM 7-bit default alphabet 160 142

and GSM 7-bit default
alphabet extension table
CDMA 7-bit ASCII 160 (can vary by network)
CDMA Unicode 70 (can vary by network)

GSM character sets are defined 3GPP TS 23.038: "Alphabets and language-specific information". CDMA
character sets are defined in 3GPP2 C.R1001-D.
Related topics
SMS device capability declaration in package manifest

A UWP app that uses SMS must declare SMS capability in its package manifest in Visual Studio.
Example package.appxmanifest :
<Capabilities>
<DeviceCapability Name="sms" />
</Capabilities>
For more information, see App capability declarations (UWP apps).
SMS app declaration in device metadata

The mobile broadband device can determine which apps it trusts to send and receive SMS messages. To do so, it
adds the package name that it trusts in the Service metadata, as shown in the following entry:
\Package\SoftwareInformation\SoftwareInfo.xml
<Package>
<Identity Name="Microsoft.SDKSamples.SMSSendReceive.JS" Version="1.0.0.0" Publisher="CN=Contoso
Corporation, O=Contoso Corporation, L=Redmond, S=Washington, C=US" />
</Package>
Related topics
Developing SMS apps
Introduction to enabling mobile broadband (MB)
experiences using portable hotspot devices
The topics in this section provide information about portable Wi-Fi hotspots for Windows 8, Windows 8.1, and
Windows 10. It provides guidelines for device manufacturers to offer experiences on a Wi-Fi hotspot that is
backed by mobile broadband (including a mobile phone), that are similar to experiences that Windows offers on
a native mobile broadband connection.
Windows 8, Windows 8.1, and Windows 10 modify operating system behavior for metered networks and
provides cost information to applications so they can do the same. However, without input from the carrier, the
default assumptions are that mobile broadband is metered and that Wi-Fi and Ethernet are unrestricted.
Because Windows cannot detect the second-hop media type, the operating system cannot provide defaults that
account for mobile broadband-backed Wi-Fi networks.
By leveraging the features that are described in this topic, a device manufacturer can provide the appropriate
feedback to Windows about the second hop and thereby enable these features to function correctly when the
mobile broadband interface is not directly attached to the computer.
In collaboration with the operator, a manufacturer can optionally offer a UWP mobile broadband app that allows
the user to reference their account, including data usage.
The following topics are available in this section:
Related topics
Personal hotspot communication channels
Because the mobile broadband interface is not directly attached to the computer, information from the operator
must be exchanged by using the personal hotspot device, as shown in the following figure:
You have two opportunities to influence the data provided by the device: in firmware at the time of setup, and by
using proprietary back channels (usually web services) that are used by the device during its operational
lifetime. These protocols are outside the scope of Microsoft’s design.
All required functionality can be implemented by the device manufacturer by using data that is provided by the
carrier as part of the firmware or initial configuration. Optional functionality can require the availability of real-
time updates.
The following topics are available in this section:
Related topics
Enabling mobile broadband experiences using portable hotspot devices
To communicate the cost of the Wi-Fi network to clients, Microsoft has defined a vendor extension to the 802.11
protocol. This extension is the Network Cost IE.
Note The 802.11 protocol allows vendor-defined information elements (IEs), and requires clients that do not
understand a particular IE to ignore it and continue processing the remaining IEs. This minimizes the
compatibility risk of adding a new IE to products that interact with existing clients of other operating system
types.
The following table shows the Network Cost IE format:
F IEL D N A M E SIZ E ( O C T ET S) VA L UE DESC RIP T IO N
Attribute ID 1 0xDD Type (vendor extension)
Length 1 0x08 Length of the following

fields
Organizationally Unique 3 0x00, 0x50, 0xF2 Vendor (Microsoft)

Identifier (OUI)
OUI Type 1 0x11 OUI type (network cost)
Cost Level 1 Exactly one of Cost Cost Level. One of exact

Level values. See values.
below.
RESERVED 1 0x00 Reserved. Should be

0x00
Cost Flags 1 OR'ed Cost Flags . See Cost Flags. Can be

below. OR'ed
RESERVED 1 0x00 Reserved. Should be

0x00
The following table shows the possible Cost Level bits (exactly one is required):
VA L UE NAME DESC RIP T IO N
0x00 Unknown The usage is unknown or

unrestricted.
0x01 Unrestricted No incremental cost applies for

transferring data on this
connection.
0x02 Fixed Data transfer is metered and

counts against a data limit. No
difference in cost applies within
this limit.
When this value is set, Windows
clients automatically treat
connection as metered.
0x04 Variable Incremental cost applies for all

usage on this link. When this value
is set, Windows clients
automatically treat connection as
metered.
The following tables shows the possible Cost flag bits. Those values MAY be or'ed
0x00 The connection cost is unknown.
0x01 Over Data Limit Usage has exceeded the data limit
of the metered network; different
network costs or conditions might
apply.
0x02 Congested The network operator is

experiencing or expecting heavy
load.
0x04 Roaming The tethering connection is

roaming outside the provider's
home network or affiliates.
0x08 Approaching Data Limit Usage is near the data limit of the
metered network; different
network costs or conditions might
apply once the limit is reached.
The following table shows some sample cost attribute values (last four bytes of IE):
Default WLAN 0x01, 0x00, 0x00, 0x00 Unrestricted connection; standard

WLAN backed by fixed broadband.
Portable Hotspot Default 0x02, 0x00, 0x00, 0x00 Metered network; limit unknown
or not yet reached; matches
Windows default for mobile
broadband connections.
Over Limit / Throttled 0x01, 0x00, 0x01, 0x00 User has exceeded data limit;
speed is reduced, but no further
usage limitation applies.
Over Limit / Charges 0x04, 0x00, 0x01, 0x00 User has exceeded data limit;
additional usage incurs
incremental charges.
Portable Hotspot / Roaming 0x04, 0x00, 0x04, 0x00 Connection is roaming;

incremental charges apply due to
network state.
Add network cost support to your device

1. Add the IE to your device’s WLAN beacon and probe response, which is fixed to the Por table Hotspot
Default value shown in the table with the sample cost attribute values. Verify that a Windows 8,
Windows 8.1, or Windows 10 computer that connects to this network automatically selects the Reduce
network usage option for this network.
2. When roaming, replace the default value with the Por table Hotspot / Roaming value that is listed in
the table with the sample cost attribute values.
3. Optionally, work with your partner carriers to determine cases where other values may be appropriate,
such as the following:
Unrestricted while on certain bearers (LTE, HSPA+, etc.),
Defined channel to detect over-limit states.
Operator-defined behavior when past data limit.
4. Optionally, if your device can use Wi-Fi as a second-hop network, check for this IE on the network to
which you connect and relay its value (or its absence) to your own SSID. If none is present, use the
Default WL AN value that is listed in the table with the sample cost attribute values.
Related topics
[MS-NCT] Network Cost Transfer protocol documentation
App installation
A mobile broadband adapter offers users the opportunity to have the appropriate mobile broadband app
automatically installed when the adapter is connected. Personal hotspots cannot benefit from the same SIM-
based carrier detection. However, personal hotspots that implement the PnP-X protocol can select an app to
install. The app is automatically installed when the computer pairs with the PnP-X device.
This can be the same app that is auto-installed for mobile broadband users, or a branded app that the device
manufacturer and the operator author together. The app should include many of the same functions as a
standard mobile broadband app. See Designing the user experience of a mobile broadband app for suggestions
on standard experiences in a mobile broadband app.
Certain classes of network devices are automatically paired; for more information, see UWP device apps for
internal devices. Other device classes do not automatically install the app until the user pairs with the device by
using the computer settings.
App privileges
Although the app does not have access to the same privileged APIs as a mobile broadband app, it can talk to the
device over the network to retrieve equivalent information if the device exposes this information.
Related topics
Introduction to enabling mobile operator
notifications and system events
This topic provides information about the Mobile Operator Notification system event. It provides guidelines for
you to develop UWP mobile broadband apps that handle incoming SMS- or USSD-based mobile operator
notifications and relevant mobile broadband system events.
Introduction
A customer’s primary experience of a mobile broadband network brand is the mobile broadband app. This app
is not expected to provide primary connection management functions, but instead provides an account
management experience and a service experience. To keep the user informed about their account status, the app
must perform some activities even when the user is not interacting with it. These activities include the following:
Responding to operator SMS or network-initiated USSD messages
Notifying the user that they are approaching their data limit
Notifying the user that their data plan has expired
Notifying the user of their roaming status
Verifying whether tethering is supported on the user’s data plan
Background brokered work items
Although UWP mobile broadband apps can run full screen, users are only expected to interact with the
application that is in the foreground. The foreground app is assumed to be the most important to the user, so
this app receives all the resources of the system. When an app is not in the foreground, it is suspended and
cannot run any code. A suspended app remains suspended until the user resumes it by bringing the app back to
the foreground. With this model of app behavior, the user experience is never affected by lags or delays caused
by the execution of unimportant background apps. In addition, reducing unnecessary background activity
optimizes battery life on a variety of form factors. The time taken to resume a suspended app is negligible and
would appear to be almost unnoticeable to most users.
Windows 10 provides Windows push notifications that can keep the app tile up-to-date even when the app is
suspended. Push notifications are optimized for system performance and longer device battery life, so it’s best
to use Windows push notifications whenever possible. If a suspended app must run its own code to do other
kinds of work, you can create background tasks.
Although UWP apps cannot run any code if they are not running in the foreground, the System Event Broker lets
you run code in response to events while an app is in the background. Apps can register work items with the
System Event Broker to respond to specific background brokered events. Windows runs the app’s work item
when background brokered events are triggered, regardless of the app’s current state (active or suspended).
In general, background events are intended as simple trigger points and are not intended to signal large
amounts of processing. As such, quotas for each app are placed on the processing time that is allowed for
background events. The background events offered by the Network Operator API, including the
MobileOperatorNotification event and HotspotAuthentication event, are treated by Windows as critical events.
Compared to general background events, background work items associated with
MobileOperatorNotification and HotspotAuthentication events run for every instance of the event
regardless of a processing time quota, although each instance of the background work item is subject to a
processing time quota. You should limit processing in the background event handler and defer larger processing
to the mobile broadband app.
In this section
Develop an app to handle the MobileOperatorNotification event
Develop an app to handle the
MobileOperatorNotification event
This topic explains how to develop a mobile broadband app that handles the MobileOperatorNotification event.
Best practices
Step 1: Background task contract declaration
Step 2: Background task handler
Step 3: Handle the Activation event
Step 4: Handle background task completion handlers
Troubleshooting
Sample backgroundtask.js file
Best practices
For background event handling, you should use the following best practices:
Do not register for background events on which you can’t take action. Processing these events will
needlessly consume the app quota.
Do not perform large amounts of processing on receipt of a background event.
Consider deferring processing to the next time the app is launched.
Consider showing a toast notification and updating tile in response to a background event. Your mobile
broadband app can process the background event payload.
Step 1: Background task contract declaration

For Windows to recognize the background task experiences that are supplied by a mobile broadband app, the
app must declare that it is providing an extension to system functionality.
To make the declaration in the package.appxmanifest file for your Visual Studio project, perform the following
steps:
To declare a background task contract
1. In Solution Explorer , double-click the package.appxmanifest file for your project.
2. On the Declarations tab, from Available Declarations , select Background Tasks and then click Add .
3. Under the Proper ties heading, enter the following app info:
In the Star t page box under App settings , for a mobile broadband app that uses JavaScript and
HTML, enter the file name that handles the background task in the app (for example,
backgroundtask .js ).
Under the Suppor ted task types heading, click the System event check box.
If this is done correctly, you should have an extension element similar to the following in the
package.appxmanifest file.
<Extension Category="windows.backgroundTasks" StartPage="backgroundtask.js">

<BackgroundTasks>
<Task Type="systemEvent" />
</BackgroundTasks>
</Extension>
Step 2: Background task handler

If your app provides a mobile operator notifications declaration, it must supply a handler for the background
task activation. The handler will get the mobile operator network account ID and event data from
Windows.Networking.NetworkOperators.NetworkOperatorNotificationEventDetails .
Because the only UI that is supported by background task is Toast , the background task handler can show Toast
or save NetworkOperatorNotificationEventDetails to local storage.
The following code examples demonstrate a background task that is designed to run when a new administrative
SMS notification is received.
C#
using Windows.Networking.NetworkOperators;
namespace MNOMessageBackground
{
public sealed class MNOBackgroundTask : IBackgroundTask
{
public void Run(Windows.ApplicationModel.Background.IBackgroundTaskInstance taskInstance)
{
NetworkOperatorNotificationEventDetails notifyData =
(NetworkOperatorNotificationEventDetails)taskInstance.TriggerDetails;
//The network account ID is stored in notifyData.NetworkAccountId
switch (notifyData.NotificationType)
{
case NetworkOperatorEventMessageType.Gsm: // 0
break;
case NetworkOperatorEventMessageType.Cdma: // 1
break;
case NetworkOperatorEventMessageType.Ussd: // 2
break;
case NetworkOperatorEventMessageType.DataPlanThresholdReached: // 3
break;
case NetworkOperatorEventMessageType.DataPlanReset: //4
break;
case NetworkOperatorEventMessageType.DataPlanDeleted: //5
break;
case NetworkOperatorEventMessageType.ProfileConnected: //6
break;
case NetworkOperatorEventMessageType.ProfileDisconnected: //7
break;
case NetworkOperatorEventMessageType.RegisteredRoaming: //8
break;
case NetworkOperatorEventMessageType.RegisteredHome: ///9
break;
case NetworkOperatorEventMessageType.TetheringEntitlementCheck: //10
break;
default:
break;
}
// Add code to save the message to app local storage, and optionally show toast notification and
tile updates.
}
}
}
JavaScript
(function () {
"use strict";
//
// The background task instance's activation parameters are available via
// Windows.UI.WebUI.WebUIBackgroundTaskInstance.current.
//
var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current,
networkOperatorEventType = Windows.Networking.NetworkOperators.NetworkOperatorEventMessageType,
key = null,
settings = Windows.Storage.ApplicationData.current.localSettings;
try {
var details = backgroundTaskInstance.triggerDetails;

// The network account ID is stored in details.networkAccountId.
switch (details.notificationType) {
case networkOperatorEventType.gsm:
showToast("Mobile Broadband message", details.message);
break;
case networkOperatorEventType.cdma:
break;
case networkOperatorEventType.ussd:
break;
case networkOperatorEventType.dataPlanThresholdReached:
showToast("Mobile Broadband message", "Data plan threshold reached");
break;
case networkOperatorEventType.dataPlanReset:
showToast("Mobile Broadband message", "Data plan reset");
break;
case networkOperatorEventType.dataPlanDeleted:
showToast("Mobile Broadband message", "Data plan deleted");
break;
case networkOperatorEventType.profileConnected:
showToast("Mobile Broadband message", "Profile connected");
break;
case networkOperatorEventType.profileDisconnected:
showToast("Mobile Broadband message", "Profile disconnected");
break;
case networkOperatorEventType.registeredRoaming:
showToast("Mobile Broadband message", "Registered roaming");
break;
case networkOperatorEventType.registeredHome:
showToast("Mobile Broadband message", "Registered home");
break;
case networkOperatorEventType.tetheringEntitlementCheck:
showToast("Mobile Broadband message", "Entitlement check completed");
break;
default:
showToast("Mobile Broadband message", "Unknown message");
break;
}
//
// A JavaScript background task must call close when it is done.
//
close();
}
catch (exception) {
// Display error message.
close();
}
Show tile and toast notifications

We recommend that you show both toast and tile notifications in your mobile broadband app because a user
can miss a toast notification due to its transient nature. For toast notification and tile update experience design
guidelines, see Designing the user experience of a mobile broadband app.
To enable toast notifications
1. In Solution Explorer , double-click the package.appxmanifest file for your project.
2. On the Application UI tab, under the Notifications heading, set Toast capable to Yes .
If this is done correctly, you should have an extension element similar to the following in the
package.appxmanifest file.
<VisualElements … ToastCapable="true"… />
The following code shows how to display a toast notification in a background task handle:
JavaScript
function showToast(title, body) {

var notifications = Windows.UI.Notifications;
var toastNotificationManager = Windows.UI.Notifications.ToastNotificationManager;
var toastXml =
toastNotificationManager.getTemplateContent(notifications.ToastTemplateType.toastText02);
var temp = "the parameter will pass to app when app activated from tap Toast ";
toastXml.selectSingleNode("/toast").setAttribute("launch", temp);
var textNodes = toastXml.getElementsByTagName("text");

textNodes[0].appendChild(toastXml.createTextNode(title));
textNodes[1].appendChild(toastXml.createTextNode(body));
var toast = new notifications.ToastNotification(toastXml);

toastNotificationManager.createToastNotifier().show(toast);
}
Get SMS text message

If the background task was triggered by an incoming SMS message, the background task details will carry the
SMS object in its payload.
JavaScript
(function () {
"use strict";
//
// Windows.UI.WebUI.WebUIBackgroundTaskInstance.current.
//
try {

if (details.notificationType === networkOperatorEventType.gsm
|| details.notificationType === networkOperatorEventType.cdma)
{
var textMessage = new Windows.Devices.Sms.SmsTextMessage.fromBinaryMessage(details.smsMessage);
// textMessage can be used to get other SmsMessage properties

// like sender number, timestamp, message part count etc.
showToast("From: " + textMessage.from + "; TimeStamp: " + textMessage.timestamp, details.message);
}
Use local storage

The background task can use local storage to save the message that you get from the background event, so that
the app can use that information later.
JavaScript
//
// Save the message
//
var settings = Windows.Storage.ApplicationData.current.localSettings;
var keyMessage = "BA5857FA-DE2C-4A4A-BEF2-49D8B4130A39";
//
// Windows.UI.WebUI.WebUIBackgroundTaskInstance.current
//
var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current;

settings.values[keyMessage] = details.message;
The following code demonstrates how to retrieve the message stored by the background task handler in the
app:
JavaScript
var settings = Windows.Storage.ApplicationData.current.localSettings;

var keyMessage = "BA5857FA-DE2C-4A4A-BEF2-49D8B4130A39";
var operatorMessage = settings.values[keyMessage];
Step 3: Handle the Activation event

If the toast sets a parameter, it will be passed to app through detail.arguments .
In JavaScript or C#, you handle the WinJS.Application.onactivated event, and then examine the event
arguments that are passed to the event handler. Activation from toast passes the event argument of type
Windows.UI.WebUI.WebUILaunchActivatedEventArgs . If the event argument’s detail.kind property is
Windows.ApplicationModel.Activation.ctivationKind .launch , the app provides either the Start experience
or the Notification experience, depending on whether the event argument’s detail.argument property is set to
null .
JavaScript
WinJS.Application.addEventListener("activated", activated; false);
function activated(eventArgs)
{
if (eventArgs.detail.kind == Windows.ApplicationModel.Activation.ActivationKind.launch)
{
if (!eventArgs.detail.arguments)
{
// Initialize logic for the Start experience here.
}
else
{
// Initialize logic for the Notification experience here.
}
}
}
Step 4: Handle background task completion handlers

The foreground app can also register a completion handler to be notified when the background task completes.
The completion status or any exception that occurs in the Run method of the background task is passed to the
completion handler in the foreground app. If the app was suspended when the task completed, it receives the
completion notification next time that the app is resumed. If the app was in the Terminated state, it does not
receive the completion notification. If the background task needs to preserve the information that it ran
successfully, it must persist the information by using State Manager or another means, such as a file that the app
can read when it returns to the Running state.
Impor tant Although the mobile operator background event is registered automatically by the system to the
app, the app still needs to run at least one time to register to the background completion or progress handlers.
C#
foreach (var cur in BackgroundTaskRegistration.AllTasks)

{
if(cur.Value.Name == “MobileOperatorNotificationHandler”)
{
cur.Value.Progress += new BackgroundTaskProgressEventHandler(OnProgress);
cur.Value.Completed += new BackgroundTaskCompletedEventHandler(OnCompleted);
}
}
//
// Handle background task completion.
private void OnCompleted(IBackgroundTaskRegistration sender, BackgroundTaskCompletedEventArgs e)
{
var taskCompletion = task as IBackgroundTaskRegistration;
var completionArgs = args.Context as BackgroundTaskCompletedEventArgs;
//
// If the background task threw an exception, display the exception in the error text box.
if (completionArgs.Status != null)
{
throw completionArgs.Status;
}
}
// Handle background task progress.

private void OnProgress(IBackgroundTaskRegistration sender, BackgroundTaskProgressEventArgs e)
{
var taskRegistration = task as IBackgroundTaskRegistration;
var progressArgs = args.Context as BackgroundTaskProgressEventArgs;
// progressArgs.Progress has the progress percentage
}
JavaScript
var iter = Windows.ApplicationModel.Background.BackgroundTaskRegistration.allTasks.first();
var hascur = iter.hasCurrent;
while (hascur) {
var cur = iter.current.value;
if (cur.name === “MobileOperatorNotificationHandler”) {
cur.addEventListener("progress", new ProgressHandler(cur).onProgress);
cur.addEventListener("completed", new CompleteHandler(cur).onCompleted);
}
hascur = iter.moveNext();
}
//
// Handle background task progress.
//
function ProgressHandler(task) {
this.onProgress = function (args) {
try {
var progress = "Progress: " + args.progress + "%";
} catch (ex) {
displayError(ex);
}
};
}
//
// Handle background task completion.
//
function CompleteHandler(task) {
this.onCompleted = function (args) {
try {
var key = task.taskId;
} catch (ex) {
displayError(ex);
}
};
}
Troubleshooting
Use these sections to help troubleshoot issues that may come up.
Trigger metadata parsing to register background tasks
For users, when the mobile broadband device is connected, Windows 8, Windows 8.1, and Windows 10
automatically installs the mobile broadband app and associated service metadata and registers background
tasks that are defined in the service metadata. However, in Windows 8.1, the app is not automatically pinned to
the Start screen.
Developers can manually trigger Windows 8, Windows 8.1, and Windows 10 to parse service metadata and
register background tasks by pressing the F5 key (or right-click and select Refresh ) in the Devices and
Printers window on the desktop. Background task registration through service metadata parsing succeeds only
when the app is deployed.
Verify that background tasks are correctly registered
Developers can verify that the Device Setup Manager (DSM) has properly parsed the service metadata by
viewing the event logs under Application and Ser vices
Logs\Microsoft\Windows\DeviceSetupManager .
1. Open Event Viewer.
2. On the Menu tab, select View , and then click Show Analytic and Debug Logs .
3. Browse to Applications and Ser vices Logs\Microsoft\Windows\DeviceSetupManager .
Events of interest include Event ID 220 that indicates that DSM has successfully registered the background task
for the MobileOperatorNotification event, and Event ID 7900, which indicates any errors that are found in the
metadata package.
Verify that provisioning metadata is successfully applied
When applying provisioning metadata, verify that
ProvisionFromXmlDocumentResults.AllElementsProvisioned is true. If not, check the
ProvisionResultsXml for more details about the error. Common mobile broadband errors include the following:
A mismatch between the SIM in the PC and the provisioning file (profile fails with ERROR_NOT_FOUND).
A mismatch between the CarrierId in the provisioning file and the service number in the experience
metadata.
Verify that background tasks are being run by the System Event Broker
You can verify that Windows is generating the MobileOperatorNotification event and that the app’s background
task is being run by the event broker by checking the Event Viewer. Logging for these events is off by default
and can be enabled by performing the following steps:
1. Open Event Viewer.
2. On the Menu tab, select View , and then click Show Analytic and Debug Logs .
3. Browse to Applications and Ser vices Logs\Microsoft\Windows\BackgroundTaskInfrastructure .
4. Right-click Diagnostic log and select Enable Log .
After you enable the logs, a successful execution of the background task results in an event of Event ID = 1 that
has the following description: “An instance of a background task with entry point
<background_task_namespace_name>.<background_task_class_name> and name
MobileOperatorNotificationHandler has been created in session 1 and given an ID of {11111111-1111-1111-
1111-111111111111}.”
If the background task is not being run, first verify that the names of your background tasks that are specified in
the service metadata match the names in the AppXManifest.xml file of your package. Verify that after deploying
the app, parsing the service metadata is triggered and inserts the mobile broadband device.
Verify that Windows receives SMS and USSD notifications
You can verify that Windows is receiving SMS and USSD notifications by checking for SmsRouter events in Event
Viewer.
In Event Viewer, under Application and Ser vices Logs\Microsoft\Windows \Mobile-Broadband-
Experience-SmsRouter\Microsoft-Windows-SMSRouter , are entries such as “The SMSRouter received a
SMS Operator Notification message” and “The SMSRouter received a Text message”. Under Application and
Ser vices Logs\Microsoft\Windows \Mobile-Broadband-Experience-SmsApi\SMSApi are entries such
as “App: Microsoft.SDKSamples.SmsSendReceive sent SMS text message on mobile broadband device:
{11111111-1111-1111-1111-111111111111}”.
Received SMS messages are not detected as operator notifications
If received SMS are not detected as operator notifications, verify the custom filtering rules for administrative
SMS notifications in the account provisioning metadata. For more info about provisioning metadata, see
Account provisioning.
In particular, if account provisioning metadata specifies the sender phone number, verify that the number
formatting specified matches that in the received message by using the SMS APIs. To verify that this is matching
correctly, temporarily change the Pattern to [^]\ * to match all messages from this sender.
Sample backgroundtask.js file
//
// A JavaScript background task runs a specified JavaScript file.
//
(function () {
"use strict";
//
Windows.UI.WebUI.WebUIBackgroundTaskInstance.current.
//
networkOperatorEventType = Windows.Networking.NetworkOperators.NetworkOperatorEventMessageType,
key = null,
settings = Windows.Storage.ApplicationData.current.localSettings;
try {
switch (details.notificationType) {
case networkOperatorEventType.gsm:
var textMessage = new
Windows.Devices.Sms.SmsTextMessage.fromBinaryMessage(details.smsMessage);
showToast("Gsm Msg From: " + textMessage.from + "; TimeStamp: " + textMessage.timestamp,
details.message);
break;
case networkOperatorEventType.cdma:
break;
case networkOperatorEventType.ussd:
break;
case networkOperatorEventType.dataPlanThresholdReached:
showToast("Mobile Broadband message", "Data plan threshold reached");
break;
case networkOperatorEventType.dataPlanReset:
showToast("Mobile Broadband message", "Data plan reset");
break;
case networkOperatorEventType.dataPlanDeleted:
showToast("Mobile Broadband message", "Data plan deleted");
break;
case networkOperatorEventType.profileConnected:
showToast("Mobile Broadband message", "Profile connected");
break;
case networkOperatorEventType.profileDisconnected:
showToast("Mobile Broadband message", "Profile disconnected");
break;
case networkOperatorEventType.registeredRoaming:
showToast("Mobile Broadband message", "Registered roaming");
break;
case networkOperatorEventType.registeredHome:
showToast("Mobile Broadband message", "Registered home");
break;
case networkOperatorEventType.tetheringEntitlementCheck:
showToast("Mobile Broadband message", "Entitlement check completed");
break;
default:
showToast("Mobile Broadband message", "Unknown message");
break;
}
taskSucceeded();
}
catch (exception) {
taskFailed();
}
function showToast(title, body) {
var notifications = Windows.UI.Notifications;

var toastNotificationManager = Windows.UI.Notifications.ToastNotificationManager;
var toastXml =
toastNotificationManager.getTemplateContent(notifications.ToastTemplateType.toastText02);
//
// Pass to app through eventArguments.arguments.
//
var temp = "\"Title\"" + ":" + "\"" + title + "\"" + "," + "\"Message\"" + ":" + "\"" + body + "\"";
if (temp.length > 251) {
temp = temp.substring(0, 251);
}
toastXml.selectSingleNode("/toast").setAttribute("launch", "'{" + temp + "}'");
var textNodes = toastXml.getElementsByTagName("text");

textNodes[0].appendChild(toastXml.createTextNode(title));
textNodes[1].appendChild(toastXml.createTextNode(body));
var toast = new notifications.ToastNotification(toastXml);

toastNotificationManager.createToastNotifier().show(toast);
}
//
// This function is called when the background task is completed successfully.
//
function taskSucceeded() {
//
// Use the succeeded property to indicate that this background task completed successfully.
//
backgroundTaskInstance.succeeded = true;
backgroundTask.taskInstance.progress = 100;
console.log("Background " + backgroundTask.taskInstance.task.name + " Completed");
//
// Write to localSettings to indicate that this background task completed.
//
key = backgroundTaskInstance.task.taskId.toString();
settings.values[key] = "Completed";
//
// A JavaScript background task must call close when it is done.
//
close();
}
//
// If the task was canceled or failed, stop the background task.
//
function taskFailed() {
console.log("Background " + backgroundTask.taskInstance.task.name + " Failed");
backgroundTaskInstance.succeeded = false;
key = backgroundTaskInstance.task.taskId.toString();
settings.values[key] = "Failed";
close();
}
})();
Related topics
This topic explains the technical details of a mobile operator notification event.
Event payload
Register for the MobileOperatorNotification event by using metadata
Define filtering rules in provisioning XML
Event payload
The MobileOperatorNotification event payload includes the following fields:
F IEL D DESC RIP T IO N
MessageType Enumeration of the message that triggered the event.
Interface The GUID that corresponds to the physical interface that is

associated with the event.
EncodingType The encoding method for the message, if MessageType is

SMS/USSD.
MessageDataSize The size of the message, in bytes, if MessageType is

SMS/USSD.
Message The raw message that is received, if MessageType is

SMS/USSD.
The MobileOperatorNotification event enables each of the scenarios that are described in Mobile operator
notification scenarios by differentiating them by using the MessageType field in the event payload. The
MessageType s are enumerated as follows:
EN UM ERAT IO N TYPE
0 GSM SMS
1 CDMA SMS
2 USSD
3 DataPlanThresholdReached
4 DataPlanReset
5 DataPlanDeleted
6 ProfileConnected
EN UM ERAT IO N TYPE
7 ProfileDisconnected
8 RegisteredRoaming
9 RegisteredHome
10 TetheringEntitlementCheck
The work item that is associated with the MobileOperatorNotification event should start with logic that
effectively differentiate the MessageType , and runs the appropriate code for each scenario.
GSM/CDMA SMS and USSD
An incoming operator message, including SMS and USSD, triggers the MobileOperatorNotification event
together with the appropriate corresponding MessageType s. Unique to these types are EncodingType ,
MessageDataSize , and Message .
DataPlanThresholdReached
By default, this message type is disabled. You can enable it by using provisioning metadata to specify the
DataUsageInMobileOperatorNotificationEnabled field, as shown here.
<Global>
<CarrierId>{2c85b76b-f859-47c4-8122-721fe8b6c25f}</CarrierId>
</Global>
<MBNProfiles>
<Name>Contoso</Name>
<AssociatedPlan>SamplePlan</AssociatedPlan>
<Context>
<AccessString>Contoso.com</AccessString>
<UserLogonCred>
<UserName>User</UserName>
</UserLogonCred>
</Context>
</DefaultProfile>
</MBNProfiles>
<Plans>
<Plan xmlns="http://www.microsoft.com/networking/CarrierControl/Plans/v1" Name="SamplePlan">
<Description PlanType="Fixed">
<DataLimitInMegabytes>500</DataLimitInMegabytes>
<DataUsageInMobileOperatorNotificationEnabled>true</DataUsageInMobileOperatorNotificationEnabled>
</Description>
</Plan>
</Plans>
For more info about account provisioning metadata, see Account provisioning.
The event is generated with this MessageType when the local data counters estimate that usage (bytes sent
and received) on the mobile broadband interface has changed by 5% since the last occurrence, except in the
following cases:
1. When connected to a home network (non-roaming), if the data plan limit has not been specified, this
event is triggered at every 100 MB of local data usage.
2. When connected to a roaming network, the data plan limit does not apply and this event is triggered at
every 5 MB of local data usage.
The local data counters in Windows 8 are updated every one minute; at most, this event is generated one time
per minute in all described scenarios. In Windows 8.1 the event is delivered in real-time when the 5% threshold
has been reached.
NOTE
Although this information is a good first-order guide, Windows cannot account for unbilled traffic or for usage on other
devices that share the same data limits (such as family plans or SIM-swapping). Mobile operator apps should use local
data counters only to approximate usage since the last sync with the operator’s own billing system. For data usage that
has already been processed, the billing system should be considered authoritative.
DataPlanReset
On the plan reset date, the Data Usage and Subscription Manager (DUSM) resets the user’s current local data
usage to zero.
DataPlanDeleted
For pre-paid data plans that have a fixed expiration date, the DUSM deletes the connection profile that is
associated with the account on the expiration date and the MobileOperatorNotification event is triggered by
using this MessageType . When the connection profile is deleted, Windows Connection Manager no longer tries
to automatically connect to the network that is described by the connection profile.
ProfileConnected and ProfileDisconnected
The MobileOperatorNotification event is generated with these MessageType s when Windows Connection
Manager connects to the network profile that is provided by the operator experience metadata. This event is
triggered on every connect and disconnect, including the initial connection that follows a sleep/resume. It is also
triggered if the device is already connected when the app and service metadata are downloaded and installed.
The ProfileConnected MessageType is triggered on L2 connectivity for the mobile broadband interface.
NOTE
This trigger occurs before network identification is complete. The NetworkStatusChanged event (part of the
NetworkInformation API) is generated when network identification determines the connectivity level of the network.
For more information about network identification, see Quickstart: Retrieving network connection information and the
NetworkInformation class.
RegisteredRoaming and RegisteredHome

The MobileOperatorNotification event is generated with these MessageType s when Windows Connection
Manager registers to a roaming network. This event is triggered on every registration, including the initial
registration following a sleep/resume. It is also triggered if the device is already registered to the network when
the app and service metadata are downloaded and installed.
The app should only notify the user one time when they register on a roaming network and one time when they
return to their home network. Because this event is triggered at every registration, the app is responsible for
keeping track of the previous registered state in the app’s session data.
TetheringEntitlementCheck
The MobileOperatorNotification event is generated with this MessageType s when the user turns on Internet
Sharing. The event is triggered every time the user tries to use Internet Sharing as long as the mobile operator
has set the AllowTethering element in the service metadata schema to EntitlementCheckRequired . For more
info about the service metadata schema, see Service metadata package schema reference.
The app should run the appropriate entitlement check mechanism supported by the mobile operator network
and send the outcome to the system by using the AuthorizeTethering method of the
NetworkOperatorNotificationEventDetails class in the Windows.Networking.NetworkOperators
namespace. If the app does not have the capability to run the entitlement check, the mobile operator should
change the Service Metadata AllowTethering element to Always or Never , so that the event is never generated.
Register for the MobileOperatorNotification event by using metadata

In general, an app must be run by the user at least one time before it can register work items with the System
Event broker. However, because the MobileOperatorNotification events are required to complete key mobile
broadband scenarios, this event is associated with the mobile broadband app by using service metadata. In the
service metadata, configure the DeviceCompanionApplications element.
<Package>
<Identity Name="MyOperatorNotification" Publisher="MyCorporation " />
<Applications>
<Application Id="MyOperatorNotification" />
<DeviceNotificationHandler EventID="MobileOperatorNotificationHandler"
EventAsset="backgroundtask.js" />
</Applications>
</Package>
The EventID attribute tells the system what kind of event to expect from the device. The value of the
EventAsset attribute should point to the entry point that implements the background task. This will tell the
system which task to run when that particular event has occurred.
Using this example, the system creates and registers an event that is specific to that device. It also registers the
mobile broadband app for this event. The app must have a JavaScript file called backgroundtask.js that is run by
the system each time that it receives an operator notification.
If the mobile broadband app is written in C#, the event asset must point to the runtime class that implements
the backgroundtask interface.
<DeviceNotificationHandler EventID="MobileOperatorNotificationHandler"
EventAsset="MNOMessageBackground.OperatorNotification" />
When the service metadata and app are downloaded, the Device Setup Manager registers the appropriate work
item with the System Event Broker before the app is run. Immediately after the work item is registered, if the
mobile broadband device is registered or connected to the network, the MobileOperatorNotification event is
triggered together with the corresponding MessageType .
Change background task registration in metadata
If the background task entry point is changed in an updated version of the mobile broadband app, the
DeviceNotificationHandler element in the service metadata must also be changed.
Service metadata is updated automatically on computers running Windows 8, Windows 8.1, and Windows 10.
Mobile broadband apps are updated in the Microsoft Store. You should avoid changing the
DeviceNotificationHandler background task registration in service metadata. If a change is required, the service
metadata should contain references to all the different background task entry points used in all your supported
versions of the mobile broadband app to preserve functionality for users who haven’t updated the mobile
broadband app.
Define filtering rules in provisioning XML
Windows accepts an XML-based provisioning file from you. A sample version of the provisioning XML is shown
here:

<Global>


</Global>
<MBNProfiles>
<Name>Contoso</Name>
<AssociatedPlan>Limited</AssociatedPlan>

<HomeProviderName>Contoso</HomeProviderName>
<Context>
<AccessString>Contoso.Contoso</AccessString>
UserLogonCred's. -->
<UserLogonCred>
<UserName>user</UserName>
</UserLogonCred>
</Context>
</DefaultProfile>
<Messages xmlns="http://www.microsoft.com/networking/CarrierControl/WWAN/v1">
<Message RuleId="Sample1" Silent="true">
<SMSBearer ClassZeroOnly="false" Sender="18005551212"/>

<Pattern>[^]*</Pattern>

</Message>
<Message RuleId="Sample2" Silent="false">

<USSDBearer/>
<Pattern>(\d+\.\d+)(\w+) of (\d+)(\w+) used as of (\S+)</Pattern>

<Units G="GB" M="MB"/>
<Fields>

<Usage Group="1" UnitGroup="2"/>
<UsageTimestamp Group="5" Format="%I:%M%p on %d %b"/>
<DataLimit Group="3" UnitGroup="4"/>
</Fields>
</Message>
</Messages>
</MBNProfiles>
<Provisioning />
The rules to identify a text message as an operator message can be defined in this XML.
Allowed sender The Sender attribute specifies the reserved sender address from which the notification
is allowed to arrive. (This number must exactly match the sender number that is received in the SMS
message, including the international format).
Pattern The regular expression to identify and optionally extract the data fields from the text message. To
match all messages from a sender, use pattern [^]* .
Related topics
This topic explains that scenarios when you would use a mobile operator notification with your mobile
broadband app.
Connect to and disconnect from mobile broadband
Network operator messages
Triggering data usage and roaming notifications locally
Data plan expiration and usage reset
Entitlement check for Internet Sharing
Connect to and disconnect from mobile broadband

Windows Connection Manager monitors available networks across Wi-Fi, mobile broadband, and Ethernet. It
makes automatic connect and disconnect decisions based on the available networks. When Windows
Connection Manager connects to and disconnects from a mobile broadband profile, a
MobileOperatorNotification background event is triggered. This event enables the mobile broadband app to
perform necessary logic when the user connects to their network, such as verifying account status, retrieving
the most recent data usage, or displaying notifications and tile updates.
Network operator messages

The mobile broadband platform in Windows 8, Windows 8.1, and Windows 10 provides enhanced functionality
that is available to a mobile broadband app only, for receiving and displaying incoming SMS and USSD
administrative messages. These messages can be used for user notification, such as approaching data usage cap,
international roaming, low balance, or to trigger a response from you mobile broadband app.
The app handles the incoming message as appropriate. Likely responses include any or all of the following:
Immediately syncing current data usage
Updating the mobile broadband app’s tile
Retrieving and applying updated operator provisioning XML
Displaying a notification to the user
If you want to display the message in the app, the background task that is triggered by the
MobileOperatorNotification event must read the message contents and store the message contents in the app’s
own local data storage. The mobile broadband SMS platform does not maintain a queue of received
administrative SMS notifications.
Mobile network operator SMS notifications
Incoming SMS messages are available to any app that has requested and been granted access to the SMS
capabilities on the computer. However, some SMS messages come directly from the carrier and should be
restricted to and handled by the mobile broadband app.
The mobile broadband SMS platform filters each new received SMS into one of two types: administrative (silent)
SMS notifications from a Mobile Network Operator (MNO), and general SMS messages. Administrative SMS
notifications that are received from an MNO are only accessible to the mobile broadband app and are hidden
from general SMS client apps.
MNOs specify custom filtering rules for administrative SMS and USSD notifications in the account provisioning
metadata. If no message filtering rules are specified, the SMS platform classifies all SMS messages as general
SMS messages that are available to any app. If an incoming SMS matches the provisioned filtering rules, the
MobileOperatorNotification event is triggered and the background work item can handle the incoming SMS
message.
Network-initiated USSD
Windows 8, Windows 8.1, and Windows 10 provide a USSD API, which is an abstraction of the underlying USSD
protocol that hides most of the details to simplify app development. Upon receiving a network-initiated USSD
that matches the provisioned filtering rules, the MobileOperatorNotification event is trigged and the
corresponding background work item can communicate over the USSD session by using the USSD API.
For more information about USSD APIs, see Windows.Networking.NetworkOperators namespace.
Triggering data usage and roaming notifications

In many areas, MNOs are required by regulatory laws to notify a user when the user reaches their data usage
limit or is roaming on a more costly network. This consumer protection mitigates the risk of excessive usage
charges. In Windows, the mobile broadband app can show toast notifications and tile updates to make the user
aware of the data usage and roaming states. These notifications can be initiated from your network back-end by
using SMS or USSD, which trigger the MobileOperatorNotification events. Alternatively, the
MobileOperatorNotification event can be triggered by using local information in the following cases.
Data usage notification by using local data counters
1. You enable local data usage notifications by using provisioning metadata.
2. Local data counters estimate that usage on the profile has changed by more than 5% of the user’s data
limit since the last update.
3. The Data Usage and Subscription Manager (DUSM) notifies the System Event Broker to trigger the
MobileOperatorNotification event.
4. The System Event Broker invokes the mobile broadband app to handle the background event.
5. The app handles the event by retrieving the most current usage information from your back-end
infrastructure.
6. If the current usage information exceeds a threshold (such as 80%), the app displays a toast notification
to the user and updates the DUSM with the current usage. Alternatively, if the current usage does not
exceed a threshold, the app does not need to display the toast notification.
Roaming notification by using Windows Connection Manager
1. Windows Connection Manager registers on a roaming mobile broadband network.
2. Windows Connection Manager notifies the System Event Broker to trigger the
MobileOperatorNotification event.
3. The System Event Broker invokes the mobile operator app to handle the background event.
4. The app identifies whether the user will incur additional usage charges when roaming on this network
and if necessary, displays a toast notification and tile updates to the user.
Data plan expiration and usage reset

The DUSM tracks details about the user’s account or accounts, including the plan expiration date for pre-paid
data plans, or the plan usage reset date for post-paid data plans. When the user’s data plan expires, the DUSM
notifies the System Event Broker to trigger the MobileOperatorNotification event. The mobile broadband app
can handle the event by displaying a toast notification and tile update to the user, informing them that their plan
has expired or directing them to renew their service.
In the case of a post-paid data plan, the DUSM will reset the plan data usage to zero on a particular date, such as
the first day of the month. When this occurs, the MobileOperatorNotification event is triggered and the app can
notify the user of their updated data usage.
Entitlement check for Internet Sharing

In Windows 8.1, Internet Sharing, commonly referred to as tethering, has been added to enable users to share
their mobile broadband network connection with one or more other devices that are not mobile broadband-
capable. Traditional tethering mechanisms include Bluetooth and USB. However, Wi-Fi can provide the fast and
easy mobile broadband connection sharing mechanism, such as personal hotspots, mobile hotspots, and so on,
since it requires little configuration, enables high-speed data transmission, and relies on the familiar Wi-Fi
connection process.
Some MNOs or MVNOs do not support Internet Sharing features on their network or they require an
entitlement check prior to setting up an Internet Sharing connection. Windows provides the necessary controls
to ensure that Windows devices comply with network policies. If the mobile operator has set the AllowTethering
element to EntitlementCheckRequired in the service metadata package, the system will trigger the
MobileOperatorNotification event. The mobile broadband app then communicates with a network service to
check whether or not the user is allowed to use the Internet Sharing feature and responds back to the system. If
the user is allowed to use the feature, Internet Sharing will successfully start, otherwise the user will be shown
either a default error message or a message defined by the mobile operator.
Related topics
Introduction to integrating Windows with wireless
hotspots
Wi-Fi hotspots have proliferated in public areas such as airports, coffee shops, and hotels. Operators of such
networks generally offer Internet access, either as a complimentary service to their clients that is funded by the
venue owner, or as a paid offering.
Various methods have been developed to handle authentication to these networks. Open networks that have
captive portals (called the “Universal Access Method” in Wireless Internet Service Provider roaming [WISPr]) are
the common denominator, as they are accessible to users on any device that has a WLAN interface and a web
browser. However, captive portal extensions (WISPr) and alternate authentication methods (Hotspot 2.0, EAP)
offer opportunities to streamline the hotspot connection experience.
The topics in this section address the interaction between a Wi-Fi hotspot operator, their app, and Windows 8,
Windows 8.1, orWindows 10. The described actions can be taken by a standard app that is downloaded from the
Microsoft Store, or by a mobile broadband app that is installed by Windows to complement a mobile broadband
device that is attached to the computer.
Related topics
Review the hotspot authentication sample
The Hotspot Authentication Sample demonstrates the application of a provisioning file and how it handles a
hotspot authentication event. This sample does not run with privileged APIs; it demonstrates the application of
signed provisioning metadata.
For an example of how to use unsigned provisioning metadata together with privilege APIs, see the Mobile
Broadband Provisioning sample.
Related topics
Integrating Windows with wireless hotspots
Update the hotspot authentication sample
The Hotspot Authentication Sample project uses a default carrier ID and application family name. To use the
sample in your own test environment, you must change the following items:
Update your Carrier ID If you are publishing a mobile broadband app, this should be the Experience ID
that is associated with your app and service metadata. If you are a Wi-Fi-only operator, generate a new
GUID to use as your company’s ID.
Update the SSID The SSID that you use for test should match the SSID in the provisioning file and must
offer captive portal and WISPr challenge to connecting clients.
Sign the provisioning file If you are a Wi-Fi-only operator, you must sign the provisioning file. In the
Windows 8 SDK or the Windows 8.1 SDK, find the tool ProvisioningTestHelper.psd1 . Import this into a
PowerShell session to add the following four additional cmdlets:
Install-TestEVCer t Generates a new CA certificate, registers it on your test machine as a trusted
EV SSL provider, and uses it to generate and sign an EV certificate for use in signing.
Conver tTo-SignedXml Uses an EV certificate (generated for test, or issued by a third-party
provider) to apply an XML-DSig signature to a Provisioning Metadata XML file. This signature from
a trusted certificate causes Windows to accept the provisioning file as valid from a mobile
broadband app that has no affiliated hardware.
Test-SignedXml Checks a provisioning file to ensure schema conformance and valid signature.
Install-RootCer tFromFile Applies the test root certificate on a different PC, to test the client
experience on a machine other than the development PC.
Related topics
Verify background events
After you connect to your hotspot network, check that the background event is launched. If not, check the
following:
Did Windows detect your hotspot? If so, the network list should indicate a limited connection. If
Windows detects connectivity to the Internet after connecting to the network, no hotspot authentication
actions are taken.
Did Windows detect WISPr on your hotspot? If so, the background event will fire or the user will be
prompted for credentials. If Windows opens the browser instead, WISPr was not detected. Check that the
XML message is present in the browser’s redirect page and that it conforms to the WISPr specification.
Is your app correctly associated with the profile? If so, the background event will fire. If not, the
user will be prompted for credentials upon manually connecting to the network. Check that the
application family name specified as the ExtensionId matches your application and that provisioning was
successful.
Next, check that you can successfully authenticate to the network. In particular, you should cover the following
cases:
Successful authentication In the ideal case, your app can provide credentials and connect the user to
the network.
User interaction If you need to interact with the user in certain cases, ensure that your app launches to
the correct context to perform the interaction, and not simply to your app’s home page.
Unsuccessful authentication Particularly when using prefixes, you should handle the possibility that a
network matches your prefix, but that you cannot generate credentials for it. In this case, you should stop
authentication.
Access denied In certain cases, your app will receive the background event, but might not be able to
retrieve the details of the authentication attempt. In this case, your background event should stop cleanly
as soon as possible.
Related topics
Captive portals
Most hotspots implement customer interaction by using a captive portal, which is a restricted network
connection in which all client HTTP requests are redirected to the provider’s web site. The web site can then
prompt users to agree to the operator’s terms and conditions, enter payment information, or enter credentials
to verify prior payment arrangements.
Several problems exist by using such an experience:
Other applications (such as email clients) are also redirected. If the user tries to use an app other than the
web browser first, they will encounter errors without knowing how to resolve them.
If the initial connection attempted is made over Secure Sockets Layer (SSL), the browser displays a
security warning to the user before the user is redirected to the captive portal. This creates a confusing
experience for users because they must ignore the security warning to get connected.
Windows supports captive portal networks by immediately opening the web browser if a captive portal is
detected. The user sees your branded web page in the foreground of their device, which helps them to
understand what actions they should take to authenticate by using the captive portal.
Windows provides mechanisms that can let users bypass captive portals on subsequent connection attempts.
However, the captive portal is always the experience that is encountered by a first-time user.
This topic discusses the following best practices for using captive portals:
Consistent connection handling
Touch-friendly web pages
Provision after purchase
Offer app installation
Consistent connection handling

To determine Internet connectivity and captive portal status when a client first connects to a network, Windows
performs a series of network tests. The destination site of these tests is msftncsi.com , which is a reserved
domain that is used exclusively for connectivity testing. When a captive portal is detected, these tests are
periodically repeated until the captive portal is released.
To avoid false positive or false negative test results, your captive portal should not do the following:
Allow access to www.msftncsi.com when the user does not have access to the Internet.
Change the captive portal behavior that is displayed to clients. For example, do not redirect some
requests and drop other requests; you should continue to redirect all requests until authentication
succeeds.
Note
Denial of Service mitigations should be based on the frequency of attempts per client, not the number of
attempts per client or the total attempts from all clients.
Touch-friendly web pages

The Windows experience is designed to be touch-first. This extends to web pages. Consider laying out your web
page with larger, easy-to-target controls for a touch user. Use layouts that do not require excessive scrolling to
interact with, and break flows into multiple pages if necessary. For more information on touch-friendly web
design, see Designing for Touch Input.
Provision after purchase

The same provisioning file that can be applied by an app can also be applied by a website. In the web page’s
JavaScript, check for the availability of the window.external.msProvisionNetworks method. If it is present,
the browser can relay a provisioning file to the operating system. See Using metadata to configure mobile
broadband experiences for more information about how to generate this provisioning file.
Note This provisioning file must be signed when it is provided by a website or an app that is not the mobile
broadband app.
Passing an XML provisioning file enables the operating system to automatically connect to other networks that
are included in the user’s service, even if they have different service set identifiers (SSIDs). If you use static
Wireless Internet Service Provider roaming (WISPr) credentials, it also enables a smoother connection
experience because in the future, Windows can automatically authenticate with those credentials.
Offer app installation

The richest experience of Windows is through the use of a mobile broadband app. It is not possible to allow
access to only one app in the Microsoft Store through a captive portal, so the app cannot be installed prior to the
user obtaining Internet connectivity. However, after the user has authenticated, consider directing them to the
Microsoft Store to install your mobile broadband app.
Related topics
WISPr authentication overview
A Wireless Internet Service Provider roaming (WISPr)-capable hotspot includes a payload in its captive portal
page that is similar to the following:
<HTML>

</HTML>
A smart client, such as Windows, interprets this XML (which is contained in an HTML comment to avoid its
display to customers), to learn where the user’s credentials must be submitted.
When a customer manually connects to a WISPr-capable network, they see the following prompt:
Customers who select No, I need to sign up are directed to your captive portal. Customers who select Yes,
I’ll enter my user name and password are prompted to enter their credentials. These credentials are
provided to your website, and the user is connected after successfully authentication.
A mobile broadband app can automatically supply credentials or replace the credentials prompt by using a
tailored purchase or authentication flow. This requires that the network support WISPr, and that the app be
installed before the user connects to the network.
If your network offers WISPr to clients by using certain UserAgent strings, the user will not see this prompt and
cannot manually enter credentials. However, your app can still participate in WISPr authentication by including
the appropriate UserAgent when it creates the network profile.
The following topics are included in this section:
For an app to participate in the hotspot authentication process, it must first create one or more profiles for Wi-Fi
hotspots. This is done by using the Provisioning Agent interface that is discussed in Using metadata to configure
mobile broadband experiences. The hotspot must use open authentication and must include the
HotspotProfile element. The following provisioning file sample shows how to associate an SSID with your app:
<SSIDConfig>
<SSID>
<name>Contoso Wi-Fi___33</name>
</SSID>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
</authEncryption>
<ExtAuth>
<ExtensionId>YourAppIdGoesHere</ExtensionId>
</ExtAuth>
<TrustedDomains>
<TrustedDomain>www.mycaptiveportal.com</TrustedDomain>
</TrustedDomains>
<UserAgent>contoso</UserAgent>
</HotspotProfile>
</security>
</MSM>
</WLANProfile>
The ExtensionId field contains the package family name of the app that generates hotspot credentials. The
package family name is automatically generated by Visual Studio. To find the package family name for your
application, open the package.appxmanifest file in your Visual Studio solution and go to the Packaging
window.
After the provisioning file is processed, the app that has the package family name “YourAppIdGoesHere” must
register for the Hotspot Authentication event. It is required that the provisioning file is processed first to grant
the specified app access to this event. An app can register a single handler for this event. The event registration
remains valid as long as there is at least one profile that refers to the corresponding app.
Sign the provisioning file

Because provisioning modifies system settings that persist after the user has exited or even uninstalled the app,
a stricter measure of verification is required than for most APIs. This verification is provided by a combination of
operator-specific hardware (the SIM), cryptographic signatures, and user confirmation. The following table lists
the verification requirements:
USER C O N F IRM AT IO N
SIM P RESEN T P RO VISIO N IN G SO URC E SIGN AT URE REQ UIREM EN T REQ UIREM EN T
Yes, MB provider Mobile broadband app None None
Yes, MB provider Operator web site Certificate must: None

- Chain back to trusted root
CA
- Be associated with mobile
broadband hardware in
APN database or experience
metadata
No, Wi-Fi provider Mobile broadband app or Certificate must: User is prompted to
web site - Chain back to trusted root confirm the first time the
CA certificate is used; none
- Be marked for Extended thereafter.
Validation
Related topics
This topic describes ways to handle the requirement for large numbers of SSIDs.
Windows 8.1 and Windows 10 significantly improve support for a large number of SSIDs by increasing the
amount of SSIDs that can be configured in a single WLAN profile. A WLAN profile can now contain up to 10,000
SSIDs. Additionally, WLAN profiles support SSID prefixes.
The following sections are included in this topic:
Multiple SSIDs per profile
Secondary SSIDs
Prefixes
Example profile
Multiple SSIDs per profile

If you are provisioning Windows 8, Windows 8.1, or Windows 10 to connect to several SSIDs, we recommend
that you provide multiple SSIDs per profile. This greatly reduces the size of the provisioning file and improves
the responsiveness of the computer.
If you intend to use APIs to mark a network that should no longer be used, be aware that these actions apply to
all SSIDs that are covered by the same profile. Therefore, it is a best practice to group related SSIDs in a single
profile.
You can have a maximum of ten profiles that can each have 25 primary SSIDs in Windows 8 and up to 10,000
SSIDs in Windows 8.1. In Windows 8.1, there are two separate XML namespaces for SSIDs. The v1 namespace
supports up to 25 SSIDs as in Windows 8. The v2 namespace supports up to 10,000 SSIDs. A profile must have
at least one SSID in the v1 namespace and can have up to 10,000 SSIDs in total.
Secondary SSIDs
Windows 8 introduced the concept of secondary SSIDs inside the HotspotAuth section of the WLAN profile to
extend the amount of SSIDs that are covered by a profile. This is still supported in Windows 8.1 and
Windows 10, but we recommend using the SSID section of the WLAN profile instead to support auto-connect
scenarios.
To configure more than 25 SSIDs per profile in Windows 8, you can specify secondary SSIDs for each profile in
the SSIDConfig note of the HotspotAuth section. This does not create additional profiles for these networks, but
associates the Hotspot settings from the profile together with that SSID.
If the user manually connects in the future and creates a new profile, the hotspot settings from this profile are
automatically associated with the user-created profile. Because secondary SSIDs do not auto connect unless the
user manually connects to them one time, these should be less common networks that most users do not
encounter.
You can have a maximum of 250 secondary SSIDs per profile.
Prefixes
To associate with a particularly large or dynamic set of SSIDs, the SSID list can contain prefixes in addition to
static SSIDs. This allows you to associate your mobile broadband app with a broad set of SSIDs that have four or
more octets in common at the beginning of the SSID.
In Windows 8, SSID prefixes are supported in the secondary SSID list only. In Windows 8.1 and Windows 10,
SSID prefixes are supported in the SSIDConfig section of the WLAN profile using the v2 namespace.
Example profile
This section shows an example profile containing an SSID in the v1 and v2 namespace each as well as an SSID
prefix.
<WLANProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WLAN/v1"
xmlns:v2="http://www.microsoft.com/networking/CarrierControl/WLAN/v2">
<name>SampleProfile</name>
<SSIDConfig>
<SSID>
<name>MySSID1</name>
</SSID>
<v2:SSID>
<v2:name>MySSID2</v2:name>
</v2:SSID>
<v2:SSIDPrefix>
<v2:name>MySSIDPrefix</v2:name>
</v2:SSIDPrefix>
</SSIDConfig>
<MSM>
<security>
<authEncryption>
</authEncryption>
</security>
</MSM>
</WLANProfile>
Related topics
Windows 8, Windows 8.1, and Windows 10 trigger the hotspot authentication event when it detects a captive
portal that supports Wireless Internet Service Provider roaming (WISPr).
When the event occurs, the receiving app must immediately call the
Windows.Networking.NetworkOperator.HotspotAuthentication.Tr yGetAuthenticationContext
function by using the event token that is provided as an argument to the event handler. This function returns an
object that manages the hotspot authentication attempt. In the event that the function fails, the event handler
must exit without performing any additional actions.
Properties on the object allow your app to retrieve the following items:
The SSID of the wireless network.
Details about the network adapter that is connected to the hotspot.
The URL that contains the WISPr message.
The XML payload of the WISPr message.
The authentication URL to which credentials are supplied.
Other APIs exist to retrieve the following items:
The BSSID of the wireless network (see Windows.Networking.Connectivity namespace ).
DHCP parameters of the network (see Win32 and COM for UWP apps).
By using this information and any other information that your app needs to obtain from the local system or the
network, credentials can be generated. The object also contains methods that permit the app to continue or
complete the hotspot authentication.
Issue credentials
Abort authentication
Use alternate authentication methods
Interact with the user
Issue credentials
In the simplest case, the app generates credentials based on information it has or can retrieve. For example, a
username and password are generated by using information in the WISPr payload and information about the
network adapter.
After performing any actions necessary to generate or obtain credentials, the app calls the IssueCredentials
method on the HotspotAuthenticationContext object. This method permits the app to supply the following:
The WISPr UserName parameter
The WISPr Password parameter
Arbitrary non-standard parameters to include in the WISPr response
Behavior on failure
If the server rejects the credentials supplied by the app, Windows disconnects from the network and does not
retry a connection in the current user session. The final flag allows the application to indicate that if the
credentials are unsuccessful, Windows should never automatically retry a connection by using this profile.
There are two variations of this API. The IssueCredentials method passes the parameters to Windows and then
returns instantly. This API does not provide the outcome of the authentication attempt. The
IssueCredentialsAsync method, introduced in Windows 8.1, is an asynchronous version that enables
applications to retrieve the result of the authentication attempt.
Abort authentication
If the app discovers that it cannot generate credentials for the current network (because roaming agreements
have changed, information is unavailable, or for another reason), it must call the Abor tAuthentication method
on the HotspotAuthenticationContext object.
Windows disconnects from the network and does not reattempt a connection in the current user session. This
function accepts a flag that indicates Windows should never automatically retry a connection using this profile.
Note This method does not remove the profile from the system, and the app can be asked for credentials
again if the user manually attempts to connect to the network. If the profile is completely removed, the app
must supply a new provisioning file that removes the associated profile.
Use alternate authentication methods

If the app can authenticate by using a method other than WISPr, it may do so. After successfully authenticating
to the network by using an alternate method, it must complete the connection by calling the
SkipAuthentication method on the HotspotAuthenticationContext object. When this method is called,
Windows re-detects connectivity to the Internet, thereby helping the user interface (UI) to correctly reflect the
authenticated state.
Note The HotspotAuthentication event is not invoked for hotspots that do not advertise support for the WISPr
protocol. However, this permits an app to choose a different protocol to use in response, or to use a custom
version of WISPr if required.
Interact with the user

If user interaction is required before authentication can proceed, the app must call the
TriggerAttentionRequired method on the HotspotAuthenticationContext object. This method is useful in
the following circumstances:
The user has elected not to store credentials in the app and must sign in.
Completing the connection will charge the user’s credit card or other account; therefore, consent is
required before proceeding.
No credit is available on the user’s account, and a new purchase is required.
This method does not complete the authentication. When this method is invoked, the app requests to be opened
in the foreground by using the specified arguments. The event token should be passed to the foreground
application so that it can retrieve the HotspotAuthenticationContext object again and complete the
authentication by using one of the other three methods.
The app’s request to open in the foreground is not guaranteed to succeed. The HotspotAuthentication event can
occur due to an automatic connection while the computer is in Connected Standby. The app is launched only
when the computer is no longer in Connected Standby, has been unlocked, and is still connected to the wireless
network. Because this delays Internet access until the user unlocks the computer, this state should be avoided
whenever credentials can be generated automatically.
Related topics
Hotspot 2.0
Hotspot 2.0 is a standard for seamless authentication to hotspots. Hotspot 2.0 offers an encrypted connection
between the client and the access point. It uses IEEE 802.11u to communicate with the provider before it
establishes a connection. Authentication and encryption are provided by using WPA2-Enterprise together with
one of several EAP methods.
The following table describes common credential types that are defined by Hotspot 2.0:
O P ERATO R C A N
EA P M ET H O D USER C A N EN T ER P RO VISIO N
C REDEN T IA L EA P M ET H O D SUP P O RT ED C REDEN T IA L S C REDEN T IA L S
Username and EAP-TTLS Yes Yes No

password
Certificate EAP-TTLS Yes Yes No
SIM EAP-SIM or EAP-AKA Yes Yes Yes
*User can select from certificates or the SIM is already present on the system.
Windows 8 and Windows 8.1 do not support the discovery or online sign-up portions of Hotspot 2.0, but they
do support WPA2-Enterprise and all EAP methods that are required by the Hotspot 2.0 specification. Therefore,
Windows 8 and Windows 8.1 can connect to a Hotspot 2.0 network when the user already has credentials.
Because Windows 8 and Windows 8.1 do not support 802.11u discovery, operators must provision Windows 8
or Windows 8.1 with wireless profiles that contain the applicable SSIDs for their networks.
Windows 10 fully supports Hotspot 2.0 Release 1, including discovery and profile creation.
Provisioning Windows using a website
This topic describes how to use a web site to let customers purchase and set up a mobile broadband plan on a
computer that is running Windows 8, Windows 8.1, or Windows 10.
For more info about mobile broadband in Windows 8, Windows 8.1, and Windows 10, see Overview of mobile
broadband.
We recommend that you develop and use a mobile broadband app as it provides the most flexibility and creates
the most integrated experience. However, in a few plan purchase and setup scenarios, a mobile broadband app
might not always be installed and available for use. For these scenarios, Windows 8, Windows 8.1, and
Windows 10 include support to automatically open a mobile broadband web site that is hosted by you and
provides the experiences that are required to complete these scenarios.
Key scenarios that require a mobile broadband web site

The following scenarios require a mobile broadband web site:
First use of a USB modem
First use of a SIM together with an embedded modem
Plan renewal when the app has been uninstalled
First use of a USB modem
A user starts with a Windows 8, Windows 8.1, or Windows 10-certified mobile broadband USB modem that
does not have an active associated data plan. The user connects the USB modem to a Windows 8, Windows 8.1,
or Windows 10 computer for the first time, and the mobile broadband class driver is automatically installed for
the device. The user opens Windows Connection Manager and chooses to connect to the mobile broadband
network.
As part of the connection process, Windows determines that the mobile broadband network does not provide
Internet access because no active data plan is associated with the device. Normally, Windows opens the mobile
broadband app so that the app can provide an option to purchase a data plan or otherwise enable Internet
access. However, because the USB modem was just installed, the mobile broadband app is not yet installed on
the computer.
In this case, Windows opens a web site provided by you. This web site provides the ability to purchase a data
plan or otherwise enable Internet access. After the experience is complete, a data plan is associated with the USB
modem and the computer is granted Internet access on the mobile broadband network.
First use of a SIM with an embedded modem
A user starts with a SIM that does not have an active associated data plan. The user inserts the SIM into a
Windows 8, Windows 8.1, or Windows 10 computer that has an embedded mobile broadband modem. The user
opens Windows Connection Manager and chooses to connect to the mobile broadband network.
Internet access because no active data plan is associated with the SIM. Normally, Windows opens the mobile
broadband app so that the app can provide an option to purchase a data plan or otherwise enable Internet
access. However, because the SIM was just inserted, the mobile broadband app is not yet installed on the
computer.
In this case, Windows opens a web site provided by you. This web site provides the ability to purchase a data
plan or otherwise enable Internet access. After the experience is complete, a data plan is associated with the SIM
and the computer is granted Internet access on the mobile broadband network.
Plan renewal when the app has been uninstalled
A user has been regularly using mobile broadband on a Windows 8, Windows 8.1, or Windows 10 computer. At
some point, the user uninstalled the mobile broadband app and the data plan expired because of an expiration
date or data usage. The user opens Windows Connection Manager and chooses to connect to the mobile
broadband network.
Internet access because an active data plan is no longer associated with the device.
Because Windows cannot start the uninstalled app, Windows opens a web site that is provided by you. On this
web site, provide an experience to renew the user’s data plan or otherwise enable Internet access. After the
experience is complete, a data plan is again associated with the user’s device and the computer is granted
Internet access on the mobile broadband network.
How to enable key scenarios

Use the following guidelines to help you enable these key scenarios.
Enable a simple connect experience
You must provide a minimal amount of data to include in the Windows 8, Windows 8.1, or Windows 10 APN
database. For more info about the Windows APN database, see APN database overview.
You must provide the following information to include in the APN database:
For Windows to connect to a mobile broadband network without requiring the user to input an APN or
access string, you must provide the APNs and/or access strings.
For Windows to automatically open a mobile broadband web site when it detects no Internet connectivity,
you must provide the URL of the web site.
Detect Internet access
When Windows first connects to a network to determine Internet connectivity, it performs various network tests.
The destination site for these tests is www.msftconnecttest.com , which is a reserved domain that is used
exclusively for connectivity testing.
To avoid false positives or false negatives, your network must allow access to www.msftconnecttest.com only
when a user has general Internet access. A user who is connected to your network without having an active data
plan must not have access to www.msftconnecttest.com . For more info, see An Internet Explorer or Edge window
opens when your computer connects to a corporate network or a public network.
Web site access
A mobile operator typically restricts the network access of a user who does not have active data plan by using
one of two methods:
Keep the user on the same APN, but block access to all network destinations except for the minimal set of
servers that are required for plan purchase and activation. This implementation is also known as a
“walled garden.”
Transition the user to a purchase APN that never provides Internet access, but provides access to the set
of servers that are required for plan purchase and activation.
A user who does not have an active data plan must be able to access the mobile broadband web site by using
one of these methods. Additionally, the user must be able to access the web site through the Internet by using
an HTTPS connection.
Device information
When Windows uses the mobile operator’s URL (AccountExperienceURL attribute in the Operator element) from
the APN Database, Windows provides the device information that is required to complete activation to the
mobile broadband web site. This device information is passed to the web site as parameters of the HTTPS
request.
The format of the URL is https://Operator URL[?propN=valN[&propN=valN]*] , where:
Operator URL URL provided by you and stored in the APN Database
propN A property name.
valN The corresponding value to the propery name.
The following table lists the properties that can be included. If a property value is not provided by the mobile
broadband device, that property is not included.
P RO P ERT Y N A M E P RO P ERT Y VA L UE
SubId Subscriber ID
For GSM devices: IMSI (up to 15 digits)
For CDMA devices: MIN or MIN(IRM) (10 digits)
DevId Device ID
For GSM devices: IMEI (up to 15 digits)
For CDMA devices: ESN (11 digits) or MEID (17
digits)
IccId SIM ICCID (19-20 digits)
Configure the computer

After a user has purchased a data plan or otherwise activated the mobile broadband device by using a web site,
it might be useful to make the following configuration changes to the computer:
Define mobile broadband connection profiles
Provide account data
Define Wi-Fi hotspot connection profiles
Instruct the computer to reconnect the mobile broadband device
The same account provisioning metadata that can be applied to a computer by using a mobile broadband app
can also be applied by a mobile broadband website. In the web page’s JavaScript, check for the availability of the
window.external.msProvisionNetworks method. If it is present, the browser can transfer account
provisioning metadata to Windows.
Note Account provisioning metadata must be signed with an extended validation (EV) certificate when
provided by the web site.
Understanding and configuring Windows
Connection Manager
IMPORTANT
This topic is intended for Microsoft's mobile operator (MO) partners who can configure how Windows connects to their
networks. If you are a customer who is experiencing Windows network connection issues, see Fix network connection
issues in Windows.
Automatic connection management, introduced in Windows 8, makes connection decisions by looking at

Ethernet, Wi-Fi, and mobile broadband interfaces. These decisions lead to automatic connect and disconnect
actions on Wi-Fi and mobile broadband interfaces.
NOTE
Windows responds to Ethernet connections but does not automatically manage Ethernet connections.
This topic describes how Windows automatically manages physical wireless connectivity and does not consider
these connections:
Dial-up connections, such as modems
Pure virtual interfaces, such as VPNs and tunneled IP connections
Connection management policies

Windows 8, Windows 8.1, and Windows 10 include a number of policies to control connection management.
These policies are not exposed in the Windows user interface but can be configured by using the
WcmSetProperty API or Group Policy.
Minimize simultaneous connections
This policy is configured using the fMinimizeConnections Group Policy. It is on by default for Windows 8,
Versions of Windows before Windows 10, version 1809, build 17763.404
In Windows 8, Windows 8.1, and versions of Windows 10 before Windows 10, version 1809, build 17763.404,
this policy is a boolean value that can be modified using either Group Policy or the WcmSetProperty API.
If this policy is disabled, the behavior is similar to that for Windows 7 in which each interface connects to the
most preferred network in range, regardless of the connectivity state of other interfaces.
If this policy is enabled, Windows attempts to maintain the smallest number of concurrent connections that offer
the best available level of connectivity. Windows maintains connectivity to the following networks:
Any Ethernet network
Any networks that were manually connected during the current user session
The most preferred connection to the Internet
The most preferred connection to the Active Directory domain, if the PC is joined to a domain
All remaining networks are soft-disconnected, as described in the next section. This is also used to evaluate
available networks that are not connected. Windows will not connect to a new network from which it would
immediately soft-disconnect.
Windows 10, version 1809, build 17763.404 and later
In Windows 10, version 1809, build 17763.404 and later, this value is an enumeration that is only available
through Group Policy.
This policy setting determines if a computer can have multiple connections to the Internet, to a Windows
domain, or to both. If multiple connections are allowed, the policy then determines how network traffic is routed.
If this policy is set to 0 , a computer can have simultaneous connections to the Internet, to a Windows domain, or
to both. Internet traffic can be routed over any connection, including a cellular connection or any metered
network. This was previously the Disabled state for this policy setting in builds of Windows before Windows 10,
version 1809, build 17663.404. This option was first available in Windows 8.
If this policy is set to 1 , any new automatic Internet connection is blocked when the computer has at least one
active Internet connection to a preferred type of network. The order of preference is as follows:
1. Ethernet
2. WLAN
3. Cellular
Ethernet is always preferred when connected. Users can still manually connect to any network. This was
previously the Enabled state for this policy setting in builds of Windows before Windows 10, version 1809, build
17763.404. This option was first available in Windows 8.
If this policy setting is set to 2 , the behavior is similar to when it is set to 1 . However, if a cellular data connection
is available, that connection will always stay connected for services that require a cellular connection. When the
user is connected to a WLAN or Ethernet connection, no Internet traffic is routed over the cellular connection.
This option was first available in Windows 10, version 1703.
If this policy setting is set to 3 , the behavior is similar to when it is set to 2 . However, if there is an Ethernet
connection, Windows does not permit users to connect to a WLAN manually. A WLAN can only be connected
(automatically or manually) when there is no Ethernet connection.
Soft disconnect
The soft disconnect policy works as follows:
1. When Windows decides that a network should no longer be connected, it does not immediately
disconnect. Abrupt disconnections degrade the user experience without providing an appreciable benefit
and are avoided when possible.
2. As soon as Windows decides to soft-disconnect an interface, it informs the TCP stack that the network
should no longer be used. The existing TCP sessions will continue uninterrupted, but new TCP sessions
will use this interface only if explicitly bound or if no other interface routes to the desired destination.
3. This notification to the TCP stack generates a network status change. Networking applications should
listen for these events and proactively move their connections to the new network, if possible.
4. Windows then checks the traffic level on the interface every 30 seconds. If the traffic level is above a
certain threshold, no further action is taken. This allows ongoing active use of the interface, such as from
a file transfer or VoIP call, to avoid disruption.
5. When the traffic drops below this threshold, the interface will be disconnected. Applications that keep
long-lived idle connections, such as an e-mail client, may be interrupted and should re-establish their
connections over a different interface.
Initial connection
Windows automatically connects and then immediately soft-disconnects in one circumstance. When a PC first
starts or resumes from standby, all interfaces simultaneously attempt to connect in order to ensure that the user
obtains network connectivity as quickly as possible. If multiple interfaces successfully connect, Windows begins
soft-disconnecting interfaces immediately.
Prohibit interconnect between domain and non-domain networks
This policy is off by default for Windows 8, Windows 8.1, and Windows 10. When this policy is enabled,
Windows attempts to prevent a PC from being interconnected between a domain network and a non-domain
network. Enterprise administrators may use this when they are concerned about potential security breaches
using a multi-homed machine as an attack point.
This policy does not affect system behavior when all connected networks route to the domain or when no
connected network routes to the domain.
Multiple wireless networks
Many Windows 8, Windows 8.1, and Windows 10 mobile devices have an external Internet connection available
to them at all times, even when in range of their enterprise Wi-Fi networks. When this policy is enabled, users
may freely connect to either their public mobile broadband network or to the enterprise’s private Wi-Fi network
and switch between them at will. However, manually connecting one will automatically cause the other to
disconnect immediately.
Ethernet
Because Windows 8, Windows 8.1, and Windows 10 cannot automatically connect Ethernet cables to or
disconnect them from a PC, they can only enforce the policy by allowing or prohibiting wireless connections.
When a PC has an Ethernet connection to the domain network, wireless networks that do not connect to the
domain cannot be connected, and vice versa. Attempts to do so will result in the following error:
For PCs that have multiple Ethernet ports, Windows cannot prevent an interconnection that is created by
physically connecting the PC to two different Ethernet networks.
Effect on soft disconnect
Because prohibiting interconnections is a security consideration, any disconnections that comply with this policy
take effect immediately, even if there is ongoing activity. Users will experience a connectivity disruption when
transitioning between public and corporate networks, even if the two networks overlap.
For example, a user engaged in a VoIP call over a mobile broadband network with a laptop docked to a
corporate Ethernet connection will lose the call, although the app may be able to automatically recover over the
new connection. If the policy was not enabled, Windows would instead soft-disconnect the mobile broadband
connection by waiting for the call to complete. On the other hand, a VoIP call started over a corporate Wi-Fi
network will not be disrupted when docked to the corporate network because both networks connect to the
domain. The Wi-Fi network is disconnected after the call is completed.
Prohibit roaming on mobile broadband networks
This policy prevents Windows from connecting to mobile broadband networks that are in a roaming state. By
default, this policy is disabled, and the user may choose to manually connect to a mobile broadband network
while roaming or to enable automatically connecting to such a network. When this policy is enabled, the user
cannot choose a roaming mobile broadband network from Connection Manager.
Network preferences
When considering which multiple connections to maintain, Windows uses a number of traits to determine the
preferred networks. This is used only when determining whether to maintain a connection to a given interface,
not for routing. If a connected interface is not in the process of being soft-disconnected, routing is determined
by the metric in the routing table. If the route metric is not specified manually, Windows will automatically
assign a route metric based on the link speed of the adapter.
Connection priorities
Windows prioritizes connections in the following order:
1. Ethernet networks
2. Networks manually connected during the current user session
3. Networks that connect to both the Internet and the Active Directory domain to which the PC is joined
4. Signal strength of the currently connected Wi-Fi network
5. The PC’s preferred network list
Even though the link speed influences routing behavior among currently connected interfaces, Windows does
not make connectivity decisions based on the link speed or throughput of a network. It is not possible to
configure Windows to change its connection preference between a mobile broadband network and a Wi-Fi
network based on the current speed of the mobile broadband network. If both are connected, the user or a
desktop app can change route metrics to influence routing preferences.
Signal strength
For Windows 8 and Windows 8.1, if Windows detects that the currently connected Wi-Fi network has very low
signal strength, it may choose to connect a mobile broadband network (if permitted by policy) to avoid
disrupting network connectivity. This helps to smooth the transition when a user is moving away from a wireless
access point.
Windows does not disconnect a more preferred Wi-Fi network until the signal strength cannot maintain the
connection. If signal strength improves, Windows may soft-disconnect the mobile broadband adapter.
Windows 10 does not use the Wi-Fi signal strength.
Preferred network list
In most situations, the preferred network list determines which wireless network profiles Windows will use to
connect. Prior to Windows 8, this list applied to Wi-Fi networks only. In Windows 8, Windows 8.1, and
Windows 10, it can also include mobile broadband networks.
Automatic generation
Windows 8, Windows 8.1, and Windows 10 automatically update the preferred network list based on user
actions. Any manual connection or disconnection will update the network list so that the same behavior will
occur automatically in the future.
The following user actions modify the preferred network list:
Initially connecting to a network The new network is added to the network list. The user specifies
whether the network will automatically connect in the future.
Connecting to a new Wi-Fi network for the first time makes the network the most preferred
network in the list.
Connecting to a new mobile broadband network for the first time makes the network the least
preferred network in the list.
Manually connecting to a Wi-Fi network Any other Wi-Fi network in range that is higher on the list
is moved below the newly connected network in the list. The user specifies whether the network
automatically connects in the future.
Disconnecting from a network Windows will not automatically connect to this network in the future.
It remains on the network list in case the user modifies this setting in the future.
Group Policy
Wi-Fi profiles created by Group Policy are at the top of the network list. The user may manually disconnect from
these networks or manually connect to other networks, but these networks remain at the highest position on the
network list until removed by Group Policy.
Carrier-provisioning metadata
Mobile broadband and Wi-Fi hotspot operators provide Windows with a series of mobile broadband and Wi-Fi
profiles by using the ProvisioningAgent or msProvisionNetworks APIs.
When initially provisioned, the operator-created profiles are added to the top (Wi-Fi only) or bottom (if mobile
broadband is included) of the existing network list. You cannot influence the position of the networks the user
provisions in the network list. However, you can define the relative order of their networks in the network list.
The user’s actions may modify the network list between applications of provisioning metadata. When
provisioning metadata is reapplied, your desired network order is restored. However, the reordered set of
networks is moved to the lowest position to which the user had moved any of your networks.
The preference between networks in the provisioning metadata is determined by the following:
1. The optional priority attribute on each network profile
2. Media type (Wi-Fi is more preferred than mobile broadband)
3. Order specified in the XML file
Manual modification
Prior to Windows 8, the Wi-Fi preferred network list was accessible to the user through the Manage Wireless
Networks control panel. Telemetry indicates that very few users ever accessed this functionality. Additionally,
this user interface was tied to Wi-Fi only and could not incorporate preferences between Wi-Fi and mobile
broadband.
Most users will not need to manually modify the network list. However, certain users or applications may find it
necessary to do so.
User interface
To remove a profile from the preferred network list while it is in range, select and hold (or right-click) the
network and choose Forget this network . A network that is not in range cannot be removed from the list
through the user interface.
Win32 APIs
An application may create new profiles in the network list using the appropriate media-specific API:
For Wi-Fi networks, use the WlanSetProfile function.
For mobile broadband networks, use the
IMbnConnectionProfileManager ::CreateConnectionProfile method.
To modify the order of the network list, use the WcmSetProfileList function. We do not recommend using the
WlanSetProfileList function, as it may disturb the position of mobile broadband profiles in the network list in
unintended ways.
To delete profiles from the network list, use the appropriate media-specific API:
For Wi-Fi networks, use the WlanDeleteProfile function.
For mobile broadband networks, use the IMbnConnectionProfile::Delete method.
Command-line
A user or script may create new profiles in the network list by using the appropriate media-specific commands:
For Wi-Fi networks, use the netsh wlan add profile command.
For mobile broadband networks, use the netsh mbn add profile command.
The order of the Wi-Fi profiles in the network list may be modified using the netsh wlan set profileorder
command. However, this is not recommended and can disturb the position of mobile broadband profiles in the
list in unintended ways.
To delete profiles from the network list, use the appropriate media-specific commands:
For Wi-Fi networks, use the netsh wlan delete profile command.
For mobile broadband networks, use the netsh mbn delete profile command.
Conflict resolution
When multiple profiles exist for the same network, Windows 8 and Windows 8.1 use the following logic to
determine which profile should be used:
1. Profile Type
a. Group Policy profiles are preferred over user-created profiles.
b. All-user profiles are preferred over single-user profiles.
2. Interface Arrival The profile on the most recently installed interface will be used.
UWP mobile broadband apps overview

UWP apps
UWP mobile broadband apps and MBAE apps
UWP apps
UWP apps are full-screen or windowed apps that are tailored for the following:
Your users’ needs
The devices that they run
Touch interaction
The Windows user interface
UWP apps are optimized for touch, are aware of the user's location and identity, and are hosted in the Microsoft
Store. UWP apps are always on and available for instant use, and always connected with the latest content from
the web. Users can discover and purchase these apps in the Microsoft Store: the apps can be installed quickly
and uninstalled cleanly.
All UWP apps share the following features and benefits:
Development platforms UWP apps are built by using the Windows Software Development Kit for
Windows 10 and the Windows Runtime APIs.
Programming languages You can build UWP apps by using JavaScript with an HTML and cascading
style sheets (CSS) presentation layer, or by using C++ or C# with an Extensible Application Markup
Language (XAML) presentation layer.
Touch optimization Touch interaction support is built-in. You can design your mobile broadband app
for touch, and Windows gives you keyboard, mouse, and graphical scaling support.
For more info about UWP apps, see Getting started with Windows 10 apps.

A UWP mobile broadband app is a UWP app that is authored by mobile operators and is associated with a
mobile broadband connection. In addition to the benefits of being a UWP app, this app has special access to
privileged mobile broadband APIs.
A mobile broadband app provides the following benefits:
Increased customer connection Users can easily discover the operator’s brand and services from the
Windows Star t screen and from the network list.
Ongoing control over the experience You can use the app to change subscribers’ account
experiences.
Reduced deployment and maintenance burden The app is automatically deployed on the customer
device either by using the Internet, or preinstalled by the original equipment manufacturer. When a user
first attaches the mobile broadband hardware, Windows automatically searches the Microsoft Store for a
mobile broadband app that has been associated with the device by using service metadata, and
automatically installs the appropriate app for the mobile broadband connection. This makes it easier for
users to discover and use a mobile broadband device and services that are associated with that device.
This app does not provide connection management functionality, but instead provides account experience and
branding for your service.
IMPORTANT
Your app must optimize for touch input and follow Windows 10 UI design principles. For more info about how to design
the user experience for mobile broadband apps, see Designing the user experience of a mobile broadband app.
UWP mobile broadband apps and MBAE

Mobile broadband app experience apps, or MBAE apps, are replaced in Windows 10, version 1803 and later by
MO UWP apps. MO UWP apps are now part of COSA and don't require creating service metadata on the
Windows Dev Center Hardware dashboard (Sysdev). Windows 8, Windows 8.1, and versions of Windows 10
before 1803 continue to use MBAE apps via service metadata published on Sysdev.
In Windows 10, version 1803, MBAE apps work without having to migrate to COSA. However, we strongly
recommend that mobile operators migrate to an MO UWP app and COSA. For details about COSA, see COSA
overview. For more information about COSA settings, see Desktop COSA/APN database settings.
If the AppID setting is filled out in COSA, Windows will not check for a matching Sysdev metadata package to
download your app. If AppID is not filled out, then Windows will check for a matching Sysdev metadata
package to download your app.
The following table provides information about the differences between MBAE and MO UWP apps.
APP TYPE TA RGET P L AT F O RM DEL IVERY M EC H A N ISM IC O N RET RIEVA L
MBAE Windows 8, Windows 8.1, Sysdev metadata Sysdev metadata or COSA if

or Windows 10 declared as part of the
profile
MO UWP app Windows 10 (preferably COSA database COSA database

version 1803 and later with
the same SDK version)
UI source code between MBAE and an MO UWP app might differ due to changes between Windows 8/Windows
8.1 and Windows 10 UI principles. Most business logic source code, however, should not require much change.
For example, the code for accessing the back end and accessing mobile broadband information might be the
same. However, MOs should validate each of the Mobile broadband app scenarios accordingly.
Account management
After users have purchased a subscription, they can perform following tasks:
View current data usage Users can view their current data usage and understand their billing cycle (or
session end date) to make an appropriate decision on their data usage.
Manage account settings Users can view and securely manage their payment and account details
(such as password, email address, and automatic payment information).
Pay a bill Users can pay their recurring or one-time bill by using your UWP app.
Account management functionality presents a subscriber’s relationship with an operator. You can use this to
create a branded experience that can distinguish your service from competitors’ services.
Design considerations include the following:
Make data usage a combination of local and back-end information To reduce the load on the
back-end servers as much as possible, Windows provides a local Data Usage API that you can use to
combine back-end data usage. You can periodically get the usage information from the back-end and
correlate that with local data usage.
Periodically update Windows with data usage Windows 10 is designed to behave intelligently on
metered networks. This can save significant network capacity because Windows and UWP apps can use
your mobile broadband network for essential traffic. To be more accurate and to include more
information for applications (for example, data limits and usage), Windows relies on you to periodically
provide correct information. Your app can set this information by using Data Usage APIs.
App startup
When the mobile broadband app is started, it should check whether Internet access is available. The app can use
an API to discover the various states of Internet connectivity. The app can then determine whether it can access
back-end data when the Internet connection is in a “walled garden” state. If there is no Internet connection, the
app should show an appropriate message or offline experience to the user.
If multiple operators’ subscriber identity modules (SIMs) are attached to the PC, the app can determine this. The
app must present a user interface that works for multiple connected operator devices or accounts.
For example, the app can read the IMSI and IMEI information from the mobile broadband device. This
information can be used as part of the authentication scheme, in addition or in place of a logon screen that
sends user-name and password information to the back-end. Windows provides an API to securely store user-
name and password information that the app can subsequently use for authentication after the first logon
attempt. All user-name and password information must be exchanged with the operator back-end over Secure
HTTP (HTTPS).
Related topics
Help and support
You can reduce customer support calls by providing help and support through your mobile broadband app.
In your app, you can provide access to self-help material in addition to assisted support channels. You can create
a section where the users can find answers to the most common questions. You can simplify the help
information based on a user’s device or firmware.
You can simplify the user experience by showing help for the user’s device only. You can get device model and
firmware information by using the Subscriber and Device Information API.
Related topics
Hot spot authentication
You should offload data traffic to Wi-Fi hot spots whenever possible. Windows Connection Manager can
automatically connect to Wi-Fi networks when they are available. To connect to Wi-Fi networks, you must
provide hotspot credentials to Windows. You can provide hotspot credentials by implementing your own
authentication in the app.
Related topics
Live tile updates
On the Windows 10 Star t menu, tiles are the primary representation of an app. Users start their apps through
those tiles, and the tiles can display new, relevant, and tailored content to the users. You can keep tiles alive with
activity and draw users back into your app repeatedly. You can display information about Premium services, or
any important information that you want to bring to users’ attention.
Related topics
Notifications
You can keep your users informed through service notifications such as plan activation status, approaching data
cap, and currently roaming. Windows supports existing channels such as SMS, USSD, and Windows Notification
Service to trigger notifications.
Your mobile broadband app should communicate time-critical events to the user through toast notifications
whether the user is in another app, on the Star t screen, or on the desktop.
Your app can receive background events to process SMS or USSD notifications. For info about background
notifications that are associated with mobile broadband apps, see these API pages under the
Windows.ApplicationModel.Background namespace:
MobileBroadbandDeviceServiceNotificationTrigger
MobileBroadbandPcoDataChangeTrigger
NetworkOperatorNotificationTrigger
SmsMessageReceivedTrigger
Related topics
Plan purchase
A simple and intuitive on-device plan purchase that is integrated with the Windows experience can simplify the
subscription acquisition process and let users purchase the subscription when they need the mobile
connectivity.
Developing a plan purchase experience involves the following:
Determination of subscription status When the app is started, it should intelligently determine
whether the device has a currently associated plan, and then show the appropriate experience based on
that. For existing users who have no current associated plan, the app can show an Account Management
experience and a Purchase Subscription experience.
To determine the current subscription status, the mobile broadband app can get device and subscription
information from Windows — for example, International Mobile Subscriber Identity (IMSI), Integrated
Circuit Card ID (ICCID), and International Mobile Equipment Identity (IMEI). It can use the connectivity
status of mobile broadband connection to determine whether the user has a plan.
Purchase or top-up experience The purchase business-logic details (such as plan information,
payment, and credit card validation) must be maintained in your app. Windows supports web services or
cellular protocols such as Unstructured Supplementary Service Data (USSD) to interact with your back-
end systems to develop this business logic.
Provisioning After the user has purchased the plan, Windows must provision the device and you must
activate the device in its back-end. Provisioning is defined as configuring a Windows-based computer
with information that is required to connect to a carrier network. This typically occurs after a subscription
purchase. Provisioning information contains mobile broadband profile (access point name [APN], user
name, and password), hot-spot profiles, Wi-Fi credentials, and plan information. Windows can use this
information to automatically connect to your network without any user input.
For more info about provisioning, see Account provisioning.
For some carriers, the activation process on the mobile network is not instantaneous and can take up to ten
minutes. Your app must handle this case elegantly and give a good user experience. The Windows activation
experience should get information about estimated activation time and display that information to the user
during the purchase.
Design considerations include the following:
Simplify the user experience by retrieving device information During a purchase, your business
logic needs device information to show the plans that are available for the device. Your app can get the
information by using the Subscriber and Device Information API; therefore, you don’t have to ask the user
to manually enter this information.
Provide a seamless connection experience by using the Provisioning API After the user has
purchased the plan, you can assign credentials to the subscription. The user must use these credentials
and connectivity parameters to connect to your network. You can use the Provisioning API to provide this
information. The Provisioning Engine will store this information and automatically connect to your
network.
Choose the back-end interaction For purchasing the plan, the user can use limited connectivity,
alternate Internet connectivity (home, coffee shop), or control channel protocols (USSD).
The following flow chart describes how plan purchase works with Windows and UWP apps:
Related topics
Premium services
You can use your mobile broadband app to let users discover and consume additional services.
Related topics
Introduction to designing the user experience of a
mobile broadband app
This topic provides information about how to design UWP mobile broadband apps for Windows 10. It provides
user experience design guidelines to design apps for users to manage their mobile broadband account and
service. It assumes you familiar with mobile broadband technology, Windows mobile broadband networking,
and the Microsoft Store app platform.
Key scenarios
App organization
Key scenarios
The mobile broadband app should include the following key scenarios:
Plan purchase
Purchase a new subscription to data service.
Refill account balance to a plan.
Account management Displays account data and current plan information.
View data usage
Display current data usage and billing cycle information.
Update Windows with the latest data usage.
Notifications Display data usage and other important account and service messages.
Help and Suppor t Display troubleshooting and customer support contact information.
App organization
The following shows how different pages in the app can be organized:
The app has an account overview landing page that provides a summary of a customer’s account and
data usage. It also contains links to other app pages.
From the landing page, end users can visit a hub page to view billing, plans, services, or help and support
details.
Some hub pages lead to task pages and flows, such as a purchase checkout flow.
Tip For prepaid plans, the account overview could directly link to a Make a Payment page for refill scenarios.
For more information about how to design these pages, see the following topics:
Design the landing page of a mobile broadband app
Design account balance and usage info in a mobile broadband app
Design help and support pages in a mobile broadband app
Design services and goods pages in a mobile broadband app
Index of UX guidelines for UWP apps
Design the landing page of a mobile broadband
app
The landing page is the first page that the user sees when they start the mobile broadband app, except for
certain cases that are described in Integrate a mobile broadband app with other Windows components.
The landing page should follow UWP app guidelines for app layout. To encourage simplicity and ease of
navigation, we recommend that you fit all contents of the landing page into a single page. The landing page is
the central hub of your app. Although it is not a primary navigation method or management page, it showcases
your app and its major functionality.
The following sections describe some of the content that you can include in the landing page:
Usage – show an overview or link
Operator messages – show an overview or link
Links to other key pages
App navigation
Operator branding
Quick summary
Usage – show an overview or link

Postpaid plans
Because it is important user to be able to see information about their data usage, usage should be highlighted
on the landing page if possible. Although an overview is encouraged, you can alternatively provide a link to a
separate page in the app that contains more details. Some suggestions for additional details can be found in the
data usage section. See Design account balance and usage info in a mobile broadband app for more info.
Prepaid plans
Data usage display is simplified for prepaid plans. A user should also be offered an option to recharge or refill
their plan. You can provide a link to a page that offers payment options. See Design billing pages in a mobile
broadband app for more info. The following shows a typical overview page for a prepaid plan:
Operator messages – show an overview or link

A list of operator text messages can be highlighted on the landing page. Because a number of operator
messages are high priority, users prefer having easy access to these. For more information about functionality
that should be included for text messages, see Design messages in a mobile broadband app.
Links to other key pages

You can provide links to other key pages on the landing page. For example, you could include a tile for Help
and Suppor t and a tile for Ser vices .
App navigation
When describing the landing page, it is important to consider navigation within the app. Your app will have
multiple pages that have various purposes. Windows 10 offers the following tools that can be used for
navigation:
Back button The Back button can be used to return to the previous page in the app. For more
information about the Back button styling, see Quickstart: styling controls.
Drop-down affordance with header text The header text can be used as a drop-down affordance for
navigation between multiple pages in an app. In the previous figures, clicking Account Over view would
result in a drop-down list of pages in the app that can be navigated to, as shown in the following figure:
For more information about designing app navigation, see Quickstart: Using single-page navigation and
select element | select object .
Operator branding
You can customize your mobile broadband app to suit your individual branding style. By using numerous
customizations, you can make your app unique and easily recognizable. For more info on how you can brand
your app, see Design branding in a mobile broadband app.
Quick summary
Appropriate design for the landing page
Show information at a glance that users will primarily look for in your app.
Use a simple layout to improve readability.
Follow UWP app guidelines.
Disable the Back button if this is the first time that the user is visiting the app.
Inappropriate design for the landing page
Don’t have scrolling on the landing page. Try to restrict all content to a single page.
Don’t have management functionality on the landing page.
Index of UX guidelines for UWP apps
Adding controls and content
Make great UWP apps
Laying out your UI
Related topics
UWP apps encourage branding in the following ways:

Customization of colors and fonts This includes being able to customize background colors and font
colors. For example, you can use your look or brand colors in the app.
Use brand imager y Windows Connection Manager uses logos together with metadata. We
recommend that you keep the imagery simple, to keep the overall look and feel of the app inviting. You
can use brand imagery on the splash screen and on the start screen tiles.
You can use branding in the following places in your mobile broadband app:
Start screen tile (small)
Start screen tile (medium)
Start screen tile (wide)
Start screen tile (large)

Integrate a mobile broadband app with other Windows components shows brand name
Uninstall user interface (UI) on the Star t menu shows an icon and name
Toast notifications
Task manager with brand icon and name

Mobile broadband information in computer settings (shows operator name)
Splash screen

For more info about Windows 10 branding guidance, see UWP app marketing guidelines.
Quick summary
Appropriate design for operator branding:
Use primary and secondary corporate brand colors in your app for backgrounds and fonts.
Use brand icons appropriately to maintain simplicity and follow UWP app design guidelines.
Inappropriate design for operator branding:
Don’t fill up white space with icons and images.
Related topics
Design account balance and usage info in a mobile
broadband app
Users primarily use your mobile broadband app to view account balance and usage information. This data
should be clearly visible on the app’s home screen.
Relevant account information for post-paid accounts includes the following:

Mobile phone number of account
Account balance remaining
Data used, roaming data used, and usage remaining
Billing period or plan expiration date
At a glance, users can clearly understand how much data they’ve used, how much data they have left, and when
the billing cycle ends (for monthly accounts).
Relevant account information for prepaid accounts includes the following:
Mobile phone number of account
Account balance remaining
Recharge Now button, which links to make a payment page
Data used and remaining
Plan expiration date (if it exists)
Quick summary
Appropriate design for displaying account info:
Show relevant account information
Show when data was last updated
Use illustrations, such as charts and graphs, to visualize data
Tip You can implement a bar chart by using a determinate progress bar control, as discussed in Adding
progress controls.
When remaining usage is low, show a link to the Plans page to upgrade the plan
Inappropriate design for displaying account information:
Don’t show a long paragraph of legal disclaimers next to data usage. This can distract users from the main
focus of the account usage section. Instead, show a link to a separate section of the app that has the full legal
disclaimers.
Related topics
Your mobile broadband app is a convenient way to communicate with your customers about important account
information. The app should have a section or link on the home screen where end users can view important
account messages. While important operator messages should be shown as tile and toast notifications, they
should also be shown in app view because of the transient nature of toast notifications and the limited amount
of text that can be shown in a tile notification.
You should not show user-to-user chat text messaging, promotions, and advertisements in the messages section
mixed together with operator notifications and alerts because customers might miss important operator
notifications. You can display promotions and advertisements in the layout of your app and display user-to-user
chat text messages in a separate section of the user interface.
The following table shows some example operator messages and alerts.
TYPE EXA M P L E M ESSA GE
International roaming Welcome to the UK. For $5 per day you have 25 MB of
data, and then it's $1 per 1 MB. SMS is $0.49 per msg.
Learn more at www.contoso.com/rates/uk.
Data usage overage You’ve used your entire 4 GB data plan. Overage bills @
$10/GB. Save on more data by upgrading your plan
today in the Plans page.
TYPE EXA M P L E M ESSA GE
Data usage status You’ve used 65% of your 40 GB data plan. Any overage
bills @ $5/GB. Tip: Data is unlimited over Wi-Fi. Learn
more in the Plans page.
Plan expiration Your plan expired on July 1, 2013. Renew your plan by
going to the Plans page.
Account update Great news! Effective immediately, Contoso is increasing

the amount of data included in your DataPro Tethering
plan from 2 GB to 4 GB. The monthly charge for your
plan will not change and no action is required by you.
Thank you for being a great customer.
Quick summary
Appropriate design for showing operator messages:
Include functionality to view a list of all messages received, view full details of a message, and delete a
message.
Show important operator messages in a section of the home screen of the app or on its own page in the
app.
Inappropriate design for showing operator messages:
Don’t show user-to-user chat text messages and promotions and advertisements mixed together with
operator notifications and alerts.
Use ListView to display messages. For more info, see Adding List View, Semantic Zoom, and other data
controls.
Use the app bar control to view and delete messages. For more info, see Guidelines for app bars.
Related topics
You should provide the user with the ability to view a billing summary, billing history, make payments, or
recharge the plan.
The Make a payment form should adhere to form guidelines that are described in Design purchase flows in a
mobile broadband app. This page can be linked to from the Billing page for post-paid plans, and through the
Recharge now button on the landing page for prepaid plans.
Quick summary
Appropriate design for the billing page:
Follow the form guidelines, including left alignment, white space, proper grid alignment, and touch
friendliness.
Use vertical scrolling for long forms because this makes it easier to tab and to use the online keyboard.
Make the making payments process a simple experience.
Inappropriate design for the billing page:
Don’t try to fill up white space.
Don’t use an iframe to host the flows. Instead, build flows directly into the app experience.
Don’t make the user wait long times without providing visual feedback.
Don’t link to external sites outside of the app.
For more information about views and layouts: see Choosing a layout.
For more information about Listviews, see Quickstart: Adding a ListView.
For design guidance for error handling, see Laying out your UI.
For accessibility guidance, see Accessibility in UWP apps using C++, C#, or Visual Basic.
For more information about how to use built-in controls, see Adding controls and content.
For touch input guidelines, see Quickstart: Touch input.
Related topics
Your mobile broadband app can include a purchase flow for users to use to purchase plans. For first-time
purchases, support your purchase flow over the web. Here are some standard recommendations for the
purchase flow.
Note Do not use an iframe to host these flows in your app.
1. Show users the plan details and allow them to select a plan before you forwarding them into a complete
purchase flow.
2. You can optionally provide a data breakdown for users to estimate the data that they will require. This can
help the user select the best plan to purchase.
3. If your purchase flow contains forms, follow these guidelines:

Allow vertical scrolling in form pages.
Make sure that all form fields are left-aligned.
Because the app must be compatible with multiple form factors, we recommend that you provide
touch-friendly spacing between form fields.
Leave plenty of white space to promote simplicity.
Follow best practices for form support. This includes, but is not limited to, providing proper
support for address, number, and credit card fields.
Make sure that the input scope is defined for form fields so that the appropriate touch keyboard
shows for fields—for example, number, text, and so on.
Make sure that the form has all controls and fields properly aligned.
Minimize the number of clicks and fields.
4. After the user enters their information, allow them to review the order before completing the purchase. If
the order is placed and activation is quick, continue with activation and redirect the app to the landing
page. If activation is expected to take longer, you can include a placeholder page for activation progress
and use a progress control to show that activation is happening. For more info about progress controls,
see Quickstart: adding progress controls.
Quick summary
Appropriate design for purchase pages:
Follow the form guidelines, which include left alignment, white space, proper grid alignment, and touch
friendliness.
Use vertical scrolling for long forms to make it easier to tab and to use the onscreen keyboard.
Let users review and select plans before you start the purchase flow.
Support purchase over the web and first-time purchase.
Inappropriate design for the purchase, recharge, refill, and billing pages:
Don’t use horizontal scrolling for long forms.
Don’t fill up all the white space.
Don’t use an iframe to host the flows.
Don’t make the user wait a long time without providing visual feedback.
Don’t link to websites outside of the app.
For more information about views and layouts: see Choosing a layout.
For more information about Listviews, see Quickstart: Adding a ListView.
For design guidance for error handling, see Laying out your UI.
For accessibility guidance, see Accessibility in UWP apps using C++, C#, or Visual Basic.
For touch input guidelines, see Quickstart: Touch input.
Related topics
Design help and support pages in a mobile
broadband app
Customers who encounter issues using your mobile broadband service will go to the Help and Support page:
We recommend that you show the following information in the Help and Support section:
Instructions or tutorial videos on how to use the mobile broadband service
FAQs about mobile broadband hardware and service
Online chat with customer support
Customer support telephone number
Hardware and software diagnostics information
Quick summary
Appropriate design for help and support page:
Displaying Help and Support content should not require Internet access. The customer might not have
Internet access because they are having issues connecting to your service.
Inappropriate design for help and support page:
Don’t display links that open a web page in an external web browser.
All help and support content should appear inside the app, and the user shouldn’t have to switch
between apps.
Related topics
Design services and goods pages in a mobile
broadband app
You can use your mobile broadband app to publicize other related services. Use the recommended layouts to
organize various services that you want to promote through the Microsoft Store. An example of service
promotion with an organization into categories is provided here.
Quick summary
Appropriate design for the Services and Goods page:
Follow the grid layout for the services page.
Use pictures and brief headings to describe each service.
Use the Microsoft Store for cross promotion.
Use natural panning and zooming as well as horizontal scrolling.
Inappropriate design for the services page:
Don’t link to external sites outside of the app.
Quickstart: Adding a ListView
Related topics
Integrate a mobile broadband app with other
Windows components
You can use Windows 10 user interface (UI) surfaces to enhance the overall experience of your mobile
broadband app.
For additional user experience design guidelines for layout, navigation, commanding, animations, touch
interaction, snapping and scaling, contracts and capabilities, tiles and notifications, UI controls, app roaming to
the cloud, and fundamentals, see Index of UX guidelines for UWP apps.
This topic contains the following sections:
App settings
Error user experience
App views
Launch points
Tile and toast notifications
Splash screen
Quick summary
App settings
You can use App settings to include settings for your apps configuration. Some examples of these are as follows:
Sign in and sign out
View and edit the user profile
Change billing address
View and edit payment options
View and set marketing preferences
Error user experience

General
Your mobile broadband app can have a number of error cases that should be dealt with gracefully. Some
common examples are as follows:
Device is missing or unplugged Appears when a device such as a SIM or a dongle is missing or
unplugged.
Locked device Appears when a connected device is locked to the user.
Internet connectivity lost Appears when no network connection is detected.
Multiple devices are plugged in Appears when a built-in adaptor and an external dongle are plugged
in. A notification bar error is recommended for such cases.
Form field validation errors Appears when a user enters incorrect information into a form. Validation
errors should be shown inline so that the user knows the field with which the error is associated.
For guidance on how to present errors, see Laying out your UI. In the example below, a notification bar is
displayed at the top of the page.
Errors in data usage

The following error cases should be shown on the overview page in the following ways:
When the user is near plan expiration : Use a bar on the top of the screen to indicate that the user’s
plan is close to expiration.
When usage is over the data cap The data bars should be full and there should also be an inline
message that describes the issue and tells the user what to do about it. Alternatively, the over data cap
usage message can be in a notification bar on the top of the page.
When the plan is expired : Use a bar on the top of the summary box to describe the issue and actions
that the user can take. In this case, data usage, billing cycle, and roaming information is not displayed.
International roaming : Indicate roaming at the bottom of the summary section.
App views
Your app should be adaptive and be able to fit a number of layouts, including:
Landscape
Portrait
Side by side with another app
Filled
Keyboard up
Note When the touch keyboard is up, make sure that elements such as form fields scroll appropriately.
The following examples show how some pages look when side by side with another app.
Make sure that your app is accessible through app views, including high-contrast mode and screen reader
readiness. For more information about how to make your app accessible, see Accessibility in UWP apps using
JavaScript.
Launch points
Your mobile broadband app is available to users in the All Apps view, in Windows Connection Manager, or
through a toast notification.
Launch from Windows Connection Manager
You can connect to the mobile broadband app by using Windows Connection Manager. Your app should open to
the landing page with account and data usage information. After you are connected, Windows Connection
Manager shows the current account and data usage.
Automatic launch from connection manager during a captive por tal purchase flow
When the user is connected to a captive portal network where web traffic is redirected, Windows provides you
the option to automatically launch their app if it’s installed. The app should open to the Plans page that provides
information on how to purchase Internet access.
Launch app from tile in All Apps view
Your app should support users who have multiple simultaneous accounts (for example, using two external USB
mobile broadband adapters). When your app is launched from a tile, your app should let users select the
account that they want to use.
If your app was suspended or already running, it should show the last page used. If your app wasn’t already
running or suspend information is not available, your app should open to the landing page.
Tile and toast notifications
In the Star t menu, tiles are the primary representation of an app. Users launch their apps through those tiles,
which can display new, relevant, and tailored content through notifications. This makes the Star t menu feel
vibrant, and allows the user to see what's new at a glance. An app can also communicate time-critical events to
the user through toast notifications, whether the user is in another app, on the Star t screen, or on the Desktop.
The methodology to design and deliver toast closely parallels that of tiles, thereby lowering the learning curve.
A toast notification can contain text and images but do not support secondary actions such as buttons. Think of
toast as similar to a Windows balloon notification from the taskbar's notification area. Like balloon notifications,
a toast appears in the lower-right corner of the screen. When a user taps or clicks on the toast, the associated
app is launched in a view that is related to the notification. This is the only mechanism by which one app can
interrupt a user in another app. Toasts can be activated, dismissed, or ignored by the user. The user can disable
all toasts for an app.
A toast notification should be used only for information of high interest to the user and typically involves some
form of user opt-in. It is a good choice for incoming email alerts, IM chat requests, and breaking news. However,
it is very important that when you consider using a toast notification, you realize that, due to its transient nature,
the user might never see it. When using toast notifications for data usage overage or roaming alerts, consider
showing the information on your tile and within your app views in case the end user misses the toast
notification.
Splash screen
You can use splash screen to promote branding. For more info about the splash screen, see Adding a splash
screen.
Quick summary
Appropriate design for operator notifications:
Use both toast and tile notifications to alert users of important and high-interest messages that relate to
the subscriber’s account and service plan.
Customize toast and tile background colors and logo based on your brand guidelines.
Include important SMS or USSD operator notifications and alerts that relate to the subscriber’s account
and service plan directly on the landing page.
Inappropriate design for operator notifications:
Don’t show toast notifications for information that is not real time (such as promotional advertisements).
Don’t show user-to-user chat messages and promotions and advertisements mixed together with
operator notifications and alerts, because end users can miss important operator notifications.
Working with tiles, badges, and toast notifications
Guidelines and checklist for toast notifications
Related topics

Retele Wi Fi Telef

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Retele Wi Fi Telef

Uploaded by

Copyright:

Available Formats

Contents

API DESC RIP T IO N

Provisioning API Enables you to provision Windows with account

SMS API Provides functions that are required to implement an

USSD API Enables you to establish an Unstructured

The following sections are available in this topic:

Mobile Broadband Account API

<DeviceCapability Name="BFCD56F7-3943-457F-A312-2E19BB6DC648" />

Network Account IDs

The connection profile API, which is part of Windows.Networking.Connectivity.NetworkInformation ,

var myNetworkAccountId = "{95499FEF-1579-4547-A0BE-FF271ADBBE76}";

var myDeviceInfo = myNetworkAccountObject.currentDeviceInformation

var myNetwork = myNetworkAccountObject.currentNetwork

var myNetwork = myNetworkAccountObject.currentNetwork

P RO P ERT Y O F M O B IL EB RO A DB A N DDEVIC EIN F O RM AT IO N

Telephone Numbers TelephoneNumbers (only available after network

To know when network connectivity changes, use the AccountUpdated event of

var myConnectionProfileList = myNetworkAccountObject.getConnectionProfiles();

2. Create an IMbnInterfaceManager instance.

Updating the provisioning metadata

Provisioning metadata contents

IDEN T IF IER DESC RIP T IO N

%d Day of month as decimal number (01 – 31)

%H Hour in 24-hour format (00 – 23)

%I Hour in 12-hour format (01 – 12)

%m Month as decimal number (01 – 12)

%M Minute as decimal number (00 – 59)

%S Second as decimal number (00 – 59)

%y Year without century, as decimal number (00 – 99)

%Y Year with century, as decimal number (0000-9999)

Unencrypted network, WISPr authentication

Encrypted network, EAP-SIM authentication

Unencrypted network, app-based authentication

Yes, MB provider Mobile broadband app None None

Yes, MB provider Operator web site Certificate must: None

Provision the device to connect automatically to a Wi-Fi network

2. Redirect to an app for authentication by using the ExtAuth directive:

This method is equivalent to invoking the IMbnVendorSpecificOperation::SetVendorSpecific method of

Updating data usage statistics for a connection profile

If an individual profile could not be applied, it will appear as follows:

Install-TestEVCert -CertName <Certificate Name> -RootCertOutputPath <complete path to the folder to

Test-ValidProvisioningXml -InputFile <complete path to the input XML file>

The following is a definition of the APN schema.

<?xml version="1.0" encoding="UTF-8"?>

Operator Specifies the details of the operator.

Name xs:string Yes The name and

AccountExperienceURL xs:anyURI No The URL of the

OperatorGUID GUID No A GUID used to identify

HardwareIdList A list of hardware IDs that are assigned to the operator.

ConnectionInfoList A list of access strings.

TrustedCertificateList A list of trusted certificates used to verify that account

OperatorList The parent element of the APN XML schema.

HardwareId An operator hardware ID.

Operator Specifies the details for an operator in the APN database.

HardwareIdList Specifies the list of hardware IDs for an operator.

ConnectionInfo An operator hardware ID.

Operator Specifies the details for an operator in the APN database.

AccessString xs:string No The name and

Username xs:string No The username is used

Password xs:string No The password used to

FriendlyName xs:string No The value shown in

Purchase xs:boolean Yes Denotes whether the

Internet xs:boolean Yes Denotes whether the