# ActivateDevice

> 建议使用 [WMPFBoot.init](/doc/oplatform/Miniprogram_Frame/api/cli/boot/init) + [WMPFDeviceApi.activateDevice](/doc/oplatform/Miniprogram_Frame/api/cli/device/activateDevice) 接口.

> 除特殊说明外，所有其他接口都需在该接口调用成功后才能使用，失败时请重试。

用于激活设备。**每次 WMPF 启动后都需要调用一次。**

## 调用参数

在完成[接入流程](/doc/oplatform/Miniprogram_Frame/process)的所有步骤后，方可获取到 `productId` 、`keyVersion` 、`deviceId` 、`signature` 。

| 属性       | 必填 | 类型     | 说明                                                              | 最低版本   |
|------------|------|----------|-------------------------------------------------------------------|------------|
| productId  | 是   | int      | 产品 id                                                           |            |
| keyVersion | 是   | int      | 密钥版本                                                          |            |
| deviceId   | 是   | string   | 设备 id                                                           |            |
| signature  | 是   | string   | 签名（不需要换行符）                                              |            |
| hostAppId  | 是   | string   | 移动应用的 AppId ，[微信开放平台](https://open.weixin.qq.com)申请 |            |
| features   | 否   | string[] | 声明使用的特性。目前支持：voip-device                             | WMPF 1.2.0 |

- **注：对于同一台设备，hostAppId、productId、keyVersion、deviceId 在生产环境应保持不变。如果在开发调试过程中，这几个参数和上次激活时发生变化，会报错 DEVICE_CHANGED，需要手动清除 WMPF Service Apk 的应用数据。**

### features

- voip-device: 使用[小程序音视频通话（for 硬件）](/miniprogram/dev/framework/device/voip/call-wmpf.md)时，启用免维护 pushToken（暂未上线）。

## 返回参数

| 属性        | 说明                   |
|-------------|------------------------|
| invokeToken | 调用凭证，用于后续操作 |

## 示例代码
```kotlin
val request = WMPFActivateDeviceRequest().apply {
    this.baseRequest = WMPFBaseRequestHelper.checked()
    this.productId = productId
    this.keyVersion = keyVerion
    this.deviceId = deviceId
    this.signature = signature.replace(Regex("[\t\r\n]"), "")
    this.hostAppId = hostAppId
}

val result =
    WMPFIPCInvoker.invokeAsync(
        request,
        IPCInvokerTask_ActivateDevice::class.java,
        object : IPCInvokeCallbackEx {
            override fun onBridgeNotFound() {
                it.onError(Exception("bridge not found"))
            }

            override fun onCallback(response: WMPFActivateDeviceResponse) {
                if (isSuccess(response)) {
                    if (response != null && !response.invokeToken.isNullOrEmpty()) {
                        initInvokeToken(response.invokeToken)
                    }

                    it.onSuccess(response)
                } else {
                    it.onError(TaskErrorException(createTaskError(response)))
                }
            }

            override fun onCaughtInvokeException(exception: java.lang.Exception?) {
                if (exception != null) {
                    it.onError(exception)
                } else {
                    it.onError(java.lang.Exception("null"))
                }
            }
        })

if (!result) {
    it.onError(Exception("invoke activateDevice fail"))
}
```

## 注意

* 强烈推荐注册 onBridgeNotFound 、onCallback 失败回调，一旦激活失败，请重试。
* 可以先通过 [ActiveStatus](ActiveStatus) 判断是否设备是否已激活。
* signature err 是指后台发现签名中的参数与本接口传入的参数不匹配。在检验签名无误的情况下，建议按照下列指引检查：
    - 确认 WMPF 升级到 v1.1.5 及以上版本；
    - 确认生成签名时的 productId、deviceId 和所使用密钥的版本(keyVersion) 与 ActivateDevice 传入的参数一致。
    - 在开发者后台生成签名时，生成签名环境的 openssl 版本推荐使用 1.1.1，已确定 1.0.x 和 3.0.x 版本会有问题，其它版本开发者可自行尝试。
* 签名校验成功只能说明签名中包含的参数和校验时提供的参数一致，并不代表 ActivateDevice 不会报错。