Monday, 25 February 2013

OAuth on getPocket.com with BB10

Introduction
Here it is the description on how to authenticate a BlackBerry10 user in your application, with pocket API.
This tutorial is written for Cascades Developers.
Pocket is a read it later service.
It help user to keep track of new links and read it later, whenever they want.
Pocket have their own API used by over 300  apps.
The authentication process is an OAuth 2.0 variant.
If you have no experience with OAuth check this before continue.
The screenshots and code that follows belongs to a pocket client that I made, called Mnemonia for BlackBerry10, available here.

Initial Setup
Create a new app profile on getpocket.com.
Go to http://getpocket.com/developer/apps/ and register a new application.
Take note somewhere of consumer_key because you will need it soon.

Flow
When you want to authenticate a user, your application have to:
  1. Make a request(all request are POST request) for an appCode to pocket.com with a redirect_uri and consumer_key as params and you will receive an appCode to save locally. The redirect_uri will be the url that pocket will invoke after the user have succesfully authorized the application.
  2. Open a new browser window to pocket.com with the appCode of point 1 and redirect_uri as parameters.At this point the application ask the user to authenticate and approve the app. If the login is succesfully the browser will be redirect to the redirect_uri link.
  3. Finally you can request an access_token and use it for the other operation: add, delete, archive, favourite etc.
Important: point the redirect_uri to a real page like this: where you tell the user that the authentication process is ok and to come back to the application.

Make Post Requests: Cascades's way
The main class for get/post request with QT, it's QNetworkAccessManager (check also this).
You should create in your Class an object QNetworkAccessManager and than connect it to a SLOT function (requestFinished in the example below):

mNetworkAccessManager = new QNetworkAccessManager(this);
connect(mNetworkAccessManager,SIGNAL(finished(QNetworkReply*)),this,SLOT(requestFinished(QNetworkReply*)));

After that all your request with networkAccessManager will finish in methoed requestFinished.

The second things you need is launch the browser, with this call:
navigator_invoke(HTTPSTRINGURL, NULL);

Now we will follow the 3 steps of previous Flow, section but with code:

Step 1: ask the app code.
We have to make a post request and pass our parameters, consumer_key and redirect_uri, in json format.
We create the JSON string manually,



As a result for the first request, requestFinished is called:



Step 2: Launch the Browser
Now that you have the appCode, you can ask authorization to the user:
This is a little function that open a new browser window with the correct parameters.

void YourClassName::launchAuthBrowser() {
    QString authUrl;
    authUrl.append("https://getpocket.com/auth/authorize?request_token=");
    authUrl.append(appCode); // the one retrieved at point 1.
    authUrl.append("&redirect_uri=");
    authUrl.append(YOURREDIRECTURI);
    navigator_invoke(authUrl.toStdString().c_str(), NULL);
}

After this call, a new browser window is presented to the user, asking for their credentials, or to create a new account.
If the authorization went ok, the browser is automatically redirected to YOURREDIRECTURI parameter.

Step 3: Finally the token!
Now your user is back to the app, after have succesfully authorized your app to use his account on pocket.com.



and in the requestFinished methoed I have this code:



The response of this request is a URL: the first value is the Token, the last one is the user username.
This last code is not a good example but just a way to take the parameters data, you should check better if the values you are reading are correct...
You have to check for errors too, watch Step 5 of http://getpocket.com/developer/docs/authentication.

Final consideration
You can save your token in your app/data directory, but you can do better following this link
If you need more assistance or have any critics with this article, write in the comments and let me know :)
.. and if you have the possibility to try Mnemonia, tell me what do you think about it!

No comments:

Post a Comment