ফোন নম্বর যাচাইকরণ প্রয়োগ করুন

আপনার ব্যবহারকারীদের জন্য যাচাই করা ফোন নম্বর পেতে কীভাবে DigitalCredential API ব্যবহার করবেন তা এই গাইডে বিস্তারিতভাবে বর্ণনা করা হয়েছে। এই প্রসেসে দুটি ধাপ রয়েছে:

1. প্রিচেক: Android Telephony API কোয়েরি করে ব্যবহারকারীর পরিষেবা প্রদানকারী এই API-কে সাপোর্ট করে কিনা তা চেক করুন। পরিষেবা প্রদানকারী কাজ না করলে, আপনার সাধারণ এসএমএস ফ্লোতে ফিরে যান।
2. TS.43 token-এর জন্য অনুরোধ করা: আপনার ক্লায়েন্ট অ্যাপ ("যাচাইকারী") ব্যবহারকারীর ডিভাইস থেকে সাময়িক TS.43 টোকেনের জন্য অনুরোধ করে। TS.43 token হল পরিষেবা প্রদানকারীর ইস্যু করা ক্রেডেনশিয়াল যা ব্যবহারকারীর পরিচয় দেখায়।
3. ফোন নম্বরের জন্য টোকেন এক্সচেঞ্জ করা: আপনার অ্যাপের ব্যাকএন্ড, ব্যবহারকারীর যাচাই করা ফোন নম্বরের জন্য TS.43 token এগ্রিগেটর বা পরিষেবা প্রদানকারীর সাথে এক্সচেঞ্জ করে।

Android ভার্সনের কম্প্যাটিবিলিটি

ফোন নম্বর যাচাইকরণ API, Android 10 (API লেভেল ২৯) এবং তার পরবর্তী ভার্সনে কাজ করে।

পূর্বশর্ত

DigitalCredential API-এর মাধ্যমে ফোন নম্বর যাচাইকরণ প্রয়োগ করতে, আপনার একটি অ্যাগ্রিগেটর বা মোবাইল পরিষেবা প্রদানকারীর সাথে অ্যাকাউন্ট থাকতে হবে। একটি এগ্রিগেটর পরিষেবা প্রদানকারীর সাথে ইন্টার‍্যাক্ট করে এবং আপনার অ্যাপের জন্য প্রয়োজনীয় API সারফেস প্রদান করে, সাধারণত একটি বিলযোগ্য ক্লাউড API এন্ডপয়েন্ট হিসেবে। এই নির্দেশিকায়, এগ্রিগেটর ও ক্যারিয়ার, উভয়কেই একসাথে এগ্রিগেটর হিসেবে উল্লেখ করা হয়েছে।

এছাড়াও, আপনার Gradle বিল্ড স্ক্রিপ্টে নিম্নলিখিত ডিপেন্ডেন্সি যোগ করতে হবে:

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

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

প্রয়োগ

Digital Credentials API কল করার আগে, Android Telephony API ব্যবহার করে ব্যবহারকারীর পরিষেবা প্রদানকারী এই ফিচারটি সমর্থন করে কিনা তা পরীক্ষা করুন।

আপনার AndroidManifest.xml ফাইলে READ_PHONE_STATE অনুমতি যোগ করুন।

val telephonyManager = context.getSystemService(Context.TELEPHONY_SERVICE) as TelephonyManager
val carrierId = telephonyManager.getSimCarrierId()

এই আইডির মাধ্যমে, আপনার এগ্রিগেটর ব্যাকএন্ডের সাথে TS.43 সাপোর্ট যাচাই করুন। এই ব্যবহারকারীর পরিষেবা প্রদানকারী কাজ না করলে, আপনি এসএমএসের মতো বিকল্প পদ্ধতিতে ফিরে যেতে পারেন, কারণ ডিজিটাল ক্রেডেনশিয়াল API কল করলে ফলাফল খালি দেখায়। অন্যথায়, ডিজিটাল ক্রেডেনশিয়াল ফ্লো ব্যবহার করে চালিয়ে যান।

শুরু থেকে শেষ পর্যন্ত প্রসেসটি সাধারণত এইসব ধাপ অনুসরণ করে:

1. কোনও অ্যাগ্রিগেটর থেকে DCQL (ডিজিটাল ক্রেডেনশিয়াল কোয়েরি ল্যাঙ্গুয়েজ) প্যারামিটারের জন্য অনুরোধ করুন: এক বা একাধিক অ্যাগ্রিগেটরকে কল করুন এবং DCQL প্যারামিটারের একটি সেটের জন্য অনুরোধ করুন। DCQL আপনাকে প্রতিটি এগ্রিগেটর থেকে আপনার প্রয়োজনীয় সঠিক ডিজিটাল ক্রেডেনশিয়াল নির্দিষ্ট করতে দেয়।

2. OpenID4VP অনুরোধ তৈরি করুন: আপনার অ্যাপের ব্যাকএন্ড থেকে, OpenID4VP অনুরোধ তৈরি করুন, যেখানে অ্যাগ্রিগেটর থেকে DCQL প্যারামিটার অন্তর্ভুক্ত থাকবে। তারপর, আপনার ক্লায়েন্ট অ্যাপে OpenID4VP অনুরোধ পাঠান।

3. ক্রেডেনশিয়াল ম্যানেজার API কল করা: আপনার ক্লায়েন্ট অ্যাপে, অপারেটিং সিস্টেমে OpenID4VP অনুরোধ পাঠাতে ক্রেডেনশিয়াল ম্যানেজার API ব্যবহার করুন। উত্তরে, আপনি একটি OpenID4VP উত্তর অবজেক্ট পাবেন যাতে TS.43 Digital Credential থাকে। এই ক্রেডেনশিয়াল এনক্রিপ্ট করা আছে এবং শুধুমাত্র সংশ্লিষ্ট অ্যাগ্রিগেটরই এটি ডিক্রিপ্ট করতে পারবে। পরিষেবা প্রদানকারীর টোকেন পাওয়ার পরে, আপনার ক্লায়েন্ট অ্যাপ থেকে অ্যাপের ব্যাকএন্ডে উত্তর পাঠান।

4. উত্তর যাচাই করা: আপনার অ্যাপের ব্যাকএন্ডে, OpenID4VP উত্তর যাচাই করুন।

5. ফোন নম্বরের জন্য এক্সচেঞ্জ করা: আপনার অ্যাপের ব্যাকএন্ড থেকে এগ্রিগেটরকে TS.43 Digital Credential পাঠান। অ্যাগ্রিগেটর ক্রেডেনশিয়াল যাচাই করে এবং যাচাই করা ফোন নম্বর ফেরত দেয়।

কোনও অ্যাগ্রিগেটর থেকে DCQL প্যারামিটারের অনুরোধ করা

আপনার অ্যাপের ব্যাকএন্ড থেকে, এগ্রিগেটরকে ডিজিটাল ক্রেডেনশিয়াল কোয়েরি ল্যাঙ্গুয়েজ (DCQL) ক্রেডেনশিয়াল অবজেক্টের জন্য অনুরোধ পাঠান। আপনার অনুরোধে একটি ননস এবং অনুরোধ আইডি প্রদান করতে ভুলবেন না। এগ্রিগেটর DCQL ক্রেডেনশিয়াল অবজেক্ট রিটার্ন করে, যার স্ট্রাকচার নিম্নলিখিতটির মতো:

{
  // The credential ID is mapped to the request ID that is sent in your request to the aggregator.
  "id": "aggregator1",
  "format": "dc-authorization+sd-jwt",
  "meta": {
    "vct_values": [
      "number-verification/device-phone-number/ts43"
    ],
    "credential_authorization_jwt": "..."
  },
  "claims": [
    {
      "path": ["subscription_hint"],
      "values": [1]
    },
    {
      "path": ["phone_number_hint"],
      "values": ["+14155552671"]
    }
  ]
}

OpenID4VP অনুরোধ তৈরি করুন

প্রথমে, আপনার অ্যাপের ব্যাকএন্ড থেকে, dcql_query অবজেক্টের মধ্যে নেস্ট করা credentials অ্যারেতে DCQL ক্রেডেনশিয়াল অবজেক্ট রেখে একটি dcql_query অবজেক্ট তৈরি করুন, যেমনটি নিম্নলিখিত উদাহরণে দেখানো হয়েছে:

"dcql_query": {
  "credentials": [
      "id": "aggregator1",
      "format": "dc-authorization+sd-jwt",
      "meta": {
        "vct_values": [
          "number-verification/device-phone-number/ts43"
        ],
        "credential_authorization_jwt": "..."
      },
      "claims": [
        {
          "path": ["subscription_hint"],
          "values": [1]
        },
        {
          "path": ["phone_number_hint"],
          "values": ["+14155552671"]
        }
      ]
  ]
}

তারপর, নিম্নলিখিত স্ট্রাকচার সহ OpenID4VP অনুরোধ তৈরি করুন:

{
  "protocol": "openid4vp-v1-unsigned",
  "data": {
    "response_type": "vp_token",
    "response_mode": "dc_api",
    "nonce": "...",
    "dcql_query": { ... }
  }
}

• protocol: ফোন নম্বর যাচাইকরণের অনুরোধের জন্য অবশ্যই openid4vp-v1-unsigned-এ সেট করতে হবে।
• response_type এবং response_mode: যথাক্রমে vp_token এবং dc_api নির্দিষ্ট ভ্যালু সহ অনুরোধের ফর্ম্যাট নির্দেশ করে এমন কনস্ট্যান্ট।
• nonce: প্রতিটি অনুরোধের জন্য আপনার ব্যাকএন্ডের মাধ্যমে তৈরি করা একটি অনন্য ভ্যালু। অ্যাগ্রিগেটর DCQL ক্রেডেনশিয়াল অবজেক্টের nonce-এর সাথে এই nonce-এর মিল থাকতে হবে।
• dcql_query: এই ক্ষেত্রে, TS.43 Digital Credential-এর জন্য অনুরোধ করা হচ্ছে তা নির্দিষ্ট করতে dcql_query ব্যবহার করুন। এছাড়াও, আপনি এখানে অন্যান্য ডিজিটাল ক্রেডেনশিয়ালের জন্য অনুরোধ করতে পারবেন।

তারপর, DigitalCredential API অনুরোধ অবজেক্টে OpenID4VP অনুরোধটি র‍্যাপ করুন এবং ক্লায়েন্ট অ্যাপে পাঠান।

{
  "requests":
    [
      {
        "protocol": "openid4vp-v1-unsigned",
        "data": {
          "response_type": "vp_token",
          "response_mode": "dc_api",
          "nonce": "...",
          "dcql_query": { ... }
        }
      }
    ]
}

নিচের স্নিপেট থেকে বোঝা যাবে যে কীভাবে DigitalCredential API অনুরোধ জেনারেট করতে হয়:

def GenerateDCRequest():
    credentials = []
    aggregator1_dcql = call_aggregator_endpoint(nonce, "aggregator1", additional_params)
    credentials.append(aggregator1_dcql) # You can optionally work with multiple
    # aggregators, or request other types of credentials

    val dc_request =
    {
      "requests":
        [
          {
            "protocol": "openid4vp-v1-unsigned",
            "data": {
              "response_type": "vp_token",
              "response_mode": "dc_api",
              "nonce": "...",
              "dcql_query": {"credentials": credentials}
            }
          }
        ]
    }
    return dc_request

ক্রেডেনশিয়াল ম্যানেজার API কল করা

আপনার ক্লায়েন্ট অ্যাপে, ক্রেডেনশিয়াল ম্যানেজার API-তে কল করুন, সাথে আপনার অ্যাপের ব্যাকএন্ডের মাধ্যমে প্রদান করা DigitalCredential API অনুরোধ।

val requestJson = generateTs43DigitalCredentialRequestFromServer()
val digiCredOption = GetDigitalCredentialOption(requestJson = requestJson)
val getCredRequest = GetCredentialRequest(
    listOf(digiCredOption)
)

coroutineScope.launch {
  try {
    val response = credentialManager.getCredential(
      context = activityContext,
      request = getCredRequest
    )
    val credential = response.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}")
      }
    }
  } catch (e : GetCredentialException) {
      // If user cancels the operation, the feature isn't available, or the
      // SIM doesn't support the feature, a GetCredentialCancellationException
      // will be returned. Otherwise, a GetCredentialUnsupportedException will
      // be returned with details in the exception message.
      handleFailure(e)
  }
}

DigitalCredential API রেসপন্সে OpenID4VP রেসপন্স থাকে। DigitalCredential ফলাফল থেকে পাওয়া একটি সাধারণ ক্রেডেনশিয়াল json নিচে দেওয়া হল:

{
  "protocol": "openid4vp-v1-unsigned",

  "data": {
    "vp_token": {
      "aggregator1": ["eyJhbGciOiAiRVMy..."] # The encrypted TS.43 Digital
                                             # Credential in an array structure.
    }
  }
}

আপনার ক্লায়েন্ট অ্যাপ থেকে DigitalCredential API রেসপন্স ব্যাকএন্ড সার্ভারে পাঠান, যেখানে এটি যাচাই করা যাবে এবং অ্যাগ্রিগেটর সহ যাচাই করা ফোন নম্বরের সাথে এক্সচেঞ্জ করার জন্য ব্যবহার করা যাবে।

কিছু ক্ষেত্রে, উত্তরে TS.43 সংক্রান্ত সমস্যা থাকতে পারে। সমস্যা সংক্রান্ত রেসপন্স হল একটি json অবজেক্ট যা OpenID4VP সমস্যা সংক্রান্ত রেসপন্স ফর্ম্যাট অনুসরণ করে:

{
  "protocol": "openid4vp-v1-unsigned",

  "data": {
    "error": "<error_code>",
    "error_description": "<Human-readable description of the error>",
  }
}

error_code-এর ২টি সম্ভাব্য ভ্যালু আছে:

• invalid_request: এটি ইঙ্গিত করে যে অনুরোধটি বিকৃত ছিল।
• server_error: এটি দেখায় যে অনুরোধ প্রসেস করার সময় সমস্যা হয়েছে। এটি লোকাল সমস্যা বা TS.43 সংক্রান্ত সমস্যা হতে পারে।

error_description ফিল্ডে সমস্যা সম্পর্কে অতিরিক্ত বিবরণ দেওয়া থাকে।

ডিজিটাল ক্রেডেনশিয়াল সংক্রান্ত উত্তর যাচাই করুন

আপনার অ্যাপের ব্যাকএন্ডে কীভাবে রেসপন্স পার্স করতে হয় এবং যাচাইকরণ ধাপটি সম্পূর্ণ করতে হয়, তার একটি উদাহরণ নিচে দেওয়া হল:

def processDigitalCredentialsResponse(response):
  # Step 1: Parse out the TS.43 Digital Credential from the response
  openId4VpResponse = response['data']

  ts43_digital_credential = response['vp_token']["aggregator1"][0]

  # Step 2: Perform response validation
  verifyResponse(ts43_digital_credential)

def verifyResponse(ts43_digital_credential):
  # The returned ts43_digital_credential is an SD-JWT-based Verifiable Credentials
  # (SD-JWT VC) as defined in this IETF spec. The section 3.4 of the specification
  # outlines how to validate the credential. At a high level, the steps involves
  # validating (1) the nonce in the response credential matches the one in the
  # request, (2) the integrity of the credential by checking the credential is
  # signed by the trusted issuer Android Telephony, and (3) other validity
  # properties associated with this credential, such as issue time and expiration
  # time

  # In most cases, you can use an SD-JWT VC library to perform these validations.

  # Some aggregators may also perform the validation logic for you. Check with your
  # aggregator to decide the exact scope of the validation required.

ফোন নম্বরের জন্য এক্সচেঞ্জ

আপনার অ্যাপের ব্যাকএন্ড থেকে, যাচাই করা TS.43 Digital Credential এগ্রিগেটরের এন্ডপয়েন্টে পাঠান, যাতে ক্রেডেনশিয়াল যাচাই করা যায় এবং যাচাই করা ফোন নম্বর পাওয়া যায়।

def processDigitalCredentialsResponse(response):
  # ... prior steps

  # Step 3: Call aggregator endpoint to exchange the verified phone number
  callAggregatorPnvEndpoint(ts43_digital_credential)