مصادقة GDK Glassware

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

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

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

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

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

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

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

تقديم بيانات وصفية عن تطبيقاتك على Glassware

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

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

تنفيذ خطوات المصادقة

يوضِّح الرسم البياني التالي مسار المصادقة الأساسية ل GDK Glassware:

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

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

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

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

    تمثّل المَعلمات ونص الطلب الذي تقدّمه أدناه المعلومات نفسها التي ستقدّمها إلى 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 API الحساب إلى أجهزة 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 وبدون حساب

ما عليك سوى تفعيل تطبيق Glassware في MyGlass لإكمال هذه العملية.

GDK مع حساب

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

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

استخدِم مكتبات العملاء لـ Mirror API متى أمكن. هذا يجعل الاتصال بـ 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 من تنفيذ مسار المصادقة.

مثال على Java

يوضّح هذا المثال كيفية استخدام مكتبة برامج Java لاستدعاء 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 واستخدامها مشابه لاستخدام AccountManager العادي على Android.

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