构建欧盟数字身份钱包Android应用指南

项目概述

欧盟数字身份钱包Android应用是一个参考实现项目，旨在为开发者提供与数字身份发行和验证服务交互的标准化解决方案。该项目采用模块化设计，支持多种运行环境和配置方式，方便开发者进行本地开发和测试。

开发环境准备

基础工具要求

要构建和运行该Android应用，您需要准备以下开发环境：

1. Android Studio：推荐使用最新稳定版本，这是开发Android应用的官方IDE
2. Java/Kotlin开发环境：项目主要使用Kotlin语言开发
3. Android设备或模拟器：用于运行和测试应用

项目结构与构建配置

该项目采用Gradle构建系统，提供了灵活的构建变体配置：

产品风味(Product Flavors)

• Dev：用于开发环境，连接基于主分支最新代码部署的服务
• Demo：用于演示环境，连接稳定的演示服务

构建类型(Build Types)

• Debug：调试版本，启用完整日志记录功能
• Release：发布版本，禁用日志记录功能

组合后形成以下构建变体(Build Variants)：

• devDebug
• devRelease
• demoDebug
• demoRelease

在Android Studio中，可以通过"Build" -> "Select Build Variant"菜单选择所需的构建变体。

运行应用

在设备上运行

1. 通过USB连接Android设备并启用开发者选项
2. 在Android Studio中选择目标设备
3. 点击"Run" -> "Run 'app'"启动应用

在模拟器上运行

1. 创建或启动Android模拟器
2. 直接点击运行按钮即可启动应用

服务配置详解

使用远程服务

应用默认配置为使用远程服务，相关配置位于core-logic模块中的ConfigWalletCoreImpl.kt文件：

private companion object {
    const val VCI_ISSUER_URL = "https://dev.issuer.eudiw.dev"
    const val VCI_CLIENT_ID = "wallet-dev"
    const val AUTHENTICATION_REQUIRED = false
}

这些配置项定义了：

• 发行者服务URL
• 客户端ID
• 是否要求身份验证

使用本地服务

要在本地开发环境中运行，需要先启动以下服务：

1. 发行者服务
2. Web验证器UI
3. Web验证器端点

然后修改ConfigWalletCoreImpl.kt文件中的配置：

private companion object {
    const val VCI_ISSUER_URL = "https://10.0.2.2"  // 本地服务地址
    const val VCI_CLIENT_ID = "wallet-dev"
    const val AUTHENTICATION_REQUIRED = false
}

注意：10.0.2.2是Android模拟器访问开发主机本地服务的特殊地址。如果使用真机调试，需要替换为开发主机的实际局域网IP地址。

自签名证书处理方案

在开发环境中，服务端常使用自签名证书。Android默认不信任这类证书，需要特殊处理：

配置步骤

1. 添加依赖：在core-logic模块的build.gradle.kts中添加Ktor相关依赖

implementation(libs.ktor.android)
implementation(libs.ktor.logging)

2. 创建自定义HTTP客户端：新建ProvideKtorHttpClient.kt文件并实现信任所有证书的逻辑

object ProvideKtorHttpClient {
    @SuppressLint("TrustAllX509TrustManager", "CustomX509TrustManager")
    fun client(): HttpClient {
        // 实现信任所有证书的逻辑
        return HttpClient(Android) {
            // 配置细节...
        }
    }
}

3. 注入自定义客户端：修改LogicCoreModule.kt中的provideEudiWallet函数

fun provideEudiWallet(...): EudiWallet = EudiWallet(...) {
    // 使用自定义HTTP客户端
    withKtorHttpClientFactory {
        ProvideKtorHttpClient.client()
    }
}

4. 调整客户端ID方案：将X509方案替换为预注册方案

withClientIdSchemes(
    listOf(
        ClientIdScheme.Preregistered(
            preregisteredVerifiers = listOf(
                PreregisteredVerifier(
                    clientId = "Verifier",
                    legalName = "Verifier",
                    verifierApi = "https://10.0.2.2"
                )
            )
        )
    )
)

安全注意事项

1. 自签名证书配置仅适用于开发环境，生产环境必须使用正规CA签发的证书
2. 信任所有证书的实现会降低安全性，仅用于测试目的
3. 发布到生产环境前，务必移除相关调试配置

通过以上步骤，开发者可以灵活地在不同环境中构建和运行欧盟数字身份钱包应用，满足从开发到演示的各种需求。