4. 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>
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" - 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
6. 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!!
7. 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:
9. 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":{}}
10. 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
11. 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.
12. API JS
Aplikacje definiujemy przez pojedynczy plik gadget.xml
Adres do tego pliku podajemy w panelu zarządzania aplikacjami i stronami.
13. 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>
14. 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.
15. 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);
}
16. 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¶meters=some_app_specific_params&
paymentType=payment&viewerId=person.abc
17. 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.
18. 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();
19. 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();
20. 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();
21. Dodawanie fotki
function uploadPhotoHandler(resp) {
if (resp.hadError()) {
// handle error
}
}
function uploadPhoto() {
nk.photos.requestUploadAppPhoto("Photo added from Dev App", null, uploadPhotoHandler);
}
uploadPhoto();
22. 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();
23. 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");
24. Wiadomość między użytkownikami
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
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/
26. 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