{"id":23159158,"url":"https://github.com/uptutu/yunpian-captcha","last_synced_at":"2025-04-04T18:42:05.116Z","repository":{"id":110611128,"uuid":"161765119","full_name":"uptutu/yunpian-captcha","owner":"uptutu","description":"A SDK for Yunpian captcha. Wrap the interface of the request Yunpian captcha.","archived":false,"fork":false,"pushed_at":"2020-06-14T16:34:59.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-10T03:47:51.637Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uptutu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-14T09:53:18.000Z","updated_at":"2020-06-14T16:35:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"e404854e-61f5-4a7e-ac82-ad26d588d3d0","html_url":"https://github.com/uptutu/yunpian-captcha","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptutu%2Fyunpian-captcha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptutu%2Fyunpian-captcha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptutu%2Fyunpian-captcha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uptutu%2Fyunpian-captcha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uptutu","download_url":"https://codeload.github.com/uptutu/yunpian-captcha/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234844,"owners_count":20905852,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-17T22:32:19.206Z","updated_at":"2025-04-04T18:42:05.099Z","avatar_url":"https://github.com/uptutu.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e yunpian-captcha \u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e Encapsulates the interface of the request Yunpian captcha.\u003c/p\u003e\n\n## 安装\n\n```shell\n$ composer require uptutu/yunpian-captcha -vvv\n```\n\n## 配置\n\n在使用本扩展之前，你需要去 [云片平台](https://www.yunpian.com/) 注册账号，然后创建应用，获取应用的 secret Key 和 secret Id\n\n\n\n## 前端接入云片行为验证\n\n### WEB\n\n#### 引入初始化 JS\n\n```html\n\u003cscript src=\"https://www.yunpian.com/static/official/js/libs/riddler-sdk-0.2.1.js\" /\u003e\n```\n\n#### 配置验证对象\n\n```js\nnew Riddler(options)\n```\n\n`options`对象为配置对象，具有如下参数：\n\n| 参数名       | 类型                                           | 是否必须 | 含义                                                         |\n| ------------ | ---------------------------------------------- | -------- | ------------------------------------------------------------ |\n| onSuccess    | function(token:string, close:function)         | T        | 验证成功处理器, token: 验证token，close：关闭SDK的UI         |\n| appId        | string                                         | T        | 应用标识, captchaId                                          |\n| version      | string                                         | T        | 接口版本号                                                   |\n| container    | HTMLElement                                    | T        | 验证逻辑绑定的元素                                           |\n| noButton     | boolean                                        | T        | 是否在`container`内渲染按钮，当`mode`不为`flat`时有效        |\n| mode         | string                                         | F        | UI接入方式，flat-直接嵌入，float-浮动，dialog-对话框, 默认`dialog` |\n| onError      | function                                       | F        | 验证异常处理器。即当云片验证服务出现异常时，可以在此回调上处理，比如，不使用验证，或者，使用图片验证服务等。 |\n| onFail       | function(code:int, msg:string, retry:function) | F        | 用户验证失败处理器, code: 错误码，msg: 错误信息，retry: 重试验证逻辑。默认实现为重新验证一次。 |\n| beforeStart  | function(next:string)                          | F        | 进入验证逻辑前的 勾子，next: 继续执行后续逻辑                |\n| expired      | int                                            | F        | 请求超时时间，单位秒，默认`30`                               |\n| jsonpField   | string                                         | F        | jsonp处理器名，默认为`ypjsonp`                               |\n| rsaPublicKey | string                                         | F        | 加密公钥，如非异常情况则无需设置                             |\n| hosts        | string                                         | F        | 验证服务器地址，如非异常情况则无需设置                       |\n| winWidth     | number                                         | F        | 窗口宽度，不小于300，默认500                                 |\n\n#### 本地化(可选)\n\n如果需要使用本地化的文案，可创建一个资源文件`riddler.local.js`，并在`riddler-sdk.js`之前引入即可。\n\n替换``riddler.local.js`内中文即可\n\n```js\nwindow.YP_RIDDLER_RESOURCE = {\n  '1': '点此进行验证',\n  '2': '请按顺序点击:',\n  '3': '按住按钮拖动拼图到所示位置',\n  '4': '验证失败，请重试'\n}\n```\n\n#### Demo\n\n```html\n\u003chtml\u003e\n\u003chead\u003e\n  \u003c!--可选，本地化文案--\u003e\n  \u003cscript src=\"/static/riddler-sdk.local.js\"\u003e\u003c/script\u003e\n\n  \u003c!--依赖--\u003e\n  \u003cscript src=\"https://www.yunpian.com/static/official/js/libs/riddler-sdk-0.2.1.js\"\u003e\u003c/script\u003e\n\n  \u003c!--初始化--\u003e\n  \u003cscript\u003e\n\n    window.onload = function () {\n\n      // 初始化\n      new YpRiddler({\n        expired: 10,\n        mode: 'dialog',\n        container: document.getElementById('cbox'),\n        appId: 'your-captchaId',\n        version: 'v1',\n        onError: function (param) {\n          if(param.code == 429) {\n            alert('请求过于频繁，请稍后再试！')\n            return\n          }\n          // 异常回调\n          console.error('验证服务异常')\n        },\n        onSuccess: function (validInfo, close) {\n          // 成功回调\n          alert(`验证通过！token=${validInfo.token}, authenticate=${validInfo.authenticate}`)\n          close()\n        },\n        onFail: function (code, msg, retry) {\n          // 失败回调\n          alert('出错啦：' + msg + ' code: ' + code)\n          retry()\n        },\n        beforeStart: function (next) {\n         console.log('验证马上开始')\n         next()\n        },\n        onExit: function() {\n          // 退出验证 （仅限dialog模式有效）\n          console.log('退出验证')\n        }\n      })\n    }\n  \u003c/script\u003e\n\u003c/head\u003e\n\n\u003cbody\u003e\n  \u003cdiv id=\"cbox\"\u003e\u003c/div\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n#### 重点：\n\nDemo 中可以看见回调成功后会有两个重要的值，token 和 authenticate \n\n将这两个值传给后端，后端将这两个值和一一些必要一起再请求云片，通过云片响应得到判断此次验证结果。\n\n## 使用\n\n### 实例化 SDK\n\n```php\nuse Uptutu\\YunpianCaptcha\\YunpianCaptcha;\n\n$secretId = \"xxxxxxxxxxx\";\n$secretKey = \"xxxxxxxxxx\";\n$captchaId = \"xxxxxxxxxx\";\n\n$y = new YunpianCaptcha($secretId, $secretKey, $captchaId);\n  \n```\n\n### 设置必要参数\n\n```php\n$parmas = [\n    'captchaId' =\u003e 'yunpian.captchaId',\n    'token' =\u003e 'token',\n    'authenticate' =\u003e 'authenticate',\n    'secretId' =\u003e 'yunpian.secretId',\n    'version' =\u003e '1.0',\n    'timestamp' =\u003e time(),\n    'nonce' =\u003e random_int(1,99999)\n];\n\n$y-\u003esetParams($parmas);\n```\n\n\n\n#### 请求参数\n\n| 参数         | 类型   | 必填 | 备注                                                         |\n| ------------ | ------ | ---- | ------------------------------------------------------------ |\n| captchaId    | string | Y    | 验证产品 id                                                  |\n| token        | string | Y    | 前端返回的 token，token 作为一次验证的标志。                 |\n| authenticate | string | Y    | 用户验证通过后，返回的参数                                   |\n| secretId     | string | Y    | 验证产品密钥 id                                              |\n| version      | string | Y    | 版本，固定值`1.0`                                            |\n| user         | string | F    | 可选值，接入方用户标志，如担心信息泄露，可采用摘要方式给出。 |\n| timestamp    | string | Y    | 当前时间戳的毫秒值，如`1541064141441`                        |\n| nonce        | string | Y    | 随机正整数, 在 1-99999 之间，与 timestamp 配合可以防止消息重放 |\n| signature    | string | Y    | 签名信息                                                     |\n\n- SDK 中的另外一个方法能计算出 符合要求的 signature 值，但前提是必须有相必要的值都被设置了。 captchaId、 secretId 和 signature 能被 setSignature() 方法自动传入选项。所以，可以不必在 setParams() 的方法中传入这三个字段 \n\n\n\n### 设置签名\n\n先来看看官方给出的 signature 计算方法：\n\n#### 签名计算方法\n\n1. 对所有请求参数（不包括 signature 参数），按照参数名ASCII码表升序顺序排序。如：foo=1， bar=2， foo_bar=3， baz=4 排序后的顺序是 bar=2， baz=4， foo=1， foo_bar=3 。\n2. 将排序好的参数名和参数值构造成字符串，格式为：key1+value1+key2+value2… 。根据上面的示例得到的构造结果为：bar2baz4foo1foo_bar3 。\n3. 选择与 secretId 配对的 secretKey ，加到上一步构造好的参数字符串之后，如 secretKey=`e3da918313c14ea8b25db31f01263f80` ，则最后的参数字符串为 `bar2barz4foo1foo_bar3e3da918313c14ea8b25db31f01263f80`\n4. 把3步骤拼装好的字符串采用 utf-8 编码，使用 MD5 算法对字符串进行摘要，计算得到 signature  参数值，将其加入到接口请求参数中即可。MD5  是128位长度的摘要算法，用16进制表示，一个十六进制的字符能表示4个位，所以签名后的字符串长度固定为32位十六进制字符。上述签名的结果为：`59db908f26fb997c30b32ddb911485c2`\n\n当然，你可以自己计算然后通过 setParams() 方法将 signature 值传递进去，但是这样的话你还要这个 SDK 做什么\n\n只需要对实例化的 SDK 执行下面的方法\n\n```php\n$y-\u003esetSignature();\n```\n\n该方法会自动计算 signature 值并添加到请求项中，这一步，也会自动将实例化 SDK 时候的三个有用的值('secretId','secretKey', 'captchaId') 加入请求项\n\n### 获取结果\n\n该 SDK 有两种检查方式\n\n1. ```php\n   $y-\u003echeck();\n   ```\n\n1. ```php\n   $y-\u003egetCheckedResponseContent();\n   ```\n   \n  1. ```php\n      $y-\u003echeckRequest($request);\n      ```\n\n第一种方式返回的是一个请求结果，布尔值，此次验证的成功与否，True 或者 False, 但在调用前务必调用`setParams()` 方法将云片服务端需要的参数传入。\n\n第二种方式返回的是该次请求返回的数据，也就是文档中的 code 和 msg\n\n第三种是直接把前端用户行为验证成功后收到的 token  和 authenticate 用数组的形式传递 直接判断该次验证是否有效。\n\n#### 相应参数\n\n| 参数 | 类型   | 必填 | 备注                   |\n| ---- | ------ | ---- | ---------------------- |\n| code | int    | Y    | 成功为0，非0为异常信息 |\n| msg  | string | Y    | 错误描述信息           |\n\n\n\n## 示例\n\n```php\n\u003c?php\n\nnamespace Example;\n\nuse Uptutu\\YunpianCaptcha\\YunpianCaptcha;\n\n$secretId = \"xxxxxxxxxxx\";\n$secretKey = \"xxxxxxxxxx\";\n$captchaId = \"xxxxxxxxxx\";\n\n$y = new YunpianCaptcha($secretId, $secretKey, $captchaId);\n\n$parmas = [\n    'token' =\u003e 'token',\n    'authenticate' =\u003e 'authenticate',\n    'version' =\u003e '1.0',\n    'timestamp' =\u003e time(),\n    'nonce' =\u003e random_int(1, 99999)\n];\n\n$y-\u003esetParams($parmas);\n$y-\u003echeck(); // return False or True\n\n$request = ['token' =\u003e '收到前端异步成功回调里的token', 'authenticate' =\u003e '收到前端异步成功回调里的authenticate'];\n$y-\u003echeckRequest($request); // return False or True\n\n// 建议如此使用\nif ($y-\u003echeckRequest($request)){\n    // Do Something\n} else {\n    // Do Something else\n}\n\n// 如果你想要返回的详细内容\n$result = $y-\u003egetCheckResponse();\n\nvar_dump($result);\n\nif ($y-\u003echeck()){\n    // Do Something\n} else {\n    // Do Something else\n}\n```\n\n\n\n## Contributing\n\nYou can contribute in one of three ways:\n\n1. File bug reports using the [issue tracker](https://github.com/uptutu/yunpianCaptcha/issues).\n2. Answer questions or fix bugs on the [issue tracker](https://github.com/uptutu/yunpianCaptcha/issues).\n3. Contribute new features or update the wiki.\n\n_The code contribution process is not very formal. You just need to make sure that you follow the PSR-0, PSR-1, and PSR-2 coding guidelines. Any new code contributions must be accompanied by unit tests where applicable._\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuptutu%2Fyunpian-captcha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuptutu%2Fyunpian-captcha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuptutu%2Fyunpian-captcha/lists"}