Configuring Dual-SIM APN Settings via Blueprint JSON on Esper-Managed Devices

Android

When managing dual-SIM devices through Esper, carrier data connectivity depends on correctly configured access point names (APNs) for each SIM slot. Without the right APN settings pushed to the device, mobile data may fail entirely or connect on only one SIM.

Why this happens

Android does not automatically provision APN settings for all carriers on dual-SIM devices. Each SIM requires its own APN entry matched to the carrier's Mobile Country Code (MCC) and Mobile Network Code (MNC). Esper delivers these settings through a Blueprint JSON field, but the Supervisor Plugin must first be installed on the device before Android will accept programmatic APN changes.

Before you begin

Gather the following before starting:

• The MCC and MNC for each carrier — request these from your carrier or check your SIM card documentation
• Confirmation that your devices are dual-SIM capable and enrolled in Esper
• Admin access to the Esper Console
• For Android 15 and above: contact information for your device OEM, as the Supervisor Plugin must be signed with device platform keys before deployment

Step 1: Install the Supervisor Plugin

APN configuration requires the Supervisor Plugin to be active on each device. The installation path depends on the Android version running on your devices.

Android 14 and below

1. Contact Esper Support and request that the signed Supervisor Plugin be uploaded to your tenant. Provide your tenant name in the request.
2. Once Esper Support confirms the upload, reboot each target device. The plugin activates automatically on reboot — no manual installation step is required on the device.

Android 15 and above

1. Contact Esper Support and request the unsigned Supervisor Plugin APK.
2. Send the APK to your device OEM and request that they sign it using the device's platform keys. If your OEM requires firmware-level permission whitelisting, refer to the Supervisor Plugin permissions documentation provided by your Esper representative.
3. Once your OEM returns the signed APK, send it to Esper Support. Esper Support uploads it to your tenant.
4. In the Esper Console, navigate to Blueprints and add the signed Supervisor Plugin as an app in the blueprint assigned to your target devices. Deploy the blueprint to push the plugin to devices.

Step 2: Build the APN JSON configuration

Construct a JSON object containing one entry per carrier. Replace the placeholder MCC and MNC values with the correct codes for each SIM.

{
  "apns": [
    {
      "name": "Carrier 1 Name",
      "apn": "carrier1.apn.address",
      "type": "default,supl",
      "mcc": "CARRIER1_MCC",
      "mnc": "CARRIER1_MNC",
      "user": "",
      "password": "",
      "authtype": 0,
      "protocol": "IPV4V6",
      "roamingProtocol": "IPV4V6",
      "carrierId": -1,
      "enabled": true
    },
    {
      "name": "Carrier 2 Name",
      "apn": "carrier2.apn.address",
      "type": "default,supl",
      "mcc": "CARRIER2_MCC",
      "mnc": "CARRIER2_MNC",
      "user": "",
      "password": "",
      "authtype": 0,
      "protocol": "IPV4V6",
      "roamingProtocol": "IPV4V6",
      "carrierId": -1,
      "enabled": true
    }
  ]
}

Note the following before saving your JSON:

• Leave user and password as empty strings if your carrier does not require authentication credentials.
• Confirm all MCC and MNC values with your carrier before fleet-wide deployment — incorrect values create APN entries the modem cannot use, which silently breaks mobile data.
• Keep type set to default,supl for standard dual-SIM configurations unless your carrier specifies otherwise.

Step 3: Apply the APN configuration through a blueprint

1. In the Esper Console, navigate to Blueprints and open the blueprint assigned to your dual-SIM device group, or create a new one.
2. Within the blueprint, go to Esper Settings → Advanced Android Settings.
3. Enable the Enable JSON toggle. This unlocks the free-text JSON field where custom Android settings are applied at the system level.
4. Paste the complete JSON object from Step 2 into the JSON field, replacing any existing placeholder content.
5. Select Save to update the blueprint.

Step 4: Validate on a single device before fleet rollout

1. In the Esper Console, navigate to Devices & Groups and select one test device from your target group.
2. Apply the updated blueprint to that device only and wait for the device to sync. Open the device's Activity Feed to confirm the blueprint was applied without errors.
3. On the device, open Settings → Network → SIM & Mobile Network → APN (the exact path varies by OEM) and confirm that both APN entries appear with the correct names.
4. Test active mobile data on each SIM slot by browsing to a known URL or running a connectivity check.
5. Once confirmed on the test device, apply the blueprint to the full device group.

Verify: Both APN entries appear on the device under mobile network settings, mobile data is active on each SIM, and the device's Activity Feed in the Esper Console shows a successful blueprint sync with no errors. The APN entries should appear within 5 minutes of the blueprint applying.

If this doesn't resolve it

If APN entries do not appear on the device or mobile data remains inactive after the blueprint applies, collect the following before contacting support:

• Your tenant name and the device serial number
• The Android version and OEM model of the affected device
• A screenshot of the Activity Feed from Devices & Groups → [Device Name] → Activity Feed showing the blueprint sync result
• Confirmation of whether the Supervisor Plugin appears as an installed app on the device
• The exact JSON you applied, with MCC and MNC values included

Contact Esper Support with this information so the issue can be investigated at the tenant or device level.

Still need help?

If the steps above don't resolve the issue, submit a support ticket with your device model, Android version, Esper Agent version, and a description of what you've already tried — this helps the support team investigate without a follow-up.