将 PartnerShare 内嵌到产品中

1. 接入模式 #

1. 产品前端：用户进入推广中心入口时，请求自身服务端获取访问 Token。前端不接触 API Secret。
2. 产品服务端：使用 API Key、时间戳和 API Secret 签名，调用 PartnerShare 登录接口换取推广者 Token，返回给前端。
3. 产品前端：使用 Token 拼接 iframe 地址并渲染，推广中心在当前页面内展示。

登录接口需要签名鉴权，API Secret 只能保存在服务端。前端不得直接调用 PartnerShare 接口。

2. 页面效果 #

3. 前置要求 #

• 已在 PartnerShare 后台完成产品创建与基础配置。
• 已完成推荐计划活动、奖励规则和推广 URL 配置，且活动处于进行中。
• 已获取该产品的 API Key 和 API Secret，鉴权方式见 API 鉴权与签名机制。

4. 获取推广者登录 Token #

按 user_id 在当前产品下查找推广者：不存在时自动创建推广者账号并加入默认推荐计划；已存在时复用并刷新登录状态。

4.1 请求头 #

4.2 请求参数 #

4.3 请求示例 #

curl -X POST "https://api-service.partnershare.net/api/open/v1/promoter/login" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pk_xxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Api-Timestamp: 1776677721" \
  -H "X-Api-Sign: {signature}" \
  -d '{"user_id":"user_10001","email":"user@example.com","username":"Alex","lang":"zh","theme_mode":"light"}'

4.4 响应示例 #

{
  "code": 0,
  "message": "Success",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "user_string_id": "ps8xk2m9qa",
    "lang": "zh",
    "theme_mode": "light"
  }
}

4.5 响应字段 #

4.6 错误 #

5. 创建 iframe #

前端从自身服务端获取 Token 后，将 iframe 的 src 设为推广中心地址：

<iframe
  src="https://promoter.partnershare.net/iframe/{token}"
  width="100%"
  height="900"
  frameborder="0"
  allow="clipboard-write"
></iframe>

每次进入推广中心页面时实时向服务端请求新的 Token 再渲染。不要把 Token 固定写入页面或长期缓存在前端。

6. 前后端分工 #

// 前端只请求自身服务端，不直接请求 PartnerShare
async function mountPartnerShareIframe() {
  const res = await fetch('/api/partner-share/iframe-token');
  const data = await res.json();
  document.querySelector('#partnerShareIframe').src =
    `https://promoter.partnershare.net/iframe/${data.token}`;
}

7. 常见问题 #

8. 接入检查清单 #

• 前端没有保存或暴露 API Secret。
• 服务端每次请求都重新生成时间戳和签名。
• 同一业务用户始终使用稳定的 user_id。
• iframe 使用最新 Token 渲染，失效后可重新获取。