This document provides an overview and examples of the NK API for developing mobile applications, websites, and OpenSocial applications. It describes REST and JS APIs for authentication, making requests, uploading photos, payments, inviting friends, adding shouts, and communicating with users. Code samples are given for common tasks like uploading photos, checking group membership, and sending messages between users. Developers can find full documentation and support for building applications on the NK platform.

1. NK API
Examples
Games and
application Websites
s
(c) Jarosław Gomułka 2012

2. API types:
● REST
● JS

3. REST API
Documentation
Created for mobile application and website solutions.

4. 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>

5. REST API - /token/get - headers
Request 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

6. 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.

7. 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

8. 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 (u003cscriptu003ealert(1);u003c/scriptu003e)","
additionalName":"mnk (u003cscriptu003ealert(1);u003c/scriptu003e)","familyName":"mnk","givenName":"du1"},"photos":
[{"value":"http://s.m.nk.pl/img/avatar/avatar_default_female","type":"thumbnail"}],"displayName":"du1 mnk
(u003cscriptu003ealert(1);u003c/scriptu003e)"}}

9. 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":{}}

10. 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

11. API JS
In 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.

12. API JS
Aplikacje definiujemy przez pojedynczy plik gadget.xml
Adres do tego pliku podajemy w panelu zarządzania aplikacjami i stronami.

13. Preparation of development environment
1. You create application in https://developers.nk.pl/developers
2. Set debug mode (data cache is disabled)
3. You add tester ID on application tester list
4. 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>

14. Examples:
Following examples are available under this URL:
https://github.com/jaaro/various/tree/master/nk
1. ROT13
2. Information about the user
3. Informacje about friends
4. Embedding flash
5. Swfobject
6. Hamster fall
7. Adding shout on NK
We suggest to test other JS API functionalities in this application: nkda.

15. 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);
}

16. Payments
Enter 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&parameters=some_app_specific_params&
paymentType=payment&viewerId=person.abc

17. 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 egbtest@nasza-klasa.pl with request for specified amount of NK
currency (EGB) , you NK profile ID and name of the application you are testing.

18. 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();

19. 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();

20. Adding user to application group:
function callback(responseItem) {
if (responseItem.hadError()) {
// handle error
} else {
console.log(responseItem);
}
}
function invite() {
nk.groups.requestAddUserToAppGroup(callback);
}
invite();

21. Adding picture:
function uploadPhotoHandler(resp) {
if (resp.hadError()) {
// handle error
}
}
function uploadPhoto() {
nk.photos.requestUploadAppPhoto("Photo added from Dev App", null, uploadPhotoHandler);
}
uploadPhoto();

22. 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();

23. 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");

24. 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();

25. 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/

26. 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