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 no console deles. Continue lendo para saber mais sobre a inscrição e conferir dicas de práticas recomendadas para ajudar seu DPC (controlador de política de dispositivo) a provisionar dispositivos. Se você tiver uma DPC, vai aprender as práticas recomendadas ao provisionar dispositivos e receber dicas para ajudar no desenvolvimento e nos testes.

Recursos para administradores de TI

Use a API do cliente para ajudar os administradores de TI a configurar o registro sem toque diretamente no console. Confira algumas tarefas que um administrador de TI pode realizar no console:

Crie, edite e exclua configurações de registro sem toque com base nas suas políticas para dispositivos móveis.
Defina uma configuração padrão para que a DPC provisione dispositivos futuros que a organização comprar.
Aplicar configurações individuais ou remover dispositivos 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 seu console de EMM, confirme se sua solução é compatível com o seguinte:

Sua solução de EMM precisa provisionar um dispositivo Android 8.0+ (Pixel 7.1+) de propriedade da empresa no modo totalmente gerenciado. Os dispositivos Android 10 ou mais recentes da empresa podem ser provisionados como totalmente gerenciados ou com um perfil de trabalho.
Como o registro sem toque baixa e instala automaticamente um DPC, ele 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 do 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 Customer. Um revendedor parceiro configura a conta para a organização de um administrador de TI quando ela 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 console (usando a Conta do Google) autorizam as solicitações de API para a API de 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 app.

Processar Termos de Serviço

Seus usuários precisam aceitar os Termos de Serviço (TOS) mais recentes 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, peça ao usuário para aceitar os Termos de Serviço 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://enterprise.google.com/android/zero-touch/customers'

# 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 (Java, Python ou solicitações HTTP), inclua o cabeçalho HTTP X-GOOG-API-FORMAT-VERSION com o valor 2 nas suas solicitações. Se o cliente não oferecer suporte a erros detalhados (.NET e outros), faça a correspondência da mensagem de erro.

Quando atualizarmos os TOS no futuro, se você seguir essa abordagem, seu app vai direcionar o usuário para aceitar os novos TOS novamente.

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. Os administradores de TI também podem gerenciar dispositivos e configurações usando o portal. Se você precisar criar um link para o portal no console ou na documentação, use este URL:

https://enterprise.google.com/android/zero-touch/customers

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, semelhante ao registro por NFC ou QR code. Seu console precisa ser compatível com dispositivos gerenciados, e seu DPC precisa ser executado no modo de dispositivo totalmente gerenciado.

O registro sem toque está disponível em dispositivos compatíveis com o Android 8.0 ou versões mais recentes. Os administradores de TI precisam comprar dispositivos compatíveis de um revendedor parceiro. O console pode rastrear quais dispositivos do administrador de TI estão disponíveis para o registro sem toque chamando customers.devices.list.

Confira um resumo de como funciona o registro:

Um dispositivo faz o check-in com um servidor do Google na primeira inicialização (ou após uma redefinição de fábrica) para o registro sem toque.
Se o administrador de TI tiver aplicado uma configuração ao dispositivo, o registro sem toque executará o assistente de configuração do Android para dispositivos totalmente gerenciados e personalizará as telas com metadados da configuração.
O registro sem toque baixa e instala seu DPC do Google Play.
Seu DPC recebe a intent ACTION_PROVISION_MANAGED_DEVICE e provisiona o dispositivo.

Se não houver uma conexão com a Internet, a verificação será feita 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 é mais útil para os administradores de TI quando eles definem uma configuração padrão que é aplicada a todos os novos dispositivos comprados pela organização. Promova a definição de uma configuração padrão no console se nenhuma estiver definida. Confira o valor de customers.configurations.isDefault para saber se uma organização definiu uma configuração padrão.

O exemplo abaixo mostra como definir uma configuração atual como 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()

Referenciar seu DPC

Recomendamos usar o nome do 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 receber a lista de todos os DPCs compatíveis. Como o nome do recurso também inclui o ID do cliente, filtre a lista usando o último componente do caminho para encontrar uma instância Dpc correspondente. O exemplo abaixo mostra como corresponder 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 você precisar mostrar o nome de um DPC na interface do usuário do console, mostre o valor retornado de customers.dpcs.dpcName.

Provisionamento

Aproveite a oportunidade para oferecer uma ótima experiência do usuário no provisionamento de dispositivos. Um nome de usuário e uma senha são tudo o que é necessário para provisionar o dispositivo. Os revendedores podem enviar dispositivos diretamente para usuários remotos. Inclua todas as outras configurações, como servidor EMM ou 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 para seu DPC como extras na intent. Seu DPC pode ler as configurações de provisionamento do PersistableBundle usando as mesmas chaves.

Recomendado: use os seguintes extras de intent para configurar seu DPC:

Não recomendado: não inclua os seguintes extras que você pode usar em outros métodos de inscrição:

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

Desenvolvimento e teste

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

um dispositivo compatível
uma conta de registro sem toque de cliente

Desenvolva e teste com dispositivos que oferecem suporte ao registro sem toque, como o Google Pixel. Não é necessário comprar 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 do seu endereço 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 desenvolvedor.

Como o registro sem toque baixa e instala automaticamente um DPC, ele precisa estar disponível no Google Play antes que você possa 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 documentação, consulte Registro sem toque para administradores de TI. Você também pode direcionar os usuários do console para esse artigo da Central de Ajuda.

Leitura adicional

Leia estes documentos para ajudar você a integrar o registro sem toque no seu console:

Registro sem toque para administradores de TI na Ajuda do Android Enterprise.
Provisione dispositivos dos clientes no site de desenvolvedores do EMM Android.

Guia de integração de EMM Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Recursos para administradores de TI

Pré-requisitos

Chamar a API

Processar Termos de Serviço

Java

.NET

Python

Link para o portal

Registro do dispositivo

Configurações padrão

Java

.NET

Python

Referenciar seu DPC

Java

.NET

Python

Provisionamento

Desenvolvimento e teste

Suporte para administradores de TI

Leitura adicional

Guia de integração de EMM