nk api - examples
TRANSCRIPT
NK APIExamples
Games and application
sWebsites
(c) Jarosław Gomułka 2012
API types:
● REST ● JS
REST API
Documentation
Created for mobile application and website solutions.
REST API
Authentication is based on OAuth standard. There are many libraries supporting this
standard. Have a look here:: http://oauth.net/code/
First you need to get nk_token via /token/get request.
POST https://opensocial.nk-net.pl/v09/token/get
POST data:
login=loginUseraNaNk&password=hasłoUseraNaNk
[no cookies]
Request Headers:
<next slide>
REST API - /token/get - headersRequest Headers:
Content-Type: application/x-www-form-urlencoded
Content-Length: 28
Authorization: OAuth oauth_signature_method="HMAC-SHA1", oauth_consumer_key="customerKeyZPanelu", oauth_timestamp="1352376881", oauth_nonce="272317321310634", oauth_version="1.0", oauth_signature="jVaVvVZcLZ1mMHzU3dzAmw3vxPE%3D"
oauth_version="1.0",
oauth_timestamp="1352376881"
oauth_nonce="272317321310634" - must be unique, at least 15 characters
oauth_signature_method="HMAC-SHA1" - you must enter this value
oauth_signature="jVaVvVZcLZ1mMHzU3dzAmw3vxPE%3D" - it needs to be calculated:)
oauth_signature obliczamy poprzez base64_encode(HMAC-SHA1(oauth_base_string, <secret from developer panel>&));
If everything goes correctly, we will get the answer:
nk_token=jakiśDziwnyNapisWBase64
REST API - base string
Example of value POST&http%3A%2F%2Fjava1.omega.nknet%3A2080%2Fv09%2Ftoken%2Fget&login%3Dabcef%26oauth_consumer_key%3DjakisCustomerKey%26oauth_nonce%3D273217097465315%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1352377781%26oauth_version%3D1.
0%26password%3DjakiśPassword
First part POST - as we were sending POST request
Second part is URL without query parameters, encoded via urldecode function
Third part are all sorted and concatenated parameters .
Remember to sign the request content (when it makes sens - check: question reported to NKsupport).
All requests need to be signed with this mechanism.
REST API - @me, @self, @all
Many endpoint specifications show strange elements like: @me, @self, @all.
@me - user currently logged in
@self, @friends, @all - indicates who can check the object on which the action is done
Download user data
GET http://opensocial.nk-net.pl/v09/social/rest/people/person.602916f34c2ee73d/@self?nk_token=pynHhd5gLOetEOL3HtkFLwAUZ-4jHwMb6yda8Dkk-ratXkexcYcJhjWliEusR_QGTpBLvl1Rto51k8-s24l9O9wFKaqQ9mvNDMKSU90Gp2f
[no cookies]
Request Headers:
Authorization: OAuth oauth_signature_method="HMAC-SHA1", oauth_consumer_key="psiloctest1", oauth_timestamp="1352379660", oauth_nonce="275096425520387", oauth_version="1.0", oauth_signature="GeGBNljcPKIQPeLXgCtYX8zgVCY%3D"
Connection: keep-alive
Response:
{"entry":{"isOwner":true,"isViewer":true,"id":"person.602916f34c2ee73d","thumbnailUrl":"http://s.m.nk.pl/img/avatar/avatar_default_female","name":{"formatted":"du1 mnk (\u003cscript\u003ealert(1);\u003c/script\u003e)","additionalName":"mnk (\u003cscript\u003ealert(1);\u003c/script\u003e)","familyName":"mnk","givenName":"du1"},"photos":[{"value":"http://s.m.nk.pl/img/avatar/avatar_default_female","type":"thumbnail"}],"displayName":"du1 mnk (\u003cscript\u003ealert(1);\u003c/script\u003e)"}}
Adding shout
POST https://opensocial.nk-net.pl/v09/social/rest/activities/@me/@self/app.sledzik?nk_token=pynHhd5gLOetEOL3HtkFLwAUZ-4jHwMb6yda8Dkk-ratXkexcYcJhjWliEusR_QGTpBLvl1Rto51k8-s24l9O9wFKaqQ9mvNDMKSU90Gp2f
POST data:
{"title":"Some short text 123"}
[no cookies]
Request Headers:
Content-Type: application/json
Content-Length: 31
Authorization: OAuth oauth_body_hash="%2FIyGusEZ4w8%2BuI9gOr5emjQha9E%3D", oauth_signature_method="HMAC-SHA1", oauth_consumer_key="psiloctest1", oauth_timestamp="1352379705", oauth_nonce="275140932345687", oauth_version="1.0", oauth_signature="Rhv3r9eVAx66MDlcTepvQ7bPkuw%3D"
Connection: close
Response 200:
{"entry":{}}
When something is not working...
We suggest the following steps:
● Check the error code. You can find many useful information there.● Check logs - http://developers.nk.pl/applications-logs/
● Catch the request with tcpdump or extract it with netcat. Then check if data is sent according to the specification
● Describe the problem in details in NK support
API JSIn this part we will show you how to create Opensocial applications.
Shindig is used as application container which implements OpenSocial standard
Shindig is responsible for:
● application rendering● proxy request creation● data cache● RPC/REST requests
We are supporting OpenSociala ver 0.9.
List of all functionalities we are supporting
is accessible in our documentation.
API JSAplikacje definiujemy przez pojedynczy plik gadget.xmlAdres do tego pliku podajemy w panelu zarządzania aplikacjami i stronami.
Preparation of development environment
1. You create application in https://developers.nk.pl/developers2. Set debug mode (data cache is disabled)3. You add tester ID on application tester list4. Enter your application: http://nk.pl/#applications_test/xyz (the exact link is in
application settings)
For the beginning we can put the following, classic example code as gadget.xml:
<?xml version="1.0" encoding="UTF-8" ?><Module> <ModulePrefs/> <Content type="html" view="canvas"> <![CDATA[ Hello World ]]> </Content></Module>
Examples:
Following examples are available under this URL: https://github.com/jaaro/various/tree/master/nk
1. ROT132. Information about the user3. Informacje about friends4. Embedding flash5. Swfobject6. Hamster fall7. Adding shout on NK
We suggest to test other JS API functionalities in this application: nkda.
Payments- JS code
function handlePaymentResponse(dataItem) {
if (dataItem.hadError()) {
alert('got an error');
} else {
var orderId = dataItem.getData().getField(opensocial.Payment.Field.ORDER_ID);
alert('payment request accepted, orderId: ' + orderId);
}
}
function makePayment() {
var params = {};
params[opensocial.Payment.Field.AMOUNT] = 5;
params[opensocial.Payment.Field.MESSAGE] = "large sword";
params[opensocial.Payment.Field.PARAMETERS] = "some_app_specific_params";
var payment = opensocial.newPayment(params);
opensocial.requestPayment(payment, handlePaymentResponse);
}
PaymentsEnter the right value in "Payment Callback URL" field (Administration panel):
When transaction is completed, nk is sending under this URL the following request:
POST /some/url HTTP/1.1
Host: gamehost.com
Content-Type: application/x-www-form-urlencoded
amount=5&appId=app.1&containerDomain=nk.pl&message=large%20sword&oauth_consumer_key=key&
oauth_nonce=252b9d59381dd803dcf156663d1375d9&oauth_signature=%2F7%2BGAbB0DDYNZwC%2BsSACe1O5Kpw%3D&
oauth_signature_method=HMAC-SHA1&oauth_timestamp=1273755263&oauth_version=1.0&
orderId=32787067d4de27d7fb97d816723d5c75bb9fd337¶meters=some_app_specific_params&
paymentType=payment&viewerId=person.abc
Payments
Application must confirm the payment has been received by generating the following response:
HTTP/1.1 200 OK
Content-Type: application/json
{"orderId":"32787067d4de27d7fb97d816723d5c75bb9fd337","responseCode":"ok","responseMessage":"all ok","signature":"7e7455aac4a1be3186185e5bd056791adf01818c"}
If the confirmation (response) is not ok, NK server will send request every minute for next 24hours or till we get the correct response.
If you want to test payments, send e-mail to [email protected] with request for specified amount of NK currency (EGB) , you NK profile ID and name of the application you are testing.
Inviting friends to the application:
function handleInviteFriendResponse(responseItem) {
if (responseItem.hadError()) {
// handle error
} else {
alert(responseItem.getData() + ' invited friend(s)');
}
}
function invite() {
var msg = 'Join me !';
var paramsObject = new Object();
nk.requestInviteFriends(msg, paramsObject, handleInviteFriendResponse);
}
invite();
Check if user is already member of the application group.
function response(data) {
if (data.hadError()) {
// handle error
} else {
var result = data.get("isInGroup").getData();
if (result) {
output("User is in application\'s group");
} else {
output("User is NOT in application\'s group");
}
}
};
function request() {
var req = opensocial.newDataRequest();
req.add(nk.groups.newIsUserInAppGroupRequest(), "isInGroup");
req.send(response);
};
request();
Adding user to application group:
function callback(responseItem) {
if (responseItem.hadError()) {
// handle error
} else {
console.log(responseItem);
}
}
function invite() {
nk.groups.requestAddUserToAppGroup(callback);
}
invite();
Adding picture:
function uploadPhotoHandler(resp) {
if (resp.hadError()) {
// handle error
}
}
function uploadPhoto() {
nk.photos.requestUploadAppPhoto("Photo added from Dev App", null, uploadPhotoHandler);
}
uploadPhoto();
How many user have installed the application?
function response(data) {
if (data.get("amount").hadError()) {
// handle error
} else {
alert(data.get("amount").getData());
}
};
function request() {
var req = opensocial.newDataRequest();
req.add(nk.newGetAmountOfUsersRequest(), "amount");
req.send(response);
};
request();
Adding shout:
function onActivityPosted(data) {
if (data.hadError()) {
alert("There was a problem: " + data.getErrorMessage());
} else {
output("The activity was posted successfully.");
}
};
function postActivity(title) {
var data = {};
data[opensocial.Activity.Field.TITLE] = title;
var activity = opensocial.newActivity(data);
opensocial.requestCreateActivity(
activity,
opensocial.CreateActivityPriority.HIGH,
onActivityPosted
);
};
postActivity("This is a sample activity");
Communication between users - message
function response(data) {
if (data.hadError()) {
alert("There was a problem: " + data.getErrorMessage());
} else {
output("The message was sent.");
}
};
function request() {
var iconUrl = new opensocial.Url({"type" : "icon", "address" : "http://www.example.org/icons/notifyIcon.jpg"});
var msgParams = {
"title" : "Title of notification",
"urls" : new Array(iconUrl), // image used in notification
"type" : "notification", // only notification is currently supported
};
var msg = opensocial.newMessage("Body of notification", msgParams); opensocial.requestSendMessage(["person.XXX"], msg, response);
};
request();
JS API
You can find many other examples in our dokumentation together with detailed features specification.
http://developers.nk.pl/documentation/nk-api/opensocial-js-api/
Some interesting features:
Please note, that even if we support some features, they may not be operated in the same way as in original OpenSocial specification, for example: Activity.
List of supported paramenters is here: http://developers.nk.pl/documentation/nk-api/opensocial-js-api/
Interesting features:
gadgets.log / gadgets.warn / gadgets.error
gadgets.json.parse / gadgets.json.stringify
gadgets.window.adjustHeight
gadgets.io.makeRequest / osapi.http.get