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!

Sunday, 17 February 2013

BB10: A little survival guide for the newbie developer

Introduction
This guide is made for BB10's developers in particular for Cascades developer with a BB10 device.
These are little advice that I found experimenting with BB10 in these last months.

Log it!
If you want to log something to the console, for better understand how your applications is working you can use qDebug() << "your string"; in c++


 or use console.log on QML


Now to be able to read your log you have to connect to your device with SSH!
To be able to do this, just right click on your usb connected device and select "Launch SSH Session" like in the following image.
After that you have a shell inside the device and you are able to send command directly from the device.
To watch the log produced by your application just type slog2info -w
and for the 2 previouse log:



SSH in device, good not only for logs!
After an ssh connection, you can type some command inside the device for example:
  • pwd: print your working directory
  • cd: to change your current directory
  • cat : print on the console the content of a file
  • ls: list the files and directory in your current directory
There are other commands, like in a unix enviroment, not all working but with just these 4 previous command you have a lot of power... and remember: With great power comes great responsibility.
For example? you can watch the content of a produced file from your app; start moving to /accounts/1000/appdata/ and than to your app directory:


Use "cat" on a file:


Renew your debug token, it is just 2 click!
Your debug token will expire.. To create a new one you can write command from your enviroment or use qde (a customized eclipse for bb10) like that:


Right Click on your usb device, than select Blackberry Tools and than Debug Token Details and you have this dialog.


Select your token and then Renew options and .. that's it!

Do you know any other useful tips?
Please write it in the comments!