Autentikasi untuk GDK Glassware

Jika Glassware GDK Anda perlu mengautentikasi pengguna terhadap layanan web, GDK menyediakan API yang memungkinkan pengguna memasukkan kredensial mereka saat menginstal Glassware Anda.

Dengan menggunakan API ini, Anda memberikan pengalaman pengguna yang konsisten bagi pengguna Glass dan menghindari overhead dalam menerapkan 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

Jika autentikasi disiapkan dengan benar, backend aplikasi web Anda akan menggunakan Mirror API untuk mengirimkan informasi akun pengguna ke Glass setelah mereka melakukan autentikasi 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 Anda secara terpisah untuk mengirim kredensial mereka ke Glass dan tidak akan ditampilkan 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 dibuat, catat Nomor Project, yang akan Anda perlukan nanti.
4. Di bagian API & auth, klik API dan aktifkan Google Mirror API untuk project baru Anda.
5. Di bagian API & auth, klik Credentials, lalu klik Create New Client ID. Centang kotak berlabel Service account untuk membuat client ID OAuth 2.0 baru untuk project.
6. Jendela pop-up akan memberi tahu Anda bahwa kunci pribadi sedang didownload ke komputer dan memberikan sandi untuk kunci pribadi tersebut. Setelah menutup jendela ini, Anda tidak akan dapat mendownload kunci pribadi ini atau melihat sandi lagi. Jika hilang, Anda harus membuat yang baru.
7. Catat alamat email akun layanan, yang akan Anda perlukan nanti untuk melakukan panggilan API.

Memberikan metadata tentang Glassware Anda

Jika sudah siap mengirimkan Kaca, Anda harus memberikan informasi berikut. Hal ini memungkinkan kami menyiapkan Glassware Anda agar diotentikasi dengan benar saat Anda menerapkannya.

• URL autentikasi Anda, yang menjadi tujuan pengalihan pengguna saat mereka mengaktifkan Glassware Anda 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 men-debug secara lokal dengan menimpa APK di perangkat. Perhatikan bahwa APK ini harus memenuhi kriteria berikut:
  • File harus di-zip.
  • Anda tidak boleh melakukan perubahan apa pun pada nama paket atau kunci penandatanganan pribadi setelah ini (pengelola paket Android tidak mengizinkan upgrade jika salah satu perubahan ini terjadi).
  • Ukurannya harus lebih kecil dari 50 megabyte.
  • Aplikasi ini harus dikompilasi menggunakan GDK versi terbaru.

Mengimplementasikan alur autentikasi

Diagram berikut menunjukkan alur autentikasi dasar untuk GDK Glassware:

Untuk menerapkan alur autentikasi:

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

   Peringatan: Jangan simpan token pengguna ini. Cookie 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 terus-menerus. Token tidak dijamin akan sama jika pengguna mengautentikasi dengan Glassware yang sama beberapa kali atau jika pengguna mengautentikasi dengan Glassware yang berbeda dari developer yang sama.

2. Pengguna memasukkan kredensialnya di halaman autentikasi Anda.

3. Server Anda memvalidasi kredensial pengguna. Jika kredensial valid, lakukan panggilan Mirror API ke metode mirror.accounts.insert. Metode ini memerlukan Anda untuk menentukan cakupan https://www.googleapis.com/auth/glass.thirdpartyauth saat mem-build objek layanan Mirror. Contoh pembuatan panggilan API ini menggunakan HTTP mentah atau Java ditampilkan di 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 sebenarnya pengguna di kolom ini, tetapi gunakan 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 pasangan nilai kunci 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 akan mendorong 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 untuk perangkat seluler.
• Jika alur Anda memiliki cakupan dan pengguna membatalkannya, buat pesan error yang dirancang dengan baik.
• Pastikan cakupan yang Anda minta benar-benar digunakan dalam Glassware Anda.
• Jika akun pengguna dapat dihubungkan, pastikan Anda menghubungkannya.
• Jika memungkinkan, data pengguna harus dicadangkan ke cloud.

Catatan: Instal Glassware setidaknya sekali melalui MyGlass untuk memastikan bahwa alur autentikasi Anda berhasil. Selama Anda telah melakukannya sekali, Anda dapat menginstal melalui sideload untuk tujuan pengujian.

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

Mirror atau hybrid tanpa akun

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

Mencerminkan dengan akun

1. Setelah mengaktifkannya 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, tunjukkan kolom login, izinkan mereka login ke layanan Anda, lalu kirimkan 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 menyetujui cakupan.
   • Jika Glassware Anda memiliki setelan yang dapat dikonfigurasi, arahkan pengguna ke halaman setelan dengan setelan default yang wajar dipilih.
   • Jika Glassware Anda tidak memiliki setelan yang dapat dikonfigurasi, arahkan pengguna ke halaman konfirmasi. Tutup pop-up jika tidak diperlukan konfigurasi tambahan.

Campuran dengan akun

1. Setelah mengaktifkannya 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 kirimkan ke cakupan.
   • Jika pengguna tidak memiliki akun, berikan link untuk membuat akun.
2. Pengguna menyetujui cakupan.
3. Kirim permintaan ke Mirror API untuk menyisipkan Akun GDK.
   • Mengarahkan pengguna ke halaman setelan dengan setelan default yang wajar.
   • Mengirim halaman konfirmasi kepada pengguna. Tutup pop-up jika tidak diperlukan konfigurasi tambahan.

Mirror atau campuran dengan akun dan cakupan kustom

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

Mencerminkan atau campuran dengan aplikasi Android/iPhone

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

GDK dan tidak ada akun

Mengaktifkan/menonaktifkan Glassware di MyGlass adalah satu-satunya yang diperlukan untuk alur ini.

GDK dengan akun

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

Contoh pembuatan akun

Gunakan library klien untuk Mirror API jika memungkinkan. Hal ini memudahkan pemanggilan mirror.accounts.insert untuk membuat akun.

Contoh HTTP mentah

Contoh di bawah ini 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 selengkapnya), jadi sebaiknya gunakan salah satu library klien Google API kami jika memungkinkan untuk mempermudahnya.

Metode dan URL permintaan:

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 Menerapkan 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);