iframe de configurações gerenciadas

O iframe de configurações gerenciadas é uma interface incorporável que permite que os administradores de TI salvem, editem e excluam as configurações gerenciadas de um app. Você pode, por exemplo, exibir um botão (ou elemento de IU semelhante) na página de detalhes ou de configurações de um app que abre o iframe.

Ações disponíveis para administradores de TI no iframe

iframe mcm
Figura 1. Exemplo de iframe de configurações gerenciadas para o Gmail.

Definir e salvar perfis de configuração

O iframe recupera e exibe o esquema de configurações gerenciadas para um app especificado. No iframe, um administrador de TI pode definir e salvar configurações como um perfil de configuração. Sempre que um administrador de TI salva um novo perfil de configuração, o iframe retorna um identificador exclusivo chamado mcmId. Isso permite que os administradores de TI criem vários perfis para o mesmo app.

Editar perfis de configuração

O iframe pode exibir perfis de configuração salvos. Os administradores de TI podem atualizar as configurações em um perfil e salvar as alterações.

Excluir perfis de configuração

Os administradores de TI podem excluir perfis de configuração do iframe. Esse recurso fica desativado por padrão.

Mostrar o iframe de configurações gerenciadas no console

Gerar um token da Web

Use Enterprises.createWebToken para gerar um token da Web que identifique a empresa. Inclua o token retornado com outros parâmetros ao renderizar o iframe no console. O exemplo a seguir mostra como recuperar o token usando a biblioteca de cliente da API EMM do Google Play para Java.

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

Renderizar o iframe

Confira um exemplo de como renderizar o iframe de configurações gerenciadas:

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

Parâmetros de URL

A tabela abaixo lista todos os parâmetros disponíveis para o URL de iframe.

ParâmetroObrigatórioDescrição
token Sim O token retornado de Enterprises.createWebToken.
packageName Sim O ID do produto do app. Por exemplo, com.google.android.gm.
mcmId Não O ID de um perfil de configurações gerenciado.
canDelete Não Se TRUE, ativa um botão no iframe que permite que os administradores de TI excluam o perfil de configurações gerenciadas. Se FALSE (valor padrão), o botão será desativado.
locale Não Uma tag de idioma BCP 47 bem formada que é usada para localizar o conteúdo no iframe. Se não for especificado, o valor padrão será en_US.

Eventos de iframe

Também é preciso processar os eventos a seguir como parte da sua integração.

EventoDescrição
onconfigupdated O usuário atualiza um perfil de configurações gerenciadas existente ou cria um novo. Isso retorna um objeto contendo:
{
  "mcmId": The ID of the managed configurations profile.
  "name": The name of the updated or newly created managed configurations profile.
}
onconfigdeleted O usuário exclui um perfil de configurações gerenciadas. Isso retorna um objeto contendo:
{
  "mcmId": The ID of the managed configurations profile.
}

O exemplo abaixo mostra como ouvir onconfigupdated, por exemplo:

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

Atualizações no esquema de configurações gerenciadas de um app

Se o desenvolvedor atualizar o esquema de configuração gerenciada de um app, os perfis de configuração salvos serão atualizados automaticamente. Por exemplo, se o desenvolvedor remover uma opção, ela será removida de todos os perfis de configuração do app. Se o desenvolvedor adicionar uma opção, o valor padrão dela (definido pelo desenvolvedor) será adicionado a todos os perfis de configuração do app.

Aplicar configurações gerenciadas aos dispositivos dos usuários

Para saber como aplicar as configurações gerenciadas aos dispositivos dos usuários, consulte Aplicar configurações gerenciadas.


Noções básicas sobre o comportamento de selecionar/desmarcar

O iframe de configurações gerenciadas agora permite que os administradores de TI desmarquem explicitamente as restrições de apps de uma configuração gerenciada quando não precisarem delas. Essa é uma mudança em relação ao comportamento anterior e pode afetar as restrições enviadas ao app com base na seleção do administrador.

A seção abaixo descreve como o iframe de configurações gerenciadas se comporta com esse novo padrão de desmarcar e o que os desenvolvedores podem esperar ser enviado como parte da configuração gerenciada.

Como usar o valor padrão para uma restrição de app

Se as restrições de apps com tipo bool, choice, integer, multi-select ou string forem fornecidas com um valor padrão, o valor padrão será aplicado como o valor da restrição de app quando os administradores salvarem a configuração gerenciada sem aplicar nenhuma mudança a essa restrição.

Por exemplo, com o seguinte esquema de restrição de apps:

"restrictions": [{
    "key": "bool_key",
    "restrictionType": "bool",
    "defaultValue": {
        "type": "bool",
        "valueBool": false
    }
}]

As restrições de apps enviadas ao dispositivo serão:

"restrictions": [{
    "key": "bool_key",
    "restrictionType": "bool",
    "value": {
        "type": "bool",
        "valueBool": false
    }
}]

Sem usar valores padrão para restrições de apps

Se as restrições de apps com o tipo bool, choice, integer, multi-select ou string não tiverem um valor padrão, essas restrições de apps não serão incluídas quando os administradores salvarem a configuração gerenciada sem aplicar nenhuma mudança nessa restrição.

Por exemplo, com o seguinte esquema de restrição de apps:

"restrictions": [{
    "key": "bool_key",
    "restrictionType": "bool"
    // defaultValue absent.
}]

As restrições de apps enviadas ao dispositivo serão:

"restrictions": [
    // Empty
]

Como usar pacotes no esquema

Esta seção se aplica às restrições de pacotes para apps:

Ter pelo menos uma restrição de app infantil com um valor padrão em uma restrição de app de pacote

Se, na restrição de app de pacotes, pelo menos uma das restrições de apps filhos com tipo bool, choice, integer, multi-select ou string for informada com um valor padrão, o valor padrão será aplicado como o valor da restrição de app, e os que não tiverem valores padrão serão excluídos quando os administradores salvarem a configuração gerenciada sem fazer mudanças nesse app.

"restrictions": [{
    "key": "bundle_key",
    "restrictionType": "bundle",
    "nestedRestriction": [{
            "key": "bool_key_1",
            "restrictionType": "bool",
            "defaultValue": {
                "type": "bool",
                "valueBool": false
            }
        },
        {
            "key": "bool_key_2",
            "restrictionType": "bool"
            // defaultValue absent.
        }
    ]
}]

As restrições de apps enviadas ao dispositivo serão:

"restrictions": [{
    "key": "bundle_key",
    "restrictionType": "bundle",
    "nestedRestriction": [{
            "key": "bool_key_1",
            "restrictionType": "bool",
            "value": {
                "type": "bool",
                "valueBool": false
            }
        },
        // The bool_key_2 child app restriction is not included.
    ]
}]

Todas as restrições de apps filhos sem valores padrão

Se, na restrição do app de pacotes, todas as restrições de apps filhos com tipo bool, choice, integer, multi-select ou string não tiverem um valor padrão, a restrição de app de pacote não será incluída quando os administradores salvarem a configuração gerenciada sem aplicar mudanças nessa restrição.

Por exemplo, com o seguinte esquema de restrição de apps:

"restrictions": [{
    "key": "bundle_key",
    "restrictionType": "bundle",
    "nestedRestriction": [{
            "key": "bool_key_1",
            "restrictionType": "bool",
            // defaultValue absent.
        },
        {
            "key": "bool_key_2",
            "restrictionType": "bool"
            // defaultValue absent.
        }
    ]
}]

As restrições de apps enviadas ao dispositivo serão:

"restrictions": [
    // Empty
]

Como usar bundle_array no esquema

Esta seção se aplica às restrições de app bundle_array. Não será relevante se as restrições do app filho com tipo bool, choice, integer, multi-select ou string tiverem valores padrão.

Por exemplo, com o seguinte esquema de restrição de apps:

"restrictions": [{
    "key": "bundle_array_key",
    "restrictionType": "bundleArray",
    "nestedRestriction": [{
        "key": "bundle_key",
        "restrictionType": "bundle",
        "nestedRestriction": [{
            "key": "bool_key",
            "restrictionType": "bool",
            "defaultValue": {
                "type": "bool",
                "valueBool": true
            }
        }]
    }]
}]

Ter pelo menos um grupo de pacotes na restrição do app bundle_array

Se pelo menos um grupo de pacotes for definido, a restrição de app bundle_array será incluída quando os administradores salvarem a configuração gerenciada.

As restrições de apps enviadas ao dispositivo serão:

"restrictions": [{
    "key": "bundle_array_key",
    "restrictionType": "bundleArray",
    "nestedRestriction": [{
        "key": "bundle_key",
        "restrictionType": "bundle",
        "nestedRestriction": [{
            "key": "bool_key",
            "restrictionType": "bool",
            "value": {
                "type": "bool",
                "valueBool": true
            }
        }]
    }]
}]

Nenhum grupo de pacote na restrição do app bundle_array

A restrição de app bundle_array não será incluída quando os administradores salvarem a configuração gerenciada sem adicionar um grupo de pacotes. As restrições de apps enviadas ao dispositivo serão:

"restrictions": [
    // Empty
]