NK API - Przykłady

NK API
Przykłady

Aplikacje
i Strony
Gry

(c) Jarosław Gomułka 2012

REST API
Dokumentacja

Stworzone na potrzeby aplikacji mobilnych oraz stron.

REST API
Autentykacja bazuje na standardzie OAuth. Istnieje bardzo wiele bibliotek
wspierających ten standard, patrz: http://oauth.net/code/

W pierwszej kolejności należy dostać nk_token poprzez request /token/get

POST https://opensocial.nk-net.pl/v09/token/get

POST data:
login=loginUseraNaNk&password=hasłoUseraNaNk

[no cookies]

Request Headers:
<następny slajd>

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" - musi być unikalna, przynajmniej 15 znaków
oauth_signature_method="HMAC-SHA1" - musi być ta wartość
oauth_signature="jVaVvVZcLZ1mMHzU3dzAmw3vxPE%3D" - to trzeba obliczyć:)

oauth_signature obliczamy poprzez base64_encode(HMAC-SHA1(oauth_base_string, <secret z panelu>&));

Jeśli wszystko pójdzie dobrze - dostaniemy odpowiedź

nk_token=jakiśDziwnyNapisWBase64

REST API - base string
Przykładowa wartość 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

Pierwsza część POST - bo wysyłaliśmy request POST
Część druga to url bez query parameters, zakodowany przez funkcje urldecode
Część trzecia to posortowane i skonkatenowane wszystkie parametry

Warto pamiętać, że trzeba podpisać też treść requestu (gdy ma to sens - patrz pytanie na supporcie).

Wszystkie requesty muszą być podpisane przez ten mechanizm!!

REST API - @me, @self, @all
W specyfikacjach wielu endpointów możemy znaleźć wynalazki typu @me, @self, @all.

@me - aktualnie zalogowany user
@self, @friends, @all - kto może zobaczyć obiekt względem którego wykonywana jest akcja

Przykłady:

Pobranie danych użytkownika
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

Odpowiedź:

{"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)"}}

Dodawanie wpisu śledzikowego
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":{}}

Co gdy coś nie działa?
Proponujemy następującą kolejność działań:
● Należy zwrócić uwagę na kod błędu. Z tej informacji naprawdę dużo
wynika!
● Zobaczyć do logów - http://developers.nk.pl/pl/logi_aplikacji/
● Złapać request tcpdump'em lub wypisać go netcatem i zobaczyć czy
wysyłane dane są zgodne ze specyfikacją.
● Zadać szczegółowo opisane pytanie na naszym serwisie wsparcia

API JS
W tej części będziemy tworzyć aplikacje opensocialowe.

Jako kontenera aplikacji używamy Shindiga który implementuje standard OpenSocial.

To Shindig odpowiada za
● renderowanie waszych aplikacji
● tworzenie proxy requestów
● cache'owanie wszystkiego
co trzeba
● RPC/REST requests
● i wiele innych

Celujemy we wspieranie OpenSociala w
wersji 0.9. Nie wspieramy całego
OpenSociala.
Lista dostępnych funkcjonalności
znajduje się w naszej dokumentacji.

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

Przygotowanie środowiska
deweloperskiego
1. Tworzymy aplikację na https://developers.nk.pl/developers
2. Ustawiamy ją na tryb debug (wyłącza cache'owanie)
3. Dodajemy swój NK ID do testerów aplikacji
4. Wchodzimy na aplikację http://nk.pl/#applications_test/cośtam (dokładny
link znajduje się w panelu deweloperskim)

Jako gadget.xml na początek możemy wkleić klasyczny Hello World;)
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs/>
<Content type="html" view="canvas">
<![CDATA[
Hello World
]]>
</Content>
</Module>

Przykłady
Poniższe przykłady dostępne na https://github.
com/jaaro/various/tree/master/nk

1. ROT13
2. Informacje o użytkowniku
3. Informacje o znajomych
4. Embedding flash
5. Swfobject
6. Pogoda na nk (ale czemu nie działa!?)
7. Hamster fall
8. Dodawanie śledzia na nk

Dalsze funkcjonalności JS API proponuję testować w aplikacji nkda.

Płatności - Kod JS
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);
}

Płatności
W panelu deweloperskim należy podać "Adres do obsługi transakcji"

W przypadku gdy transakcja zakończy się sukcesem, nk wysyła pod ten adres 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

Płatności
Aplikacja musi potwierdzić otrzymanie płatności poprzez wygenerowanie
następującej odpowiedzi na request:

HTTP/1.1 200 OK
Content-Type: application/json

{"orderId":"32787067d4de27d7fb97d816723d5c75bb9fd337","responseCode":"ok","
responseMessage":"all ok","signature":"7e7455aac4a1be3186185e5bd056791adf01818c"}

W przypadku gdy z potwierdzeniem jest coś nie tak, nasz server będzie wysyłał request
potwierdzający płatność co minute przez następne 24 godziny (lub do momentu otrzymania poprawnej
odpowiedzi).

Jak testować płatności: Wyślij maila na adres egbtest@nasza-klasa.pl z prośbą o przyznanie egb na
potrzeby testów płatności.

Zapraszanie znajomych do aplikacji
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();

Sprawdzanie czy użytkownik jest
zapisany do grupy aplikacji
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();

Dodawanie użytkownika do grupy
aplikacji
function callback(responseItem) {
if (responseItem.hadError()) {
// handle error
} else {
console.log(responseItem);
}
}

function invite() {
nk.groups.requestAddUserToAppGroup(callback);
}

invite();

Dodawanie fotki
function uploadPhotoHandler(resp) {
if (resp.hadError()) {
// handle error
}
}

function uploadPhoto() {
nk.photos.requestUploadAppPhoto("Photo added from Dev App", null, uploadPhotoHandler);
}

uploadPhoto();

Ile osób zainstalowało aplikację
if (data.get("amount").hadError()) {
// handle error
} else {
alert(data.get("amount").getData());
}
};

var req = opensocial.newDataRequest();
req.add(nk.newGetAmountOfUsersRequest(), "amount");
req.send(response);
};

request();

Dodawanie wpisu (śledzika)
function onActivityPosted(data) {
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");

Wiadomość między użytkownikami
alert("There was a problem: " + data.getErrorMessage());
} else {
output("The message was sent.");
}
};

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
Dużo więcej przykładów znajdziecie w naszej dokumentacji
(wraz z dokładną specyfikacją funkcji! )

http://developers.nk.pl/documentation/nk-api/opensocial-js-api/

Kilka ciekawych funkcji
Należy pamiętać, że nawet w funkcjach które wspieramy, niektóre parametry mogą być obsługiwane
inaczej niż w oryginalnej specyfikacji OpenSocial - np. Activity.

Lista wspieranych parametrów znajduje się na http://developers.nk.pl/documentation/nk-
api/opensocial-js-api/

Ciekawsze funkcje

gadgets.log / gadgets.warn / gadgets.error

gadgets.json.parse / gadgets.json.stringify

gadgets.window.adjustHeight

gadgets.io.makeRequest / osapi.http.get

NK API - Przykłady

More Related Content

Similar to NK API - Przykłady (20)

NK API - Przykłady