================
服务端SDK
================
.. include:: ../baidu.rst
.. contents:: 目录
	:depth: 4



基本介绍
==============

服务端的SDK存在的目的是为了让真正的验证请求和回答都来自于可信的终端：网站主服务器和极验服务器。

极验为每一种服务器端开发语言提供了SDK，并以web客户端为例子提供了相应的Demo，开发人员可以快速的搭建起相应的演示程序。

开发人员使用Demo提供的默认验证模块快速搭建本地应用并成功运行后，只需要经过如下步骤做出相应修改就可以完成个人专属验证模块的绑定


1. 从 `验证后台 <http://user.geetest.com/>`__ 注册账号
#. 添加验证，可以获取一组当前验证的ID/Key
#. 将ID和Key分别替换到Demo项目中的captcha_id/private_key变量的值
#. 检验验证Demo正常运行。运行Demo程序，手动拖动验证模块并通过验证，重复几次，查看后端SDK验证结果是否一致
#. 检验验证后台统计工具。从 `验证后台 <http://user.geetest.com>`__ 查看相应的验证模块的验证统计数据变化
#. 顺利完成环境搭建,而且和您的专属验证模块成功绑定

SDK接口说明
====================

极验 **sdk3.0.0** 版本开始对后端服务器sdk接口进行了重新设计以及统一
并且在 **sdk3.1.0** 版本后更新了一个防刷特性, 因为改变了接口所以老用户并没有开启,如果需要开启请先联系极验客服

现在每个语言的SDK基本只提供5个接口:
* 构造函数
* 预处理接口
* 获取预处理结果的接口
* 极验服务器状态正常的二次验证接口
* 极验服务器状态宕机的二次验证接口

接下来会对每个接口进行说明,但是不会涉及具体的使用环境,具体的使用环境会在之后各个开发语言里去具体说明

..  _constructer:

构造函数
--------------

* 作用: 初始化GeetestLib对象
* 参数: 接受2个参数
	* para1: **string**, 验证ID
	* para2: **string**, 验证Key

..  _pre-process:

预处理接口
--------------

* 作用: 判断极验的服务器状态, 并生成好验证初始化的标准串,
* 参数: 有两个重载
	* 重载1: 不接受任何参数
	* 重载2: 接受1个参数, 为当前用户的标识
		* para1: **string**, 当前用户的标识
* 返回: **Int**, 1 表示极验服务器状态正常, 0 表示极验服务器宕机
* **PS**: 开发者需要自己把这个服务状态保存到session中

..  _get-response-str:

获取预处理结果的接口
------------------------------------

* 作用: 获取预处理结果标准串, 用于返回给前端初始化验证

* 参数: **不接受任何参数**

* 返回: **string**

..  _sucess-validate:

极验服务器状态正常的二次验证接口
---------------------------------------------

* 作用: 向极验服务器请求验证结果

* 参数: 有两个重载
	* 重载1: 接受3个参数, 为http请求的表单值
		* para1: **string**, 对应的表单 `key` 为 **geetest_challenge**
		* para2: **string**, 对应的表单 `key` 为 **geetest_validate**
		* para3: **string**, 对应的表单 `key` 为 **geetest_seccode**
	* 重载1: 接受4个参数, 前三个参数为http请求的表单值, 最后一个参数为用户标识
		* para1: **string**, 对应的表单 `key` 为 **geetest_challenge**
		* para2: **string**, 对应的表单 `key` 为 **geetest_validate**
		* para3: **string**, 对应的表单 `key` 为 **geetest_seccode**
		* para4: **string**, 当前用户的标识
* 返回: **Int**, 1 表示验证通过， 0 表示验证未通过

* **PS**: 如果session中保存的极验服务器状态为正常情况下使用的二次验证

..  _fail-validate:

极验服务器状态宕机的二次验证接口
-------------------------------------------

* 作用: 极验服务器宕机情况下在本地完成二次验证

* 参数: 接受3个参数, 为http请求的表单值
	* para1: **string**, 对应的表单 `key` 为 **geetest_challenge**
	* para2: **string**, 对应的表单 `key` 为 **geetest_validate**
	* para3: **string**, 对应的表单 `key` 为 **geetest_seccode**

* 返回: **Int**, 1 表示验证通过， 0 表示验证未通过

* **PS**: 如果session中保存的极验服务器状态为宕机情况下使用的二次验证

语言展示
===================

php
------------

获取代码
~~~~~~~~~~~~~~~

在github中clone出最新Demo项目，快速搭建本地应用：

.. code::

    git clone https://github.com/GeeTeam/gt-php-sdk.git

前往 `项目主页 <https://github.com/GeeTeam/gt-php-sdk>`__

引用SDK

将sdk目录下的**lib/class.geetestlib.php**文件复制到你的项目中然后引用

.. code-block :: php

	require_once 'yourpath/class.geetestlib.php';

API
~~~~~~~~~~~

* **GeetestLib($captcha_id, $private_key)**: `构造函数 <#constructer>`_
* **pre_process($user_id=null)** : `预处理接口 <#pre-process>`_
* **get_response_str()** : `获取预处理结果的接口 <#get-response-str>`_
* **success_validate($challenge, $validate, $seccode, $user_id=null)** : `极验服务器状态正常的二次验证接口 <#sucess-validate>`_
* **fail_validate($challenge, $validate)** : `极验服务器状态宕机的二次验证接口 <#fail-validate>`_

代码示例
~~~~~~~~~~~~~~~~~

初始化验证

.. code-block :: php

	<?php
	require_once dirname(dirname(__FILE__)) . '/lib/class.geetestlib.php';
	require_once dirname(dirname(__FILE__)) . '/config/config.php';
	$GtSdk = new GeetestLib(CAPTCHA_ID, PRIVATE_KEY);
	session_start();
	$user_id = "test";
	$status = $GtSdk->pre_process($user_id);
	$_SESSION['gtserver'] = $status;
	$_SESSION['user_id'] = $user_id;
	echo $GtSdk->get_response_str();
	?>


二次验证

.. code-block :: php

	<?php
	require_once dirname(dirname(__FILE__)) . '/lib/class.geetestlib.php';
	require_once dirname(dirname(__FILE__)) . '/config/config.php';
	session_start();
	$GtSdk = new GeetestLib(CAPTCHA_ID, PRIVATE_KEY);
	$user_id = $_SESSION['user_id'];
	if ($_SESSION['gtserver'] == 1) {
	    $result = $GtSdk->success_validate($_POST['geetest_challenge'], $_POST['geetest_validate'], $_POST['geetest_seccode'], $user_id);
	    if ($result) {
	        echo 'Yes!';
	    } else{
	        echo 'No';
	    }
	}else{
	    if ($GtSdk->fail_validate($_POST['geetest_challenge'],$_POST['geetest_validate'],$_POST['geetest_seccode'])) {
	        echo "yes";
	    }else{
	        echo "no";
	    }
	}
	?>


java
------------

获取代码
~~~~~~~~~~~~~~

在github中clone出最新Demo项目，快速搭建本地应用：

.. code::

    git clone https://github.com/GeeTeam/gt-java-sdk.git

前往 `项目主页 <https://github.com/GeeTeam/gt-java-sdk>`__

引用SDK

将SDK中的目录下的 **src/com** 目录复制到你的项目中

.. code-block :: java

	import com.geetest.sdk.java.GeetestLib;

API
~~~~~~~~~~~~~

* **GeetestLib(String captchaId, String privateKey)** : `构造函数 <#constructer>`_
* **preProcess()** : `预处理接口 <#pre-process>`_
* **getResponseStr()** : `获取预处理结果的接口 <#get-response-str>`_
* **enhencedValidateRequest(String challenge, String validate, String seccode)** : `极验服务器状态正常的二次验证接口 <#sucess-validate>`_
*	**failbackValidateRequest(String challenge, String validate, String seccode)** : `极验服务器状态宕机的二次验证接口 <#fail-validate>`_

代码示例
~~~~~~~~~~~~~

验证初始化

.. code-block :: java

	public class StartCaptchaServlet extends HttpServlet {

		private static final long serialVersionUID = 1L;

		protected void doGet(HttpServletRequest request,
				HttpServletResponse response) throws ServletException, IOException {

			GeetestLib gtSdk = new GeetestLib(GeetestConfig.getCaptcha_id(), GeetestConfig.getPrivate_key());

			String resStr = "{}";
			int gtServerStatus = gtSdk.preProcess();
			//将服务器状态设置到session中
			request.getSession().setAttribute(gtSdk.gtServerStatusSessionKey, gtServerStatus);
			resStr = gtSdk.getResponseStr();
			PrintWriter out = response.getWriter();
			out.println(resStr);

		}
	}

二次验证

.. code-block :: java

	public class VerifyLoginServlet extends HttpServlet {

		private static final long serialVersionUID = 244554953219893949L;

		protected void doPost(HttpServletRequest request,
				HttpServletResponse response) throws ServletException, IOException {

			GeetestLib gtSdk = new GeetestLib(GeetestConfig.getCaptcha_id(), GeetestConfig.getPrivate_key());

			String challenge = request.getParameter(GeetestLib.fn_geetest_challenge);
			String validate = request.getParameter(GeetestLib.fn_geetest_validate);
			String seccode = request.getParameter(GeetestLib.fn_geetest_seccode);

			//从session中获取gt-server状态
			int gt_server_status_code = (Integer) request.getSession().getAttribute(gtSdk.gtServerStatusSessionKey);

			String gtResult = "fail";

			if (gt_server_status_code == 1) {
				//gt-server正常，向gt-server进行二次验证
				gtResult = gtSdk.enhencedValidateRequest(challenge, validate, seccode);
				System.out.println(gtResult);
			} else {
				// gt-server非正常情况下，进行failback模式验证
				gtResult = gtSdk.failbackValidateRequest(challenge, validate, seccode);
			}


			if (gtResult.equals(GeetestLib.success_res)) {
				PrintWriter out = response.getWriter();
				out.println(GeetestLib.success_res + ":" + gtSdk.getVersionInfo());
			} else{
				PrintWriter out = response.getWriter();
				out.println(GeetestLib.fail_res + ":" + gtSdk.getVersionInfo());
			}

		}
	}

csharp
------------

获取代码
~~~~~~~~~~~~~~

在github中clone出最新Demo项目，快速搭建本地应用：

.. code::

    git clone https://github.com/GeeTeam/gt-csharp-sdk.git

前往 `项目主页 <https://github.com/GeeTeam/gt-csharp-sdk>`__

先将代码编译成对应 .Net Framework 版本的DLL文件
注: 支持 3.5以上版本

将编译完成后的DLL添加到项目引用中

.. code-block :: csharp

	using GeetestSDK;

API
~~~~~~~~~~~~

* **GeetestLib(String publicKey, String privateKey)** : `构造函数 <#constructer>`_
* **preProcess()** : `预处理接口 <#pre-process>`_
* **getResponseStr()** : `获取预处理结果的接口 <#get-response-str>`_
* **enhencedValidateRequest(String challenge, String validate, String seccode)** : `极验服务器状态正常的二次验证接口 <#sucess-validate>`_
* **failbackValidateRequest(String challenge, String validate, String seccode)** : `极验服务器状态宕机的二次验证接口 <#fail-validate>`_

代码示例
~~~~~~~~~~~~

初始化验证

.. code-block :: csharp

	namespace demo
	{
	    public partial class GetCaptcha : System.Web.UI.Page
	    {
	        protected void Page_Load(object sender, EventArgs e)
	        {
	            Response.ContentType = "application/json";
	            Response.Write(getCaptcha());
	            Response.End();
	        }
	        private String getCaptcha()
	        {
	            GeetestLib geetest = new GeetestLib(GeetestConfig.publicKey, GeetestConfig.privateKey);
	            Byte gtServerStatus = geetest.preProcess();
	            Session[GeetestLib.gtServerStatusSessionKey] = gtServerStatus;
	            return geetest.getResponseStr();
	        }
	    }
	}

二次验证

.. code-block :: csharp

	namespace demo
	{
	    public partial class Validate : System.Web.UI.Page
	    {
	        protected void Page_Load(object sender, EventArgs e)
	        {
	        }
	        protected void submitBtn_Click(object sender, EventArgs e)
	        {
	            GeetestLib geetest = new GeetestLib(GeetestConfig.publicKey, GeetestConfig.privateKey);
	            Byte gt_server_status_code = (Byte) Session[GeetestLib.gtServerStatusSessionKey];
	            int result = 0;
	            String challenge = Request.Form.Get(GeetestLib.fnGeetestChallenge);
	            String validate = Request.Form.Get(GeetestLib.fnGeetestValidate);
	            String seccode = Request.Form.Get(GeetestLib.fnGeetestSeccode);
	            if (gt_server_status_code == 1) result = geetest.enhencedValidateRequest(challenge, validate, seccode);
	            else result = geetest.failbackValidateRequest(challenge, validate, seccode);
	            if (result == 1) Response.Write("success");
	            else Response.Write("fail");
	        }
	    }
	}

python
------------

获取代码
~~~~~~~~~~~~~~~

在github中clone出最新Demo项目，快速搭建本地应用：

.. code::

    git clone https://github.com/GeeTeam/gt-python-sdk.git

前往 `项目主页 <https://github.com/GeeTeam/gt-python-sdk>`_

安装代码

.. code-block :: bash

	sudo python setup.py install

引用代码

.. code-block :: python

	from geetest import GeetestLib

API
~~~~~~~~~~~~~~

* **GeetestLib(self, captcha_id, private_key)** : `构造函数 <#constructer>`_
* **pre_process(self)** : `预处理接口 <#pre-process>`_
* **get_reponse_str(self)** : `获取预处理结果的接口 <#get-response-str>`_
* **success_validate(self, challenge, validate, seccode)** :  `极验服务器状态正常的二次验证接口 <#sucess-validate>`_
* **failback_validate(self, challenge, validate, seccode)** : `极验服务器状态宕机的二次验证接口 <#fail-validate>`_

代码示例
~~~~~~~~~~~~~~~

初始化验证

.. code-block :: python

	@app.route('/getcaptcha', methods=["GET"])
	def get_captcha():
	    gt =  GeetestLib(captcha_id, private_key)
	    status = gt.pre_process()
	    session[gt.GT_STATUS_SESSION_KEY] = status
	    response_str = gt.get_response_str()
	    return response_str

二次验证

.. code-block :: python

	@app.route('/validate', methods=["POST"])
	def validate_capthca():
	    gt = GeetestLib(captcha_id, private_key)
	    status = session[gt.GT_STATUS_SESSION_KEY]
	    challenge = request.form[gt.FN_CHALLENGE]
	    validate = request.form[gt.FN_VALIDATE]
	    seccode = request.form[gt.FN_SECCODE]
	    if status:
	        result = gt.success_validate(challenge, validate, seccode)
	    else:
	        result = gt.failback_validate(challenge, validate, seccode)
	    result = "sucess" if result else "fail"
	    return result


node
------------

安装geetest


.. code::

    npm install geetest

在github中clone出最新Demo项目，快速搭建本地应用：

.. code::

    git clone https://github.com/GeeTeam/gt-node-sdk.git

前往 `项目主页 <https://github.com/GeeTeam/gt-node-sdk>`__


其它语言
----------------

由于web开发语言各类众多，其它语言类型官方无法全部覆盖，故会给出相应的开发原理文档，有兴趣的用户可以通过此文档，集成极验验证模块。

下面将列出来自热心的第三方开发者的贡献的SDK项目，特列表出来，供网站主参考：


- asp
    -  *git clone https://github.com/GeeTeam/gt-asp-sdk.git*
    - `项目主页 <https://github.com/GeeTeam/gt-asp-sdk>`__
- ruby
    -  *git clone https://github.com/GeeTeam/gt-ruby-sdk.git*
    - `项目主页 <https://github.com/GeeTeam/gt-ruby-sdk>`__
- vb
    -  *git clone https://github.com/GeeTeam/gt-vb-sdk.git*
    - `项目主页 <https://github.com/GeeTeam/gt-vb-sdk>`__


注意：以上SDK仅供开发参考，官方不承诺提供长期技术支持


成为贡献者
=================

- 如果您对我们的SDK有更好的意见或者建议
- 如果您愿意补充我们的服务端应用语言类型

欢迎成为本SDK在github中的贡献者。

联系QQ：1295351490