This feature is in Beta. It's only available for certain customers at this time.
After setting up your Esper account, creating a blueprint is the first step to managing your devices in an efficient, flexible, and dynamic way. This article covers each setting, as well as the process for creating a blueprint and applying those changes to your devices.
In this article:
Step 1: Creating a Blueprint
To add a blueprint, go to Blueprints Manager and click on Create Blueprint.
Choose from the following options:
- Create New Blueprint: create a new blueprint.
- Create Blueprint from JSON Config: create a blueprint from a JSON file.
- Download JSON Config: download the JSON config to be used for a new Blueprint.
- Create Blueprint from Template: Create a blueprint from a Template. Learn more about creating a Blueprint from a Template.
Create New Blueprint
When you create a new blueprint, you set the settings and policies for every device linked to that blueprint. When the device's configurations match the blueprint, it operates at a Desired State.
Name and describe the blueprint. Then click Continue.
Blueprint Sections
Understanding Blueprint Terms
Version Number: This blueprint’s version. Whenever you make a change, a new version will be saved in the Blueprint Manager.
Published Status: Indicates if the changes are published or not. Blueprints must be saved before they can be published.
Sections: The sections that control device configurations such as Wi-Fi connectivity, App Installations, and other software and hardware settings.
How to Apply
Blueprints determine which configurations are applied and at what point they should be applied.
Always Apply: The strictest provisioning method. Every time the device interacts with the Console, the setting in the blueprint will be applied even if the end-user makes changes, those changes will reset.
For the device user, this means that they are free to change the volume. However, the Console user will need to explicitly set the device back to the way it is described in the blueprint to reach its desired state.
For a Console user with permission to make changes to the device, even if they change the device’s volume from the Console, the blueprint will revert these changes when it reaches the device.
The blueprint creator will be able to change the volume if they make a change to the volume setting in the
Provision Only: The setting will apply once–at the time of provisioning. Some features make sense to set as Provision Only, such as time zone settings if you are provisioning devices that will be shipped to different regions.
Ignore: The setting will be ignored. At the time of provisioning, it will have whichever settings the device had by default or before provisioning. Changes can be made to this setting at any point.
In some cases, it makes sense to ignore a device’s brightness settings and let the user control it. Console users with the ability to interact with that device or Group will also be able to make changes to these settings.
You can quickly change these settings by using the top dropdown menu of each section.
Apps and Configuration
Device Mode
Device Mode determines how users will interact with the device. There are two modes: Multi-app Mode and Kiosk Mode.
Multi-app Mode
The Device mode function enables you to switch a device between Multi-Appmode and Kiosk mode. When a device is in Multi-App mode, the end user can see and use all the approved apps.
Kiosk Mode
When a device is in Kiosk Mode, the device acts as a kiosk, and end users can only interact with the kiosk app, similar to a pinned app.
To change a device to Kiosk Mode, click Switch to Kiosk Mode. On the slide-out from the right side, click the radio button for the mode you prefer. If you click the Kiosk Mode radio button, you will also need to choose the application that will be pinned to the device’s start screen as its primary application. Select it from the searchable Kiosk App dropdown, and then click Save.
Launcher
Choose the launcher.
Esper Launcher
Most users will use the default Esper DPC Launcher. Once selected, the Esper Device agent will take administrative control of the device, and only approved applications will be able to be installed or used, in addition to other Esper features. This gives you more control over the applications that can be used, and the actions that can be taken on the device.
Android Launcher
If you select the Default Android Launcher, the device will function on the Android experience. The device user will be able to exit the Esper Agent as they would any other Android application. The Esper Agent will continue to run in the background and provide some device management, but many management features will not be available.
Specifically, the following features will be unavailable:
- Over-the-Air OS updates for Esper Foundation for Android OS
- The latest Device Agent updates for devices running an Android 6 and lower
The device screen will look and act much like a regular Android device, with the Esper Device Agent showing up as an app that can be opened or closed.
Permissions
Default application permissions determine enforcement of the runtime rules across all the apps on a device including Enterprise applications installed by Esper, in-ROM applications that are enabled, as well as applications installed via Managed Google Play. This ensures you can control the user experience on the device regarding how run-time permissions are granted.
Allow Automatically: This rule will grant all the permissions for any application requests without showing a prompt to the user. Allow automatically is the typical setting for trusted Kiosk Mode applications. Esper will grant permissions to the calendar, camera, microphone, etc.
Ask User: All applications on the device will show a permission request for the user to accept or deny. For example, each time before accessing a device module, all applications will prompt the user with a message such as “Allow application X to access the Gallery? Allow or Deny." The Ask user option might not be ideal in some solutions, especially Kiosk-based applications. However, it can help in unusual situations when dealing with app permissions— contact us directly to find out more.
Deny Automatically: Permissions revert to their default state as set by the device manufacturer. Any previously granted permissions are not affected. You can grant permissions to applications individually from the Esper Console. Users can grant permissions to apps individually from the Esper Console or Android Settings (if Android Launcher is enabled).
Learn more about Android runtime permissions.
Allow Local App Installs: Enable this to allow the device user to install applications from an unknown (or any) source.
Allow Application Uninstall: Enable this to allow the device user to uninstall apps from the device.
These settings are typically used when the devices are loaned out to guests, such as through a hotel. Disabling these settings will prevent device users from installing or uninstalling applications.
Application Management
Applications are managed through Blueprints, however, Esper does not always control every application, especially those installed from the Google Play Store. Applications follow certain rules if they are pre-loaded, added from the Esper Cloud, or from the Google Play Store. To understand how applications are managed, read more about Application and Blueprint syncs.
To add an application, click Add Application.
This setting will allow you to install applications during provisioning.
You’ll have the options to:
- upload an APK.
- choose from an uploaded application and version.
- add an application from Google Play (if enrolled in EMM).
- or set the state of a pre-installed app.
For a pre-installed application, you have the following options:
- Show: this will display the application on the home screen.
- Hide: this will hide the application on the home screen.
- Disable: this will prevent the application from running in the background.
Removing an app will remove it from the Home screen and set the app to its default state (show/hide)—reboot required.
Connectivity
In order for devices to communicate with Esper, they must have access to at least one access point. If primarily connecting to Wi-Fi, it’s recommended that a Wi-Fi SSID is set in the blueprint.
Esper implements several steps to ensure that devices are connected to the internet. Learn more about Wi-Fi Sync Scenarios.
Allow Wi-Fi
When you add a Wi-Fi access point to the blueprint, you need to enter the details of the Wi-Fi access point. To add, click the Add Wi-Fi Access Point link.
Enter the details and click Add. You can also select from previously added Esper-managed access points.
Allow Bluetooth®
If you want the device user to use Bluetooth on the device, set the Bluetooth toggle button to enabled. If not, disable it.
Allow SMS
SMS controls the sending and receiving of SMS or text messages. If SMS is disabled, the device cannot send or receive text messages from any application. Enable SMS if you wish to send and receive messages.
Allow Near-Field Communication (NFC)
If you want device users to use Near-Field Communication (NFC) on their devices when supported, enable NFC. If you don’t, disable it. If any applications require NFC, make sure this setting is enabled.
Restrict Incoming Calls
Enable this to block incoming calls from all but the specified contacts.
Click Add/Edit Contacts to enter the caller details.
You can add phone numbers or upload a CSV file of contacts to add to the allowed list only.
All numbers must be preceded by a +country code (for example, +1 for the USA). A comma must separate all numbers.
The following are general guidelines for the CSV when uploading the CSV for Contacts.
- Download the template CSV file.
- Fill in the Contact's information according to the header (for example, Phone Number, Tag, Tag, Tag)
a. Please make sure that the Country Code is included in the Phone Number (for example, +1)
b. Phone numbers should not include parentheses or hyphens (for example, +18881234567)
c. Tag should not contain any Numeric or special characters (for example, hyphens, quotes, etc.) - Upload the filled-out CSV (make sure the header is included in the file)
a. For Mac Users, you want to alter the file's End-Of-Line character to the Windows or Linux format.
Restrict Outgoing Calls
Enable this to enable calls from all contacts except for those in the Restricted list.
Wi-Fi Access Points
You can preload preferred Wi-Fi networks to which the provisioned device will automatically connect as they become available, with a default timeout of 35 seconds. The device will automatically connect to the given Wi-Fi access points as per the availability and network strength after onboarding.
The Wi-Fi On/Off and Wi-Fi access points features are not available for devices running Android 10.0 and above.
When adding a new access point, you have four fields to configure: Wi-Fi SSID, Wi-Fi Password, Wi-Fi Security type, and Hidden. The Wi-Fi SSID and Wi-Fi Password fields are text fields for the SSID and password. Select the security type from the drop-down menu. There are four possible choices:
- NONE
- WPA- Wireless Protected Access
- WEP- Wired Equivalent Privacy
- EAP- Extensible Authentication Protocol
None: None is an open-type network. Requirement: SSID
WEP: WEP is an open-type network with a password. Requirements: SSID, Password (limit: 13 characters)
WPA: Android refers to WPA as WPA/WPA2, but technically, WPA and WPA2 are slightly different. WPA is an enhanced version of WEP. Requirements: SSID, Password (limit: 63 characters) EAP: Internally EAP is known as WPA/WPA2/WPA3-Enterprise.
If you select EAP, you will be prompted to enter additional information.
Wi-Fi EAP Method is a drop-down with the following options:
- PEAP
Phase 2 Authentication
Identity (Optional)
Anonymous Identity (Optional)
Password - TLS
Identity (Optional) - TTLS
Identity (Optional)
Anonymous Identity (Optional)
Password
- PWD
Identity (Optional)
Password (Optional)
Similarly, the Phase 2 Authentication is also a drop-down with the following options:
- NONE
- PAP
Identity (Optional)
Anonymous Identity (Optional)
Password - MSCHAP
Identity (Optional)
Anonymous Identity (Optional)
Password - MSCHAPV2
Anonymous Identity (Optional)
Password - GTC Do not valid
Identity (Optional)
Anonymous Identity (Optional)
Password - SIM
- AKA
- AKA_PRIME
Choose 'Yes' from the hidden field drop-down to create hidden Wi-Fi networks. You cannot scan a hidden Wi-Fi network from the device. For example, when you open the Wi-Fi section of your device, you will not see a hidden network if one is within range.
In Android 10 and above, when a Wi-Fi access point is added directly from the device, it is recommended that GPS is ON so that the Wi-Fi access point can reflect on the Console.
Strict Wi-Fi Access Point Synchronization
During a converge, all other Esper-managed access points from the device except those provided in the blueprint. Device users will still be able to add Wi-Fi access points if this is selected.
Esper-managed access points: Any Wi-Fi access points are added to the device through the Esper Console or the Esper Settings app.
Click on the Details dropdown to learn more about Strict Synchronization.
Should you use Strict Mode?
In some situations, devices must connect to access points that aren’t listed in the blueprint. For example, a device may be on Blueprint A and then move to Blueprint B, and retain the access points from Blueprint A.
This can be unexpected for some users. If you only want the devices to connect to the access points in the blueprint, use Strict Mode. Keep in mind that this setting still allows device users to connect to access points not listed in the blueprint (although you can hide the Wi-Fi access
In the example above, all other Esper-managed access points will be removed except for Andi’s Wi-Fi. The device will attempt to connect with Andi’s Wi-Fi. For more information about how blueprint affects Wi-Fi scenarios, see Wi-Fi Sync Scenarios.
What isn’t affected by Strict Mode?
Any Wi-Fi access points added to the device outside of Esper (for example, through the Android Launcher) won’t be affected by Strict Mode.
Need a more detailed explanation of how Strict Mode works?
After device A converges to Blueprint B, Esper checks its Wi-Fi access points. If Wi-Fi XYZ was added by Esper, the device attempts to connect with Wi-Fi access point ABC. If it's successful, XYZ will be removed. If not, it will remain connected to XYZ.
If XYZ wasn't added by Esper, XYZ will not be removed.
What makes a Wi-Fi access point "added by Esper"?
If the device belonged to a previous Blueprint, all the access points on that Blueprint would be considered added by Esper. During 6-tap Provisioning, when the user is asked to provide a Wi-Fi access point, that access point is also considered added by Esper.
What if I enable Strict Mode without specifying an access point?
The device will first try to connect to a mobile network, then ethernet. If it has an Esper-managed Wi-Fi connection, the blueprint will fail. If not, the blueprint will succeed.
Security
ADB Access
Android Debug Bridge (adb) is a command-line tool that provides a Unix shell to communicate with an Android device. If the adb access option is checked in the blueprint, you may enable adb via the Device Settings and select the session duration. If the adb option is unchecked in the blueprint, you won't be able to turn on adb from the Device Settings. Opening the adb port is required on most stock Android devices before adb debugging.
Keep in mind that adb access could make your devices vulnerable to security threats. Only enable it for situations where adb access is required.
Safe Mode Login
When Safe-Mode login is enabled, users will be able to boot to Safe Mode on the device. When Safe-Mode login is disabled, users will be unable to boot to Safe Mode.
Factory Reset
Factory Reset controls if users can perform a factory reset using the Android Settings app. When Factory Reset is disabled, the user will not be able to complete a factory reset on the device. This does not prevent a hard-key factory reset, see Factory Reset Protection to prevent a hard-key factory reset.
Disabling Factory Reset from System Settings will also remove User Factory Reset configurations from the User Mode in the Esper Settings App.
Screen Timeout
Choose the timeout period for the device.
Lock Screen
The lock screen enables the default lock screen to be displayed whenever a device screen times out, according to the timeout specified in the settings section. If this is enabled, the device user will have the option to set the password. The users must enter a password that follows the rules.
Lock Screen Password
The Lock Screen Password specifies the conditions for the device unlock password. The default is None.
If you choose alphabetic or alphanumeric, you must set a password length of at least 4 characters and up to 25. Use the up/down arrows to set the required password length.
- Alphabetic: Restricts acceptable passwords to only upper and lowercase alphabetic characters (A to Z, and a to z).
- Alphanumeric: Expands acceptable passwords to include numbers and special characters in addition to alphabetic characters.
- Numeric: Restricts acceptable passwords to numbers only.
The user will set up the password for a device during the initial setup. The lock screen setting must be enabled to set the password type and character limit. If you select either Alphabetic or Alphanumeric password rules, then the lock screen will be set to On by Esper if it is currently Off.
If a user sets a password and a Blueprint is converged that has a "None" setting later, the user's preference will take priority. You can remove the password from the device remotely using our API. Contact the Esper team for more information.
Display & Branding
Brightness
Use the brightness slider to increase or decrease the brightness of the screen.
Screen Orientation
Select screen orientation from the options: Auto, Landscape, and Portrait. Some device makers swap the settings for Landscape and Portrait. If your device was provisioned with a specific orientation but is locked into the other orientation, try switching this setting to achieve the proper screen orientation.
ScreenShot
This setting will allow or restrict the device user from taking a screenshot.
Notification Bar
This setting will enable or disable the notification bar on the device.
Notification Disabled
- App running in Kiosk Mode: Only the Kiosk app will be visible along with the back key in the navigation bar. No status bar.
- App running in Multi-app Mode: The status bar will be visible along with the Navigation bar.
Notification Enabled
- App running in Kiosk Mode: The status bar will be visible along with the Kiosk app. No drop-down to view notifications.
- App running in Multi-app Mode: The status bar and a notification bar will be shown along with a drop-down to show notifications.
You may choose to leave this setting On if you request bug report submissions from device users. User bug report requests from Esper must be sent via the notification bar.
Home Screen Wallpaper
You can upload wallpaper files in either portrait or landscape mode. Click upload and browse a file up to 5MB in size.
Lock Screen Wallpaper
You can upload a lock screen image or use the same image for the home screen and lock screen. Lockscreen wallpapers are limited to Portrait or Landscape.
Esper Setting App
This setting controls the user's access to settings available via a hidden dock on the device. The Esper Setting App has two modes:
- User Mode
- Admin Mode
Click Customize Setting to select different settings for the two modes.
- About: Provides information regarding the endpoint name the device is enrolled in if the customer has access to multiple Esper endpoints.
- Accessibility: Only compatible with Android 9 and below. Select from a variety of accessibility settings.
- High Contrast
- Color Correction - Deuteranomaly
- Color Correction - Protanomaly
- Color Correction - Tritanomaly
- Mono Audio (only for Foundation devices)
- Display Size
- Talkback
- Text to Speech
- Reset to Default
- Auto-Rotation: Turn auto-rotation On or Off. It has multiple states— Auto, Landscape, Portrait, Inverted Landscape, Inverted Portrait
- Bluetooth: Navigate to the Android settings application on Android 8.1 and lower devices to change the Bluetooth setting. The scan button on the bottom right will allow searches and show nearby devices. Click the Connect button to pair the device; the connection will happen immediately. You can connect only non-A2DP devices like headphones, mouse, and keyboards and can’t connect mobile phones and laptops.
Bluetooth works as a one-to-one relationship between devices. If you need to pair a new device, you’ll need to delete and unpair the old device before connecting the new one.
- Clear App Data: Clears the data and cache for a particular application.
- Display: Manage screen rotation, screen brightness, and screen timeout.
- Factory Reset: Perform a factory reset of the device, regardless of the blueprint applied.
- Esper Branding: Turn off the Esper logo on the device's Home screen.
- Flashlight: Turn On the Torch (AKA “flashlight”) if the device has a camera flash LED.
- Input Selection: Navigate to Android settings on Android 8.1 and lower devices to change the input selection for the device.
- Keyboard: Navigate to Android settings on Android 8.1 and lower devices to change the keyboard settings.
- Kiosk App Selection: Change the App that runs in Kiosk Mode. The device user can choose any app installed on the device to act as the kiosk app, with the Esper Console kept in sync with the configuration stats.
- Language: Navigate to Android settings on Android 8.1 and lower devices to change the language setting.
- Mobile Data: Access mobile data on the device.
- Reboot: Ability to reboot the device. Only available on Android 7 and above.
- Sound: Manage ringtone, alarm, device, and notification volume.
- Storage: Helps grant permissions to any directories on the device. On Android 10 or below devices, it is advised that the Console admins inform the users to grant permissions to the root folder. On Android 11 devices, permission cannot be granted to the root folders and download folders.
- Time and Date: Navigate to Android settings on Android 8.1 and lower devices to change the date and time for the device.
- Wi-Fi: Change the Wi-Fi access point used by the device. In Android 10 devices and above, it is recommended to enable GPS to view the network information on the device’s Wi-Fi screen. In the devices below Android 10, enabled GPS is needed to display scanned network information.
- Data Roaming: Enables access to data roaming.
- Wi-Fi Tethering: Enables access to Wi-Fi tethering.
- Airplane Mode: Enables access to airplane mode.
Esper Settings 
Esper Settings App
This toggle button helps you hide the Esper Settings App. The Esper Setting App can be accessed only by the hidden dock.
A hidden dock is available in both the Kiosk Mode and the Multi-app Mode. You can access it with 3-taps on the right corner in Kiosk Mode or 3-clicks on the power button in Multi-app Mode.
Set Admin Pin
Admin Mode is password-protected to prevent unauthorized access. This password controls access to the hidden dock available in Kiosk Mode, the Esper Settings app, and serves as the PIN used for IMEI-based onboarding via AfW. The password is alphanumeric and can have 1 to 10 characters.
The default password is 1234. It is possible to set up a template without a password for these features or just leave the default password; Esper strongly recommends setting up a more complex password for stronger security. The same password will be set for all devices provisioned using the blueprint.
A hidden dock is available in both the Kiosk and Multi-app Modes. You can access it with 3-taps on the right corner in Kiosk Mode or 3-clicks on the power button in Multi-app Mode.
Android Setting App
This setting will display the icon for the default Android settings application on the device’s Home screen. Clicking this icon will take the user to the default Android settings. Depending on the other configurations set in the blueprints, some options may be disabled for the user.
Enable JSON
When enabled, this setting allows you to input valid JSON code.
Files
You can upload and push files to all the devices provisioned using this blueprint. Click Add File to upload a new file. You can edit and remove an already uploaded file. To clear the entire file list, click Clear File List.
To understand how files sync to the device in different scenarios, see File Sync.
Platform Services
Enroll Device In EMM
If you want device users access to your Managed Google Play Store, set the Google Play Store setting to On; if you don’t, set it to Off. You’ll still be able to install any approved Google Play Store applications from Esper if the Play Store is turned Off. This only applies to GMS devices, as AOSP devices do not include Google Play Store support.
Allow Personal Accounts
This setting enables you to restrict the number of Google accounts that can be added to the device and used with Google apps like Gmail, Google Play Store, and YouTube. By default, any number of accounts can be added to a specific device; this setting restricts this number. For example, if you set this setting to two, only two accounts will be permitted on the device, further addition (or deletion) of accounts will not be possible unless a different blueprint is reapplied.
Notes:
- If you don’t check the Google account restrictions box and plan to provision your device in Multi-app Mode, we recommend disabling the Google Play Store to prevent the installation of unapproved applications.
- The Google Account Restriction feature is applicable only to Google Mobile Services (GMS) Android devices. If you include the Android Settings App and wish to prevent any Google accounts from being added, set the number of accounts to zero.
Google Play Store Visibility
This setting will allow the Google Play Store on the device’s home screen. Toggle On to display Google Play Store. If you don’t, set it to Off.
Allow Device Access To Google Assistant
If you’d like device users to be able to use voice commands via Google Assistant on supported devices, enable Google Assistant. If not, disable it.
On some devices, this setting may need to be on if you wish to have the Google Play Store show up on the device.
Factory Reset Protection
Factory Reset Protection (FRP) places an auto-lock on a GMS-certified device if a user factory resets it with soft or hard keys. FRP will auto-lock the device and keep it locked until a pre-authorized Google account ID is entered. See additional information about getting your Google Account ID.
When you turn on the FRP button in the blueprint, you’ll need to pick a Google account to authorize future device unlocks. Your chosen Google account ID will reverse any future auto-lock events triggered by user factory resets for all devices provisioned with this template.
Factory reset protection is only available on GMS devices running Android 5.1 and above.
Hardware Settings
External Device
This setting allows you to connect external devices. If you want device users to be able to connect other hardware to the device, set the External Device toggle button to on. If you don’t, set it Off.
USB Tethering
USB tethering allows users to connect USB devices, such as a flash drive, digital camera, mouse, or keyboard to the device. If you want device users to be able to connect other hardware to the device, set USB Connectivity to On. If you don’t, set it Off.
File Transfer
If you’d like device users to be able to transfer files from the device using a USB cable or flash drive, enable this. If not, disable it.
Camera
If you want device users to be able to use the camera, enable this. If not, disable it. Your application can still access the camera if this setting is disabled.
Location
If you'd like the device to use location services, enable this. If not, disable it.
Sound
Adjust the device’s sound settings.
If Android settings are disabled, the end user won’t be able to manipulate this in any way.
System Updates
Choose the system update preference.
- Update Automatically: Updates device when the newest system update becomes available.
- Postpone Installation: Postpone the update for 30 days before the update occurs automatically.
- Windowed Installation: Installs system updates during a selected maintenance window.
- Disable Update: Disables OS updates on the device. Updates will default to the Postpone Installation option if this option is unavailable. This feature may require a Supervisor Plugin, Knox-enabled device, or Lenovo device with CSDK support.
Time & Date
Edit Time & Date
Using the toggle button, enable/disable the device user’s ability to edit the time and date.
Time Zone
Select the time zone in which the device will be deployed. After deployment, you will have the ability to change the device’s time zone remotely via the blueprint.
If you don’t specify a device time zone, the time zone set by the device will be used.
The Time Zone field has a robust search capability. As you begin to type, suggestions will be displayed. For example, typing "Pacific" will bring up all the time zones that start with "Pacific." Listings are by country, for example, to find the timezones for the USA, search for "America" or "US".
Language
Set the device's language during 6-tap provisioning.
Requirements: This setting requires a Supervisor Plugin or Knox-compatible device post-provisioning
Click Save when you are ready to save the blueprint.
Step 2: Saving, Publishing, and Converging
After you’ve created a blueprint, or made changes to it, you can press Save.
Pressing Save will save the changes you made, but won’t have any effect on the devices linked to the blueprint.
After saving, you’ll notice that the version number changes. From the blueprint, you can click on the version number to see a list of your saved history.
After saving the blueprint, you can press Edit Blueprint to make more changes. Or, if you’re done making changes, press Publish.
Press Publish when you are ready to publish the new blueprint version.
You can choose two options:
- Publish: Publish the changes without converging. This means the blueprint settings will not be applied to its linked devices.
- Publish & Converge: Publish the changes and converge (apply changes to the linked devices). You can enable this option by checking the Publish & Converge devices box.
Devices will be in Drift until they are converged to the new blueprint version. You can manually Converge devices from the Devices & Groups section as well.