Autentikasi untuk GDK Glassware

Jika GDK Glassware perlu mengautentikasi pengguna terhadap layanan web, GDK akan menyediakan API yang memungkinkan pengguna memasukkan kredensialnya saat menginstal Glassware.

Dengan menggunakan API ini, Anda akan memberikan pengalaman pengguna yang konsisten bagi pengguna Glass dan menghindari biaya penerapan skema autentikasi kustom Anda sendiri.

Catatan: Saat ini, Anda hanya dapat menguji dan menggunakan API ini setelah kami mengupload APK ke MyGlass, yang terjadi selama proses peninjauan.

Membuat akun layanan Google API

Setelah autentikasi disiapkan dengan benar, backend aplikasi Anda akan menggunakan Mirror API untuk mengirim informasi akun pengguna ke Glass setelah mereka mengautentikasi dengan layanan Anda.

Untuk mengakses API ini, buat project Google API, lalu buat client ID untuk "akun layanan" (dan bukan "aplikasi web"). Dengan menggunakan akun layanan, pengguna tidak perlu memberikan izin aplikasi secara terpisah untuk mengirimkan kredensial mereka ke Glass dan tidak akan diberi halaman izin OAuth dan halaman autentikasi Anda lagi.

Untuk membuat akun ini:

1. Buka Google Developers Console.
2. Klik tombol Create Project dan masukkan informasi yang diminta.
3. Setelah project Anda dibuat, catat Nomor Project, yang akan diperlukan nanti.
4. Di bagian APIs & amp; auth, klik APIs dan aktifkan Google Mirror API untuk project baru Anda.
5. Di bagian APIs & amp; auth, klik Credentials, lalu klik Create New Client ID. Centang kotak berlabel Akun layanan untuk membuat client ID OAuth 2.0 baru untuk project.
6. Jendela pop-up akan menginformasikan bahwa kunci pribadi sedang didownload ke komputer Anda dan memberikan sandi untuk kunci pribadi tersebut. Setelah jendela ini ditutup, Anda tidak akan dapat mendownload kunci pribadi ini atau melihat sandinya lagi. Jika keduanya hilang, Anda harus membuat yang baru.
7. Catat alamat email akun layanan, yang akan Anda perlukan nanti untuk melakukan panggilan API.

Menyediakan metadata tentang Glassware Anda

Jika sudah siap mengirimkan Glassware, Anda perlu memberikan informasi berikut. Hal ini memungkinkan kami menyiapkan Glassware untuk diautentikasi dengan benar saat Anda menerapkannya.

• URL autentikasi Anda, yang menjadi tujuan pengguna saat mengaktifkan Glassware di MyGlass.
• Jenis akun (string yang akan Anda gunakan saat memanggil Android AccountManager API di perangkat Glass)
• Nama paket aplikasi Anda dari AndroidManifest.xml
• ID project Google API numerik dari project yang Anda buat di atas
• APK yang akan diupload di MyGlass. Untuk pengujian, Anda hanya perlu menyediakan APK ini sekali untuk menangani download awal saat Glassware diaktifkan dari MyGlass; setelah itu, Anda dapat melakukan iterasi dan debug secara lokal dengan menimpa APK di perangkat. Perhatikan bahwa APK ini harus memenuhi kriteria berikut:
  • Gambar harus disesuaikan dengan zip.
  • Anda tidak boleh mengubah nama paket atau kunci penandatanganan pribadi setelah ini (pengelola paket Android tidak mengizinkan upgrade jika salah satu dari perubahan ini).
  • Ukuran file harus lebih kecil dari 50 megabyte.
  • Versi ini harus dikompilasi menggunakan GDK versi terbaru.

Menerapkan alur autentikasi

Diagram berikut menunjukkan alur autentikasi dasar untuk GDK Glassware:

Untuk menerapkan alur autentikasi:

1. Saat mengaktifkan Glassware di MyGlass, pengguna akan dialihkan ke URL autentikasi Anda. Permintaan ini menyertakan parameter kueri bernama userToken yang perlu Anda gunakan nanti.

   Peringatan: Jangan simpan token pengguna ini. Hanya digunakan oleh endpoint autentikasi Google untuk memetakan permintaan kembali ke pengguna asal selama sesi tersebut saja dan tidak berisi informasi apa pun yang dapat digunakan untuk mengidentifikasi pengguna secara persisten. Token tidak dijamin sama jika pengguna mengautentikasi dengan Glassware yang sama beberapa kali, atau jika pengguna melakukan autentikasi dengan Glassware yang berbeda dari developer yang sama.

2. Pengguna memasukkan kredensial di halaman autentikasi.

3. Server Anda memvalidasi kredensial pengguna. Jika kredensial valid, lakukan panggilan Mirror API ke metode mirror.accounts.insert. Metode ini mengharuskan Anda menentukan cakupan https://www.googleapis.com/auth/glass.thirdpartyauth saat mem-build objek layanan Cermin. Contoh panggilan API ini menggunakan HTTP mentah atau Java ditampilkan dalam contoh pembuatan akun.

   Parameter dan isi permintaan yang Anda berikan di bawah mewakili informasi yang sama dengan yang akan Anda berikan ke AccountManager Android jika Anda membuat akun langsung di perangkat.

   Nama properti	Nilai	Deskripsi
   features[]	daftar string	Daftar fitur (lihat AccountManager.hasFeatures).
   password	string	Sandi akun (lihat AccountManager.getPassword). Sebaiknya Anda tidak menyimpan sandi pengguna yang sebenarnya di kolom ini, tetapi gunakan sandi tersebut untuk menyimpan data pribadi yang berumur panjang seperti token refresh.
   userData[]	daftar objek	Satu atau beberapa pasangan data pengguna yang terkait dengan akun (lihat AccountManager.getUserData).
   userData[].key	string	Kunci yang terkait dengan key-value pair data pengguna tertentu.
   userData[].value	string	Nilai yang terkait dengan pasangan nilai kunci data pengguna tertentu.
   authTokens[]	daftar objek	Satu atau beberapa token autentikasi yang terkait dengan akun (lihat AccountManager.getAuthToken).
   authTokens[].type	string	Jenis token autentikasi.
   authTokens[].authToken	string	Token autentikasi.

4. Setelah menerima permintaan mirror.account.insert, Mirror API mengirim akun ke perangkat Glass pengguna, tempat Anda kini dapat mengaksesnya menggunakan class AccountManager.

Alur autentikasi yang direkomendasikan

Ikuti panduan berikut untuk menerapkan alur autentikasi yang mudah digunakan:

• Optimalkan alur Anda untuk perangkat seluler.
• Jika alur Anda memiliki cakupan dan pengguna membatalkannya, miliki pesan error yang dirancang dengan baik.
• Pastikan cakupan yang Anda minta benar-benar digunakan di Glassware Anda.
• Jika akun pengguna dapat terhubung, pastikan Anda menghubungkannya.
• Jika memungkinkan, data pengguna harus dicadangkan ke cloud.

Catatan: Instal Glassware Anda setidaknya sekali melalui MyGlass untuk memastikan alur autentikasi Anda berhasil. Selama hal ini dilakukan sekali, Anda dapat menginstal melalui sideload untuk tujuan pengujian.

Untuk mempertahankan konsistensi dalam autentikasi Glassware, gunakan salah satu alur autentikasi berikut:

Cermin atau campuran tanpa akun

1. Setelah mengaktifkan di MyGlass, URL autentikasi Anda akan terbuka di pop-up.
2. Tindakan ini langsung mengarahkan pengguna ke cakupan yang akan disetujui.
3. Setelah pengguna menerima atau membatalkan cakupan, tutup pop-up.

Cerminkan dengan akun

1. Setelah mengaktifkan di MyGlass, URL autentikasi Anda akan terbuka di pop-up.
   • Jika pengguna sudah login ke layanan Anda, arahkan pengguna langsung ke cakupan.
   • Jika pengguna tidak login, tampilkan kolom login, izinkan mereka login ke layanan Anda, lalu kirim ke cakupan.
   • Jika pengguna tidak memiliki akun, berikan link untuk membuat akun. Pengguna harus memiliki cara untuk membuat akun sebagai bagian dari proses alur penginstalan.
2. Pengguna menerima cakupan.
   • Jika Glassware Anda memiliki setelan yang dapat dikonfigurasi, arahkan pengguna ke halaman setelan dengan default yang wajar dipilih.
   • Jika Glassware Anda tidak memiliki setelan yang dapat dikonfigurasi, arahkan pengguna ke halaman konfirmasi. Tutup pop-up jika tidak memerlukan konfigurasi tambahan.

Sistem kerja hybrid dengan akun

1. Setelah mengaktifkan di MyGlass, URL autentikasi Anda akan terbuka di pop-up.
   • Jika pengguna sudah login ke layanan Anda, arahkan pengguna langsung ke cakupan.
   • Jika pengguna tidak login, tampilkan kolom login, izinkan mereka login, lalu kirim ke cakupan.
   • Jika pengguna tidak memiliki akun, berikan link untuk membuat akun.
2. Pengguna menerima cakupan.
3. Kirim permintaan ke Mirror API untuk menyisipkan Akun GDK.
   • Arahkan pengguna ke halaman setelan dengan pilihan default yang wajar.
   • Kirim halaman konfirmasi kepada pengguna. Tutup pop-up jika tidak perlu konfigurasi tambahan.

Duplikasi atau campuran dengan akun dan cakupan kustom

1. Setelah mengaktifkan di MyGlass, URL autentikasi Anda akan terbuka di pop-up.
   • Jika pengguna sudah login ke layanan Anda, arahkan pengguna ke cakupan internal Anda
   • Jika pengguna tidak login, tampilkan kolom login, izinkan mereka login, lalu kirim ke cakupan internal Anda
   • Jika pengguna tidak memiliki akun, berikan link untuk membuat akun.
2. Saat pengguna menyetujui cakupan kustom Anda, arahkan pengguna ke cakupan Google.
3. Kirim permintaan ke Mirror API untuk menyisipkan Akun GDK.
   • Arahkan pengguna ke halaman setelan dengan pilihan default yang wajar.
   • Kirim halaman konfirmasi kepada pengguna. Tutup pop-up jika tidak perlu konfigurasi tambahan.

Mirror atau hybrid dengan aplikasi Android/iPhone

1. Setelah mengaktifkan di MyGlass, URL autentikasi Anda akan terbuka di pop-up.
2. Tindakan ini langsung mengarahkan pengguna ke cakupan yang akan disetujui.
3. Setelah pengguna menerima cakupan:
   • Jika pengguna memiliki aplikasi pendamping dan diautentikasi, tutup jendela pop-up.
   • Jika tidak, arahkan pengguna ke interstisial yang mengarahkannya untuk mendownload aplikasi dari Google Play Store atau iOS Store
4. Setelah menginstal aplikasi dan mengautentikasi, tutup jendela pop-up

GDK dan tanpa akun

Mengaktifkan Glassware di MyGlass adalah hal yang diperlukan untuk alur ini.

GDK dengan akun

1. Setelah mengaktifkan di MyGlass, URL autentikasi Anda akan terbuka di pop-up.
   • Jika pengguna sudah login ke layanan, arahkan pengguna ke layar konfirmasi.
   • Jika pengguna tidak login, tampilkan kolom login, izinkan mereka login, lalu kirim ke layar konfirmasi.
   • Jika pengguna tidak memiliki akun, berikan link untuk membuat akun.
2. Pengguna menerima cakupan.
3. Kirim permintaan ke Mirror API untuk menyisipkan Akun GDK.
4. Tampilkan layar konfirmasi, dan tutup layar setelah menampilkannya untuk waktu singkat.

Contoh pembuatan akun

Gunakan library klien untuk Mirror API jika memungkinkan. Hal ini membuat panggilan mirror.accounts.insert untuk membuat akun menjadi lebih mudah.

Contoh HTTP mentah

Contoh di bawah hanya menampilkan URL permintaan dan contoh isi JSON yang diharapkan. Membuat permintaan HTTP mentah atas nama akun layanan jauh lebih rumit (lihat Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server untuk mengetahui detail lengkapnya), jadi sebaiknya gunakan salah satu library klien Google API kami jika memungkinkan.

Metode permintaan dan URL:

POST https://www.googleapis.com/mirror/v1/accounts/{userToken}/com.example.myapp/username%40email.com

Isi permintaan:

{
    "features": ["a", "b", "c"],
    "userData": [
        { "key": "realName", "value": "Rusty Shackleford" },
        { "key": "foo", "value": "bar" }
    ],
    "authTokens": [
        { "type": "your_token_type", "authToken": "zT419Ma3X2pBr0L..." }
    ]
}

Ganti {userToken} di URL permintaan dengan token yang diteruskan ke URL autentikasi Anda pada langkah 1 dalam Mengimplementasikan alur autentikasi.

Contoh Java

Contoh ini menunjukkan cara menggunakan library klien Java untuk memanggil mirror.accounts.insert

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.mirror.Mirror;
import com.google.api.services.mirror.model.Account;
import com.google.api.services.mirror.model.AuthToken;
import com.google.common.collect.Lists;
...

/** Email of the Service Account */
private static final String SERVICE_ACCOUNT_EMAIL =
    "<some-id>@developer.gserviceaccount.com";

/** Path to the Service Account's Private Key file */
private static final String SERVICE_ACCOUNT_PKCS12_FILE_PATH =
    "/path/to/<public_key_fingerprint>-privatekey.p12";

/** The account type, usually based on your company or app's package. */
private static final String ACCOUNT_TYPE = "com.example.myapp";

/** The Mirror API scopes needed to access the API. */
private static final String MIRROR_ACCOUNT_SCOPES =
    "https://www.googleapis.com/auth/glass.thirdpartyauth";

/**
 * Build and returns a Mirror service object authorized with the service accounts.
 *
 * @return Mirror service object that is ready to make requests.
 */
public static Mirror getMirrorService() throws GeneralSecurityException,
    IOException, URISyntaxException {
  HttpTransport httpTransport = new NetHttpTransport();
  JacksonFactory jsonFactory = new JacksonFactory();
  GoogleCredential credential = new GoogleCredential.Builder()
      .setTransport(httpTransport)
      .setJsonFactory(jsonFactory)
      .setServiceAccountId(SERVICE_ACCOUNT_EMAIL)
      .setServiceAccountScopes(MIRROR_ACCOUNT_SCOPES)
      .setServiceAccountPrivateKeyFromP12File(
          new java.io.File(SERVICE_ACCOUNT_PKCS12_FILE_PATH))
      .build();
  Mirror service = new Mirror.Builder(httpTransport, jsonFactory, null)
      .setHttpRequestInitializer(credential).build();
  return service;
}

/**
 * Creates an account and causes it to be synced up with the user's Glass.
 * This example only supports one auth token; modify it if you need to add
 * more than one, or to add features, user data, or the password field.
 *
 * @param mirror the service returned by getMirrorService()
 * @param userToken the user token sent to your auth callback URL
 * @param accountName the account name for this particular user
 * @param authTokenType the type of the auth token (chosen by you)
 * @param authToken the auth token
 */
public static void createAccount(Mirror mirror, String userToken, String accountName,
    String authTokenType, String authToken) {
  try {
    Account account = new Account();
    List<AuthToken> authTokens = Lists.newArrayList(
        new AuthToken().setType(authTokenType).setAuthToken(authToken));
    account.setAuthTokens(authTokens);
    mirror.accounts().insert(
        userToken, ACCOUNT_TYPE, accountName, account).execute();
  } catch (IOException e) {
    e.printStackTrace();
  }
}

Mengambil Akun di Glass

Mengambil dan menggunakan objek Account di Glass mirip dengan menggunakan AccountManager Android standar.

1. Deklarasikan izin manifes berikut dalam file AndroidManifest.xml Anda:

   <uses-permission android:name="android.permission.GET_ACCOUNTS" />
   <uses-permission android:name="android.permission.USE_CREDENTIALS" />
   

2. Ambil akun Glassware:

   AccountManager accountManager = AccountManager.get(mContext);
   // Use your Glassware's account type.
   Account[] accounts = accountManager.getAccountsByType("com.example");
   
   // Pick an account from the list of returned accounts.
   

3. Ambil token autentikasi dari Account:

   // Your auth token type.
   final String AUTH_TOKEN_TYPE = "oauth2:https://www.example.com/auth/login";
   
   accountManager.getAuthToken(account, AUTH_TOKEN_TYPE, null, activity, new AccountManagerCallback<Bundle>() {
       public void run(AccountManagerFuture<Bundle> future) {
           try {
               String token = future.getResult().getString(AccountManager.KEY_AUTHTOKEN);
               // Use the token.
           } catch (Exception e) {
               // Handle exception.
           }
       }
   }, null);