Guia de integração de EMM

Este guia ajuda na integração dos provedores de gerenciamento de mobilidade empresarial (EMM) o registro sem toque no console. 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ê tiver um DPC, você vai aprender as práticas recomendadas para provisionar dispositivos e receber ajuda com desenvolvimento e testes.

Recursos para administradores de TI

Use a API do cliente para ajudar os administradores de TI a configurar o registro sem toque diretamente seu console. Confira algumas tarefas que um administrador de TI pode concluir no seu 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 o DPC provisione aos dispositivos futuros às compras da organização.
• Aplique configurações individuais a dispositivos ou remova dispositivos do registro sem toque inscrição.

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

Pré-requisitos

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

• Sua solução de EMM precisa provisionar um Android 8.0 ou mais recente (Pixel 7.1 ou versões mais recentes) de propriedade da empresa no modo totalmente gerenciado. 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 faz o download e a instalação de um DPC automaticamente, seu O DPC precisa estar disponível no Google Play. Temos 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 do provedor de EMM para adicionar o DPC à lista.
• Seus clientes precisam de uma conta de registro sem toque para chamar a API. Um revendedor parceiro configura a conta para a organização de um administrador de TI quando o a organização compra os dispositivos dela.
• O dispositivo precisa ser compatível com os Serviços do Google Mobile (GMS) e o Google Play Services precisa estar sempre ativado para o registro sem toque para funcionar corretamente.

Chamar a API

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

Processar os Termos de Serviço

Seus usuários precisam aceitar os Termos de Serviço (TOS) mais recentes antes chamando 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:

// 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;
}

// 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.
            // ...
        }
    }
}

# 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 o cliente não oferecer suporte a erros detalhados (.NET e outros), corresponda à mensagem de erro.

Se você seguir essa abordagem, quando atualizarmos os TOS, o app direcione 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 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 portal de seu console ou em sua documentação, use este URL:

https://partner.android.com/zerotouch

Você pode informar aos administradores de TI que eles precisam fazer login com Conta do Google.

Registro do dispositivo

O registro sem toque é um mecanismo para registrar dispositivos e funciona como o NFC inscrição ou inscrição por QR code. Seu console precisa ter suporte para dispositivos gerenciados e o DPC precisa funcionar no modo de dispositivo totalmente gerenciado.

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

Veja um resumo de como funciona a inscrição:

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

Se não houver conexão com a Internet, a verificação vai acontecer disponíveis. 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. Configuração "Promover" uma configuração padrão do seu console, caso não tenha sido definida. Confira a de customers.configurations.isDefault para para descobrir se uma organização definiu uma configuração padrão.

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

// 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();

// 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();

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

Recomendamos usar o nome de recurso da API customers.dpcs.name para identificar o DPC e usá-lo nas configurações. O nome do recurso contém um identificador exclusivo e imutável para o DPC. Ligação customers.dpcs.list para ver a lista de todos os compatíveis DPCs. 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 Dpc correspondente. O exemplo abaixo mostra como corresponder ao DPC e persistir para uso posterior em uma configuração:

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

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

# 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 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 para o provisionamento de dispositivos. Você só precisa de um nome de usuário e uma senha para provisionar o dispositivo. Os revendedores podem enviar dispositivos diretamente para usuários remotos. Incluir todas as outras configurações, como o servidor de EMM ou a unidade organizacional, 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 seu DPC usando uma intent do Android. O sistema envia os valores android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE ao seu DPC como extras na intent. O DPC pode ler as configurações de provisionamento do PersistableBundle usando as mesmas chaves.

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

• EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE
• EXTRA_PROVISIONING_LOCALE
• EXTRA_PROVISIONING_TIME_ZONE
• EXTRA_PROVISIONING_LOCAL_TIME
• EXTRA_PROVISIONING_LEAVE_ALL_SYSTEM_APPS_ENABLED
• EXTRA_PROVISIONING_MAIN_COLOR
• EXTRA_PROVISIONING_DISCLAIMERS

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

• EXTRA_PROVISIONING_DEVICE_ADMIN_COMPONENT_NAME
• EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_CHECKSUM
• EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_COOKIE_HEADER
• EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION
• EXTRA_PROVISIONING_DEVICE_ADMIN_SIGNATURE_CHECKSUM

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 o seguinte:

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

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

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

Como o registro sem toque faz o download e instala automaticamente DPC, seu DPC precisa estar disponível no Google Play antes do teste na nuvem. Não é possível fazer testes com uma versão de desenvolvimento do DPC.

Suporte para administradores de TI

Se você precisar ajudar os administradores de TI na interface do seu console ou na sua documentação, Consulte as orientações em 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 aos seus console:

• Registro sem toque para administradores de TI no Android Enterprise Socorro.
• Provisionar dispositivos de clientes usando o EMM Android site para desenvolvedores.