# Vivo 账户授权操作文档

更新时间：2026-08-19

## 1. 文档目的

本文用于指导业务或运营同学完成 Vivo 二代账户授权。  
授权完成后，系统才能将百度转化数据回传给对应的 Vivo 投放账户。

## 2. 适用范围

- 适用于需要接入 Vivo 转化回传的广告账户
- 一个 `secondaryAccountId` 需要单独授权一次
- 同一个二代账号下的投放账户共用这一套授权 token

## 3. 授权后的作用

授权成功后，系统会为该 `secondaryAccountId` 获取并保存：

- `access_token`
- `refresh_token`

系统后续会自动使用该账户 token 进行 Vivo 转化回传，并自动处理 token 刷新，无需人工重复操作。

## 4. 回调地址

本项目 Vivo 授权回调地址为：

```text
https://tencent.bjhcstszkj.cn/vivo/callback
```

## 5. 授权链接说明

Vivo 授权链接格式如下：

```text
https://open-ad.vivo.com.cn/OAuth?clientId={数据库维护的clientId}&state={secondaryAccountId}&redirectUri=https%3A%2F%2Ftencent.bjhcstszkj.cn%2Fvivo%2Fcallback
```

说明：

- `clientId`：由技术在数据库中维护，不再写死在配置文件
- `state`：请填写当前需要授权的 Vivo 二代账户 ID，即 `secondaryAccountId`
- `redirectUri`：固定回调地址，无需修改

## 6. 操作步骤

### 步骤一：确认待授权账户

先确认本次需要授权的 Vivo 二代账户 `secondaryAccountId`。

例如：

```text
123456789
```

### 步骤二：生成对应授权链接

将上面的 `secondaryAccountId` 替换进 `state` 参数中。

例如，若二代账户 ID 为 `123456789`，数据库维护的 `clientId` 为 `20260819030`，则授权链接为：

```text
https://open-ad.vivo.com.cn/OAuth?clientId=20260819030&state=123456789&redirectUri=https%3A%2F%2Ftencent.bjhcstszkj.cn%2Fvivo%2Fcallback
```

### 步骤三：使用该账户登录并授权

1. 打开授权链接
2. 使用对应的 Vivo 二代账户登录
3. 按页面提示完成授权确认

注意：

- 必须使用目标二代账户本人或有授权权限的账号进行操作
- 不同 `secondaryAccountId` 不能共用一次授权

### 步骤四：等待跳转完成

授权成功后，页面会自动跳转到：

```text
https://tencent.bjhcstszkj.cn/vivo/callback
```

系统收到回调后，会自动完成 token 保存。

成功时，页面一般会返回类似结果：

```json
{
  "secondaryAccountId": "123456789",
  "tokenExpireAt": 1780000000000,
  "refreshTokenExpireAt": 1790000000000,
  "authorized": true
}
```

只要看到 `authorized: true`，即可视为授权成功。

## 7. 授权成功后的系统行为

授权成功后，系统会自动：

1. 保存该账户的授权 token
2. 后续回传时优先使用缓存 token
3. token 临近过期时自动刷新
4. 刷新后自动更新缓存和数据库

业务侧无需额外处理。

## 8. 常见问题

### 8.1 一个账户需要授权几次？

通常一个 `secondaryAccountId` 授权一次即可。  
只有在以下情况可能需要重新授权：

- Vivo 侧主动失效授权
- refresh token 失效
- 账户权限发生变化

### 8.2 多个账户是否可以共用一次授权？

不可以。  
每个 `secondaryAccountId` 需要单独授权。

### 8.3 授权成功后多久可以使用？

通常授权回调成功后即可使用。

### 8.4 如果授权后仍无法回传怎么办？

请提供以下信息给技术排查：

- 授权使用的 `secondaryAccountId`
- 授权时间
- 授权链接
- 回调页面返回内容截图

## 9. 业务侧操作模板

如果需要发给业务同学，可以直接使用下面这段话：

```text
请使用对应的 Vivo 投放账户打开以下授权链接并完成授权：

https://open-ad.vivo.com.cn/OAuth?clientId={数据库中的clientId}&state={secondaryAccountId}&redirectUri=https%3A%2F%2Ftencent.bjhcstszkj.cn%2Fvivo%2Fcallback

说明：
1、请将 {secondaryAccountId} 和 {clientId} 替换为实际值
2、必须使用该二代账户本人或具备授权权限的账号登录
3、授权成功后页面会自动跳转到回调地址
4、若页面返回 authorized=true，则表示授权成功
```

## 10. 备注

当前项目正式授权回调域名为：

```text
https://tencent.bjhcstszkj.cn
```

当前授权回调完整地址为：

```text
https://tencent.bjhcstszkj.cn/vivo/callback
```