مصادقة GDK Glassware

إذا كانت GDK Glassware تحتاج إلى مصادقة المستخدمين مقابل خدمة ويب، فإن GDK توفر واجهة برمجة تطبيقات تتيح للمستخدم إمكانية إدخال بيانات الاعتماد عند تثبيت Glassware.

باستخدام واجهة برمجة التطبيقات هذه، فإنك تقدم تجربة مستخدم متسقة لمستخدمي Glass وتجنب النفقات العامة لتطبيق مخططات المصادقة المخصصة.

إنشاء حساب خدمة Google API

عند إعداد المصادقة بشكل صحيح، تستخدم الواجهة الخلفية لتطبيق الويب واجهة برمجة التطبيقات Mirror API لإرسال معلومات حسابات المستخدمين إلى Glass بعد إجراء مصادقة مع خدمتك.

للوصول إلى واجهة برمجة التطبيقات هذه، يمكنك إنشاء مشروع Google API ثم إنشاء معرِّف عميل "لحساب خدمة" (وليس "تطبيق ويب"). وباستخدام حساب الخدمة، لا يحتاج المستخدمون إلى منح إذن التطبيق بشكل منفصل لإرسال بيانات الاعتماد إلى Glass ولن يتم تقديم كل من صفحة أذونات OAuth وصفحة المصادقة التابعة لك مرة أخرى.

لإنشاء هذا الحساب:

  1. انتقل إلى Google Developers Console.
  2. انقر على الزر Create Project (إنشاء مشروع) وأدخِل المعلومات المطلوبة.
  3. بعد إنشاء مشروعك، دوِّن رقم المشروع، والذي ستحتاج إليه لاحقًا.
  4. ضمن واجهات برمجة التطبيقات والمصادقة، انقر على واجهات برمجة التطبيقات ومكّن واجهة برمجة تطبيقات Google Mirror لمشروعك الجديد.
  5. ضمن واجهات برمجة التطبيقات والمصادقة، انقر على بيانات الاعتماد، ثم انقر على إنشاء معرِّف عميل جديد. ضع علامة في المربّع حساب الخدمة لإنشاء معرِّف عميل OAuth 2.0 جديد للمشروع.
  6. ستخبرك النافذة المنبثقة أنه يتم تنزيل المفتاح الخاص على جهاز الكمبيوتر وتملك كلمة المرور لهذا المفتاح الخاص. بعد إغلاق هذه النافذة، لن تتمكن من تنزيل هذا المفتاح الخاص أو رؤية كلمة المرور مرة أخرى. وإذا فُقدت في أي وقت، يجب عليك إنشاء رمز جديد.
  7. دوّن عنوان البريد الإلكتروني لحساب الخدمة، والذي ستحتاج إليه لاحقًا لإجراء طلب بيانات من واجهة برمجة التطبيقات.

تقديم بيانات وصفية حول Glassware

عندما تكون على استعداد لإرسال Glassware، سيلزمك تقديم المعلومات التالية. ويتيح لنا هذا إعداد Glassware لتتم مصادقتها بشكل صحيح عند تنفيذها.

  • عنوان URL للمصادقة الذي تتم إعادة توجيه المستخدمين إليه عند تشغيلهم لـ Glassware في MyGlass.
  • نوع الحساب (السلسلة التي ستستخدمها عند طلب واجهات برمجة تطبيقات AccountManager من Android على جهاز Glass)
  • اسم الحزمة لتطبيقك من AndroidManifest.xml
  • رقم تعريف مشروع Google API الرقمي للمشروع الذي أنشأته أعلاه
  • APK للتحميل على MyGlass. ولاختبار هذا الأمر، لن يلزمك سوى توفير ملف APK هذا مرة واحدة للتعامل مع التنزيل الأولي عند تشغيل Glassware من MyGlass. وبعد ذلك، يمكنك تكراره وتصحيح أخطائه محليًا عن طريق استبدال ملف APK على جهازك. تجدر الإشارة إلى أن حِزمة APK هذه يجب أن تستوفي المعايير التالية:
    • يجب أن يكون محاذيًا بتنسيق zip.
    • يجب عدم إجراء أي تغييرات على اسم الحزمة أو مفتاح التوقيع الخاص بعد ذلك (لا يسمح مدير حزم Android بالترقيات في حال تطبيق أي من هذه التغييرات).
    • يجب أن يكون حجمه أقل من 50 ميغابايت.
    • ويجب جمعها باستخدام أحدث إصدار من GDK.

تنفيذ عملية المصادقة

يوضح الشكل التوضيحي التالي خطوات المصادقة الأساسية لGDK Glassware:

لتنفيذ تدفق المصادقة:

  1. عند تشغيل المستخدمين لـ Glassware في MyGlass، تتم إعادة توجيههم إلى عنوان URL للمصادقة. وتتضمّن هذه الطلبات معلّمة طلب بحث باسم userToken تحتاج إلى استخدامها لاحقًا.

  2. يُدخِل المستخدم بيانات اعتماده على صفحة المصادقة.

  3. يتحقق الخادم من بيانات اعتماد المستخدم. إذا كانت بيانات الاعتماد صالحة، يمكنك إجراء طلب بيانات من Mirror API باستخدام الطريقة mirror.accounts.insert. تتطلب هذه الطريقة تحديد نطاق https://www.googleapis.com/auth/glass.thirdpartyauth عند إنشاء كائن خدمة المرآة. يتم عرض أمثلة لإجراء طلب بيانات من واجهة برمجة التطبيقات باستخدام HTTP أو جافا غير منسقة في أمثلة على إنشاء الحساب.

    تمثل المعلمات ونص الطلب الذي تقدمه أدناه المعلومات نفسها التي ستقدمها إلى AccountManager في Android إذا كنت تنشئ الحساب مباشرة على الجهاز.

    اسم الموقع القيمة الوصف
    features[] قائمة السلاسل قائمة بالميزات (راجِع AccountManager.hasFeatures).
    password سلسلة كلمة مرور الحساب (راجِع AccountManager.getPassword). ننصحك بعدم تخزين كلمة المرور الفعلية للمستخدم في هذا الحقل، بل استخدامها لتخزين البيانات الخاصة التي تم إنشاؤها منذ فترة طويلة، مثل الرمز المميز لإعادة التحميل.
    userData[] قائمة الكائنات زوج واحد أو أكثر من بيانات المستخدمين المرتبطة بالحساب (راجِع AccountManager.getUserData).
    userData[].key سلسلة هو المفتاح المرتبط بزوج معيّن من مفتاح قيمة بيانات المستخدم.
    userData[].value سلسلة القيمة المرتبطة بزوج معيّن من مفتاح مفتاح بيانات المستخدم.
    authTokens[] قائمة الكائنات رمز مصادقة مميز واحد أو أكثر مرتبط بالحساب (راجِع AccountManager.getAuthToken).
    authTokens[].type سلسلة نوع الرمز المميز للمصادقة.
    authTokens[].authToken سلسلة الرمز المميز للمصادقة.

  4. عند تلقّي طلب mirror.account.insert، ترسل واجهة برمجة تطبيقات Mirror الحساب إلى جهاز Glass للمستخدم، حيث يمكنك الآن الوصول إليه باستخدام فئة AccountManager.

اتبع هذه الإرشادات لتنفيذ تدفق مصادقة سهل الاستخدام:

  • تحسين التدفق لأجهزة الجوّال.
  • إذا كان تدفقك يتضمن نطاقًا وألغى المستخدم هذه الخطوات، فلديك رسالة خطأ مصممة جيدًا.
  • تأكَّد من أنّ النطاقات التي تطلبها مستخدَمة فعليًا في Glassware.
  • إذا كان حساب المستخدم يمكن ربطه، فتأكد من ربطه.
  • حيثما كان ذلك ممكنًا، ينبغي الاحتفاظ بنسخة احتياطية من بيانات المستخدم في السحاب.

للحفاظ على الاتساق في مصادقة Glassware، استخدم أحد مسارات المصادقة التالية:

نسخة مطابقة أو مختلطة بدون حساب

  1. بعد التبديل إلى MyGlass، يتم فتح عنوان URL للمصادقة في نافذة منبثقة.
  2. يؤدي ذلك إلى إرسال المستخدم مباشرةً إلى النطاقات لقبولها.
  3. بعد قبول المستخدم للنطاقات أو إلغائها، أغلِق النافذة المنبثقة.

النسخ المطابق باستخدام حساب

  1. بعد التبديل إلى MyGlass، يتم فتح عنوان URL للمصادقة في نافذة منبثقة.
    • إذا كان المستخدم قد سجّل الدخول من قبل إلى خدمتك، فأرسل المستخدم مباشرةً إلى النطاقات.
    • إذا لم يسجّل المستخدم الدخول، يمكنك عرض حقول تسجيل الدخول والسماح له بتسجيل الدخول إلى خدمتك، ثم إرسالها إلى النطاقات.
    • إذا لم يكن لدى المستخدم حساب، يمكنك تقديم رابط لإنشاء حساب. يجب أن يتوفر لدى المستخدمين طريقة لإنشاء حساب كجزء من عملية تدفق التثبيت.
  2. يقبل المستخدم النطاقات.
    • إذا كانت Glassware تتضمن إعدادات قابلة للتهيئة، فأرسل المستخدم إلى صفحة الإعدادات مع تحديد الإعدادات الافتراضية المعقولة.
    • إذا لم تتضمن Glassware أي إعدادات قابلة للتهيئة، فأرسل المستخدم إلى صفحة التأكيد. أغلق النافذة المنبثقة إذا لم تكن هناك حاجة إلى تهيئة إضافية.

هجين باستخدام حساب

  1. بعد التبديل إلى MyGlass، يتم فتح عنوان URL للمصادقة في نافذة منبثقة.
    • إذا كان المستخدم قد سجّل الدخول من قبل إلى خدمتك، فأرسل المستخدم مباشرةً إلى النطاقات.
    • إذا لم يسجّل المستخدم الدخول، يمكنك عرض حقول تسجيل الدخول والسماح له بتسجيل الدخول ثم إرسالها إلى النطاقات.
    • إذا لم يكن لدى المستخدم حساب، يمكنك تقديم رابط لإنشاء حساب.
  2. يقبل المستخدم النطاقات.
  3. أرسل طلبًا إلى Mirror API لإدراج حساب GDK.
    • أرسل المستخدم إلى صفحة الإعدادات مع تحديد الإعدادات الافتراضية المعقولة.
    • أرسِل صفحة التأكيد إلى المستخدم. أغلق النافذة المنبثقة إذا لم تكن هناك تهيئة إضافية مطلوبة.

النسخ المطابق أو المختلط باستخدام حساب ونطاقات مخصصة

  1. بعد التبديل إلى MyGlass، يتم فتح عنوان URL للمصادقة في نافذة منبثقة.
    • إذا كان المستخدم قد سجّل الدخول بالفعل إلى خدمتك، فأرسل المستخدم إلى نطاقاتك الداخلية
    • إذا لم يسجّل المستخدم الدخول، يمكنك عرض حقول تسجيل الدخول والسماح له بتسجيل الدخول ثم إرسالها إلى نطاقاتك الداخلية.
    • إذا لم يكن لدى المستخدم حساب، يمكنك تقديم رابط لإنشاء حساب.
  2. عندما يقبل المستخدم نطاقاتك المخصصة، أرسل المستخدم إلى نطاقات Google.
  3. أرسل طلبًا إلى Mirror API لإدراج حساب GDK.
    • أرسل المستخدم إلى صفحة الإعدادات مع تحديد الإعدادات الافتراضية المعقولة.
    • أرسِل صفحة التأكيد إلى المستخدم. أغلق النافذة المنبثقة إذا لم تكن هناك تهيئة إضافية مطلوبة.

النسخ المطابق أو المختلط باستخدام تطبيق Android/iPhone

  1. بعد التبديل إلى MyGlass، يتم فتح عنوان URL للمصادقة في نافذة منبثقة.
  2. يؤدي ذلك إلى إرسال المستخدم مباشرةً إلى النطاقات لقبولها.
  3. بعد قبول المستخدم للنطاقات:
    • إذا كان المستخدم لديه التطبيق المصاحب وتمت مصادقته، أغلِق النافذة المنبثقة.
    • وإلا، فأرسل المستخدم إلى إعلان بيني يوجّهه إلى تنزيل التطبيق من متجر Google Play أو متجر iOS
  4. بعد تثبيت التطبيق والمصادقة، أغلِق النافذة المنبثقة.

GDK وبدون حساب

كل ما تحتاج إليه للتبديل بين تشغيل الأواني الزجاجية في MyGlass وجعلها في هذه العملية.

GDK باستخدام حساب

  1. بعد التبديل إلى MyGlass، يتم فتح عنوان URL للمصادقة في نافذة منبثقة.
    • إذا كان المستخدم قد سجّل الدخول من قبل إلى خدمتك، فأرسل المستخدم إلى شاشة التأكيد.
    • إذا لم يسجل المستخدم الدخول، فاعرض حقول تسجيل الدخول واسمح له بتسجيل الدخول، ثم أرسله إلى شاشة التأكيد.
    • إذا لم يكن لدى المستخدم حساب، يمكنك تقديم رابط لإنشاء حساب.
  2. يقبل المستخدم النطاقات.
  3. أرسل طلبًا إلى Mirror API لإدراج حساب GDK.
  4. اعرض شاشة التأكيد، ثم أغلق الشاشة بعد عرضها لفترة زمنية قصيرة.

أمثلة على إنشاء الحسابات

استخدم مكتبات العميل لواجهة برمجة تطبيقات المرآة إن أمكن. يؤدي هذا الإجراء إلى تسهيل الاتصال بالرقم mirror.accounts.insert لإنشاء الحساب.

مثال على بروتوكول HTTP غير منسق

لا يعرض المثال أدناه سوى عنوان URL للطلب ومثال على نص JSON الذي يتوقعه. إن إجراء طلبات HTTP أولية نيابة عن حساب خدمة هو أمر أكثر تعقيدًا بكثير (راجع استخدام OAuth 2.0 لتطبيقات خادم إلى خادم للحصول على التفاصيل الكاملة)، لذلك نوصي باستخدام إحدى مكتبات العميل في Google API إذا كان ذلك ممكنًا لجعل ذلك أكثر سهولة.

طريقة الطلب وعنوان URL:

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

نص الطلب:

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

استبدل {userToken} في عنوان URL للطلب بالرمز المميز الذي تم تمريره إلى عنوان URL للمصادقة في الخطوة 1 من تنفيذ عملية المصادقة.

مثال جافا

يوضح هذا المثال كيفية استخدام مكتبة عميل جافا لاستدعاء 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();
  }
}

استرداد الحسابات على Glass

يتشابه استرداد كائنات Account واستخدامها على Glass مع استخدام Android العادي AccountManager.

  1. يُرجى الإقرار بأذونات البيان التالية في ملف AndroidManifest.xml:

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

  2. استرداد حسابات 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. استرداد رمز مصادقة مميز من 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);