程序化创建Vuforia Targets及Android端Vuforia API实操咨询

阿华AIGC实验室

2026-5-21

嘿，我来帮你理清楚程序化创建Vuforia Targets（Android原生、不用Unity）的入门路径和关键知识点！

核心前置知识

熟悉Android原生开发（Java/Kotlin）：毕竟要脱离Unity做原生应用，得能搞定Activity生命周期、权限申请、相机调用这些基础操作，不然连项目都搭不起来。
吃透Vuforia的核心概念：先把Dataset（数据集）、Target（识别目标）、Cloud/Device Database这些术语搞明白，官方文档里的基础概念部分一定要过一遍，不然看API会像看天书。
掌握REST API基础：程序化创建Target要调用Vuforia的Cloud API，得会用OkHttp/Retrofit这类库发HTTP请求，能解析JSON响应，还要懂HMAC签名这种身份验证方式。
权限与安全意识：Vuforia API需要Access Key和Secret Key，得知道怎么安全存储这些密钥（别硬编码在代码里），还要熟悉Android的相机、网络权限申请流程。

Android原生入门简易教程（非Unity）

步骤1：准备Vuforia开发者环境

先去Vuforia开发者后台注册账号，创建一个Cloud Recognition类型的数据库，拿到对应的Access Key和Secret Key——这俩是调用API的通行证，别弄丢了。

步骤2：搭建Android项目并集成Vuforia Engine

新建一个Android项目（选Java或Kotlin都行），在项目的build.gradle里添加Vuforia的依赖，或者手动导入SDK里的aar包。
配置AndroidManifest.xml：添加相机权限、网络权限，还要加上Vuforia需要的meta-data（把你的Access Key填进去）。

步骤3：实现物体/图像扫描

先从简单的2D Image Target入手：

用Android原生相机API或者Vuforia自带的相机控制类，捕获一张清晰的图像（要求分辨率至少640x480，纹理丰富，避免纯色或模糊的图）。
如果要做3D Object Target：
用Vuforia的ObjectScanner类，它会引导用户围绕物体多角度拍摄，生成扫描所需的点云数据，这个类的用法可以参考官方的扫描示例。

步骤4：调用Vuforia Cloud API上传目标

这是核心步骤，要构造符合要求的HTTP请求：

向https://vws.vuforia.com/targets发送POST请求，用Multipart表单上传目标名称、宽度（2D Target）、图像/点云文件。
请求头里必须带上用Access Key和Secret Key生成的HMAC SHA-256签名，Vuforia靠这个验证你的身份。
给你一段Kotlin示例代码（用OkHttp）：

val okHttpClient = OkHttpClient()
// 构造表单数据
val requestBody = MultipartBody.Builder()
    .setType(MultipartBody.FORM)
    .addFormDataPart("name", "MyFirstTarget")
    .addFormDataPart("width", "50.0") // 单位是毫米
    .addFormDataPart("image", "target_image.jpg", 
        RequestBody.create(MediaType.parse("image/jpeg"), File("/path/to/your/image.jpg")))
    .build()

// 生成HMAC签名（这里需要你自己实现generateHmacSignature方法，按照Vuforia文档的算法来）
val authHeader = "VWS ${yourAccessKey}:${generateHmacSignature(requestBody, yourSecretKey)}"

val request = Request.Builder()
    .url("https://vws.vuforia.com/targets")
    .addHeader("Authorization", authHeader)
    .addHeader("Content-Type", "multipart/form-data")
    .post(requestBody)
    .build()

// 发送异步请求
okHttpClient.newCall(request).enqueue(object : Callback {
    override fun onFailure(call: Call, e: IOException) {
        // 处理请求失败逻辑，比如网络错误
        e.printStackTrace()
    }

    override fun onResponse(call: Call, response: Response) {
        response.body()?.string()?.let { responseBody ->
            // 解析返回的JSON，拿到Target ID和状态
            println("Response: $responseBody")
        }
    }
})

步骤5：验证并加载目标

上传后，Vuforia需要一点时间处理目标，你可以调用/targets/{targetId}的GET接口查询状态，等状态变成active后，就可以在应用里用CloudRecoService加载你的Cloud Database，开始识别目标了。

实用提示

先从2D Image Target练手，比3D Object Target简单很多，容易快速看到效果。
官方的Vuforia Engine Android Samples里有Cloud Recognition的示例代码，直接参考里面的API调用和签名生成逻辑，能少踩很多坑。
调试API的时候，先用Postman测试请求，确保签名和参数都正确，再写到代码里，效率更高。

内容的提问来源于stack exchange，提问作者Amine