دمج "مدير بيانات الاعتماد" مع ميزة "تسجيل الدخول باستخدام حساب Google"

يوضّح هذا المستند كيفية نقل مربّع الحوار تسجيل الدخول باستخدام حساب Google باستخدام حساب Google من خدمات Google Identity Services (GIS) إلى واجهة برمجة تطبيقات "مدير بيانات الاعتماد" باستخدام مكتبة مساعد Google ID.

تم إعداد تطبيق يستخدم واجهة برمجة تطبيقات "مدير بيانات الاعتماد" لتزويد المستخدم بواجهة مستخدم Android متسقة تسمح للمستخدم بالاختيار من قائمة خيارات تسجيل الدخول المحفوظة، بما في ذلك الحسابات التي تتيح استخدام مفتاح مرور. هذه هي واجهة برمجة تطبيقات Android التي يُنصح بها لدمج أنواع بيانات الاعتماد ومقدّمي البيانات المختلفين. بدءًا من نظام التشغيل Android 14، يمكن للمستخدمين أيضًا الاستفادة من تطبيقات إدارة كلمات المرور التابعة لجهات خارجية باستخدام واجهة برمجة تطبيقات "مدير بيانات الاعتماد".

تعريف التبعيات

في ملف build.gradle الخاص بالوحدة، حدِّد التبعيات باستخدام أحدث إصدار:

dependencies {
  // ... other dependencies

  implementation "androidx.credentials:credentials:<latest version>"
  implementation "androidx.credentials:credentials-play-services-auth:<latest version>"
  implementation "com.google.android.libraries.identity.googleid:googleid:<latest version>"
}

اتّبِع التعليمات لإعداد مشروع وحدة تحكم واجهة Google API. استبدل الإرشادات المتعلقة بتضمين التبعيات بالتعليمات المذكورة أعلاه.

إنشاء نسخة افتراضية لطلب تسجيل الدخول إلى حساب Google

لبدء عملية التنفيذ، أنشئ مثيلاً لطلب تسجيل الدخول إلى Google. استخدِم GetGoogleIdOption لاسترداد الرمز المميّز لمعرّف Google الخاص بالمستخدم.

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(SERVER_CLIENT_ID)
  .build()

GetGoogleIdOption googleIdOption = new GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(SERVER_CLIENT_ID)
  .build();

عليك أولاً طلب البيانات من واجهة برمجة التطبيقات مع ضبط معلَمة setFilterByAuthorizedAccounts على true. في حال عدم توفّر بيانات اعتماد، يمكنك طلب البيانات من واجهة برمجة التطبيقات مرة أخرى وضبط setFilterByAuthorizedAccounts على false.

إذا أردت تسجيل دخول المستخدمين تلقائيًا متى أمكن، فعِّل الميزة باستخدام setAutoSelectEnabled في طلب GetGoogleIdOption. يمكن تسجيل الدخول تلقائيًا عند استيفاء المعايير التالية:

• لدى المستخدم بيانات اعتماد واحدة محفوظة للتطبيق، وهي كلمة مرور محفوظة واحدة أو حساب Google محفوظ واحد.
• لم يوقف المستخدم تسجيل الدخول التلقائي في إعدادات حساب Google.

لتحسين أمان تسجيل الدخول وتجنُّب هجمات إعادة التشغيل، استخدِم setNonce لتضمين رقم هاتف في كل طلب. مزيد من المعلومات عن إنشاء رقم خاص

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(SERVER_CLIENT_ID)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

GetGoogleIdOption googleIdOption = new GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(SERVER_CLIENT_ID)
  .setNonce(<nonce string to use when generating a Google ID token>);
  .build();

تسجيل الدخول باستخدام حساب Google

في ما يلي خطوات إعداد عملية "تسجيل الدخول باستخدام حساب Google":

1. أنشئ مثيل GetCredentialRequest وأضِف googleIdOption الذي تم إنشاؤه أعلاه لاسترداد بيانات الاعتماد.
2. مرِّر هذا الطلب إلى مكالمة getCredential() (Kotlin) أو getCredentialAsync() (Java) لاسترداد بيانات الاعتماد المتاحة للمستخدم.
3. بعد نجاح واجهة برمجة التطبيقات، يمكنك استخراج CustomCredential التي تؤدي إلى نتيجة بيانات GoogleIdTokenCredential.
4. يجب أن يكون نوع CustomCredential مساويًا لقيمة GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL. حوِّل الكائن إلى GoogleIdTokenCredential باستخدام طريقة GoogleIdTokenCredential.createFrom.
5. إذا نجحت عملية التحويل، استخرِج رقم تعريف GoogleIdTokenCredential، وتحقّق منه، ثم صادق بيانات الاعتماد على خادمك.
6. إذا تعذّر إتمام عملية التحويل باستخدام GoogleIdTokenParsingException، قد تحتاج إلى تعديل إصدار تسجيل الدخول باستخدام حساب Google.
7. رصد أي أنواع بيانات اعتماد مُخصَّصة غير معروفة

val request: GetCredentialRequest = Builder()
  .addGetCredentialOption(googleIdOption)
  .build()

coroutineScope.launch {
  try {
    val result = credentialManager.getCredential(
      request = request,
      context = activityContext,
    )
    handleSignIn(result)
  } catch (e: GetCredentialException) {
    handleFailure(e)
  }
}

fun handleSignIn(result: GetCredentialResponse) {
  // Handle the successfully returned credential.
  val credential = result.credential

  when (credential) {
    is PublicKeyCredential -> {
      // Share responseJson such as a GetCredentialResponse on your server to
      // validate and authenticate
      responseJson = credential.authenticationResponseJson
    }

    is PasswordCredential -> {
      // Send ID and password to your server to validate and authenticate.
      val username = credential.id
      val password = credential.password
    }

    is CustomCredential -> {
      if (credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL) {
        try {
          // Use googleIdTokenCredential and extract id to validate and
          // authenticate on your server.
          val googleIdTokenCredential = GoogleIdTokenCredential
            .createFrom(credential.data)
        } catch (e: GoogleIdTokenParsingException) {
          Log.e(TAG, "Received an invalid google id token response", e)
        }
      } else {
        // Catch any unrecognized custom credential type here.
        Log.e(TAG, "Unexpected type of credential")
      }
    }

    else -> {
      // Catch any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential")
    }
  }
}

GetCredentialRequest request = new GetCredentialRequest.Builder()
  .addGetCredentialOption(googleIdOption)
  .build();

// Launch sign in flow and do getCredential Request to retrieve the credentials
credentialManager.getCredentialAsync(
  requireActivity(),
  request,
  cancellationSignal,
  <executor>,
  new CredentialManagerCallback<GetCredentialResponse, GetCredentialException>() {
    @Override
    public void onResult(GetCredentialResponse result) {
      handleSignIn(result);
    }

    @Override
    public void onError(GetCredentialException e) {
      handleFailure(e);
    }
  }
);

public void handleSignIn(GetCredentialResponse result) {
  // Handle the successfully returned credential.
  Credential credential = result.getCredential();

  if (credential instanceof PublicKeyCredential) {
    String responseJson = ((PublicKeyCredential) credential).getAuthenticationResponseJson();
    // Share responseJson i.e. a GetCredentialResponse on your server to validate and authenticate
  } else if (credential instanceof PasswordCredential) {
    String username = ((PasswordCredential) credential).getId();
    String password = ((PasswordCredential) credential).getPassword();
    // Use id and password to send to your server to validate and authenticate
  } else if (credential instanceof CustomCredential) {
    if (GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL.equals(credential.getType())) {
      try {
        // Use googleIdTokenCredential and extract id to validate and
        // authenticate on your server
        GoogleIdTokenCredential googleIdTokenCredential = GoogleIdTokenCredential.createFrom(((CustomCredential) credential).getData());
      } catch (GoogleIdTokenParsingException e) {
        Log.e(TAG, "Received an invalid Google ID token response", e);
      }
    } else {
      // Catch any unrecognized custom credential type here.
      Log.e(TAG, "Unexpected type of credential");
    }
  } else {
    // Catch any unrecognized credential type here.
    Log.e(TAG, "Unexpected type of credential");
  }
}

زر "تسجيل الدخول باستخدام حساب Google"

يتوفّر زر "تسجيل الدخول باستخدام حساب Google" في "مدير بيانات الاعتماد" الذي يتضمّن أحدث مكتبة مساعد لـ Google ID. لبدء عملية تسجيل الدخول باستخدام زر "تسجيل الدخول باستخدام حساب Google"، استخدِم GetSignInWithGoogleOption بدلاً من GetGoogleIdOption، وتعامل مع الدالة التي تم إرجاعها GoogleIdTokenCredential بالطريقة نفسها التي كنت تتّبعها في السابق.

الاشتراك من خلال Google

إذا لم يتم عرض أي نتائج بعد ضبط setFilterByAuthorizedAccounts على true أثناء إنشاء مثيل GetGoogleIdOption والتمرير إلى GetCredentialsRequest، يعني ذلك أنّه ما من حسابات معتمَدة لتسجيل الدخول. في هذه المرحلة، يجب إعداد setFilterByAuthorizedAccounts(false) والاتصال بالاشتراك باستخدام Google.

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(false)
  .setServerClientId(SERVER_CLIENT_ID)
  .build()

GetGoogleIdOption googleIdOption = new GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(false)
  .setServerClientId(SERVER_CLIENT_ID)
  .build();

بعد إنشاء مثيل لطلب الاشتراك في Google، ابدأ مسار المصادقة بطريقة مشابهة كما هو مذكور في قسم تسجيل الدخول باستخدام حساب Google.

التعامل مع تسجيل الخروج

عندما يسجّل المستخدم خروجه من تطبيقك، يمكنك استدعاء طريقة واجهة برمجة التطبيقات clearCredentialState() لمحو حالة بيانات اعتماد المستخدم الحالية وإعادة ضبط الحالة الداخلية لتسجيل الدخول.