NK APIPrzykłady

Aplikacje i

GryStrony

(c) Jarosław Gomułka 2012

Rodzaje API

● REST ● JS

REST APIDokumentacja

Stworzone na potrzeby aplikacji mobilnych oraz stron.

REST APIAutentykacja 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 - headersRequest Headers:Content-Type: application/x-www-form-urlencodedContent-Length: 28Authorization: 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ówoauth_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 stringPrzykł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 POSTCzęść druga to url bez query parameters, zakodowany przez funkcje urldecodeCzęść 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, @allW 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żytkownikaGET 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 (\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)"}}

Dodawanie wpisu śledzikowegoPOST 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/jsonContent-Length: 31Authorization: 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 JSW 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 JSAplikacje definiujemy przez pojedynczy plik gadget.xmlAdres do tego pliku podajemy w panelu zarządzania aplikacjami i stronami.

Przygotowanie środowiska deweloperskiego1. Tworzymy aplikację na https://developers.nk.pl/developers2. Ustawiamy ją na tryb debug (wyłącza cache'owanie)3. Dodajemy swój NK ID do testerów aplikacji4. 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. ROT132. Informacje o użytkowniku3. Informacje o znajomych4. Embedding flash5. Swfobject6. Pogoda na nk (ale czemu nie działa!?)7. Hamster fall8. Dodawanie śledzia na nk

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

Płatności - Kod JSfunction 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ściW 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.1Host: gamehost.comContent-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ściAplikacja musi potwierdzić otrzymanie płatności poprzez wygenerowanie następującej odpowiedzi na request:

HTTP/1.1 200 OKContent-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 aplikacjifunction 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 aplikacjifunction 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 aplikacjifunction callback(responseItem) { if (responseItem.hadError()) { // handle error } else { console.log(responseItem); }}

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

invite();

Dodawanie fotkifunction 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ę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();

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

Wiadomość między użytkownikamifunction 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

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 funkcjiNależ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