Guida all'integrazione EMM

Questa guida aiuta i fornitori di gestione della mobilità aziendale (EMM) a integrare la registrazione zero-touch nella loro console. Continua a leggere per scoprire di più sulla registrazione e scoprire consigli sulle best practice per aiutare il tuo DPC (controller dei criteri dei dispositivi) a eseguire il provisioning dei dispositivi. Se hai un DPC, imparerai le best practice per il provisioning dei dispositivi e riceverai consigli su sviluppo e test.

Funzionalità per gli amministratori IT

Utilizza l'API per i clienti per aiutare gli amministratori IT a configurare la registrazione zero-touch direttamente dalla console. Ecco alcune attività che un amministratore IT potrebbe completare nella tua console:

  • Creare, modificare ed eliminare le configurazioni della registrazione zero-touch in base ai criteri relativi ai dispositivi mobili.
  • Imposta una configurazione predefinita in modo che il DPC esegua il provisioning dei dispositivi futuri acquistati dall'organizzazione.
  • Applica singole configurazioni ai dispositivi o rimuovi i dispositivi dalla registrazione zero-touch.

Per scoprire di più sulla registrazione zero-touch, leggi la panoramica.

Prerequisiti

Prima di aggiungere la registrazione zero-touch alla console EMM, verifica che la tua soluzione supporti quanto segue:

  • La tua soluzione EMM deve eseguire il provisioning di un dispositivo Android 8.0 o versioni successive (Pixel 7.1 e versioni successive) di proprietà dell'azienda in modalità completamente gestita. I dispositivi Android 10 e versioni successive di proprietà dell'azienda possono essere gestiti completamente o con un profilo di lavoro.
  • Poiché la registrazione zero-touch scarica e installa automaticamente un DPC, quest'ultimo deve essere disponibile su Google Play. Gestiamo un elenco di DPC compatibili che gli amministratori IT possono configurare utilizzando l'API del cliente o il portale. Invia una richiesta di modifica del prodotto tramite la community dei provider EMM per aggiungere il tuo DPC all'elenco.
  • I tuoi clienti hanno bisogno di un account di registrazione zero-touch per chiamare l'API del cliente. Un rivenditore partner configura l'account per l'organizzazione di un amministratore IT quando l'organizzazione acquista i suoi dispositivi.
  • Il dispositivo deve essere compatibile con Google Mobile Services (GMS) e Google Play Services deve essere sempre attivo affinché la registrazione zero-touch funzioni correttamente.

Chiama l'API

Gli utenti della tua console (utilizzando il proprio Account Google) autorizzano le richieste API all'API del cliente. Questo flusso è diverso dall'autorizzazione che esegui per altre API EMM. Leggi Autorizzazione per scoprire come eseguire questa operazione nella tua app.

Gestire i Termini di servizio

I tuoi utenti devono accettare i Termini di servizio (TdS) più recenti prima di chiamare l'API. Se la chiamata API restituisce un codice di stato HTTP 403 Forbidden e il corpo della risposta contiene un TosError, chiedi all'utente di accettare i TdS accedendo al portale della registrazione zero-touch. L'esempio seguente mostra uno dei modi in cui puoi eseguire questa operazione:

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 il client API di Google supporta errori dettagliati (richieste Java, Python o HTTP), includi nelle richieste l'intestazione HTTP X-GOOG-API-FORMAT-VERSION con il valore 2. Se il client non supporta gli errori dettagliati (.NET e altri), associa il messaggio di errore.

Quando in futuro aggiorneremo i TdS, se segui questo approccio, la tua app indirizzerà l'utente ad accettare di nuovo i nuovi TdS.

Gli amministratori IT utilizzano il portale di registrazione zero-touch per gestire gli utenti della propria organizzazione. Non puoi offrire questa funzionalità tramite l'API del cliente. Gli amministratori IT possono anche gestire dispositivi e configurazioni utilizzando il portale. Se devi creare un link al portale dalla console o nella documentazione, utilizza questo URL:

https://partner.android.com/zerotouch

Potresti voler comunicare agli amministratori IT che viene loro richiesto di accedere con il proprio Account Google.

Registrazione del dispositivo

La registrazione zero-touch è un meccanismo per registrare i dispositivi ed è simile alla registrazione NFC o del codice QR. La console deve supportare i dispositivi gestiti e il DPC deve poter essere eseguito in modalità dispositivo completamente gestito.

La registrazione zero-touch è disponibile sui dispositivi supportati con Android 8.0 o versioni successive. Gli amministratori IT devono acquistare i dispositivi supportati da un rivenditore partner. La console può tenere traccia dei dispositivi dell'amministratore IT disponibili per la registrazione zero-touch chiamando il numero customers.devices.list.

Ecco una panoramica di come funziona la registrazione:

  1. Un dispositivo si mette in contatto con un server Google al primo avvio (o dopo un ripristino dei dati di fabbrica) per la registrazione zero-touch.
  2. Se l'amministratore IT ha applicato una configurazione al dispositivo, la registrazione zero-touch esegue la configurazione guidata di Android per i dispositivi completamente gestiti e personalizza le schermate con i metadati della configurazione.
  3. La registrazione zero-touch scarica e installa il tuo DPC da Google Play.
  4. Il DPC riceve l'intent ACTION_PROVISION_MANAGED_DEVICE ed esegue il provisioning del dispositivo.

In assenza di una connessione a internet, il controllo viene eseguito quando ne diventa disponibile una. Per scoprire di più sul provisioning dei dispositivi con la registrazione zero-touch, consulta la sezione Provisioning qui sotto.

Configurazioni predefinite

La registrazione zero-touch è di grande aiuto per gli amministratori IT quando impostano una configurazione predefinita che viene applicata a qualsiasi nuovo dispositivo acquistato dalla loro organizzazione. Promuovi l'impostazione di una configurazione predefinita dalla console, se non ne è impostata una. Puoi controllare il valore di customers.configurations.isDefault per scoprire se un'organizzazione ha impostato una configurazione predefinita.

L'esempio seguente mostra come rendere predefinita una configurazione esistente:

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

Riferimento al DPC (controller criteri dispositivi)

Ti consigliamo di utilizzare il nome risorsa API customers.dpcs.name per identificare il DPC e utilizzarlo nelle configurazioni. Il nome della risorsa contiene un identificatore univoco e non modificabile per il DPC. Chiama il numero customers.dpcs.list per visualizzare l'elenco di tutti i DPC supportati. Poiché il nome della risorsa include anche l'ID cliente, filtra l'elenco utilizzando l'ultimo componente del percorso per trovare un'istanza Dpc corrispondente. L'esempio riportato di seguito mostra come creare una corrispondenza con il DPC e mantenere l'utilizzo in un secondo momento in una configurazione:

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 devi mostrare il nome di un DPC nell'interfaccia utente della console, visualizza il valore restituito da customers.dpcs.dpcName.

In fase di provisioning

Approfitta di questa opportunità per offrire un'esperienza utente ottimale per il provisioning dei dispositivi. Sono necessari solo nome utente e password per eseguire il provisioning del dispositivo. Ricorda che i rivenditori potrebbero spedire i dispositivi direttamente agli utenti remoti. Includi tutte le altre impostazioni, ad esempio il server EMM o l'unità organizzativa, in customers.configuration.dpcExtras.

Lo snippet JSON riportato di seguito mostra parte di una configurazione di esempio:

{
  "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 registrazione zero-touch installa e avvia il DPC utilizzando un intent Android. Il sistema invia i valori nella proprietà JSON android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE al tuo DPC come extra nell'intent. Il DPC può leggere le impostazioni di provisioning da PersistableBundle utilizzando le stesse chiavi.

Consigliato: utilizza i seguenti extra per l'intent per configurare il DPC:

Non consigliato. Non includere i seguenti extra che potresti utilizzare in altri metodi di registrazione:

Per informazioni su come estrarre e utilizzare queste impostazioni nel DPC, consulta Provisioning dei dispositivi dei clienti.

Sviluppo e test

Per sviluppare e testare le funzionalità di registrazione zero-touch della tua console, ti serviranno quanto segue:

  • un dispositivo supportato
  • un account di registrazione zero-touch del cliente

Sviluppa ed esegui test con dispositivi che supportano la registrazione zero-touch, come Google Pixel. Non è necessario acquistare i dispositivi di sviluppo da un rivenditore partner.

Contattaci per ottenere un account cliente di prova e accedere al portale della registrazione zero-touch. Inviaci un'email dall'indirizzo email aziendale associato a un Account Google. Comunicaci il produttore e il numero IMEI di uno o due dispositivi e li aggiungeremo al tuo account di sviluppo.

Tieni presente che, poiché la registrazione zero-touch scarica e installa automaticamente un DPC, quest'ultimo deve essere disponibile su Google Play prima di poter testare il provisioning. Non puoi eseguire test con una versione di sviluppo del DPC.

Assistenza per gli amministratori IT

Se hai bisogno di aiutare gli amministratori IT nell'interfaccia della console o nella documentazione, consulta la pagina Registrazione zero-touch per gli amministratori IT per ulteriori indicazioni. Puoi anche indirizzare gli utenti della console all'articolo del Centro assistenza in questione.

Per approfondire

Leggi questi documenti per aiutarti a integrare la registrazione zero-touch nella tua console: