This is our second post about our integration with QQ. Last week I explained the WHY we integrated with QQ, and today I’ll cover, in a bit more detail, the HOW.
To set the stage, the overall QQ integration experience was not too difficult. While there were some tricky parts along the way, the biggest challenge was that all the documentation was in Chinese (http://connect.qq.com). This added a layer of complexity to how quickly we were able to integrate.
With that in mind, I’d like to share some of our step-by-step experiences with integration (with pictures!) to help you through the process if you plan on doing the same.
To start, we needed to create a developer account on the QQ Connect Platform.
(1) Create an account
To use QQ connect, you’ll need to register for an account first. Go to http://connect.qq.com and click the ‘登录(Login)’ button.
A popup should show up, asking you to login. If you haven’t already created an account in the past, click the ‘注册新帐号(register)’ button, which will open the register page.
(2) Make your account a developer account
After register/login, you will be redirected to the developer account settings page that you can see below. There are two types of account: 1. corporate and 2. personal. If you are trying to integrate a company’s product, they suggest that you create a corporate account instead of a personal account, as you won’t be able to transfer your application between developer accounts. You will be able to do those transfers on a corporate account. A key thing to note is that is that the phone number has to be a Chinese phone number in order to proceed.
3. Create an Application on QQ Connect platform
After completing registration, you need to create your Application by clicking the “管理中心(management center)” button in the menu, as you can see below. Then click the “创建应用(Create Application)” button.
Click the ‘创建应用’ to start creating your application.
There are two types of Application that you will need to differentiate between: “网站(website)” and “移动应用(mobile app)”. They made it easy so that you can start with either one, and then later add support for the other.
For the example below, we started with “网站(website)” first. All of the fields are required to be completed, and keep in mind that the “网站地址(website url)” does not support ‘https’. You will need to create a static or separate page for it. The callback url is where your application receives the callback from QQ servers, once a user authenticates. Please note that the callbacks won’t succeed unless your domain matches the one listed in the callback url field. Once you create the application, you will get a QQ app_id and app_key. Now you are ready to start implementing QQ Login!
4. Implement QQ Login
QQ supports both client-side and server-side authentication. In our example we chose to use the server-side integration. You can initiate a request when the user clicks on the button in the following format:
In this case, the client_id is your application’s app_id, you could find it from the “Management Center”. The callback url is where QQ calls back after successful authorization. Please note that the domain of the redirect_uri should match the one in your callback url field (figure 7 above). The scope is the where you ask for user permissions. That value could be one or more QQ API names (you can find them here: http://wiki.connect.qq.com/api列表), when there is more than one name, you will need to use a comma to separate them. If you keep scope empty, you will, by default, get the permission to access ‘get_user_info’ API. If you’d like to get all of the permissions, simply set the scope value to be ‘all’.
If you are using Omniauth, this Omniauth-QQ plugin (https://github.com/beenhero/omniauth-qq) will help you directly retrieve user’s QQ info from env["omniauth.auth"] in the callback.
5. Integrate QQ Connect with mobile SDK
QQ provides both iOS SDK and Android SDKs. Integration with iOS SDK is fairly straightforward. We suggest you follow the steps listed here: http://wiki.connect.qq.com/ios_sdk环境搭建.
During our experience, we ran into a few small issues with the Android SDK (http://wiki.connect.qq.com/创建实例并实现回调_android_sdk). For example, when we added `mTencent.onActivityResult` into the code as the instructions suggest, an error appeared saying “Tencent Object doesn’t have onActivityResult defined”. Thankfully, QQ updated their SDK early 2014, and you can now get around that error by simply adding the following code into your application manifest (http://wiki.open.qq.com/wiki/mobile/Android_SDK使用说明).
6. Test and Release
As you’d expect, QQ needs to approve your app before real users can use it. So in order to test your code, you will need to create test accounts. You can create up to 10 test accounts by editing “协作者测试号(test account ids)” through the “信息编辑(edit info)” page. You should test it locally by setting your callback url to be ‘127.0.0.1’.
Once you have tested your app, and filled in all the required information, the “提交审核(submit for review)” button will become enabled. Please note, that in figure 9 below, the button is not enabled because the icons had not been provided.
Until your application passes QQ review, only test accounts would be able to complete the “QQ Login”. However, QQ needs you to deploy your code so that they can test and approve it. This becomes a bit of a “catch-22”. One way to work through that is to deploy a separate page for review purpose. The way we did this was to deploy QQ Login code to a test server, and provide both test server url and production url in the callback urls field, then send review request against test server url.
When it comes to mobile apps, it becomes a bit simpler. You do not need to submit to the app store to get approved by QQ. Instead you can provide the download URL for your app’s IPA (iOS) or APK (Android) in the “平台信息(platform info)” section. For Android apps, go to the “Android platform” section and provide the app download url in the “apk下载地址(apk download url)” field(figure 10 below). For iOS apps, go to the “iPhone/iPad platform” section and provide the app download url in the “介绍网站地址(website introduction page url)” field (figure 11 below).
Once you pass the review, the status will turn all green. Congratulations! (figure 12 below).
QQ has a farily quick review process, and can usually finish the Website review in one day, and Mobile App reviews in approximately 3 days. If your review is taking longer than that, you can send an email to firstname.lastname@example.org with some additional testing instructions.
We hope you found this, and our previous post on QQ helpful. We’d love to hear what you thought in the comments section below!
Think this is interesting? We're hiring! See our current openings here.