Guida all'integrazione EMM

Questa guida aiuta i provider di gestione della mobilità aziendale (EMM) a integrare la registrazione zero-touch nella console. Continua a leggere per scoprire di più sulla registrazione e consultare le best practice per aiutare il DPC (controller dei criteri dei dispositivi) a eseguire il provisioning dei dispositivi. Se disponi di un DPC (controller criteri dispositivi), imparerai le best practice per il provisioning dei dispositivi e riceverai consigli per aiutarti con 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. Di seguito sono riportate alcune attività che un amministratore IT potrebbe completare nella tua console:

• Crea, modifica ed elimina configurazioni della registrazione zero-touch in base ai tuoi criteri relativi ai dispositivi mobili.
• Imposta una configurazione predefinita in modo che il DPC esegua il provisioning di dispositivi futuri degli acquisti effettuati dall'organizzazione.
• Applica singole configurazioni ai dispositivi o rimuovi i dispositivi dalla registrazione zero-touch.

Per ulteriori informazioni sulla registrazione zero-touch, leggi le Panoramica.

Prerequisiti

Prima di aggiungere la registrazione zero-touch alla console EMM, verifica che il tuo supporta quanto segue:

• La tua soluzione EMM deve eseguire il provisioning di un Android 8.0 o versioni successive (Pixel 7.1 e versioni successive) di proprietà dell'azienda dispositivo in modalità completamente gestita. Per i dispositivi di proprietà dell'azienda con Android 10 o versioni successive è possibile eseguire il provisioning come dispositivi completamente gestiti o con un profilo di lavoro.
• Poiché la registrazione zero-touch scarica e installa automaticamente un DPC, Il DPC deve essere disponibile su Google Play. Manteniamo un elenco di DPC compatibili che gli amministratori IT possono configurare usando 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 devono avere 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 che l'organizzazione acquista i propri dispositivi.
• Il dispositivo deve essere compatibile con Google Mobile Services (GMS). e Google Play Services deve essere sempre attivo per la registrazione zero-touch funzionino correttamente.

Chiama l'API

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

Gestire i Termini di servizio

Gli 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 elemento TosError. Chiedi all'utente di accettare i TdS accedendo al portale della registrazione zero-touch. Nell'esempio riportato di seguito mostra uno dei modi per farlo:

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

Quando aggiorneremo i TdS in futuro, se seguirai questo approccio, la tua app indica all'utente di accettare nuovamente i nuovi TdS.

Link al portale

Gli amministratori IT usano il portale della registrazione zero-touch per gestire gli utenti per organizzazione, non puoi offrire questa funzionalità tramite l'API del cliente. Gli amministratori IT possono anche gestire dispositivi e configurazioni utilizzando il portale. Se è necessario collegarsi al dalla console o nella documentazione, usa questo URL:

https://partner.android.com/zerotouch

Potrebbe essere utile informare gli amministratori IT che devono accedere con il proprio Account Google

Registrazione dei dispositivi

La registrazione zero-touch è un meccanismo per registrare i dispositivi ed è simile all'NFC la registrazione o la registrazione con codice QR. La console deve supportare i dispositivi gestiti e il DPC deve essere in grado di funzionare in modalità dispositivo completamente gestito.

La registrazione zero-touch è disponibile sui dispositivi supportati con Android 8.0 o in un secondo momento. Gli amministratori IT devono acquistare dispositivi supportati da un partner di Google. La tua console può monitorare quali dispositivi dell'amministratore IT sono disponibili per la registrazione zero-touch chiamata al numero customers.devices.list.

Ecco come funziona la registrazione:

1. Un dispositivo esegue il check-in 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 esegue la configurazione guidata di Android del dispositivo completamente gestito e personalizza schermate con metadati dalla configurazione.
3. La registrazione zero-touch scarica e installa il tuo DPC da Google Play.
4. Il DPC riceve il Intenzione di ACTION_PROVISION_MANAGED_DEVICE e esegue il provisioning del dispositivo.

Se non è presente una connessione a internet, il controllo viene eseguito quando ne diventa disponibile una. Per ulteriori informazioni sul provisioning dei dispositivi con la registrazione zero-touch, consulta la sezione Provisioning di seguito.

Configurazioni predefinite

La registrazione zero-touch è utile soprattutto agli amministratori IT quando impostano una configurazione predefinita e verrà applicata a tutti i nuovi dispositivi acquistati dall'organizzazione. Promuovi impostazione 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 eseguire una configurazione esistente valore predefinito:

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

Fare riferimento al DPC

Ti consigliamo di utilizzare il nome risorsa API customers.dpcs.name per identificare il DPC e utilizzarlo nelle configurazioni. Il nome della risorsa contiene identificatore univoco e permanente per il DPC. Chiama customers.dpcs.list per visualizzare l'elenco di tutti i dispositivi supportati DPC (controller criteri dispositivi). 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 che segue mostra come abbinare il tuo DPC e mantenere per utilizzarlo in un secondo momento in un configurazione:

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

Provisioning

Approfitta di questa opportunità per offrire un'esperienza utente ottimale per il provisioning dei dispositivi. Un nome utente e una password dovrebbero essere tutto ciò che serve per eseguire il provisioning del dispositivo. Ricorda che i rivenditori potrebbero spedire i dispositivi direttamente agli utenti remoti. Includi tutte le altre impostazioni, come il server EMM o l'unità organizzativa, in customers.configuration.dpcExtras

Lo snippet JSON 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 tuo DPC utilizzando un intent Android. Il sistema invia i valori nei campi android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE al DPC (controller criteri dispositivi) come extra nell'intento. Il DPC può leggere le impostazioni di provisioning PersistableBundle utilizzando le stesse chiavi.

Consigliato: usa i seguenti extra per intent. per impostare il 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

Non consigliato: non includere quanto segue. extra che potresti usare in altri metodi di registrazione:

• 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

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

Sviluppo e test

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

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

Sviluppo e test con dispositivi che supportano la registrazione zero-touch registrazione, 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 di registrazione zero-touch. Inviaci un'email dal tuo indirizzo email aziendale associato a un account Google Account. Comunicaci il produttore e il codice IMEI di uno o due dispositivi e li aggiungeremo al tuo sviluppo .

Ricorda che la registrazione zero-touch scarica e installa automaticamente Il DPC (controller criteri dispositivi) deve essere disponibile su Google Play per poter eseguire il test per eseguire il provisioning. Non puoi eseguire test con una versione di sviluppo del DPC (controller criteri dispositivi).

Assistenza per gli amministratori IT

Se hai bisogno di aiutare gli amministratori IT nell'interfaccia della tua console o nella tua documentazione, consulta la pagina Registrazione zero-touch per gli amministratori IT per istruzioni. Tu può anche indirizzare gli utenti della console a quell'articolo del Centro assistenza.

Per approfondire

Leggi questi documenti per integrare la registrazione zero-touch nel tuo Console:

• Registrazione zero-touch per gli amministratori IT nella Guida di Android Enterprise.
• Esegui il provisioning dei dispositivi dei clienti da Android EMM. sito per sviluppatori.