Overview

All the examples in this document are based on Flask、Tornado、Django framework。

Development environment

Item Description
Compatibility Compatible with python 2 & 3, but recommend to use python 2.7+
Dependency Web framework（e.g. django, tornado, etc). Use pip install -r requirement.txt to install all the dependencies.

Resources

Item Description
Data communication flow chart Data communication flow chart
Download SDK gt3-python-sdk

Python SDK Installation

Download​ ​SDK

There are two ways to download SDK.

Use​ ​command​ ​line​ ​to​ ​get​ ​from​ ​Github

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

Or download​ ​SDK​ ​manually

Get​ ​the​ ​latest​ ​SDK​ ​from Github: gt3-python-sdk (in .zip format)

Import SDK

You might need sudo to execute the following commands.

When the development environment is ready, use the following commend to install SDK.

python setup.py install

Use the following commend to import SDK.

from geetest import GeetestLib

Configure key pair and modify the request

Configure key pair

Get your key pair from GeeTest Dashboard. The key pair consists of a public​ ​key(captcha ID) and a private​ ​key (KEY)​. Then, configure the key pair in the following path.

  • Django：/demo/django_demo/app/views.py
  • Flask：/demo/flask_demo/start.py
  • Tornado：/demo/tornado_demo/start.py

Modify the request (optional)

Variable Description
user_id User identification. If you concern about the risk of user information, you can preprocess (e.g. hashed) it.
client_type Type of client. Web (web browser for computers)，h5 (mobile browser，include webview)，native(native mobile app)，unknown (unknow client type)
ip_address Client request for your server IP address, unknow means unknow IP address

API example

The following examples are based on Tornado framework.

Captcha initialization

Initiate captcha via API1, get challenge and set the status

class PcGetCaptchaHandler(SessionBaseHandler):
    def get(self):
        user_id = 'test'
        gt = GeetestLib(pc_geetest_id, pc_geetest_key)
        status = gt.pre_process(user_id, JSON_FORMAT=0, ip_address="127.0.0.1")
        if not status:
            status = 2
        self.session[gt.GT_STATUS_SESSION_KEY] = status
        self.session["user_id"] = user_id
        response_str = gt.get_response_str()
        self.write(response_str)

Notice：status indicates captcha initialization. Status=1 refers to successful initialization, status=0 refers to downtime. Please store the status, since it will be needed in secondary verification. In the demo above, session has been used to store status.

Secondary verification (API2), including uptime and downtime

class PcValidateHandler(SessionBaseHandler):
    def post(self):
        gt = GeetestLib(pc_geetest_id, pc_geetest_key)
        challenge = self.get_argument(gt.FN_CHALLENGE, "")
        validate = self.get_argument(gt.FN_VALIDATE, "")
        seccode = self.get_argument(gt.FN_SECCODE, "")
        status = self.session[gt.GT_STATUS_SESSION_KEY]
        user_id = self.session["user_id"]
        if status == 1:
            result = gt.success_validate(challenge, validate, seccode, user_id, JSON_FORMAT=0)
        else:
            result = gt.failback_validate(challenge, validate, seccode)
            self.session["user_id"] = user_id
        result = "<html><body><h1>登录成功</h1></body></html>" if result else "<html><body><h1>登录失败</h1></body></html>"
        self.write(result)

How to simulate the Failback mode? Please fill in an incorrect string (e.g. 123456789) for the captcha ID. Then, it will enter the Failback mode.

Run demo

You might need sudo to execute the following commands.

Run Flask demo

Use commend line to enter the path of the flask_demo folder, then executes the command:

$ python start.py

To view the demo, please visit​ ​​http://localhost:5000 ​in​ ​browser​.

Run Tornado demo

Use commend line to enter the path of the tornado_demo folder, then executes the command:

$ python start.py

To view the demo, please visithttp://localhost:8088 ​in​ ​browser​.

Run Django demo

Use commend line to enter the path of the django_demo folder, then executes the command:

$ python manage.py runserver 0.0.0.0:8000

To view the demo, please visithttp://localhost:8000 ​in​ ​browser​.

Troubleshooting: secondary verification failure

  1. SDK internal logic errors. Please check: a) whether session is stored and read successfully, b) whether the code could successfully process to the module which send a request to GeeTest server, c) check the return value of GeeTest server.
  2. Multiple submission. The API which initiates the secondary verification is only available for one time.
  3. The challenge is inconsistent. Please ensure the consistency of challenge during the whole verification process.
  4. Check if gt and key in the code are correct in SDK. Please check if the parameters has been passed correctly.
  5. Please provide challenge to our service team. They could help you to check the log.