Guide d'intégration EMM

Ce guide aide les fournisseurs de solutions de gestion de la mobilité en entreprise (EMM) à intégrer l'enregistrement sans contact à leur console. Poursuivez votre lecture pour en savoir plus sur l'enregistrement et découvrir les bonnes pratiques à suivre pour aider votre DPC (outil de contrôle des règles relatives aux appareils) à provisionner des appareils. Si vous disposez d'un DPC, vous connaîtrez les bonnes pratiques de provisionnement des appareils et obtiendrez des conseils pour vous aider à réaliser des tâches de développement et de test.

Fonctionnalités pour les administrateurs informatiques

Aidez les administrateurs informatiques à configurer l'enregistrement sans contact directement depuis la console à l'aide de l'API client. Voici quelques tâches qu'un administrateur informatique peut accomplir dans votre console:

  • Créez, modifiez et supprimez des configurations d'enregistrement sans contact en fonction de vos règles pour appareils mobiles.
  • Définissez une configuration par défaut afin que votre DPC provisionne les futurs appareils achetés par l'organisation.
  • Appliquez des configurations individuelles à des appareils ou supprimez des appareils de l'enregistrement sans contact.

Pour en savoir plus sur l'enregistrement sans contact, consultez la présentation.

Prérequis

Avant d'ajouter l'enregistrement sans contact à votre console EMM, vérifiez que votre solution est compatible avec les éléments suivants:

  • Votre solution EMM doit provisionner un appareil Android 8.0 (ou version ultérieure) appartenant à l'entreprise en mode entièrement géré. Les appareils Android 10 et versions ultérieures appartenant à l'entreprise peuvent être provisionnés comme étant entièrement gérés ou avec un profil professionnel.
  • Étant donné que l'enregistrement sans contact télécharge et installe automatiquement un DPC, celui-ci doit être disponible sur Google Play. Nous gérons une liste de DPC compatibles que les administrateurs informatiques peuvent configurer à l'aide de l'API client ou du portail. Envoyez une demande de modification de produit via la communauté des fournisseurs EMM pour ajouter votre DPC à la liste.
  • Vos clients doivent disposer d'un compte d'enregistrement sans contact pour appeler l'API client. Un revendeur partenaire configure le compte de l'organisation d'un administrateur informatique lorsque celle-ci achète des appareils.
  • L'appareil doit être compatible avec les services Google Mobile (GMS) et les services Google Play doivent être activés à tout moment pour que l'enregistrement sans contact fonctionne correctement.

Appeler l'API

Les utilisateurs de votre console (à l'aide de leur compte Google) autorisent vos requêtes API adressées à l'API client. Ce flux est différent de l'autorisation que vous effectuez pour d'autres API EMM. Pour savoir comment procéder dans votre application, consultez la section Autorisation.

Gérer les conditions d'utilisation

Vos utilisateurs doivent accepter les dernières conditions d'utilisation avant d'appeler l'API. Si l'appel d'API renvoie un code d'état HTTP 403 Forbidden et que le corps de la réponse contient TosError, invitez l'utilisateur à accepter les conditions d'utilisation en se connectant au portail d'enregistrement sans contact. L'exemple ci-dessous montre l'une des façons de procéder:

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 votre client API Google accepte les erreurs détaillées (requêtes Java, Python ou HTTP), incluez l'en-tête HTTP X-GOOG-API-FORMAT-VERSION avec la valeur 2 dans vos requêtes. Si votre client n'est pas compatible avec les erreurs détaillées (.NET et autres), faites correspondre le message d'erreur.

Si vous suivez cette approche, lorsque nous mettrons à jour les conditions d'utilisation, votre application demandera à l'utilisateur d'accepter de nouveau les nouvelles conditions d'utilisation.

Les administrateurs informatiques utilisent le portail d'enregistrement sans contact pour gérer les utilisateurs de leur organisation. Vous ne pouvez pas proposer ce service via l'API client. Les administrateurs informatiques peuvent également gérer les appareils et les configurations à l'aide du portail. Si vous devez créer un lien vers le portail à partir de votre console ou dans votre documentation, utilisez cette URL:

https://partner.android.com/zerotouch

Vous pouvez informer les administrateurs informatiques qu'ils sont invités à se connecter avec leur compte Google.

Enregistrement des appareils

L'enregistrement sans contact est un mécanisme permettant d'enregistrer des appareils, semblable à l'enregistrement NFC ou à l'enregistrement par code QR. Votre console doit prendre en charge les appareils gérés, et votre DPC doit pouvoir s'exécuter en mode appareil entièrement géré.

L'enregistrement sans contact est disponible sur les appareils compatibles équipés d'Android 8.0 ou version ultérieure. Les administrateurs informatiques doivent acheter des appareils compatibles auprès d'un revendeur partenaire. Votre console peut suivre les appareils de l'administrateur informatique pouvant être enregistrés sans contact en appelant customers.devices.list.

Voici un aperçu du fonctionnement de l'enregistrement:

  1. Un appareil se connecte à un serveur Google au premier démarrage (ou après une réinitialisation d'usine) pour l'enregistrement sans contact.
  2. Si l'administrateur informatique a appliqué une configuration à l'appareil, l'enregistrement sans contact exécute l'assistant de configuration Android de l'appareil entièrement géré et personnalise les écrans avec les métadonnées de la configuration.
  3. L'enregistrement sans contact télécharge et installe votre DPC depuis Google Play.
  4. Votre DPC reçoit l'intent ACTION_PROVISION_MANAGED_DEVICE et provisionne l'appareil.

En l'absence de connexion Internet, la vérification est effectuée lorsqu'une connexion est disponible. Pour en savoir plus sur le provisionnement des appareils avec l'enregistrement sans contact, consultez la section Provisionnement ci-dessous.

Configurations par défaut

L'enregistrement sans contact est particulièrement utile aux administrateurs informatiques lorsqu'ils définissent une configuration par défaut qui s'applique à tous les nouveaux appareils achetés par leur organisation. Promouvez la définition d'une configuration par défaut à partir de votre console, le cas échéant. Vous pouvez vérifier la valeur de customers.configurations.isDefault pour savoir si une organisation a défini une configuration par défaut.

L'exemple ci-dessous montre comment définir une configuration existante comme configuration par défaut:

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

Référencer votre DPC

Nous vous recommandons d'utiliser le nom de ressource d'API customers.dpcs.name pour identifier votre DPC et l'utiliser dans les configurations. Le nom de la ressource contient un identifiant unique et immuable pour le DPC. Appelez customers.dpcs.list pour obtenir la liste de tous les DPC compatibles. Étant donné que le nom de la ressource inclut également le numéro client, filtrez la liste à l'aide du dernier composant de chemin d'accès pour trouver une instance Dpc correspondante. L'exemple ci-dessous montre comment faire correspondre votre DPC et comment la conserver pour une utilisation ultérieure dans une configuration:

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 vous devez afficher le nom d'un DPC dans l'interface utilisateur de votre console, affichez la valeur renvoyée par customers.dpcs.dpcName.

Provisionnement

Profitez-en pour proposer une expérience utilisateur optimale lors du provisionnement des appareils. Un nom d'utilisateur et un mot de passe devraient suffire pour provisionner l'appareil. N'oubliez pas que les revendeurs peuvent expédier des appareils directement à des utilisateurs distants. Incluez tous les autres paramètres, tels que le serveur EMM ou l'unité organisationnelle, dans customers.configuration.dpcExtras.

L'extrait de code JSON ci-dessous montre une partie d'un exemple de configuration:

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

L'enregistrement sans contact installe et lance votre DPC à l'aide d'un intent Android. Le système envoie les valeurs de la propriété JSON android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE à votre DPC en tant qu'extras dans l'intent. Votre DPC peut lire les paramètres de provisionnement à partir de PersistableBundle à l'aide des mêmes clés.

Recommandé : utilisez les extras d'intent suivants pour configurer votre DPC :

Approche déconseillée : n'incluez pas les extras suivants que vous pourriez utiliser avec d'autres méthodes d'enregistrement :

Pour savoir comment extraire et utiliser ces paramètres dans votre DPC, consultez Provisionner les appareils du client.

Développement et tests

Pour développer et tester les fonctionnalités d'enregistrement sans contact de votre console, vous avez besoin des éléments suivants:

  • un appareil compatible
  • un compte d'enregistrement sans contact client

Développez et testez avec des appareils compatibles avec l'enregistrement sans contact, tels que le Google Pixel. Vous n'avez pas besoin d'acheter vos appareils de développement auprès d'un revendeur partenaire.

Contactez-nous pour obtenir un compte client de test et accéder au portail d'enregistrement sans contact. Envoyez-nous un e-mail à partir de votre adresse e-mail professionnelle associée à un compte Google. Indiquez-nous le fabricant et le code IMEI d'un ou deux appareils, et nous les ajouterons à votre compte de développement.

N'oubliez pas que, comme l'enregistrement sans contact télécharge et installe automatiquement un DPC, celui-ci doit être disponible sur Google Play pour que vous puissiez tester le provisionnement. Vous ne pouvez pas effectuer de test avec une version de développement de votre DPC.

Assistance pour les administrateurs informatiques

Si vous avez besoin d'aide pour les administrateurs informatiques dans l'interface de votre console ou dans votre documentation, consultez la page Enregistrement sans contact pour les administrateurs informatiques pour obtenir des conseils. Vous pouvez également rediriger les utilisateurs de votre console vers cet article du centre d'aide.

Complément d'informations

Lisez ces documents pour vous aider à intégrer l'enregistrement sans contact dans votre console: