Esta página foi traduzida pela API Cloud Translation.

Guia de integração de EMM

Este guia ajuda os provedores de gerenciamento de mobilidade empresarial (EMM) a integrar o registro sem toque aos consoles deles. Continue lendo para saber mais sobre a inscrição e conferir as práticas recomendadas para ajudar seu DPC (controlador de política de dispositivo) a provisionar dispositivos. Se você tem um DPC, você vai aprender as práticas recomendadas ao provisionar dispositivos, além de receber dicas para ajudar no desenvolvimento e nos testes.

Recursos para administradores de TI

Use a API de cliente para ajudar os administradores de TI a configurar o registro sem toque diretamente no seu console. Estas são algumas tarefas que um administrador de TI pode concluir no seu console:

Criar, editar e excluir configurações de registro sem toque com base nas políticas para dispositivos móveis.
Defina uma configuração padrão para que o DPC provisione futuros dispositivos que a organização comprar.
Aplique configurações individuais a dispositivos ou remova-os do registro sem toque.

Para saber mais sobre o registro sem toque, leia a visão geral.

Pré-requisitos

Antes de adicionar o registro sem toque ao console de EMM, confirme se a solução é compatível com o seguinte:

Sua solução de EMM precisa provisionar um dispositivo Android 8.0 ou mais recente (Pixel 7.1 ou mais recente) da empresa no modo totalmente gerenciado. Os dispositivos Android 10 ou versões mais recentes da empresa podem ser provisionados como totalmente gerenciados ou com um perfil de trabalho.
Como o registro sem toque faz o download e instala automaticamente um DPC, seu DPC precisa estar disponível no Google Play. Mantemos uma lista de DPCs compatíveis que os administradores de TI podem configurar usando a API do cliente ou o portal. Envie uma solicitação de modificação de produto pela comunidade de provedores de EMM para adicionar seu DPC à lista.
Seus clientes precisam de uma conta de registro sem toque para chamar a API do cliente. Um revendedor parceiro configura a conta para a organização de um administrador de TI quando a organização compra os dispositivos.
O dispositivo precisa ser compatível com os Serviços do Google Mobile (GMS), e o Google Play Services precisa estar sempre ativado para que o registro sem toque funcione corretamente.

Chamar a API

Os usuários do seu console (usando as próprias Contas do Google) autorizam suas solicitações de API para a API do cliente. Esse fluxo é diferente da autorização que você realiza para outras APIs de EMM. Leia Autorização para saber como fazer isso no seu aplicativo.

Processar os Termos de Serviço

Os usuários precisam aceitar os Termos de Serviço mais recentes (TOS) antes de chamar a API. Se a chamada de API retornar um código de status HTTP 403 Forbidden e o corpo da resposta contiver um TosError, solicite que o usuário aceite os TOS fazendo login no portal de registro sem toque. O exemplo abaixo mostra uma das maneiras de fazer isso:

Java

// Authorize this method call as a user that hasn't yet accepted the ToS.
final String googleApiFormatHttpHeader = "X-GOOG-API-FORMAT-VERSION";
final String googleApiFormatVersion = "2";
final String tosErrorType =
      "type.googleapis.com/google.android.device.provisioning.v1.TosError";

try {
  // Send an API request to list all the DPCs available including the HTTP header
  // X-GOOG-API-FORMAT-VERSION with the value 2. Import the  exception:
  // from googleapiclient.errors import HttpError
  AndroidProvisioningPartner.Customers.Dpcs.List request =
        service.customers().dpcs().list(customerAccount);
  request.getRequestHeaders().put(googleApiFormatHttpHeader, googleApiFormatVersion);
  CustomerListDpcsResponse response = request.execute();
  return response.getDpcs();

} catch (GoogleJsonResponseException e) {
  // Get the error details. In your app, check details exists first.
  ArrayList<Map> details = (ArrayList<Map>) e.getDetails().get("details");
  for (Map detail : details) {
    if (detail.get("@type").equals(tosErrorType)
          && (boolean) detail.get("latestTosAccepted") != true) {
      // Ask the user to accept the ToS. If they agree, open the portal in a browser.
      // ...
    }
  }
  return null;
}

.NET

// Authorize this method call as a user that hasn't yet accepted the ToS.
try
{
    var request = service.Customers.Dpcs.List(customerAccount);
    CustomerListDpcsResponse response = request.Execute();
    return response.Dpcs;
}
catch (GoogleApiException e)
{
    foreach (SingleError error in e.Error?.Errors)
    {
        if (error.Message.StartsWith("The user must agree the terms of service"))
        {
            // Ask the user to accept the ToS. If they agree, open the portal in a browser.
            // ...
        }
    }
}

Python

# Authorize this method call as a user that hasn't yet accepted the ToS.
tos_error_type = ('type.googleapis.com/'
                  'google.android.device.provisioning.v1.TosError')
portal_url = 'https://partner.android.com/zerotouch'

# Send an API request to list all the DPCs available including the HTTP
# header X-GOOG-API-FORMAT-VERSION with the value 2. Import the exception:
# from googleapiclient.errors import HttpError
try:
  request = service.customers().dpcs().list(parent=customer_account)
  request.headers['X-GOOG-API-FORMAT-VERSION'] = '2'
  response = request.execute()
  return response['dpcs']

except HttpError as err:
  # Parse the JSON content of the error. In your app, check ToS exists first.
  error = json.loads(err.content)
  tos_error = error['error']['details'][0]

  # Ask the user to accept the ToS (not shown here). If they agree, then open
  # the portal in a browser.
  if (tos_error['@type'] == tos_error_type
      and tos_error['latestTosAccepted'] is not True):
    if raw_input('Accept the ToS in the zero-touch portal? y|n ') == 'y':
      webbrowser.open(portal_url)

Se o cliente da API do Google oferecer suporte a erros detalhados (solicitações Java, Python ou HTTP), inclua o cabeçalho HTTP X-GOOG-API-FORMAT-VERSION com o valor 2 nas solicitações. Se seu cliente não for compatível com erros detalhados (.NET e outros), corresponda à mensagem de erro.

Se você seguir essa abordagem, quando atualizarmos os TOS no futuro, o app vai direcionar o usuário a aceitar novamente o novo TOS.

Link para o portal

Os administradores de TI usam o portal de registro sem toque para gerenciar os usuários da organização. Não é possível oferecer isso pela API do cliente. Eles também podem gerenciar dispositivos e configurações usando o portal. Se você precisar incluir um link para o portal no seu console ou na sua documentação, use este URL:

https://partner.android.com/zerotouch

Informe aos administradores de TI que eles precisam fazer login com a Conta do Google.

Registro do dispositivo

O registro sem toque é um mecanismo para registrar dispositivos e é como o registro de NFC ou de QR code. Seu console precisa oferecer suporte a dispositivos gerenciados, e o DPC precisa ser executado no modo de dispositivo totalmente gerenciado.

O registro sem toque está disponível em dispositivos com suporte e com o Android 8.0 ou mais recente. Os administradores de TI precisam comprar dispositivos compatíveis de um revendedor parceiro. Para rastrear quais dispositivos do administrador de TI estão disponíveis para o registro sem toque, o console pode chamar customers.devices.list.

Veja como o registro funciona:

Um dispositivo faz check-in com um servidor do Google na primeira inicialização ou após uma redefinição para a configuração original para o registro sem toque.
Se o administrador de TI aplicou uma configuração ao dispositivo, o registro sem toque vai executar o assistente de configuração Android do dispositivo totalmente gerenciado e personalizar as telas com metadados da configuração.
O registro sem toque faz o download e instala seu DPC pelo Google Play.
Seu DPC recebe a intent ACTION_PROVISION_MANAGED_DEVICE e provisiona o dispositivo.

Se não houver conexão de Internet, a verificação acontecerá quando uma estiver disponível. Para saber mais sobre o provisionamento de dispositivos com o registro sem toque, consulte Provisionamento abaixo.

Configurações padrão

O registro sem toque ajuda os administradores de TI quando eles definem uma configuração padrão aplicada a todos os novos dispositivos comprados pela organização. Promova a definição de uma configuração padrão no seu console, caso não tenha sido definida. Verifique o valor de customers.configurations.isDefault para descobrir se uma organização definiu uma configuração padrão.

O exemplo abaixo mostra como tornar uma configuração atual padrão:

Java

// Send minimal data with the request. Just the 2 required fields.
// targetConfiguration is an existing configuration that we want to make the default.
Configuration configuration = new Configuration();
configuration.setIsDefault(true);
configuration.setConfigurationId(targetConfiguration.getConfigurationId());

// Call the API, including the FieldMask to avoid setting other fields to null.
AndroidProvisioningPartner.Customers.Configurations.Patch request = service
      .customers()
      .configurations()
      .patch(targetConfiguration.getName(), configuration);
request.setUpdateMask("isDefault");
Configuration results = request.execute();

.NET

// Send minimal data with the request. Just the 2 required fields.
// targetConfiguration is an existing configuration that we want to make the default.
Configuration configuration = new Configuration
{
    IsDefault = true,
    ConfigurationId = targetConfiguration.ConfigurationId,
};

// Call the API, including the FieldMask to avoid setting other fields to null.
var request = service.Customers.Configurations.Patch(configuration,
                                                     targetConfiguration.Name);
request.UpdateMask = "IsDefault";
Configuration results = request.Execute();

Python

# Send minimal data with the request. Just the 2 required fields.
# target_configuration is an existing configuration we'll make the default.
configuration = {
    'isDefault': True,
    'configurationId': target_configuration['configurationId']}

# Call the API, including the FieldMask to avoid setting other fields to null.
response = service.customers().configurations().patch(
    name=target_configuration['name'],
    body=configuration, updateMask='isDefault').execute()

Como fazer referência ao seu DPC

Recomendamos usar o nome de recurso da API customers.dpcs.name para identificar seu DPC e usá-lo nas configurações. O nome do recurso contém um identificador exclusivo e imutável para o DPC. Chame customers.dpcs.list para conferir a lista de todos os DPCs compatíveis. Como o nome do recurso também inclui o ID de cliente, filtre a lista usando o último componente do caminho para encontrar uma instância de Dpc correspondente. O exemplo abaixo mostra como associar seu DPC e persistir para uso posterior em uma configuração:

Java

// Return a customer Dpc instance for the specified DPC ID.
String myDpcIdentifier = "AH6Gbe4aiS459wlz58L30cqbbXbUa_JR9...xMSWCiYiuHRWeBbu86Yjq";
final int dpcIdIndex = 3;
final String dpcComponentSeparator = "/";
// ...
for (Dpc dpcApp : dpcs) {
    // Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID}, check the
    // fourth component matches the DPC ID.
    String dpcId = dpcApp.getName().split(dpcComponentSeparator)[dpcIdIndex];
    if (dpcId.equals(myDpcIdentifier)) {
        System.out.format("My DPC is: %s\n", dpcApp.getDpcName());
        return dpcApp;
    }
}
// Handle the case when the DPC isn't found...

.NET

// Return a customer Dpc instance for the specified DPC ID.
var myDpcIdentifer = "AH6Gbe4aiS459wlz58L30cqbbXbUa_JR9...fE9WdHcxMSWCiYiuHRWeBbu86Yjq";
const int dpcIdIndex = 3;
const String dpcComponentSeparator = "/";
// ...
foreach (Dpc dpcApp in dpcs)
{
    // Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID}, check the
    // fourth component matches the DPC ID.
    String dpcId = dpcApp.Name.Split(dpcComponentSeparator)[dpcIdIndex];
    if (dpcId.Equals(myDpcIdentifer))
    {
        Console.WriteLine("Matched DPC is: {0}", dpcApp.DpcName);
        return dpcApp;
    }
}
// Handle the case when the DPC isn't found...

Python

# Return a customer Dpc instance for the specified DPC ID.
my_dpc_id = 'AH6Gbe4aiS459wlz58L30cqb...fE9WdHcxMSWCiYiuHRWeBbu86Yjq'
# ...
for dpc_app in dpcs:
  # Because the DPC name is in the format customers/{CUST_ID}/dpcs/{DPC_ID},
  # check the fourth component matches the DPC ID.
  dpc_id = dpc_app['name'].split('/')[3]
  if dpc_id == my_dpc_id:
    return dpc_app

# Handle the case when the DPC isn't found...

Se for necessário mostrar o nome de um DPC na interface do usuário do console, mostre o valor retornado de customers.dpcs.dpcName.

Provisionando

Aproveite a oportunidade para oferecer uma ótima experiência ao usuário no provisionamento de dispositivos. Um nome de usuário e uma senha são suficientes para provisionar o dispositivo. Vale lembrar que os revendedores podem enviar dispositivos diretamente para usuários remotos. Inclua todas as outras configurações, como o servidor de EMM ou a unidade organizacional, em customers.configuration.dpcExtras.

O snippet JSON abaixo mostra parte de um exemplo de configuração:

{
  "android.app.extra.PROVISIONING_LOCALE": "en_GB",
  "android.app.extra.PROVISIONING_TIME_ZONE": "Europe/London",
  "android.app.extra.PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED": true,
  "android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE": {
    "workflow_type": 3,
    "default_password_quality": 327680,
    "default_min_password_length": 6,
    "company_name": "XYZ Corp",
    "organizational_unit": "sales-uk",
    "management_server": "emm.example.com",
    "detail_tos_url": "https://www.example.com/policies/terms/",
    "allowed_user_domains": "[\"example.com\", \"example.org\", \"example.net\"]"
    }
}

O registro sem toque instala e inicia o DPC usando uma intent do Android. O sistema envia os valores na propriedade JSON android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE ao DPC como extras na intent. Seu DPC pode ler as configurações de provisionamento do PersistableBundle usando as mesmas chaves.

Recomendado: use os extras de intent a seguir para configurar o DPC:

Não recomendado: não inclua os seguintes extras que podem ser usados em outros métodos de registro:

Para saber como extrair e usar essas configurações no DPC, leia Provisionar dispositivos de clientes.

Desenvolvimento e teste

Para desenvolver e testar os recursos de registro sem toque do console, você vai precisar do seguinte:

um dispositivo compatível
uma conta de registro sem toque para clientes

Desenvolva e teste com dispositivos com suporte ao registro sem toque, como o Google Pixel. Você não precisa comprar seus dispositivos de desenvolvimento de um parceiro revendedor.

Entre em contato para receber uma conta de cliente de teste e acesso ao portal de registro sem toque. Envie um e-mail usando seu endereço de e-mail corporativo associado a uma Conta do Google. Informe o fabricante e o número IMEI de um ou dois dispositivos para que eles sejam adicionados à sua conta de desenvolvimento.

Como o registro sem toque faz o download e instala automaticamente um DPC, seu DPC precisa estar disponível no Google Play antes de você testar o provisionamento. Não é possível testar com uma versão de desenvolvimento do seu DPC.

Suporte para administradores de TI

Se você precisar ajudar os administradores de TI na interface do console ou na sua documentação, consulte o artigo Registro sem toque para administradores de TI. Também é possível direcionar os usuários do console para esse artigo da Central de Ajuda.

Guia de integração de EMM

Recursos para administradores de TI

Pré-requisitos

Chamar a API

Processar os Termos de Serviço

Java

.NET

Python

Link para o portal

Registro do dispositivo

Configurações padrão

Java

.NET

Python

Como fazer referência ao seu DPC

Java

.NET

Python

Provisionando

Desenvolvimento e teste

Suporte para administradores de TI

Leia mais