डिजिटल क्रेडेंशियल का अनुरोध करना

Android ऐप्लिकेशन में डिजिटल क्रेडेंशियल की पुष्टि करने की सुविधा का इस्तेमाल, उपयोगकर्ता की पहचान (जैसे, सरकारी आईडी) की पुष्टि करने और उसे अनुमति देने के लिए किया जा सकता है. साथ ही, इसका इस्तेमाल उपयोगकर्ता की प्रॉपर्टी (जैसे, ड्राइविंग लाइसेंस, अकैडमिक डिग्री या उम्र या पते जैसी विशेषताएं) की पुष्टि करने के लिए किया जा सकता है. इसके अलावा, इसका इस्तेमाल उन मामलों में किया जा सकता है जहां किसी इकाई की प्रामाणिकता की पुष्टि करने के लिए, क्रेडेंशियल जारी करने और उसकी पुष्टि करने की ज़रूरत होती है.

Verifier API, Android 9 (एपीआई लेवल 28) और इसके बाद के वर्शन पर काम करता है.

लागू करना

अपने Android प्रोजेक्ट में डिजिटल क्रेडेंशियल की पुष्टि करने के लिए, यह तरीका अपनाएं:

  1. अपने ऐप्लिकेशन की बिल्ड स्क्रिप्ट में डिपेंडेंसी जोड़ें और CredentialManager क्लास को शुरू करें.
  2. डिजिटल क्रेडेंशियल का अनुरोध बनाएं और इसका इस्तेमाल करके, DigitalCredentialOption को शुरू करें. इसके बाद, GetCredentialRequest बनाएं.
  3. getCredential फ़्लो को लॉन्च करें. इसके लिए, अनुरोध करें, ताकि आपको GetCredentialResponse मिल सके या किसी भी तरह की गड़बड़ी को मैनेज किया जा सके. जवाब मिलने के बाद, उसकी पुष्टि करें.

डिपेंडेंसी जोड़ना और शुरू करना

अपनी Gradle बिल्ड स्क्रिप्ट में ये डिपेंडेंसी जोड़ें:

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-beta01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-beta01")
}

इसके बाद, CredentialManager क्लास का कोई इंस्टेंस शुरू करें.

val credentialManager = CredentialManager.create(context)

डिजिटल क्रेडेंशियल का अनुरोध करना

डिजिटल क्रेडेंशियल का अनुरोध बनाएं और इसका इस्तेमाल करके, DigitalCredentialOption को शुरू करें.

// The request in the JSON format to conform with
// the JSON-ified Credential Manager - Verifier API request definition.
val requestJson = generateRequestFromServer()
val digitalCredentialOption =
    GetDigitalCredentialOption(requestJson = requestJson)

// Use the option from the previous step to build the `GetCredentialRequest`.
val getCredRequest = GetCredentialRequest(
    listOf(digitalCredentialOption)
)

यहां दिए गए उदाहरण में, OpenId4Vp1 अनुरोध दिखाया गया है. इस अनुरोध में मौजूद फ़ील्ड के बारे में जानकारी पाने के लिए, OpenID दस्तावेज़ देखें.

{
  "requests": [
    {
      "protocol": "openid4vp-v1-unsigned",
      "data": {
        "response_type": "vp_token",
        "response_mode": "dc_api",
        "nonce": "OD8eP8BYfr0zyhgq4QCVEGN3m7C1Ht_No9H5fG5KJFk",
        "dcql_query": {
          "credentials": [
            {
              "id": "cred1",
              "format": "mso_mdoc",
              "meta": {
                "doctype_value": "org.iso.18013.5.1.mDL"
              },
              "claims": [
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "family_name"
                  ]
                },
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "given_name"
                  ]
                },
                {
                  "path": [
                    "org.iso.18013.5.1",
                    "age_over_21"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

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

बनाए गए अनुरोध के साथ getCredential फ़्लो लॉन्च करें. अनुरोध पूरा होने पर आपको GetCredentialResponse मिलेगा. अनुरोध पूरा न होने पर, आपको GetCredentialException मिलेगा.

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

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

// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
    val credential = result.credential
    when (credential) {
        is DigitalCredential -> {
            val responseJson = credential.credentialJson
            validateResponseOnServer(responseJson)
        }
        else -> {
            // Catch any unrecognized credential type here.
            Log.e(TAG, "Unexpected type of credential ${credential.type}")
        }
    }
}

// Handle failure.
fun handleFailure(e: GetCredentialException) {
  when (e) {
        is GetCredentialCancellationException -> {
            // The user intentionally canceled the operation and chose not
            // to share the credential.
        }
        is GetCredentialInterruptedException -> {
            // Retry-able error. Consider retrying the call.
        }
        is NoCredentialException -> {
            // No credential was available.
        }
        else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
    }
}
इस इमेज में, getCredential को कॉल करने पर दिखने वाला डिजिटल क्रेडेंशियल सिलेक्टर दिखाया गया है.
पहली इमेज. getCredential को कॉल करने पर, दिखने वाला डिजिटल क्रेडेंशियल सिलेक्टर.

एक से ज़्यादा क्रेडेंशियल के लिए अनुरोध करने की सुविधा

Digital Credentials API, OpenID4VP का इस्तेमाल करके एक साथ कई तरह के क्रेडेंशियल का अनुरोध करने की सुविधा भी देता है:

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

एक ही अनुरोध में कई क्रेडेंशियल का अनुरोध करने का उदाहरण यहां दिया गया है:

{
  "credentials": [
    {
      "id": "gov_id1",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "org.iso.18013.5.1.mDL"
      },
      "claims": [
        {
          "path": [
            "org.iso.18013.5.1",
            "age_over_21"
          ]
        }
      ]
    },
    {
      "id": "boarding_pass1",
      "format": "dc+sd-jwt",
      "meta": {
        "vct_values": [
          "https://credentials.example.airline/boarding-pass"
        ]
      },
      "claims": [
        {
          "path": [
            "flight_number"
          ]
        },
        {
          "path": [
            "seat"
          ]
        }
      ]
    }
  ]
}
इमेज में, अलग-अलग तरह के क्रेडेंशियल को कॉल करते समय, डिजिटल क्रेडेंशियल चुनने वाला टूल दिखाया गया है.
पहली इमेज. एक से ज़्यादा तरह के क्रेडेंशियल को कॉल करने पर, दिखाया जाने वाला डिजिटल क्रेडेंशियल सिलेक्टर

जवाब मैनेज करना

क्रेडेंशियल का अनुरोध करने के बाद, CredentialManager से मिले GetCredentialResponse को मैनेज करें.

// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
    val credential = result.credential
    when (credential) {
        is DigitalCredential -> {
            val responseJson = credential.credentialJson
            validateResponseOnServer(responseJson)
        }
        else -> {
            // Catch any unrecognized credential type here.
            Log.e(TAG, "Unexpected type of credential ${credential.type}")
        }
    }
}

गड़बड़ियों को ठीक करना

आपके ऐप्लिकेशन को ऐसी गड़बड़ियों को मैनेज करना चाहिए जो हो सकती हैं. इनमें, डिवाइस पर क्रेडेंशियल मौजूद न होने या उपयोगकर्ता के कार्रवाई रद्द करने जैसी गड़बड़ियां शामिल हैं:

// Handle failure.
fun handleFailure(e: GetCredentialException) {
    when (e) {
        is GetCredentialCancellationException -> {
            // The user intentionally canceled the operation and chose not
            // to share the credential.
        }
        is GetCredentialInterruptedException -> {
            // Retry-able error. Consider retrying the call.
        }
        is NoCredentialException -> {
            // No credential was available.
        }
        is GetCredentialUnknownException -> {
            // An unknown, usually unexpected, error has occurred. Check the
            // message error for any additional debugging information.
        }
        is GetCredentialCustomException -> {
            // You have encountered a custom error thrown by the wallet.
            // If you made the API call with a request object that's a
            // subclass of GetCustomCredentialOption using a 3rd-party SDK,
            // then you should check for any custom exception type constants
            // within that SDK to match with e.type. Otherwise, drop or log the
            // exception.
        }
        else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
    }
}