文章摘要

MNSIN

先看效果

浅刻广告获取资源插件使用说明

感谢您使用浅刻广告获取资源插件。

子比主题是一款良心、厚道的好产品！创作不易，支持正版，从我做起。

浅刻官网：https://www.mnsin.com

作者联系方式：QQ 76853442

1. 插件功能说明

浅刻广告获取资源插件是给 Zibll 主题付费资源增加“看广告获取”的扩展功能。

插件不会替代 Zibll 原来的支付系统。普通付费、积分付费、会员付费仍然走 Zibll 原支付逻辑；只有文章付费模式设置为“广告获取”时，才会进入本插件的广告获取流程。

1.1 资源广告获取

管理员可以把某篇文章的付费资源设置为“广告获取”。

用户访问该资源时，前台会显示“看广告获取”按钮。用户点击后，插件会创建一次广告观看会话，展示广告后端返回的二维码。用户扫码进入小程序观看激励视频，观看完成后，PC 页面轮询到完成状态，然后给用户生成一条 Zibll 已完成订单。

生成订单后，用户就可以正常查看或下载资源。

1.2 多次广告获取

插件支持一个资源要求观看多次广告。

例如：

普通用户：3 次
VIP1：2 次
VIP2：50 次

用户每完整观看一次广告，插件记录一次进度。未达到次数时，不会生成订单，只提示还差几次。达到要求次数后，才生成订单并解锁资源。

广告进度默认 7 天内有效。

1.3 跳过广告直接购买

用户不想看广告时，可以点击“跳过广告，直接购买”。

支付金额按后台或文章单独设置的广告单价计算：

支付金额 = 剩余广告次数 × 单次广告折算金额

已经看过的广告会扣减。

例如资源需要 5 次广告，用户已看 2 次，单次广告折算 0.1 元：

剩余 3 次 × 0.1 元 = 0.3 元

跳过广告购买时仍调用 Zibll 原来的收银台，不走广告完成逻辑。

1.4 会员广告次数

后台可以分别设置普通用户、VIP1、VIP2 的观看次数。

如果文章本身设置为“广告获取”，即使 Zibll 主题原来给会员免费，也不会直接放行，仍按本插件设置的会员观看次数执行。

管理员可见资源，方便后台测试和排查。

1.5 看广告领积分

插件支持单独开启“看广告领积分”。

用户完成广告后，插件会调用 Zibll 积分函数给用户增加积分。

积分业务类型默认：

points

1.6 日志和限制

插件内置：

广告会话创建日志
广告完成日志
资源解锁日志
积分到账日志
创建广告会话频率限制
每日完成广告次数限制
进度清理
日志导出

这些功能用于排查广告接口、二维码、轮询、订单写入是否正常。

2. 插件安装

上传插件目录到：

wp-content/plugins/

后台进入：

插件 -> 启用 浅刻广告获取资源

启用后后台会出现：

浅刻广告

如果没有看到菜单，请确认当前站点已加载 Zibll 主题和 CSF 设置框架。

3. 后台设置说明

后台路径：

浅刻广告 -> 广告设置

3.1 启用看广告获取资源

总开关。关闭后前台不会显示广告获取。

3.2 广告接口域名

广告后端域名，不要带结尾斜杠。

示例：

https://api.example.com

WordPress 前台不会直接请求这个域名，而是先请求本站 admin-ajax.php，再由 WordPress 后端代理请求广告接口。

3.3 创建观看会话接口

默认：

/api/v1/app/pc-reward-ad/create

插件会向这个接口发送 POST 请求，用于创建一次广告观看会话。

3.4 检查观看结果接口

默认：

/api/v1/app/pc-reward-ad/status

插件会轮询这个接口，检查当前这一次广告是否完成。

3.5 业务类型 bizType

资源获取默认：

download

广告后端可以根据 bizType 区分业务场景。

3.6 广告参数标识

默认：

pc_rewarded_video

插件创建广告会话时会同时提交：

{
  "adParam": "pc_rewarded_video",
  "adConfigKey": "pc_rewarded_video",
  "adScene": "pc_rewarded_video"
}

广告后端可以用这个值选择不同广告平台、不同广告位或不同小程序广告配置。

3.7 接口签名密钥

如果广告后端返回签名，可以填写密钥并开启签名校验。

插件支持两种签名位置：

JSON 字段：sign
响应头：X-Signature

签名算法：

HMAC-SHA256

3.8 广告结果轮询间隔

单位：秒。

只轮询当前这一条广告是否完成。完成后立即停止轮询，不会自动连续播放下一条。

3.9 广告会话创建次数限制

限制同一用户或同一浏览器在一个时间窗口内最多创建多少次广告会话，防止刷接口。

3.10 每日完成广告次数限制

限制同一用户或同一浏览器每天最多完成多少次广告。

填 0 表示不限制。

3.11 二维码有效期

默认 120 秒。

二维码过期后，用户需要重新生成。

3.12 广告订单有效期

用户通过广告获取资源后，插件会写入一条 Zibll 已完成订单。

这里用于控制广告订单有效期。

3.13 普通用户 / VIP1 / VIP2 观看广告次数

分别设置不同用户等级需要观看几次广告。

填 0 或留空时，VIP 设置会跟随普通用户默认值。

3.14 单次广告折算金额

用于“跳过广告，直接购买”的价格计算。

跳过广告价格 = 剩余广告次数 × 单次广告折算金额

3.15 看广告领积分

开启后，用户可以通过广告获取积分。

需要 Zibll 积分函数可用。

4. 文章设置说明

编辑文章时，在 Zibll 付费配置里选择：

广告获取

只有选择“广告获取”的资源才会走本插件逻辑。

普通商品、积分商品、会员商品不会被本插件强行改成广告获取。

文章也可以单独设置广告次数和单次广告折算金额。文章单独设置优先级高于后台全局设置。

5. 前台用户流程

5.1 看广告获取资源

用户打开付费资源。
前台显示“看广告获取”。
用户点击按钮。
WordPress 请求广告后端创建会话。
前台展示二维码。
用户扫码进入小程序。
用户观看激励视频。
小程序通知广告后端该会话已完成。
PC 页面轮询到 completed=true。
插件记录一次广告进度。
如果次数够了，插件生成 Zibll 已完成订单。
页面刷新后，用户可以查看或下载资源。

5.2 跳过广告直接购买

用户点击“跳过广告，直接购买”。
插件按剩余广告次数计算价格。
调用 Zibll 原收银台。
用户支付完成后按 Zibll 原逻辑获取资源。

6. 广告接口模板

更换广告方时，推荐让广告后端统一适配下面两个接口。这样插件不用改代码，只改后台接口地址即可。

6.1 创建观看会话接口

请求方式：

POST /api/v1/app/pc-reward-ad/create
Content-Type: application/json

请求体：

{
  "source": "pc",
  "pcClientId": "当前PC用户或浏览器标识",
  "bizType": "download",
  "bizId": 391,
  "adParam": "pc_rewarded_video",
  "adConfigKey": "pc_rewarded_video",
  "adScene": "pc_rewarded_video"
}

必须返回：

{
  "code": 0,
  "message": "ok",
  "data": {
    "sessionId": "pcad_xxxxx",
    "pollToken": "poll_xxxxx",
    "qrcodeUrl": "https://api.example.com/qrcode.png"
  }
}

推荐完整返回：

{
  "code": 0,
  "message": "ok",
  "data": {
    "sessionId": "pcad_xxxxx",
    "pollToken": "poll_xxxxx",
    "miniProgramAppId": "wx你的appid",
    "miniProgramPath": "pageB/pc-reward-ad/pc-reward-ad?sid=pcad_xxxxx&token=client_xxxxx",
    "qrcodeUrl": "https://api.example.com/static/qrcode/pc-reward-ad/pcad_xxxxx.png",
    "expireAt": 1780000000,
    "expiresIn": 120,
    "status": 1,
    "statusText": "等待观看"
  }
}

字段兼容：

标准字段	兼容字段
sessionId	session_id、sid
pollToken	poll_token
miniProgramAppId	mini_program_app_id、appId、appid
miniProgramPath	mini_program_path、path
qrcodeUrl	qrCodeUrl、qrcode_url、qr_code_url、qrcode、qrCode
expireAt	expire_at
expiresIn	expires_in
statusText	status_text、msg、message

6.2 检查观看结果接口

请求方式：

GET /api/v1/app/pc-reward-ad/status?sessionId=pcad_xxxxx&pollToken=poll_xxxxx

等待观看：

{
  "code": 0,
  "message": "ok",
  "data": {
    "sessionId": "pcad_xxxxx",
    "completed": false,
    "expired": false,
    "failed": false,
    "status": 1,
    "statusText": "等待观看"
  }
}

观看完成：

{
  "code": 0,
  "message": "ok",
  "data": {
    "sessionId": "pcad_xxxxx",
    "completed": true,
    "expired": false,
    "failed": false,
    "status": 2,
    "statusText": "已完成",
    "completedAt": 1780000010
  }
}

二维码过期：

{
  "code": 0,
  "message": "ok",
  "data": {
    "sessionId": "pcad_xxxxx",
    "completed": false,
    "expired": true,
    "failed": false,
    "status": -1,
    "statusText": "二维码已过期",
    "failReason": "expired"
  }
}

广告失败：

{
  "code": 0,
  "message": "ok",
  "data": {
    "sessionId": "pcad_xxxxx",
    "completed": false,
    "expired": false,
    "failed": true,
    "status": -2,
    "statusText": "广告未完整观看",
    "failReason": "not_completed"
  }
}

7. 接口签名模板

如果开启签名校验，广告后端可以返回：

{
  "code": 0,
  "message": "ok",
  "data": {
    "sessionId": "pcad_xxxxx",
    "pollToken": "poll_xxxxx",
    "qrcodeUrl": "https://api.example.com/qrcode.png",
    "expiresIn": 120
  },
  "sign": "签名结果"
}

也可以通过响应头返回：

X-Signature: 签名结果

PHP 签名示例：

$payload = [
    'sessionId' => 'pcad_xxxxx',
    'pollToken' => 'poll_xxxxx',
    'qrcodeUrl' => 'https://api.example.com/qrcode.png',
    'expiresIn' => 120,
];

$canonical = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$sign = hash_hmac('sha256', $canonical, $secret);

注意：

sign 字段本身不参与签名。
WordPress 后台密钥必须和广告后端密钥一致。
开启签名后，签名不一致会提示广告接口签名校验失败。

8. 换广告源说明

别人换广告方时，不需要改插件代码。

只要新广告后端能按本说明的 create/status 模板返回数据，就只需要改后台配置：

广告接口域名
创建观看会话接口
检查观看结果接口
业务类型 bizType
广告参数标识
签名密钥
是否启用签名校验

如果广告方返回格式完全不一样，建议在广告后端做一层适配，把不同广告方的返回统一转换成本插件接口模板。

不建议让使用者直接改插件核心文件。

9. 哪些文件需要加密

9.1 已加密的核心文件

inc/reward-ad-download.php

这是核心业务文件，包含：

后台设置注册
文章广告获取模式接入
前台广告弹窗渲染
广告会话创建
广告状态轮询
多次广告进度记录
跳过广告购买价格计算
Zibll 订单写入
积分写入
日志记录
限流规则
签名校验
管理员可见逻辑

加密这个文件不会影响别人换广告源，因为广告源通过后台接口配置替换。

9.2 未建议加密的文件

xinghui-reward-ad.php
README.md
DEPLOYMENT.md
assets/css/reward-ad-download.css
assets/js/reward-ad-download.js
assets/js/reward-ad-editor.js

原因：

xinghui-reward-ad.php 需要保留 WordPress 插件头信息，否则后台可能识别不到插件。
CSS 和 JS 是浏览器加载资源，加密 PHP 对它们无效。
README 和 DEPLOYMENT 是使用说明，需要保留明文。

10. SourceGuardian 加密

支持 PHP 7.2 – 8.3 的版本。

使用 SG16 Pro 虚拟机模式，服务器需要安装 SourceGuardian Loader，并按面板提示在 php.ini 增加：

sourceguardian.enable_vm_hybrid=1

已测试：

插件是否能正常启用
后台“浅刻广告”菜单是否显示
前台是否能创建二维码
status 是否能轮询完成
完成广告后是否能生成 Zibll 订单
是否出现插件启用异常输出
是否出现 headers already sent

11. 最小广告后端要求

广告后端至少要做这些事：

接收 WordPress 的 create 请求。
创建广告观看会话。
生成小程序码。
返回 sessionId、pollToken、qrcodeUrl。
用户扫码进入小程序。
小程序播放激励视频。
用户完整观看后，广告后端把会话标记为完成。
WordPress 轮询 status 时返回 completed=true。
会话过期后返回 expired=true。
广告异常时返回 failed=true。

安全建议：

pollToken 只给 PC 轮询使用。
小程序码里的 token 只允许使用一次。
完成广告时校验 openid。
会话建议 120 秒过期。
完成或过期后删除二维码图片。

12. 常见问题

12.1 提示缺少广告参数

检查后台“广告参数标识”是否填写：

pc_rewarded_video

同时检查广告后端是否把该参数传到小程序页面，或根据该参数选择了正确广告位。

12.2 提示缺少 sessionId、pollToken 或 qrcodeUrl

create 接口返回不完整。

至少返回：

{
  "data": {
    "sessionId": "pcad_xxxxx",
    "pollToken": "poll_xxxxx",
    "qrcodeUrl": "https://api.example.com/qrcode.png"
  }
}

12.3 一直等待观看

检查 status 接口完成后是否返回：

{
  "data": {
    "completed": true
  }
}

12.4 会员为什么还要看广告

只要文章设置为“广告获取”，会员也按插件后台设置的会员广告次数执行。

如果想让某类会员少看广告，就在后台单独设置 VIP1 或 VIP2 的观看次数。

12.5 普通商品为什么不走广告

普通商品、积分商品、会员商品保持 Zibll 原支付逻辑。

只有付费模式明确设置为“广告获取”时，才走广告流程。

本站收集的资源仅供内部学习研究软件设计思想和原理使用，学习研究后请自觉删除，请勿传播，因未及时删除所造成的任何后果责任自负。

如果用于其他用途，请购买正版支持作者，谢谢！若您认为「MNSIN.COM」发布的内容若侵犯到您的权益，请联系站长邮箱:xing_h_j@163.com 进行删除处理。
本站资源大多存储在云盘，如发现链接失效，请联系我们，我们会第一时间更新。

THE END

建站笔记建站资源子比美化
# WordPress插件 # Zibll主题 # 浅刻广告 # 资源获取 # 看广告获取 # 广告获取插件 # 付费资源 # 积分功能