Managed configurations iframe

The managed configurations iframe is an embeddable UI that lets IT admins save, edit, and delete an app’s managed configuration settings. You can, for example, display a button (or similar UI element) in an app’s details or settings page that opens the iframe.

Actions available to IT admins from the iframe

Figure 1. Example managed configurations iframe for Gmail.

Set and save configuration profiles

The iframe retrieves and displays the managed configurations schema for a specified app. Within the iframe, an IT admin can set configurations and save them as a configuration profile. Each time an IT admin saves a new configuration profile, the iframe returns a unique identifier called mcmId. This makes it possible for IT admins to create multiple profiles for the same app.

Edit configuration profiles

The iframe is capable of displaying saved configuration profiles. IT admins can update the settings within a profile and save their changes.

Delete configuration profiles

IT admins can delete configuration profiles from the iframe. This feature is disabled by default.

Display the managed configurations iframe in your console

Generate a web token

Use Enterprises.createWebToken to generate a web token that identifies the enterprise. You must include the returned token, along with other parameters, when rendering the iframe in your console. The following example shows how to retrieve the token using the Google Play EMM API Client Library for Java.

public AdministratorWebToken getAdministratorWebToken(
    String enterpriseId,
    AdministratorWebTokenSpec tokenSpec) throws IOException {
  return androidEnterprise
     .enterprise()
     .createWebToken(enterpriseId, tokenSpec)
     .execute();
}

Render the iframe

Here's an example of how to render the managed configurations iframe:

<script src="https://apis.google.com/js/api.js"></script>
<div id="container" style="width: 1000px; height: 1000px"></div>
<script>
  gapi.load('gapi.iframes', function() {
    var options = {
      'url': 'https://play.google.com/managed/mcm?token=web_token&packageName=app_package_name',
      'where': document.getElementById('container'),
      'attributes': { style: 'height:1000px', scrolling: 'yes'}
    }

    var iframe = gapi.iframes.getContext().openChild(options);
  });
</script>

URL parameters

The table below lists all the available parameters for the iframe URL.

Parameter	Required	Description
token	Yes	The token returned from Enterprises.createWebToken.
packageName	Yes	The product ID of the app. For example, com.google.android.gm.
mcmId	No	The ID of a managed configurations profile.
canDelete	No	If TRUE, enables a button in the iframe that allows IT admins to delete the managed configurations profile. If FALSE (default value), the button is disabled.
locale	No	A well-formed BCP 47 language tag that is used to localize the content in the iframe. If not specified, the default value is en_US.

Iframe events

You should also handle the following events as part of your integration.

Event	Description
onconfigupdated	The user updates an existing managed configurations profile or creates a new one. This returns an object containing: { "mcmId": The ID of the managed configurations profile. "name": The name of the updated or newly created managed configurations profile. }
onconfigdeleted	The user deletes an existing managed configurations profile. This returns an object containing: { "mcmId": The ID of the managed configurations profile. }

The sample below shows how to listen for onconfigupdated, as an example:

iframe.register('onconfigupdated', function(event) {
  console.log(event);
}, gapi.iframes.CROSS_ORIGIN_IFRAMES_FILTER);

Updates to an app's managed configurations schema

If the developer updates an app’s managed configuration schema, saved configuration profiles are automatically updated. For example, if the developer removes an option, the option will be removed from all existing configuration profiles for the app. If the developer adds an option, the default value for the option (defined by the developer) will be added to all existing configuration profiles for the app.

Apply managed configurations to users' devices

To learn how to apply managed configurations to users' devices, see Apply managed configurations.