メニュー

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Super SIM: Understanding Network Access Profiles

The Super SIM API provides you with the ability to specify which mobile networks a device containing a Super SIM is permitted to connect to. This guide will quickly bring you up to speed with how this works so that you will be able to apply your own lists of networks to your groups of SIMs.

Each Super SIM is represented in the Super SIM API by a Sim resource. You organize Sim resources into groups by assigning them to Fleet resources. A Fleet is a collection of Sims with the same behavior. You can have as many Fleets as you need. You might have a Fleet per product, for example, or multiple Fleets per product with each Fleet dedicated to a specific territory and/or sub-SKU. The choice is really up to you and your use-case.

Each Fleet is assigned a Network Access Profile resource. A Network Access Profile essentially defines a collection of cellular networks which the Fleet’s Sims are permitted to access. Again, you can use as many or as few (you need at least one) Network Access Profiles as you need. A given Fleet can use only one Network Access Profile at a time, but a single Network Access Profile can be shared by multiple Fleets simultaneously:

Each Network Access Profile’s list of the mobile networks that it provides access to is exclusive: if a particular mobile network is not on the list, it does not belong to that Network Access Profile and cannot be accessed by Sims in any Fleet using that Profile. Mobile networks are represented in the API by Network resources.

How does a Super SIM know which networks it can use? From the Network Access Profile its Fleet is using. When a device attempts to initiate a cellular connection it will only be able to do so if its modem can detect one of the Networks within the relevant Network Access Profile’s list of permitted networks. All other networks are considered forbidden, and the modem will not connect to them automatically. Even if the device commands its modem to connect manually, if the target network is a forbidden network, it will not connect — the network will return the error 5004 / ROAMING_NOT_ALLOWED.

Using the API to work with Network Access Profiles

You can get and set the list of Networks a Sim can connect to at any time. For a given Sim, start by accessing its Fleet’s networkAccessProfileSid property to get the SID of the Network Access Profile that the Fleet is currently using. Then use that SID to get the Network Access Profile itself.

A Network Access Profile resource doesn’t include the list of networks as a property. Instead it provides the URL from which the list can be retrieved. Access the Network Access Profile’s links property; its own networks property has the URL you require. For example:

{
  "unique_name": "NAP Name",
  "sid": "HAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "date_created": "2020-05-01T20:00:00Z",
  "date_updated": "2020-05-01T20:00:00Z",
  "url": "https://supersim.twilio.com/v1/NetworkAccessProfiles/HAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "links": {
    "Networks": "https://supersim.twilio.com/v1/NetworkAccessProfiles/HAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Networks"
  }
}

A request sent to this URL will return a paged list of zero or more Network resources representing the networks available to the NAP. The returned JSON contains a meta field which holds the paging information, including the current page number, the number of entries per page and the URL of the next page of data in sequence — this will be null if there are no further pages. The JSON also contains a networks field and this is the array of Network resources. Each of these Network resources contains information about the network represented, including:

  • Its friendly_name property, which is usually but not always the network’s brand name.
  • Its iso_country property, which will be its primary operating territory.
  • Its identifiers property, which is an array of objects, each one of which comprises key mobile industry standard network identifiers for that network: its MCC (Mobile Country Code) and MNC (Mobile Network Code), accessed respectively through the object’s mcc and mnc properties. See MCC and MNC, below, for more information

Please see the Network resource documentation for a full list of resource properties.

MCC and MNC

MCC and MNC are the standard means by which mobile network operators identify themselves. You can find a full list of MCCs and MNCs here. It’s important to understand that because of the many mergers and takeovers that have taken place in the global mobile network industry over the past 30 years, a given network operator may use multiple MNCs for a given MCC. To be sure to include all of a network operator’s networks in Network Access Profile, you will to include all of its MNCs in its Network resource.

For example, Vodafone in the UK (MCC 234) has three MNCs: 15, 27 and 91. So its Network resource would look something like this:

{ "friendly_name": "Vodafone",
   "iso_country": "gb",
   "identifiers": [
      { "mnc": 15, "mcc": 234 },
      { "mnc": 27, "mcc": 234 },
      { "mnc": 91, "mcc": 234 }
   ]
}

For the same reasons, you may find that a known MNC is not accompanied by an expected Friendly Name. For instance, T-Mobile USA recently acquired Sprint, which uses the MNC 530. We will continue to show Sprint as the friendly name while Sprint remains a separate entity for commercial purposes.

Granting and forbidding access to networks

To allow all of a Fleet’s Sims to access a network, or to block them from using one, simply update the list of Network resources within the Network Access Profile being used by the Fleet, or assign the Fleet an alternative NAP which has the required networks in its array of Network resources. However you update the list of available networks, devices currently connected to a newly-forbidden network will remain connected, but will not be allowed to connect to that network when they next attach.

You can change a Fleet’s Network Access Profile by updating its networkAccessProfileSid property with the SID of the Network Access Profile you want the Fleet to use.

If you need to change the network list for a subset of the Fleet’s Sims, you will need to assign the subset to a new Fleet that has been set to use a suitably configured Network Access Profile, which may also be a new resource or one you are using for other Fleets.

To update a Fleet’s Network Access Profile directly, either POST a Network SID to the NAP’s Networks sub-resource — see above for guidance on discovering the URL of this sub-resource — to add it, or make a DELETE request to the same URL and pass SID of the Network you wish to remove from the list. Updating the NAP this way will affect every Fleet that is using it.

サマリー

Network Access Profiles provide a powerful and flexible means of managing access to mobile networks. You can change the list of cellular networks to which a given Sim is permitted to use by changing the Fleet it belongs to, by switching its Fleet to a different Network Access Profile, or by updating the Fleet’s Network Access Profile directly. All Fleets must have a Network Access Profile. Network Access Profiles can be shared by multiple Fleets, or used on a one-to-one basis — the choice is yours, determined by your use case.

Rate this page:

ヘルプが必要ですか?

誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。