Guía de integración de EMM

En esta guía, se ayuda a los proveedores de administración de movilidad empresarial (EMM) a integrar la inscripción automática en su consola. Continúa leyendo para obtener más información sobre la inscripción y consulta las prácticas recomendadas para ayudar a tu DPC (controlador de políticas de dispositivos) a aprovisionar dispositivos. Si tienes un DPC, conocerás las prácticas recomendadas para aprovisionar dispositivos y obtendrás consejos para ayudarte con el desarrollo y las pruebas.

Funciones para administradores de TI

Usa la API del cliente para ayudar a los administradores de TI a configurar la inscripción automática directamente desde tu consola. Estas son algunas tareas que un administrador de TI puede completar en tu consola:

  • Crea, edita y borra configuraciones de inscripción automática según tus políticas para dispositivos móviles.
  • Establece una configuración predeterminada para que tu DPC aprovisione los dispositivos futuros que compre la organización.
  • Aplicar configuraciones individuales a los dispositivos o quitarlos de la inscripción automática

Para obtener más información sobre la inscripción automática, lee la descripción general.

Requisitos previos

Antes de agregar la inscripción automática a tu consola de EMM, confirma que tu solución admita lo siguiente:

  • Tu solución de EMM debe aprovisionar un dispositivo de la empresa con Android 8.0 o versiones posteriores (Pixel 7.1 o versiones posteriores) en modo completamente administrado. Los dispositivos empresariales que ejecutan Android 10 y versiones posteriores se pueden aprovisionar como completamente administrados o con un perfil de trabajo.
  • Debido a que la inscripción automática descarga e instala automáticamente un DPC, tu DPC debe estar disponible en Google Play. Mantenemos una lista de DPC compatibles que los administradores de TI pueden configurar mediante la API del cliente o el portal. Envía una solicitud de modificación de producto a través de la comunidad de proveedores de EMM para agregar tu DPC a la lista.
  • Tus clientes necesitan una cuenta de inscripción automática para llamar a la API del cliente. Un socio revendedor configura la cuenta para la organización de un administrador de TI cuando la organización compra sus dispositivos.
  • El dispositivo debe ser compatible con los Servicios de Google para dispositivos móviles (GMS) y los Servicios de Google Play deben estar habilitados en todo momento para que la inscripción automática funcione correctamente.

Llama a la API

Los usuarios de tu consola (con sus Cuentas de Google) autorizan tus solicitudes a la API a la API del cliente. Este flujo es diferente de la autorización que realizas para otras APIs de EMM. Lee el artículo sobre Autorización para obtener información sobre cómo hacerlo en tu app.

Administra las Condiciones del Servicio

Los usuarios deben aceptar las Condiciones del Servicio más recientes antes de llamar a la API. Si la llamada a la API muestra un código de estado HTTP 403 Forbidden y el cuerpo de la respuesta contiene un TosError, pídele al usuario que acceda al portal de inscripción automática para aceptar las Condiciones del Servicio. En el siguiente ejemplo, se muestra una de las formas en que puedes hacerlo:

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)

Si tu cliente de la API de Google admite errores detallados (solicitudes de Java, Python o HTTP), incluye el encabezado HTTP X-GOOG-API-FORMAT-VERSION con el valor 2 en tus solicitudes. Si tu cliente no admite errores detallados (.NET y otros), haz coincidir el mensaje de error.

Cuando actualicemos las Condiciones del Servicio en el futuro, si sigues este enfoque, la app indicará al usuario que vuelva a aceptar las nuevas Condiciones del Servicio.

Los administradores de TI usan el portal de inscripción automática para administrar a los usuarios de su organización; esto no se puede ofrecer a través de la API del cliente. Los administradores de TI también pueden administrar dispositivos y parámetros de configuración a través del portal. Si necesitas establecer un vínculo al portal desde tu consola o en tu documentación, usa esta URL:

https://partner.android.com/zerotouch

Te recomendamos que informes a los administradores de TI que se les solicita que accedan con sus Cuentas de Google.

Inscripción de dispositivos

La inscripción automática es un mecanismo para inscribir dispositivos y es similar a la inscripción de NFC o la inscripción de código QR. Tu consola debe ser compatible con dispositivos administrados, y tu DPC debe poder ejecutarse en modo de dispositivo completamente administrado.

La inscripción automática está disponible en dispositivos compatibles que ejecutan Android 8.0 o versiones posteriores. Los administradores de TI deben comprar dispositivos compatibles a un distribuidor socio. La consola puede llamar a customers.devices.list para hacer un seguimiento de cuáles de los dispositivos del administrador de TI están disponibles para la inscripción automática.

A continuación, se describe cómo funciona la inscripción:

  1. Un dispositivo se comprueba en un servidor de Google en el primer inicio (o después de restablecer la configuración de fábrica) para la inscripción automática.
  2. Si el administrador de TI aplicó una configuración al dispositivo, la inscripción automática ejecutará el asistente de configuración de Android del dispositivo completamente administrado y personaliza las pantallas con metadatos de la configuración.
  3. La inscripción automática descarga e instala tu DPC desde Google Play.
  4. Tu DPC recibe el intent ACTION_PROVISION_MANAGED_DEVICE y aprovisiona el dispositivo.

Si no hay conexión a Internet, la verificación se realiza cuando hay una disponible. Para obtener más información sobre el aprovisionamiento de dispositivos con inscripción automática, consulta Aprovisionamiento a continuación.

Configuración predeterminada.

La inscripción automática ayuda más a los administradores de TI cuando establecen una configuración predeterminada que se aplica a cualquier dispositivo nuevo que compre su organización. Promueve el establecimiento de una configuración predeterminada desde tu consola si no está establecida. Puedes verificar el valor de customers.configurations.isDefault para averiguar si una organización estableció una configuración predeterminada.

En el siguiente ejemplo, se muestra cómo podrías hacer que una configuración existente sea la predeterminada:

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

Cómo hacer referencia a tu DPC

Te recomendamos que uses el nombre de recurso de la API customers.dpcs.name para identificar tu DPC y usarlo en los parámetros de configuración. El nombre del recurso contiene un identificador único que no cambia para el DPC. Llama a customers.dpcs.list para obtener la lista de todos los DPC compatibles. Debido a que el nombre del recurso también incluye el ID de cliente, filtra la lista con el último componente de ruta de acceso para encontrar una instancia Dpc que coincida. En el siguiente ejemplo, se muestra cómo hacer coincidir tu DPC y conservarlo para usarlo más adelante en una configuración:

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

Si necesitas mostrar el nombre de un DPC en la interfaz de usuario de la consola, muestra el valor que muestra customers.dpcs.dpcName.

Aprovisionamiento

Aprovecha la oportunidad de proporcionar una excelente experiencia del usuario para la provisión de dispositivos. Un nombre de usuario y una contraseña deberían ser todo lo necesario para aprovisionar el dispositivo. Recuerda que los revendedores pueden enviar dispositivos directamente a usuarios remotos. Incluye todas las demás opciones de configuración, como el servidor de EMM o la unidad organizativa, en customers.configuration.dpcExtras.

El siguiente fragmento de JSON muestra parte de una configuración de ejemplo:

{
  "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\"]"
    }
}

La inscripción automática instala e inicia tu DPC con un intent de Android. El sistema envía los valores de la propiedad JSON android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE a tu DPC como extras en el intent. Tu DPC puede leer la configuración de aprovisionamiento de PersistableBundle con las mismas claves.

Recomendado: Usa los siguientes intents adicionales para configurar tu DPC:

No se recomienda: no incluyas los siguientes extras que podrías usar en otros métodos de inscripción:

Si quieres obtener información para extraer y usar esta configuración en tu DPC, consulta Cómo aprovisionar dispositivos de clientes.

Desarrollo y pruebas

Para desarrollar y probar las funciones de inscripción automática de tu consola, necesitarás lo siguiente:

  • un dispositivo compatible
  • una cuenta de inscripción automática para clientes

Desarrolla y prueba con dispositivos compatibles con la inscripción automática, como los Google Pixel. No es necesario que compres los dispositivos de desarrollo a un socio revendedor.

Comunícate con nosotros a fin de obtener una cuenta de cliente de prueba y acceder al portal de inscripción automática. Envíanos un correo electrónico desde tu dirección de correo electrónico corporativa que está asociada con una Cuenta de Google. Indícanos el fabricante y el número IMEI de uno o dos dispositivos, y los agregaremos a tu cuenta de desarrollo.

Recuerda que, debido a que la inscripción automática descarga e instala automáticamente un DPC, tu DPC debe estar disponible en Google Play para que puedas probar el aprovisionamiento. No puedes realizar pruebas con una versión de desarrollo de tu DPC.

Asistencia para administradores de TI

Si necesitas ayudar a los administradores de TI en la interfaz de tu consola o en la documentación, consulta Inscripción automática para administradores de TI a fin de obtener orientación. También puedes dirigir a los usuarios de tu consola a ese artículo del Centro de ayuda.

Lecturas adicionales

Lee estos documentos para ayudarte a integrar la inscripción automática en tu consola: