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 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.

GetBalance API

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

Balance resource

Headers

The following headers may be included in every request from the Mobile Plans service to the mobile provider’s endpoint.

Error codes

The table below defines the error codes that should be used in the HTTP response.

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:

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
Content-type: application/json
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:

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
Content-type: application/json
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 is performed via certificate based client authentication.

A certificate with the following Subject Name will be passed during the call to the Mobile Operator API:

C=US, ST=WA, L=Redmond, O=Microsoft Corporation, CN=partners.datamart.windows.com

The certificate chains to this CA: DigiCert Global Root G2.

We recommend that all Mobile Operators validate that the Subject Name of the certificate matches the one above.

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 database settings.

Download the COSA/APN update spreadsheet.