Autentikasi untuk GDK Glassware

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

Dengan menggunakan API ini, Anda memberikan respons bagi pengguna Glass dan menghindari beban kerja penerapan skema otentikasi kustom.

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

Membuat akun layanan Google API

Jika autentikasi disiapkan dengan benar, backend aplikasi web Anda menggunakan Mirror API untuk mendorong informasi akun ke Glass setelah mereka melakukan otentikasi pada layanan Anda.

Untuk mengakses API ini, buat proyek API Google, lalu buat client ID untuk "akun layanan" (dan bukan "aplikasi web"). Menurut menggunakan akun layanan, pengguna tidak perlu memberikan izin izin aplikasi untuk mengirimkan kredensial mereka ke Glass dan tidak akan halaman izin OAuth dan halaman autentikasi Anda halaman 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 yang Anda perlukan nanti.
4. Di bagian APIs & auth, klik APIs dan aktifkan Google Mirror API untuk proyek baru Anda.
5. Di bagian APIs & auth, klik Credentials, lalu klik Create New Client identitas. Centang kotak berlabel Akun layanan untuk membuat OAuth 2.0 baru client ID untuk project tersebut.
6. Jendela pop-up akan memberi tahu Anda bahwa kunci pribadi sedang didownload ke komputer Anda dan memberikan Anda {i>password<i} untuk kunci pribadi itu. Setelah menutup jendela ini, Anda tidak akan dapat mendownload jendela pribadi ini atau melihat {i>password-<i}nya lagi. Jika hilang, Anda harus membuat satu.
7. Catat alamat email akun layanan, yang akan diperlukan nanti untuk melakukan panggilan API.

Menyediakan metadata tentang Gelas Anda

Jika Anda sudah siap untuk mengirimkan Barang Pecah belah, Anda harus memberikan informasi berikut. Hal ini memungkinkan kami menyiapkan Glassware Anda untuk diotentikasi dengan benar ketika Anda menerapkannya.

• URL autentikasi Anda, yang menjadi tujuan pengalihan pengguna saat mereka akan 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 atas
• APK yang akan diupload di MyGlass. Untuk pengujian, Anda hanya perlu menyediakan APK ini sekali untuk menangani download awal ketika Glassware Anda 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:
  • ID ini harus selaras dengan zip.
  • Anda tidak boleh membuat perubahan apa pun pada nama paket atau penandatanganan pribadi setelah ini (pengelola paket Android tidak mengizinkan upgrade jika perubahan tersebut terjadi).
  • Ukurannya harus lebih kecil dari 50 megabyte.
  • File harus dikompilasi menggunakan GDK versi terbaru.

Mengimplementasikan alur autentikasi

Diagram berikut menunjukkan alur otentikasi dasar untuk Peralatan Pecah Belah GDK:

Untuk mengimplementasikan alur autentikasi:

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

   Peringatan: Jangan simpan token pengguna ini. Ini hanya digunakan oleh endpoint autentikasi untuk memetakan kembali permintaan ke pengguna asal selama sesi itu saja dan tidak berisi informasi apa pun yang dapat digunakan untuk mengidentifikasi pengguna secara terus-menerus. Token tidak dijamin akan hal yang sama jika pengguna mengautentikasi dengan Glassware yang sama beberapa kali atau jika pengguna mengotentikasi dengan Glassware yang berbeda dari developer.

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 mengharuskan Anda menentukan https://www.googleapis.com/auth/glass.thirdpartyauth cakupan saat Anda membuat Duplikasi objek layanan. Contoh pembuatan panggilan API ini menggunakan data mentah HTTP atau Java ditampilkan dalam contoh pembuatan akun.

   Parameter dan isi permintaan yang Anda berikan di bawah mewakili informasi 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). Saran dari kami bahwa Anda tidak menyimpan {i>password<i} pengguna yang sebenarnya di {i>field<i} ini, namun menggunakannya untuk menyimpan data pribadi jangka panjang seperti token refresh.
   userData[]	daftar objek	Satu atau beberapa pasang data pengguna yang terkait dengan akun (lihat AccountManager.getUserData).
   userData[].key	string	Kunci yang terkait dengan nilai kunci data pengguna tertentu berpasangan.
   userData[].value	string	Nilai yang terkait dengan nilai kunci data pengguna tertentu berpasangan.
   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, sehingga Anda kini dapat mengaksesnya menggunakan class AccountManager.

Alur autentikasi yang direkomendasikan

Ikuti panduan ini untuk menerapkan alur autentikasi yang mudah digunakan:

• Optimalkan alur Anda untuk perangkat seluler.
• Jika alur Anda memiliki cakupan dan pengguna membatalkannya, miliki pesan error.
• 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: Pasang Peralatan Gelas Anda minimal sekali melalui MyGlass untuk memastikan bahwa alur otentikasi Anda berhasil. Selama Anda pernah melakukan ini sekali, Anda dapat menginstal melalui sideload untuk tujuan pengujian.

Untuk menjaga konsistensi dalam autentikasi Glassware, gunakan salah satu alur autentikasi:

Duplikasi atau campuran tanpa akun

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

Cerminkan dengan akun

1. Setelah mengaktifkan di MyGlass, URL autentikasi Anda akan terbuka di jendela pop-up.
   • Jika pengguna sudah login ke layanan Anda, kirim pengguna secara langsung ke ruang lingkup.
   • Jika pengguna tidak login, tampilkan kolom login, izinkan mereka untuk login ke layanan Anda, lalu mengirimkannya ke cakupan.
   • Jika pengguna tidak memiliki akun, berikan tautan untuk membuat menggunakan akun layanan. Pengguna harus memiliki cara untuk membuat akun sebagai bagian dari dalam alur penginstalan.
2. Pengguna menyetujui cakupan.
   • Jika Glassware Anda memiliki setelan yang dapat dikonfigurasi, kirim pengguna ke setelan default yang wajar.
   • Jika Glassware Anda tidak memiliki pengaturan yang dapat dikonfigurasi, kirim pengguna ke halaman konfirmasi. Tutup pop-up jika tidak ada konfigurasi tambahan tidak diperlukan.

Campuran dengan akun

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

Cerminkan 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
   • Jika pengguna tidak login, tampilkan kolom login, izinkan mereka untuk login di dalamnya, lalu mengirimkannya ke cakupan internal
   • Jika pengguna tidak memiliki akun, berikan link untuk membuat akun.
2. Saat pengguna menyetujui cakupan kustom Anda, kirim pengguna ke cakupan Google.
3. Kirim permintaan ke Mirror API untuk menyisipkan Akun GDK.
   • Arahkan pengguna ke halaman setelan dengan setelan default yang wajar.
   • Mengirim halaman konfirmasi kepada pengguna. Tutup pop-up jika tidak ada tambahan diperlukan.

Cerminkan atau campuran dengan aplikasi Android/iPhone

1. Setelah mengaktifkan di MyGlass, URL autentikasi Anda akan terbuka di jendela pop-up.
2. Tindakan ini akan langsung mengarahkan pengguna ke cakupan yang akan disetujui.
3. Setelah pengguna menyetujui cakupan:
   • Jika pengguna memiliki aplikasi pendamping dan diautentikasi, tutup jendela pop-up jendela.
   • Jika tidak, arahkan pengguna ke iklan interstisial yang mengarahkan mereka untuk mendownload aplikasi dari Google Play Store atau iOS Store
4. Setelah menginstal aplikasi dan mengautentikasi, 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 mengaktifkan di MyGlass, URL autentikasi Anda akan terbuka di jendela pop-up.
   • Jika pengguna sudah login ke layanan Anda, kirim pengguna ke konfirmasi pertemuan.
   • Jika pengguna tidak login, tampilkan kolom login, izinkan mereka untuk {i>login<i}, lalu arahkan 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, dan tutup layar setelah menampilkannya selama dalam waktu singkat.

Contoh pembuatan akun

Menggunakan 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 layanan menjadi jauh lebih rumit (lihat Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server untuk detail selengkapnya), jadi sebaiknya gunakan salah satu Google API kami library klien agar lebih mudah dilakukan.

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 pada langkah 1 dari Mengimplementasikan alur autentikasi.

Contoh Java

Contoh ini memperlihatkan 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 Account objek pada Glass mirip dengan menggunakan AccountManager.

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