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 menyediakan perangkat DPC (pengontrol kebijakan perangkat). Jika memiliki DPC, Anda akan mempelajari praktik terbaik saat menyediakan perangkat dan mendapatkan saran untuk membantu 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 oleh admin IT di konsol Anda:

  • Membuat, mengedit, dan menghapus konfigurasi pendaftaran zero-touch berdasarkan kebijakan seluler Anda.
  • Tetapkan konfigurasi default agar DPC Anda menyediakan perangkat mendatang yang dibeli organisasi.
  • Terapkan konfigurasi satu per satu ke perangkat atau hapus perangkat dari pendaftaran zero-touch.

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

Prasyarat

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

  • Solusi EMM Anda perlu menyediakan perangkat Android 8.0+ (Pixel 7.1+) milik perusahaan dalam mode terkelola sepenuhnya. Perangkat Android 10+ milik perusahaan dapat disediakan sebagai dikelola sepenuhnya atau dengan profil kerja.
  • Karena pendaftaran zero-touch otomatis mendownload dan menginstal DPC, DPC Anda harus tersedia dari Google Play. Kami menyimpan daftar DPC yang kompatibel yang dapat dikonfigurasi oleh admin IT menggunakan API pelanggan atau portal. 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 agar pendaftaran zero-touch berfungsi dengan benar.

Memanggil API

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

Menangani Persyaratan Layanan

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

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)

Jika klien Google API Anda mendukung error mendetail (permintaan Java, Python, atau HTTP), sertakan header HTTP X-GOOG-API-FORMAT-VERSION dengan nilai 2 dalam permintaan Anda. Jika klien Anda tidak mendukung error mendetail (.NET dan lainnya), cocokkan pesan error tersebut.

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

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

https://partner.android.com/zerotouch

Anda dapat memberi tahu admin IT bahwa mereka akan diminta untuk login dengan Akun Google mereka.

Pendaftaran perangkat

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

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

Berikut ringkasan cara kerja pendaftaran:

  1. Perangkat melakukan pemeriksaan dengan server Google saat memulai pertama kali (atau setelah reset ke setelan pabrik) untuk pendaftaran zero-touch.
  2. Jika admin IT telah menerapkan konfigurasi ke perangkat, pendaftaran zero-touch akan menjalankan wizard penyiapan Android perangkat yang terkelola sepenuhnya dan mempersonalisasi layar dengan metadata dari konfigurasi.
  3. Pendaftaran zero-touch akan 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 saat koneksi tersedia. Untuk mempelajari penyediaan perangkat dengan pendaftaran zero-touch lebih lanjut, lihat Penyediaan di bawah.

Konfigurasi default

Pendaftaran zero-touch sangat membantu admin IT saat mereka menetapkan konfigurasi default yang diterapkan ke perangkat baru yang dibeli organisasi mereka. Promosikan setelan konfigurasi default dari konsol Anda jika belum ditetapkan. Anda dapat memeriksa nilai customers.configurations.isDefault untuk mengetahui apakah organisasi telah menetapkan konfigurasi default.

Contoh di bawah menunjukkan cara yang dapat Anda lakukan untuk menjadikan konfigurasi yang ada sebagai default:

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

Mereferensikan DPC

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

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

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, bahwa reseller dapat mengirimkan perangkat langsung kepada pengguna jarak jauh. Sertakan semua setelan lainnya, seperti server EMM atau unit organisasi, di customers.configuration.dpcExtras.

Cuplikan JSON di bawah ini 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 di 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:

Tidak direkomendasikan—jangan sertakan tambahan berikut yang mungkin Anda gunakan di metode pendaftaran lain:

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

Pengembangan dan pengujian

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

  • perangkat yang didukung
  • akun pendaftaran zero-touch pelanggan

Kembangkan dan uji dengan perangkat yang mendukung pendaftaran zero-touch, seperti Google Pixel. Anda tidak perlu membeli perangkat pengembangan dari partner reseller.

Hubungi kami untuk mendapatkan akun pelanggan pengujian dan akses ke portal pendaftaran zero-touch. Kirim email kepada kami dari alamat email perusahaan Anda yang terkait dengan Akun Google. Beri tahu kami nomor produsen dan IMEI satu atau dua perangkat, dan kami akan menambahkannya ke akun pengembangan Anda.

Perlu diingat, karena pendaftaran zero-touch otomatis mendownload dan menginstal DPC, DPC Anda harus tersedia dari Google Play sebelum Anda dapat menguji penyediaan. Anda tidak dapat melakukan pengujian 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 untuk mendapatkan panduan. Anda juga dapat mengarahkan pengguna konsol Anda ke artikel pusat bantuan tersebut.

Bacaan lebih lanjut

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