Panduan integrasi EMM

Panduan ini membantu penyedia pengelolaan mobilitas perusahaan (EMM) mengintegrasikan pendaftaran zero-touch ke konsol mereka. Lanjutkan membaca untuk mempelajari lebih lanjut pendaftaran dan melihat saran praktik terbaik untuk membantu perangkat penyediaan DPC (pengontrol kebijakan perangkat). Jika Anda memiliki DPC, Anda akan mempelajari praktik terbaik saat menyediakan perangkat dan mendapatkan saran bantuan melalui pengembangan dan pengujian.

Fitur untuk admin IT

Gunakan API pelanggan untuk membantu admin IT menyiapkan pendaftaran zero-touch langsung dari konsol Anda. Berikut beberapa tugas yang mungkin diselesaikan admin IT di konsol Anda:

• Membuat, mengedit, dan menghapus konfigurasi pendaftaran zero-touch berdasarkan kebijakan seluler.
• Tetapkan konfigurasi default agar DPC menyediakan perangkat di masa mendatang pembelian organisasi.
• Menerapkan konfigurasi individual ke perangkat atau menghapus perangkat dari zero-touch pendaftaran.

Untuk mempelajari pendaftaran zero-touch lebih lanjut, baca ringkasan.

Prasyarat

Sebelum menambahkan pendaftaran zero-touch ke konsol EMM, pastikan yang mendukung hal berikut:

• Solusi EMM Anda perlu menyediakan Android 8.0+ (Pixel 7.1+) milik perusahaan perangkat Anda dalam mode terkelola sepenuhnya. Perangkat Android 10 dan yang lebih baru milik perusahaan dapat disediakan sebagai terkelola sepenuhnya atau dengan profil kerja.
• Karena pendaftaran zero-touch otomatis mendownload dan menginstal DPC, DPC harus tersedia dari Google Play. Kami mempertahankan daftar DPC yang kompatibel yang dapat dikonfigurasi oleh admin IT menggunakan API atau portal pelanggan. Kirimkan permintaan modifikasi produk melalui komunitas Penyedia EMM untuk menambahkan DPC ke daftar.
• Pelanggan Anda memerlukan akun pendaftaran zero-touch untuk memanggil API pelanggan. Reseller partner menyiapkan akun untuk organisasi admin IT saat organisasi membeli perangkat mereka.
• Perangkat harus kompatibel dengan Layanan Seluler Google (GMS) dan layanan Google Play harus diaktifkan setiap saat untuk pendaftaran zero-touch berfungsi dengan baik.

Memanggil API

Pengguna konsol Anda (menggunakan Akun Google mereka) mengizinkan permintaan API Anda untuk API pelanggan. Alur ini berbeda dengan otorisasi yang Anda lakukan untuk EMM API lainnya. Baca Otorisasi untuk mempelajari cara melakukannya di aplikasi Anda.

Menangani Persyaratan Layanan

Pengguna Anda harus menyetujui Persyaratan Layanan terbaru (ToS) sebelum memanggil API. Jika panggilan API menampilkan kode status HTTP 403 Forbidden dan isi respons berisi TosError, minta pengguna untuk menyetujui ToS dengan login ke portal pendaftaran zero-touch. Contoh di bawah ini menunjukkan salah satu cara untuk melakukannya:

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

Apakah klien Google API Anda mendukung error mendetail (Java, Python, atau HTTP permintaan), sertakan header HTTP X-GOOG-API-FORMAT-VERSION dengan nilai 2 dalam permintaan Anda. Jika klien Anda tidak mendukung {i>error<i} yang terperinci (.NET dan yang lain), cocokkan pesan {i>error<i}.

Saat kami memperbarui ToS pada masa mendatang, jika Anda mengikuti pendekatan ini, aplikasi Anda mengarahkan pengguna untuk menyetujui ulang ToS yang baru.

Tautkan ke portal

Admin IT menggunakan portal pendaftaran zero-touch untuk mengelola pengguna organisasi—Anda tidak dapat menawarkan ini melalui API pelanggan. Admin IT juga dapat mengelola perangkat dan konfigurasi menggunakan portal. Jika Anda perlu menautkan ke dari konsol atau dokumentasi Anda, gunakan URL ini:

https://partner.android.com/zerotouch

Sebaiknya beri tahu admin IT bahwa mereka diminta login dengan Akun Google.

Pendaftaran perangkat

Pendaftaran zero-touch adalah mekanisme untuk mendaftarkan perangkat dan mirip dengan NFC atau pendaftaran kode QR. Konsol Anda harus mendukung perangkat terkelola dan DPC harus dapat berjalan dalam mode perangkat yang terkelola sepenuhnya.

Pendaftaran zero-touch tersedia di perangkat yang didukung yang menjalankan Android 8.0 atau nanti. Admin IT harus membeli perangkat yang didukung dari partner reseller. Konsol Anda dapat melacak perangkat admin IT mana yang tersedia untuk pendaftaran zero-touch dengan memanggil customers.devices.list.

Berikut adalah garis besar cara kerja pendaftaran:

1. Perangkat melakukan check in dengan server Google saat pertama kali dimulai (atau setelah setelan pabrik reset) untuk pendaftaran zero-touch.
2. Jika admin IT telah menerapkan konfigurasi ke perangkat, zero-touch pendaftaran menjalankan wizard penyiapan perangkat Android yang terkelola sepenuhnya dan mempersonalisasi layar dengan metadata dari konfigurasi.
3. Pendaftaran zero-touch mendownload dan menginstal DPC dari Google Play.
4. DPC Anda menerima intent ACTION_PROVISION_MANAGED_DEVICE dan menyediakan perangkat.

Jika tidak ada koneksi internet, pemeriksaan dilakukan ketika ada seseorang yang tersedia. Untuk mempelajari lebih lanjut penyediaan perangkat dengan pendaftaran zero-touch, lihat Penyediaan di bawah.

Konfigurasi default

Pendaftaran zero-touch sangat membantu admin IT saat mereka menetapkan konfigurasi default yang diterapkan ke perangkat baru apa pun yang dibeli oleh organisasi mereka. Setelan promosi konfigurasi {i>default<i} dari konsol Anda jika belum ada. Anda dapat memeriksa nilai customers.configurations.isDefault hingga mengetahui apakah suatu organisasi telah menetapkan konfigurasi {i>default<i}.

Contoh di bawah ini menunjukkan cara membuat konfigurasi yang ada menjadi default:

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

Mereferensikan DPC

Sebaiknya gunakan nama resource API customers.dpcs.name untuk mengidentifikasi DPC dan menggunakannya dalam konfigurasi. Nama resource berisi ID yang unik dan tidak berubah untuk DPC. Telepon customers.dpcs.list untuk mendapatkan daftar semua data yang didukung DPC. Karena nama resource juga menyertakan ID pelanggan, filter daftar menggunakan komponen jalur terakhir untuk menemukan instance Dpc yang cocok. Contoh di bawah ini menunjukkan cara mencocokkan DPC dan mempertahankannya untuk digunakan nanti di konfigurasi:

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

Jika Anda perlu menampilkan nama DPC di antarmuka pengguna konsol, tampilkan nilai yang ditampilkan dari customers.dpcs.dpcName.

Penyediaan

Manfaatkan kesempatan ini untuk memberikan pengalaman pengguna yang luar biasa untuk penyediaan perangkat. Hanya nama pengguna dan sandi yang diperlukan untuk menyediakan perangkat. Ingat, reseller mungkin mengirimkan perangkat langsung ke pengguna jarak jauh. Sertakan semua setelan lainnya, seperti server EMM atau unit organisasi, di customers.configuration.dpcExtras

Cuplikan JSON di bawah menunjukkan bagian dari contoh konfigurasi:

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

Pendaftaran zero-touch menginstal dan meluncurkan DPC menggunakan Intent Android. Sistem mengirimkan nilai-nilai dalam Properti JSON android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE ke DPC Anda sebagai tambahan dalam intent. DPC Anda dapat membaca setelan penyediaan dari PersistableBundle menggunakan kunci yang sama.

Direkomendasikan—gunakan tambahan intent berikut untuk menyiapkan 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

Tidak direkomendasikan—jangan sertakan hal berikut tambahan yang mungkin Anda gunakan dalam metode pendaftaran lainnya:

• 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

Untuk mempelajari cara mengekstrak dan menggunakan setelan ini di DPC, baca Penyediaan perangkat pelanggan.

Pengembangan dan pengujian

Untuk mengembangkan dan menguji fitur pendaftaran zero-touch konsol, Anda harus hal berikut:

• perangkat yang didukung
• akun pendaftaran zero-touch pelanggan

Mengembangkan dan menguji dengan perangkat yang mendukung zero-touch pendaftaran domain, seperti Google Pixel. Anda tidak perlu membeli perangkat pengembangan dari mitra pengecer.

Hubungi kami untuk mendapatkan akun pelanggan uji coba dan akses ke portal pendaftaran zero-touch. Kirim email kepada kami dari alamat email perusahaan Anda yang yang terkait dengan menggunakan Akun Layanan Anda. Beri tahu kami produsen serta nomor IMEI dari satu atau dua perangkat dan kami akan menambahkannya ke aplikasi pengembangan menggunakan akun layanan.

Ingat, karena pendaftaran zero-touch otomatis mendownload dan menginstal DPC, DPC harus tersedia di Google Play sebelum Anda dapat menguji penyediaan resource. Anda tidak dapat menguji dengan versi pengembangan DPC.

Dukungan untuk admin IT

Jika Anda perlu membantu admin IT di antarmuka konsol atau dokumentasi Anda, Lihat Pendaftaran zero-touch untuk admin IT sebagai panduan. Anda juga dapat mengarahkan pengguna konsol Anda ke artikel pusat bantuan tersebut.

Bacaan lebih lanjut

Baca dokumen ini untuk membantu Anda mengintegrasikan pendaftaran zero-touch di konsol:

• Pendaftaran zero-touch untuk admin IT di Android Enterprise Bantuan.
• Menyediakan perangkat pelanggan dari EMM Android Situs developer.