वर्शन की ज़रूरी शर्तें

क्रेडेंशियल मैनेजर की 'क्रेडेंशियल वापस पाएं' सुविधा, Android 9 (एपीआई लेवल 28) और इसके बाद के वर्शन वाले डिवाइसों पर काम करती है. साथ ही, यह Google Play services (GMS) के कोर वर्शन 24220000 या इसके बाद के वर्शन और androidx.credentials लाइब्रेरी के वर्शन 1.5.0 या इसके बाद के वर्शन पर भी काम करती है.

ज़रूरी शर्तें

पासकी के लिए इस्तेमाल किए जाने वाले सर्वर की तरह, रिलाइंग पार्टी सर्वर सेट अप करें. अगर आपके पास पासकी की मदद से पुष्टि करने के लिए पहले से कोई सर्वर सेट अप है, तो पासकी वापस पाने के लिए भी उसी सर्वर-साइड इंटिग्रेशन का इस्तेमाल करें.

डिपेंडेंसी

अपने ऐप्लिकेशन मॉड्यूल की build.gradle फ़ाइल में, ये डिपेंडेंसी जोड़ें:

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha02"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha02"
}

पासकी वापस पाने की सुविधा, androidx.credentials लाइब्रेरी के वर्शन 1.5.0 और इसके बाद के वर्शन में उपलब्ध है. हालांकि, हमारा सुझाव है कि जहां तक हो सके, डिपेंडेंसी के सबसे नए स्टेबल वर्शन का इस्तेमाल करें.

खास जानकारी

  1. पासकी वापस पाने की सुविधा के लिए पासकी बनाना: पासकी वापस पाने की सुविधा के लिए पासकी बनाने के लिए, यह तरीका अपनाएं:
    1. क्रेडेंशियल मैनेजर को इंस्टैंशिएट करना: CredentialManager ऑब्जेक्ट बनाएं.
    2. ऐप्लिकेशन सर्वर से क्रेडेंशियल बनाने के विकल्प पाना: अपने ऐप्लिकेशन सर्वर से, क्लाइंट ऐप्लिकेशन को वह जानकारी भेजें जिसकी ज़रूरत पासकी वापस पाने की सुविधा के लिए पासकी बनाने के लिए होती है.
    3. पासकी वापस पाने की सुविधा के लिए पासकी बनाना: अगर उपयोगकर्ता आपके ऐप्लिकेशन में साइन इन है, तो उसके खाते के लिए पासकी वापस पाने की सुविधा के लिए पासकी बनाएं.
    4. क्रेडेंशियल बनाने के जवाब को मैनेज करना: प्रोसेस करने के लिए, अपने क्लाइंट ऐप्लिकेशन से क्रेडेंशियल को अपने ऐप्लिकेशन सर्वर पर भेजें. साथ ही, किसी भी तरह की गड़बड़ी को मैनेज करें.
  2. **पासकी वापस पाने की सुविधा के लिए पासकी से साइन इन करना**: पासकी वापस पाने की सुविधा के लिए पासकी से साइन इन करने के लिए, यह तरीका अपनाएं:
    1. ऐप्लिकेशन सर्वर से क्रेडेंशियल वापस पाने के विकल्प पाना: अपने ऐप्लिकेशन सर्वर से, क्लाइंट ऐप्लिकेशन को वह जानकारी भेजें जिसकी ज़रूरत पासकी वापस पाने की सुविधा के लिए पासकी को वापस पाने के लिए होती है.
    2. पासकी वापस पाने की सुविधा के लिए पासकी पाना: जब उपयोगकर्ता कोई नया डिवाइस सेट अप करता है, तो क्रेडेंशियल मैनेजर से पासकी वापस पाने की सुविधा के लिए पासकी का अनुरोध करें. इससे उपयोगकर्ता, कोई और जानकारी दिए बिना साइन इन कर सकता है.
    3. क्रेडेंशियल वापस पाने के जवाब को मैनेज करना: उपयोगकर्ता को साइन इन करने के लिए, क्लाइंट ऐप्लिकेशन से पासकी वापस पाने की सुविधा के लिए पासकी को ऐप्लिकेशन सर्वर पर भेजें.
  3. पासकी वापस पाने की सुविधा के लिए पासकी मिटाना.

पासकी वापस पाने की सुविधा के लिए पासकी बनाना

आपके ऐप्लिकेशन में, उपयोगकर्ता के साइन इन करने के सभी मामलों को शामिल किया जाना चाहिए, ताकि यह पक्का किया जा सके कि सक्रिय उपयोगकर्ताओं के लिए पासकी वापस पाने की सुविधा के लिए पासकी बनाई गई हो. इन स्थितियों में, पासकी वापस पाने की सुविधा के लिए पासकी बनाएं:

  • अगर उपयोगकर्ता साइन इन है और पासकी वापस पाने की सुविधा के लिए पासकी पहले से नहीं बनाई गई है. जैसे, मुख्य Activity के लिए onCreate तरीके में.
  • जब उपयोगकर्ता साइन इन कर रहा हो या नए खाते के रजिस्ट्रेशन की प्रोसेस पूरी कर रहा हो.

हर बार लॉग इन करने पर, पासकी वापस पाने की सुविधा के लिए क्रेडेंशियल बनाने या उसकी जांच करने के ओवरहेड से बचने और परफ़ॉर्मेंस को ऑप्टिमाइज़ करने के लिए, लोकल स्टोरेज में boolean फ़्लैग या क्रेडेंशियल बनाने का टाइमस्टैंप सेट करें. जैसे, has_synced_restore_credential. इससे यह ट्रैक किया जा सकेगा कि पासकी पहले से बनाई गई है या नहीं.

क्रेडेंशियल मैनेजर को इंस्टैंशिएट करना

CredentialManager ऑब्जेक्ट को इंस्टैंशिएट करने के लिए, अपने ऐप्लिकेशन के गतिविधि के कॉन्टेक्स्ट का इस्तेमाल करें.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

अपने ऐप्लिकेशन सर्वर से क्रेडेंशियल बनाने के विकल्प पाना

अपने ऐप्लिकेशन सर्वर में, फ़ाइडो के नियमों के मुताबिक काम करने वाली लाइब्रेरी का इस्तेमाल करें, ताकि आपके क्लाइंट ऐप्लिकेशन को वह जानकारी भेजी जा सके जिसकी ज़रूरत पासकी वापस पाने की सुविधा के लिए क्रेडेंशियल बनाने के लिए होती है. जैसे, उपयोगकर्ता, ऐप्लिकेशन, और कॉन्फ़िगरेशन की अन्य प्रॉपर्टी के बारे में जानकारी. सर्वर-साइड इंटिग्रेशन के बारे में ज़्यादा जानकारी के लिए, सर्वर-साइड के लिए दिशा-निर्देश देखें.

पासकी वापस पाने की सुविधा के लिए पासकी बनाना

सर्वर से भेजे गए सार्वजनिक पासकोड बनाने के विकल्पों को पार्स करने के बाद, पासकी वापस पाने की सुविधा के लिए पासकी बनाएं. इसके लिए, इन विकल्पों को a CreateRestoreCredentialRequest ऑब्जेक्ट में रैप करें. इसके बाद, CredentialManager ऑब्जेक्ट के साथ the createCredential() तरीके को कॉल करें.

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

कोड के बारे में अहम बातें

  • CreateRestoreCredentialRequest ऑब्जेक्ट में ये फ़ील्ड शामिल होते हैं:

    • requestJson: ऐप्लिकेशन सर्वर से भेजे गए क्रेडेंशियल बनाने के विकल्प. ये विकल्प, वेब ऑथेंटिकेशन एपीआई फ़ॉर्मैट में होते हैं PublicKeyCredentialCreationOptionsJSON.

    • isCloudBackupEnabled: Boolean फ़ील्ड. इससे यह तय किया जाता है कि पासकी वापस पाने की सुविधा के लिए पासकी का बैकअप क्लाउड पर लिया जाना चाहिए या नहीं. डिफ़ॉल्ट रूप से, यह फ़्लैग true होता है. इस फ़ील्ड में ये वैल्यू होती हैं:

      • true: (सुझाया जाता है) इस वैल्यू से, पासकी वापस पाने की सुविधा के लिए पासकी का बैकअप क्लाउड पर लिया जा सकता है. हालांकि, इसके लिए ज़रूरी है कि उपयोगकर्ता ने Google बैकअप और पूरी तरह सुरक्षित (E2EE) एन्क्रिप्टशन की सुविधा चालू की हो. जैसे, स्क्रीन लॉक.
      • false: इस वैल्यू से, पासकी को क्लाउड पर नहीं, बल्कि स्थानीय तौर पर सेव किया जाता है. अगर उपयोगकर्ता, क्लाउड से डेटा वापस पाने का विकल्प चुनता है, तो पासकी नए डिवाइस पर उपलब्ध नहीं होती.

क्रेडेंशियल बनाने के जवाब को मैनेज करना

क्रेडेंशियल मैनेजर एपीआई, टाइप CreateRestoreCredentialResponse का जवाब दिखाता है. इस जवाब में, सार्वजनिक पासकोड क्रेडेंशियल के रजिस्ट्रेशन का जवाब JSON फ़ॉर्मैट में होता है.

अपने ऐप्लिकेशन से सार्वजनिक पासकोड को रिलाइंग पार्टी सर्वर पर भेजें. यह सार्वजनिक पासकोड, पासकी बनाते समय जनरेट किए गए सार्वजनिक पासकोड जैसा होता है. सर्वर पर पासकी बनाने के लिए इस्तेमाल किया जाने वाला कोड, पासकी वापस पाने की सुविधा के लिए पासकी बनाने के लिए भी इस्तेमाल किया जा सकता है. सर्वर-साइड इंटिग्रेशन के बारे में ज़्यादा जानकारी के लिए, पासकी के लिए दिशा-निर्देश देखें.

पासकी वापस पाने की सुविधा के लिए पासकी बनाने की प्रोसेस के दौरान, इन गड़बड़ियों को मैनेज करें:

  • CreateRestoreCredentialDomException: यह गड़बड़ी तब होती है, जब requestJson अमान्य होता है और यह PublicKeyCredentialCreationOptionsJSON के लिए, WebAuthn फ़ॉर्मैट के मुताबिक नहीं होता.
  • E2eeUnavailableException: यह गड़बड़ी तब होती है, जब isCloudBackupEnabled की वैल्यू true होती है, लेकिन उपयोगकर्ता के डिवाइस में डेटा बैकअप या पूरी तरह सुरक्षित (E2EE) एन्क्रिप्टशन की सुविधा नहीं होती. जैसे, स्क्रीन लॉक.
    यह पक्का करने के लिए कि पासकी वापस पाने की सुविधा के लिए पासकी हर मामले में बनाई जाए, आपको E2eeUnavailableException को साफ़ तौर पर मैनेज करना होगा. इसके लिए, isCloudBackupEnabled को true पर सेट करके, createCredential को कॉल करें. अगर E2eeUnavailableException गड़बड़ी होती है, तो इसे पकड़ें और isCloudBackupEnabled को false पर सेट करके, createCredential को फिर से कॉल करें.
  • IllegalArgumentException: यह गड़बड़ी तब होती है, जब createRestoreRequest खाली हो या मान्य JSON न हो. इसके अलावा, यह गड़बड़ी तब भी होती है, जब इसमें WebAuthn की खास जानकारी के मुताबिक, मान्य user.id न हो.

पासकी वापस पाने की सुविधा के लिए पासकी से साइन इन करना

डिवाइस सेट अप करने की प्रोसेस के दौरान, उपयोगकर्ता को चुपचाप साइन इन करने के लिए, पासकी वापस पाने की सुविधा के लिए क्रेडेंशियल का इस्तेमाल करें.

ऐप्लिकेशन सर्वर से क्रेडेंशियल वापस पाने के विकल्प पाना

सर्वर से पासकी वापस पाने की सुविधा के लिए पासकी पाने के लिए, क्लाइंट ऐप्लिकेशन को ज़रूरी विकल्प भेजें. इस चरण के लिए, पासकी से जुड़े दिशा-निर्देशों के लिए, पासकी से साइन इन करना देखें. सर्वर-साइड इंटिग्रेशन के बारे में ज़्यादा जानकारी के लिए, सर्वर-साइड ऑथेंटिकेशन गाइड देखें.

पासकी वापस पाने की सुविधा के लिए पासकी पाना

नए डिवाइस पर पासकी वापस पाने की सुविधा के लिए पासकी पाने के लिए, CredentialManager ऑब्जेक्ट पर getCredential() तरीके को कॉल करें.

हमारा सुझाव है कि पासकी वापस पाने की सुविधा के लिए पासकी को इन दोनों स्थितियों में फ़ेच करें:

  • डिवाइस पर ऐप्लिकेशन को पहली बार लॉन्च करने पर. इस स्थिति में, क्रेडेंशियल वापस पाने की सुविधा, ऐप्लिकेशन के डेटा को वापस पाने की सुविधा से अलग होती है.
  • अगर ऐप्लिकेशन के डेटा का बैकअप लेने और उसे वापस पाने की सुविधा चालू है, तो ऐप्लिकेशन का डेटा वापस पाने के तुरंत बाद, पासकी वापस पाने की सुविधा के लिए पासकी पाएं. अपने ऐप्लिकेशन के बैकअप को कॉन्फ़िगर करने के लिए, BackupAgent का इस्तेमाल करें. साथ ही, पक्का करें कि आपने onRestoreFinished कॉलबैक में, getCredential की सुविधा पूरी कर ली हो. onRestore तरीके का इस्तेमाल न करें, क्योंकि इसे सिर्फ़ की-वैल्यू बैकअप के लिए कॉल किया जाता है. वहीं, onRestoreFinished को किसी भी तरह के बैकअप को वापस पाने के लिए कॉल किया जाता है. इससे, उपयोगकर्ताओं के नए डिवाइस को पहली बार खोलने पर होने वाली संभावित देरी से बचा जा सकता है. साथ ही, उपयोगकर्ता आपके ऐप्लिकेशन को खोले जाने का इंतज़ार किए बिना, उससे इंटरैक्ट कर सकते हैं. उदाहरण के लिए, इससे आपका ऐप्लिकेशन, उपयोगकर्ता को नए डिवाइस पर पहली बार ऐप्लिकेशन खोलने से पहले सूचनाएं भेज सकता है. यह सुविधा, मैसेजिंग या कम्यूनिकेशन ऐप्लिकेशन के लिए खास तौर पर काम की है.

अगर आपने नया BackupAgent बनाया है और पहले allowBackup="true" के साथ बैकअप की सुविधा चालू की थी, तो अपने ऐप्लिकेशन के मेनिफ़ेस्ट में, बूलियन वैल्यू android:fullBackupOnly="true" सेट करें. इससे यह पक्का होता है कि आपके ऐप्लिकेशन के बैकअप और उसे वापस पाने की सुविधा का व्यवहार बना रहे.

// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

क्रेडेंशियल मैनेजर एपीआई, टाइप GetCredentialResponse का जवाब दिखाता है. इस जवाब में मौजूद क्रेडेंशियल, साफ़ तौर पर RestoreCredential टाइप का होता है. इसमें सार्वजनिक पासकोड होता है.

साइन-इन के जवाब को मैनेज करना

ऐप्लिकेशन से सार्वजनिक पासकोड को रिलाइंग पार्टी सर्वर पर भेजें. इसका इस्तेमाल, उपयोगकर्ता को साइन इन करने के लिए किया जा सकता है. सर्वर साइड पर, यह कार्रवाई पासकी का इस्तेमाल करके साइन इन करने जैसी होती है. सर्वर पर पासकी की मदद से साइन इन करने के लिए इस्तेमाल किया जाने वाला कोड, पासकी वापस पाने की सुविधा के लिए पासकी की मदद से साइन इन करने के लिए भी इस्तेमाल किया जा सकता है. पासकी के लिए सर्वर-साइड इंटिग्रेशन के बारे में ज़्यादा जानकारी के लिए, पासकी से साइन इन करना देखें.

पासकी वापस पाने की सुविधा के लिए पासकी मिटाना

क्रेडेंशियल मैनेजर, स्टेटलेस होता है. साथ ही, इसे उपयोगकर्ता की गतिविधि के बारे में जानकारी नहीं होती. इसलिए, यह इस्तेमाल के बाद, पासकी वापस पाने की सुविधा के लिए पासकी को अपने-आप नहीं मिटाता. पासकी वापस पाने की सुविधा के लिए पासकी मिटाने के लिए, clearCredentialState() तरीके को कॉल करें. सुरक्षा के लिए, जब भी कोई उपयोगकर्ता साइन आउट करे, तो पासकी मिटा दें. इससे यह पक्का होता है कि अगली बार जब उपयोगकर्ता, उसी डिवाइस पर ऐप्लिकेशन खोलेगा, तो वह साइन आउट होगा. साथ ही, उसे फिर से साइन इन करने के लिए कहा जाएगा.

किसी ऐप्लिकेशन को अनइंस्टॉल करने का मतलब है कि उपयोगकर्ता, उस डिवाइस से पासकी वापस पाने की सुविधा के लिए पासकी को मिटाना चाहता है. यह उपयोगकर्ता के साइन आउट करने के इरादे जैसा ही है.

पासकी वापस पाने की सुविधा के लिए पासकी सिर्फ़ इन स्थितियों में हटाई जाती हैं:

  • सिस्टम-लेवल की कार्रवाइयां: उपयोगकर्ता, ऐप्लिकेशन को अनइंस्टॉल करते हैं या उसका डेटा मिटाते हैं.
  • ऐप्लिकेशन-लेवल के कॉल: अपने ऐप्लिकेशन के कोड में, उपयोगकर्ता के साइन आउट करने की प्रोसेस को मैनेज करते समय, clearCredentialState() को कॉल करके, पासकी को प्रोग्राम के ज़रिए मिटाएं.

जब उपयोगकर्ता आपके ऐप्लिकेशन से साइन आउट करता है, तो CredentialManager ऑब्जेक्ट पर clearCredentialState() तरीके को कॉल करें.

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)