畅言社会化评论系统社交评论插件开发

畅言 社会化评论系统 技术文档Web 网站接入指南概述畅言提供了多种接入方式，开发者可以按需选择：使用 JS 嵌入的方式；直接调用畅言开放 API 接口的方式多种接入方式1、JS 嵌入流程注册完成后出现如下图界面JS 代码嵌入JS 代码嵌入是最简易的网站接入方式。将生成的 JS 代码复制并粘贴到您网页需要的地方；如果您的网站使用的模板，您也可以复制代码到您的模板中，社会化评论框将在所有网页自动出现，此时您就可以轻松获取畅言服务！2、API 接口调用除了使用 JS 代码嵌入方式外，您还可以通过调用畅言平台的 API 接口，获得更深度的定制。具体的 API调用方式及接口说明文档，请参考 开放平台-API 开放接口。注意：当您使用 JS 嵌入的方式来生成评论框，但是文章没有唯一 URL 地址时，或者对于同一篇文章有多页展示，但是需要显示的是相同的评论内容时，可以配置 source id 来区分文章（即文章的 id）。具体如何配置，请参考 高级开发-自定义配置自定义配置概述在插入通用代码时，可以增加一些参数，来实现自定义的功能配置 source id当您使用 JS 嵌入的方式来生成评论框，但是文章没有唯一 URL 地址时，或者对于同一篇文章有多页展示，但是需要显示的是相同的评论内容时，可以配置 source id 来区分文章（即文章的 id）。“#source id#“是您需要配置的部分，如下图配置 owner id当您需要使用删除通知接口时，需要先配置 owner id（即文章所有者的 id）。“#owner id#“是您需要配置的部分，如下图发布者删除评论概述对于 UGC（如博客等）类网站，当内容发布者发布的内容被评论，但是却想要删除此评论时，畅言提供了以下解决方案。在使用前请先配置 owner id。具体如何配置，请参考 高级开发-自定义配置发布者删除评论1、删除评论流程图如下2、验证接口（需要您提供）描述：用于验证当前登录用户是否为内容发布者URL： 点击到后台设置中填写请求方式：GET请求参数：参数名 类型 是否必须 说明owner_id String Y 内容所有者 ID-由您提供topic_url String N 当前页面的 URL，和 topic_source_id 二选其一topic_source_id String N 内容 ID，和 topic_url 二选其一 -由您提供返回：JSON 格式字段名 类型 说明owner int 有无删除评论的权限（1：有权限， 0：无权限）代码样式“owner“: 13、验证删除信息接口（需要您提供）描述：验证前端发起的删除请求是否内容所有者发起URL： 点击到后台设置中填写请求方式：POST请求参数：参数名 类型 是否必须 说明client_id String Y APP ID-由畅言供owner_id String Y 内容所有者 ID-由您提供topic_id String Y 新闻 ID畅言 IDcomment_id String Y 评论 ID畅言 IDtopic_url String N 当前页面的 URL，和 topic_source_id 二选其一topic_source_id String N 文章 ID，和 topic_url 二选其一 -由您提供返回：JSON 格式字段名 类型 说明success int 是否删除成功（1：删除成功， 0：删除失败）代码样式“success“: 14、删除评论接口（畅言提供）描述：验证通过后，调用畅言删除接口URL：/api/open/ugc/comment/delete请求方式：POST请求参数：参数名 类型 是否必须 说明client_id String Y APP ID-由畅言供owner_id String Y 内容所有者 ID-由您提供topic_id String Y 新闻 ID畅言 IDcomment_id String Y 评论 ID畅言 IDsign String Y签名方式为按照所有参数（除 sign 参数外）的字典顺序即 name=value 的形式以)4、获取用户信息接口（需要您提供）描述：畅言调用此接口，查询是否有用户登录（若有则畅言实现同步登录）URL： 点击到后台设置中填写请求方式：GET请求参数：参数如下参数名 类型 是否必须 说明callback String Y 回调函数返回：Jsonp 格式，返回参数如下参数名 类型 说明cy_user_id int 畅言 uidnickname String 第三方接入网站用户的昵称，长度小于 63 个字节（如果为空则传空字符串） 。img_url String 第三方接入网站用户的头像，长度小于 1023 个字节（如果为空则传空字符串） 。profile_url String 第三方接入网站用户的个人中心地址，长度小于 1023 个字节（如果为空则传空字符串） 。user_id String 第三方接入网站的用户 id，长度小于 100 个字节（如果为空则传空字符串）is_login int 用户是否登录标志 0 表示未登录， 1 表示已登录（登录需要返回user 对象）sign String参数签名信息。签名方式为按照所有参数(除 sign 参数外)的字典顺序即 name=value 的形式以&符号链接起来，然后以client_secret 作为密钥进行用 HMACSHA1 算法进行签名）isv 应该对所有入参（除 sign 外）计算签名，然后与此参数进行比较，以防止参数被篡改。callback String 回调函数返回代码示例：已登录用户，假设参数 callback 的值为“aaa“aaa( “is_login “: 1,“user“: “img_url“: “/r/www/cache/xmas2012/images/car.png“,“nickname“: “aaas“,“profile_url“: ““,“user_id“: 42417,“cy_user_id“:“23243“,“sign“:“werdfasdfasdf“)返回代码示例：未登录用户,假设参数 callback 的值为“aaa“aaa(“is_login “: 0)5、用户退出接口（由您提供）描述：当畅言退出时，调用此接口，实现用户在您的网站退出URL： 点击到后台设置中填写请求方式：GET请求参数：参数如下参数名 类型 是否必须 说明code int Y 0 退出失败，1 退出成功callback String Y 回调函数返回：Jsonp 格式，返回参数如下参数名 类型 说明code int 0 退出失败，1 退出成功返回代码示例：假设参数 callback 的值为“aaa“aaa(“code“：1)6、畅言退出接口（由畅言提供）描述：当用户单点登录成功后，用户在第三方退出时，第三方需要调用畅言的退出接口，以通知畅言也让此用户在畅言退出。URL：/api/services/user/logout请求方式：GET请求参数：参数如下参数名 类型 是否必须 说明callback String Y 回调函数返回格式：Jsonp 格式参数名 类型 说明code int 0 退出失败，1 退出成功返回代码示例：假设参数 callback 的值为“aaa“aaa(“code“：1)Oauth 认证Oauth2.01、Oauth2.0 概述Oauth2.0 认证框架提供了第三方应用的认证流程，第三方应用可以通过 HTTP 服务获得有限的资源访问权限，即第三方应用可以通过该协议获取访问畅言系统部分资源的权限。通过该认证方式保证用户的密码不会泄露给第三方应用，同时用户还可以选择性地授权第三方应用访问用户自己有限的信息。2、Oauth2.0 流程畅言 Oauth2.01、畅言 Oauth2.0 概述由于畅言支持社会化登录，所以授权相对复杂些。在使用前请先申请 client_id 与 client_secre。畅言开放平台的 Oauth2.0 认证框架支持的认证方式为：授权码(Authorization Code)认证。第三方应用首先通过client_id 和 RedirectUri 引导用户进入畅言平台的认证接口，当用户认证成功后会通过 HTTP Redirect 的方式将该 Code 传递给第三方提供的 Redirect Uri。然后第三方通过该 Authorization Code 和自己申请到的 client_secret 向畅言服务器请求获取 AccessToken，如果全部成功则畅言服务器返回一个AccessToken 给第三方。之后第三方就可以通过该 AccessToken 访问畅言系统的 OAuth API。畅言平台的 Oauth2.0 暂不支持 RefreshToken 的策略。2、畅言 Oauth2.0 流程3、获取 AuthorizationCode接口名：/api/oauth2/authorizeURL：/api/oauth2/authorize请求方式：GET请求参数：参数名 类型 是否必须 说明client_id String Y 畅言 appIdredirect_uri String Y 授权回调地址，必须和用户注册时填的一致response_type String Y 响应类型,必须为 codescope String N 用户授权时向用户显示的可进行授权的列表platform_id long Nplatform_id 可取0(具体的第三方登录页 2为新浪、3 为 qq、4 为腾讯微博、5 为网易微博、6 为人人、7 为百度、8 为豆瓣、11 为搜狐 Passport)、默认（游客和第三方）state String N client 端的状态值,用于第三方应用防止CSRF 攻击，成功授权后回调时会原样带回。display String N授权页面的终端类型，取值见下面的说明。（default 默认的授权页面，适用于 web 浏览器；mobile 指移动设备）。scope String N 用户授权时向用户显示的可进行授权的列表返回：字段名 类型 说明Code String 用户授权的 codeState String 如果请求时传递了 state 参数，会回传该参数代码样式请求授权 code/api/oauth2/authorize? client_id= cy11Xlbrmzyh&redirect_uri=& response_type=code&platform_id=-1如果授权成功，畅言授权服务器会将用户浏览器重定向到 redirect_uri?code=CODE第三方应用（ISV）获取到畅言授权的 code（code 有效期为 10 分钟，且只能使用一次）之后，就可以使用此 code 调用/api/oauth2/token 接口，换取用户授权的 access_token。4、获取 AccessToken接口名：/api/oauth2/tokenURL：/api/oauth2/token请求方式：POST请求参数：参数名 类型 是否必须 说明client_id String Y 畅言 appIdclient_secret String Y appKeygrant_type String Y响应类型（可以为authorization_code、password、refresh_token），当前只支持 authorization_codecode String N 授权接口返回的授权码（当参数 grant_type值为 authorization_code 必填)redirect_uri String N 回调地址（当参数 grant_type 值为authorization_code 必填）refresh_token String N 用于刷新的 refresh_token（当参数grant_type 值为 refresh_token 必填）返回：字段名 类型 说明access_token String 访问畅言用户资源的凭证，调用开放接口时需要expires_in long access_token 的失效时间，单位为秒代码样式“access_token“: “10000|5.a6b7dbd428f731035f771b8d15063f61.86400.1292922000-222209506“,“expires_in“: 87063分类 接口 接口说明api/open/topic/load加载文章的评论列表。根据文章topic_source_id 或者 URL 获取文章id(topic_id)，并返回第一页评论信息api/open/comment/list 通过分页方式获得评论数据api/open/user/info获取登录用户的信息(包括绑定的账号）基本接口api/open/user/comment/submit 发表评论并分享到第三方分类 接口 接口说明api/open/user/passport/unbinding 解除用户（某个账号）的绑定用户接口api/oauth2/binding绑定（第三方开放平台账号到当前登录）用户api/open/user/comment/share 只分享评论（到第三方开放平台）api/open/user/comment/reply 获取用户收到的最新回复列表api/open/comment/reply 获取某个评论的回复列表api/opentopic/comment/sum 获取文章评论总数api/open/topic/info获取文章的新闻评论数、参与数、喜欢数评论接口api/open/user/attachment/add 上传图片喜欢接口 api/open/topic/action 喜欢（文章）顶踩接口 api/open/comment/action 顶/踩（回复）错误代码概述当接入方调用开放 API 出现错误时，返回相应的错误代码。错误代码由五位数字组成，从左到右，第一数字表示服务级错误，第二位和第三位表示服务模块代码，第四位和第五位表示具体错误代码第一数字 第二、三个数字 第四、五个数字服务级错误（1 为业务错误，2 为权限错误） 服务模块代码 具体错误代码业务错误1、服务模块错误代码错误代码 错误类型00 通用错误01 主体02 用户2、具体业务错误代码错误代码 错误类型10000 系统内部错误10001 非法的请求参数10002 验证码错误10100 文章 url 或者文章 id 为空10200 不能解绑当前登录用户10201 不能主动绑定来自同一平台的 2 个用户10202 同一平台用户绑定数不能超过 5 个10203 游客昵称包含非法词10204 游客昵称或邮箱长度过长10205 解绑的账号不属于没有与登录用户过权限错误1、服务模块错误代码错误代码 错误类型00 通用错误01 Oauth 授权验证02 频率控制2、具体业务错误代码错误代码 错误类型20000 Oauth 授权验证异常20101 code 过期20102 code 非法20103 code 重复使用20104 token 过期20105 token 非法20106 签名错误20107 非法的 client_id20108 redirect_uri 非法20109 参数 response_type 必须为 code20110 参数 grant_type 必须为authorization_code20111 缺少 Oauth 授权参数20112 参数 nonce 的值重复使用数据导出概述畅言提供了数据导出功能，用户可以根据自己的需要导出特定时间段的数据,不包括删除的评论,不包括删除的评论导出数据的格式说明参数名 类型 说明success boolean 数据是否导出成功message String 错误信息，导出失败时提示comments JSON 评论数组 评论列表topicUrl String 文章 URLtopicTitle String 文章标题topicId long 文章 IDsourceTopicId String 文章的原始 IDtopicLikeSum long 文章的被喜欢数topickShareSum long 文章被分享数cmtId long 评论 IDcontent String 评论内容attachs Json 数组 图片评论ctime Date 评论发表时间sp long 评论被顶次数op long 评论被踩次数replyId long 所回复的评论的 ID，为 0 表示没有回复其他评论nickname String 用户昵称from String 用户账号来源iconUrl String 用户头像(如果为空，表示使用默认头像）userProfileUrl String 用户个人主页代码样式“success“: true,“comments“: “attachs“: “url“: “/comment/o5NB5aX_png“,“cmtId“: 36475,“content“: “分享图片 5555“,“ctime“: “2013-05-14 16:13:25“,“from“: “游客“,“iconUrl“: “,“nickname“: “赢者无敌 1914“,“op“: 0,“replyId“: 0,“sourceTopicId“: “,“sp“: 0,“topicId“: 897,“topicLikeSum“: 0,“topicTitle“: “Insert title here+finalJs-用户信息完毕“,“topicUrl“: “http:/localhost:8081/“,“topickShareSum“: 0,“userProfileUrl“: “/u/s3000019708561“,“attachs“: ,“cmtId“: 36474,“content“: “1223“,“ctime“: “2013-05-14 16:09:53“,“fr