จัดการการออกข้อมูลเข้าสู่ระบบด้วยแอปของผู้ถือ

หากต้องการรับและจัดเก็บข้อมูลเข้าสู่ระบบจากผู้ออกบัตร แอปผู้ถือบัตรจะต้องจัดการขั้นตอนการออกบัตร การออกข้อมูลเข้าสู่ระบบสามารถทริกเกอร์ได้ 2 วิธีดังนี้

• ขั้นตอนที่ผู้ออกบัตรเป็นผู้เริ่ม: ผู้ใช้เรียกใช้คำขอให้ออก VDC จากแอปพลิเคชันหรือเว็บไซต์ของผู้ออกบัตร เช่น เว็บไซต์อาจเสนอตัวเลือก "เพิ่มหนังสือเดินทางลงใน Wallet" ให้แก่ผู้ใช้ ผู้ออกจะเรียกใช้ API การออกข้อมูลเข้าสู่ระบบของ Credential Manager เพื่อส่งคำขอข้อเสนอข้อมูลเข้าสู่ระบบ OpenID4VCI หากต้องการจัดการคำขอดังกล่าว ผู้ถือต้องผสานรวมกับ Credential Manager ก่อนเพื่อลงทะเบียนข้อมูลเมตา Credential Manager จะแสดงตัวเลือกที่เกี่ยวข้องให้ผู้ใช้เลือก หลังจากผู้ใช้เลือกตัวเลือกผู้ถือแล้ว ระบบจะเรียกใช้แอปพลิเคชันผู้ถือและดำเนินการตามขั้นตอนที่จำเป็นเพื่อดำเนินการออกให้เสร็จสมบูรณ์
• ขั้นตอนที่เริ่มต้นโดยผู้ถือบัตร: ผู้ใช้ส่งคำขอเพิ่ม VDC จากแอปพลิเคชันของผู้ถือบัตร เช่น ผู้ถืออาจเสนอให้มีปุ่ม "เพิ่มหนังสือเดินทาง" ในกรณีนี้ ผู้ถือจะเก็บรักษารายชื่อผู้ออกบัตรและข้อมูลเมตาที่รองรับไว้ โดยไม่จำเป็นต้องผสานรวมกับ Android Credential Manager เพื่อดำเนินการฟังก์ชันนี้ให้เสร็จสมบูรณ์

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีการทำงานของข้อมูลเข้าสู่ระบบกับ Holder API ได้ที่เกี่ยวกับการจัดเก็บข้อมูลเข้าสู่ระบบดิจิทัล

ความเข้ากันได้กับเวอร์ชัน Android

Holder API ใช้ได้ใน Android 6 (ระดับ API 23) ขึ้นไป

การใช้งาน

หากต้องการใช้ Credential Manager Holder API ให้เพิ่มทรัพยากร Dependency ต่อไปนี้ลงในสคริปต์บิลด์ของโมดูลแอป

dependencies {
    // Use to implement credentials registrys

    implementation "androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04"

}

dependencies {
    // Use to implement credentials registrys

    implementation("androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04")

}

สร้าง RegistryManager

สร้างอินสแตนซ์ RegistryManager และลงทะเบียนคำขอ RegisterCreationOptionsRequest ด้วยอินสแตนซ์ดังกล่าว

val registryManager = RegistryManager.create(context)

try {
    registryManager.registerCreationOptions(object :
        RegisterCreationOptionsRequest(
            creationOptions = buildIssuanceData(),
            matcher = loadIssuanceMatcher(),
            type = DigitalCredential.TYPE_DIGITAL_CREDENTIAL,
            id = "openid4vci",
        ) {}
    )
} catch (e: Exception) {
    Log.e(TAG, "Issuance registration failed.", e)
}

ตัวจับคู่คือไฟล์ไบนารี WebAssembly (Wasm) ที่รับ creationOptions ที่ตั้งค่าไว้ระหว่างการลงทะเบียนและข้อเสนอข้อมูลเข้าสู่ระบบที่ผู้ออกส่งมาเพื่อกำหนดรายการที่แสดงใน UI ของ Credential Manager ดูตัวอย่าง Matcher ได้ที่แอป Wallet ตัวอย่างโอเพนซอร์ส

จัดการคำขอออกใบรับรอง

ถัดไป วอลเล็ตต้องจัดการเมื่อผู้ใช้เลือกตัวเลือกการสร้างข้อมูลเข้าสู่ระบบ กำหนดกิจกรรมที่คอยฟังตัวกรอง Intent androidx.credentials.registry.provider.action.CREATE_CREDENTIAL ดังที่แสดงในวอลเล็ตตัวอย่าง

Intent ที่เปิดกิจกรรมประกอบด้วยคำขอสร้างและต้นทางการเรียก ซึ่งคุณสามารถดึงข้อมูลได้ด้วยฟังก์ชัน PendingIntentHandler.retrieveProviderCreateCredentialRequest API จะแสดงผล ProviderCreateCredentialRequest ที่มีข้อมูลทั้งหมดที่เชื่อมโยงกับคำขอสร้าง ซึ่งมีองค์ประกอบหลัก 2 อย่าง ได้แก่

• แอปที่ส่งคำขอ คุณสามารถเรียกข้อมูลนี้ได้ด้วย getCallingAppInfo
• คำขอจากแอปการโทร คุณสามารถเรียกข้อมูลนี้ได้ด้วย getCallingRequest ซึ่งจะแสดงผลเป็น CreateCredentialRequest หากคำขอเป็นข้อมูลเข้าสู่ระบบดิจิทัล คำขอนั้นจะเป็นอินสแตนซ์ของ CreateDigitalCredentialRequest ซึ่งมี JSON ของคำขอการออกในพร็อพเพอร์ตี้ requestJson คุณสามารถประมวลผลได้ด้วยโค้ดตัวอย่างต่อไปนี้

val pendingIntentRequest =
    PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)
val request = pendingIntentRequest!!.callingRequest
if (request is CreateDigitalCredentialRequest) {
    Log.i(TAG, "Got DC creation request: ${request.requestJson}")
    processCreationRequest(request.requestJson)
}

เอกสารรับรองคีย์

โปรดทราบข้อมูลต่อไปนี้เกี่ยวกับเอกสารรับรองคีย์

• เมื่อสร้างเอกสารรับรองคีย์ คุณอาจใช้ BigInteger.toByteArray เพื่อแปลงคีย์เป็นคีย์เว็บ JSON เป็นต้น บางครั้งวิธีนี้อาจเพิ่มไบต์เครื่องหมายและทำให้เกิดข้อผิดพลาดในการตรวจสอบความถูกต้อง หากเกิดกรณีนี้ขึ้น ให้นำไบต์เหล่านี้ออกก่อนส่งเอกสารรับรองคีย์ไปยังผู้ออกบัตร
• เราขอแนะนำให้ใช้ android_key_attestation เป็นประเภทหลักฐานคีย์

แสดงการตอบกลับการสร้าง

เมื่อ Wallet ทำตามขั้นตอนที่จำเป็นในการบันทึกข้อมูลเข้าสู่ระบบเสร็จแล้ว ให้ทำกิจกรรมให้เสร็จสิ้นด้วยการตอบกลับข้อมูลเข้าสู่ระบบ ดังนี้

val resultData = Intent()
PendingIntentHandler.setCreateCredentialResponse(
    resultData,
    CreateDigitalCredentialResponse(response.responseJson)
)
setResult(RESULT_OK, resultData)
finish()

หากมีข้อยกเว้น คุณสามารถส่งข้อยกเว้นของข้อมูลเข้าสู่ระบบในลักษณะเดียวกันได้ ดังนี้

val resultData = Intent()
PendingIntentHandler.setCreateCredentialException(
    resultData,
    CreateCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

ดูตัวอย่างทั้งหมดของการแสดงผลการตอบกลับข้อมูลเข้าสู่ระบบในบริบทได้ที่แอปตัวอย่าง