API IKOL z punktu widzenia programisty
Niedawno pisaliśmy o otwarciu całego środowiska IKOL API, z darmowym dostępem dla wszystkich, którzy chcą tworzyć aplikację monitoringu GPS, bez potrzeby martwienia się o całą infrastrukturę serwerową systemu. Dzisiejszy wpis będzie techniczno-informatycznym opisem, instrukcją, tworzenia aplikacji mobilnej lub webowej w oparciu o interfejs programowania IKOL API.
Czym jest API?
API, (ang. application programming interface) jest w dzisiejszych czasach nieodłączną częścią internetu. Do czego służy? API służy do integrowania dwóch systemów, na przykład aplikacji IKOL Tracker z platformą IKOL dostępną na system.ikol.pl. Jedna z tych zintegrowanych stron posiada cały system serwerów (platforma IKOL) i to ona udostępnia API. Druga strona to klient. Klient to oddzielny program (w powyższym przykładzie aplikacja IKOL Tracker), która poprzez kod programistyczny i udostępnione API może pobierać dane z serwerów IKOL tak, by wykorzystać je do czegoś przydatnego dla użytkowników.
Poniżej prezentowany jest jedynie zarys aplikacji, która może przedstawiać dowolnemu użytkownikowi systemu IKOL aktualną pozycję lokalizatora. Biblioteka funkcji API rozwija się wraz z rozbudową systemu IKOL i umożliwia wykonanie dużo bardziej skomplikowanych aplikacji, niż zarys przedstawiony poniżej. Aplikacja mobilna IKOL Tracker, rozwijana i utrzymywana przez dział rozwoju software’u IKOL, została zbudowana w oparciu o IKOL API. Oznacza to, że każdy może stworzyć taką aplikację jak IKOL Tracker dla dowolnej platformy.
1. Tworzenie sesji użytkownika
Aby móc otrzymać jakiekolwiek informacje o lokalizatorach, użytkowniku, pozycji GPS itp., konieczne jest przeprowadzenie użytkownika i otrzymanie klucza sesji. Nawiązywanie sesji przeprowadzane jest za pomocą funkcji iaLoginSession. Jako parametry wywołania tej funkcji podaje się login (login) oraz hasło (password) użytkownika, klucz API aplikacji wygenerowany w panelu IKOL (appkey). W przypadku tworzenia aplikacji mobilnych, które będą umożliwiały prezentowanie powiadomień mobilnych, konieczne jest jeszcze podanie identyfikatora GCM/FCM (gcm_id) oraz określenie, że dana instancja aplikacji jest gotowa na otrzymywanie tych powiadomień (gcm_stat).
| https://api.ikol.pl/iaLoginSession?login=user&password=pass&appkey=nHgdYtdg54&gcm_id= bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1&gcm_stat=1&output=json
Jako odpowiedź API zwróci identyfikator sesji (sid), który będzie wykorzystywany dalej przy wszystkich zapytania do systemu ikol API. { |
2. Otrzymywanie informacji o zalogowanym użytkowniku
Po zalogowaniu użytkownika aplikacja może chcieć zaprezentować jaki użytkownik został uwierzytelniony. W celu otrzymania informacji o użytkowniku należy skorzystać z funkcji iaGetUserInformation i jako parametr (key) podać identyfikator użytkownika. Warto w tym miejscu zauważyć, że w każdym kolejnym wywoływaniu funkcji ikol API konieczne jest podanie parametru identyfikatora sesji (sid).
https://api.ikol.pl/iaGetUserInformation?sid=rokm0290p8qvgke2d5114df85&key=kayne@example.com&output=json
Zwrotnie system prześle podstawowe informacje o zalogowanym użytkowniku takie jak jego imię, nazwisko, email, telefon, datę ostatniego logowania oraz URL zdjęcia awatara. W zależności od konstrukcji budowanego systemu, otrzymane informacje o użytkowniku powinny być w jakiś sposób lokalnie przetrzymywane (cachowane lub zapisywane w lokalnej bazie danych) i okresowo odświeżane aby móc prezentować aktualne dane na wypadek gdyby zostały zmodyfikowane przez administratora systemu.
| { „users”: { „kayne@example.com”: { „login”: „kayne@example.com”, „name”: „Kayne”, „surname”: „”, „email”: „kayne@example.com”, „phone”: „”, „activitydate”: 20170105145125, „picture”: „https://storage.ikol.pl/data/us/pics/Xmt7WNCdWO48jgI/picture_100.jpg”, „stat”: 0, „statdesc”: „OK” } }, „result”: 0, „resultdesc”: „OK” } |
3. Pobieranie listy lokalizatorów
Po otrzymaniu informacji o zalogowanym użytkowniku, można zacząć zajmować się kluczowymi rzeczami związanymi z monitoringiem GPS lokalizatorów. Należy zacząć od pobrania listy lokalizatorów danego użytkownika. Służy do tego funkcja iaGetUserLocators. Jako parametr funkcji podaje się uprawnienie do lokalizatora (access_rights), które jest wymagane dla zalogowanego użytkownika. Np. podanie DSPLY jako wartości parametru access_right spowoduje, że zostanie zwrócona lista lokalizatorów, których pozycję geograficzną (niezbędną do pokazanie na mapie) może uzyskać zalogowany użytkownik. Analogicznie podanie DSPLY,ALERT jako wartości tego parametru spowoduje, że zwrócona zostanie lista lokalizatorów, które zalogowany użytkownik może przeglądać na mapie. Może zmieniać ustawienia dotyczące alertów.
| https://api.ikol.pl/iaGetUserLocators?sid=rokm0290p8qvgke2d5114df85&access_rights=DSPLY&output=json |
Zwrotnie system przekaże tablicę zawierającą wszystkie podstawowe informacje o lokalizatorach. Oprócz takich danych jak marka i model pojazdu, sugerowana ikona prezentująca pojazd czy etykieta ustawiona przez użytkownika, najważniejsza będzie, z punktu widzenia twórcy aplikacji, informacja o kluczu API danego lokalizatora. Klucz API zwrócony we właściwości generalinfo.key jest konieczny do identyfikowania lokalizatora w kolejnych, niżej opisanych, funkcjach IKOL API. Dane otrzymane jako wynik tej funkcji powinny pozwolić na wyświetlenie pewnego rodzaju listy lokalizatorów w tworzonej aplikacji. Sugeruje się, aby dane te również były przechowywane lokalnie w celu optymalizacji działania aplikacji i okresowo odświeżane. W tym miejscu warto zwrócić uwagę na platformę sprzętową lokalizatora, która przekazywana jest we właściwości generalinfo.platform i może przyjmować wartości V, P lub M oznaczające odpowiednio lokalizatory montowane w pojazdach, lokalizatory przenośne i lokalizatory mobilne (IKOL X). Od platformy będzie zależało jakiego rodzaju informacje będą przekazywane dla danego lokalizatora (opisane w kolejnych krokach).
| { „locators”: [{ „group”: { „name”: „Test locators”, „order”: „1”, „default_open”: „1” }, „generalinfo”: { „key”: „apikey1”, „id”: „868789020145498”, „platform”: „V” }, „display”: { „label”: „CC9827A”, „icon”: „http://system.ikol.pl/graphics/icons/maps/v/carsmpy.png” }, „vehicle”: { „make”: „Mercedes”, „model”: „SPRINTER”, „plateid”: „CC9827A”, „vin”: „993477388288222” }, „users”: { „mainuser”: „Roger Bond” } }, { „group”: { „name”: „Test locators”, „order”: „1”, „default_open”: „1” }, „generalinfo”: { „key”: „apikey2”, „id”: „862170014709487”, „platform”: „V” }, „display”: { „label”: „John Wright”, „icon”: „http://system.ikol.pl/graphics/icons/maps/v/carsmpb.png” }, „vehicle”: { „make”: „Honda”, „model”: „ACCORD”, „plateid”: „X0PLATE”, „vin”: „ABC123456789ABCDEH” }, „users”: { „mainuser”: „Ann Frost” } }, { „group”: { „name”: „Private locators”, „order”: „2”, „default_open”: „0” }, „generalinfo”: { „key”: „apikey3”, „id”: „860599000023472”, „platform”: „P” }, „display”: { „label”: „ikol SPOT”, „icon”: „http://system.ikol.pl/graphics/icons/maps/v/carpckr.png” }, „users”: { „mainuser”: „Rex” } }], „result”: „0”, „resultdesc”: „OK” } |
4. Pobieranie aktualnej pozycji lokalizatora
W końcu można przejść do sedna aplikacji monitorującej pozycje GPS, czyli do pobierania współrzędnych geograficznych lokalizatora. Służy do tego funkcja iaGetLocatorLastPosition, przy wywołaniu której jako parametr (key) należy podać klucz API lokalizatora (co najmniej jeden).
https://api.ikol.pl/iaGetLocatorLastPosition?sid=rokm0290p8qvgke2d5114df85&key=apikey2&timezone=utc&output=json
Zwrotnie system przekaże aktualną pozycję geograficzną, prędkość, wysokość oraz kierunek przemieszczania się lokalizatora. Dodatkowo, w zależności od platformy lokalizatora, przekazane będą takie informacje jak poziom paliwa, stan uruchomionego wyłącznika rozrusznika, imię i nazwisko zidentyfikowanego kierowcy, stan napięcia głównego zasilania czy stan naładowania baterii zapasowej. Ilość dostępnych informacji uzależniona jest od rodzaju wyposażenia lokalizatora i przekazywana jest we właściwości locator.key.position.mask. W celu należytej prezentacji odebranych danych aplikacja powinna przedstawić pozycję geograficzną lokalizatora na mapie. Istnieje wiele różnych systemów mapowych zarówno dla aplikacji mobilnych jak i webowych, które oferują oddzielne API umożliwiające prezentację pozycji geograficznej za pomocą markera na mapie. We właściwości locator.key.position.extra.icon proponowana jest ikona lokalizatora, która zawiera w postaci graficznej wszystkie podstawowe informacje o lokalizatorze (np. czy stan zasilania, baterii i sygnały GPS jest prawidłowy). Oczywiście projektując aplikację można korzystać z własnych ikon lub markerów.
| { „locator”: { „apikey2”: { „request”: { „stat”: „0”, „statdesc”: „OK” }, „position”: { „mask”: „dfb”, „gps”: { „timestamp”: „20150531142322”, „expired”: „0”, „geopoint”: { „lat”: „52.169508”, „lng”: „20.938908” }, „acquisition”: „GPS”, „accuracy”: „1”, „heading”: { „value”: „27”, „dir”: „NE” }, „gpsfix”: „1”, „speed”: „0”, „speedlimit”: „0”, „altitude”: „107.6” }, „extra”: { „icon”: „http://img.ikol.pl/graphics/icons/maps/v/cartrkr_0_0_0_0_1_3_0_0.png”, „driver”: { „name”: „Michau0142 Kowalski”, „ibutton”: „” } }, „tech”: { „ignition”: „0”, „movestate”: „3”, „power”: „12.866”, „powerok”: „1”, „engineon”: „0”, „odometer”: { „value”: „67508.8”, „valuetype”: „H” }, „worktime”: „28.505555555556”, „fuel”: { „level”: „16”, „leveltype”: „P”, „range”: „143” }, „rpm”: 1742, „coolanttemp”: 62, „axleweight”: 1500, „tachodata”: { „driver1”: „1132”, „driver2”: „0000” } „indicators”: { „mask”: „1111111111111111”, „active_mask”: „0000000010001000” }, „ignitioncrtl”: { „status”: „0”, „phase”: „0” } } } } }, „result”: „0”, „resultdesc”: „OK” } |
5. Otrzymywanie powiadomień GCM/FCM
Jeśli podczas otwierania sesji użytkownika podany był identyfikator urządzenia mobilnego, systemy powiadomień systemu IKOL będą wysyłały wiadomości alarmowe poprzez GCM/FCM (Google/Firebase Cloud Messaging). Aplikacja mobilna powinna w takim przypadku móc obsłużyć otrzymywane wiadomości i odpowiednio je przekazać użytkownikowi aplikacji. Przykładowa wiadomości alarmowa będzie miała prezentowaną poniżej treść, która zawiera wszystkie informacje umożliwiające wyświetlenie wiadomości alarmowej użytkownikowi. Właściwość locator.key.event informuje o rodzaju alertu, który został wzbudzony.
| { „message”:{ „type”:1, „timestamp”:”20160431150516″ }, „locator”:{ „apikeyX”:{ „id”:”IT:0106e9ed”, „vehicle”: { „make”: „Honda”, „model”: „ACCORD”, „plateid”: „X0PLATE”, „vin”: „ABC123456789ABCDEH”, „label”: „John Wright”, „icon”: „http://system.ikol.pl/graphics/icons/maps/v/carsmpb.png” }, „event”:”0200″, „timestamp”:”20160231124700″, „params”:{ „stat”:1, „name”:”120 min.”, „key”:”apikey1:3730″ }, „geopoint”:{ „lng”:21.928678, „lat”:51.129543 } } } } |
6. Kończenie sesji użytkownika
Gdy użytkownik kończy pracę z aplikacją dobrą praktyką jest zakończenie otwartej sesji. W tym celu należy posłużyć się funkcję iaLogoutSession i jako parametr się podać identyfikator bieżącej aktywnej sesji.
Kategorie: Wszystkie, Ciekawostki | Komentarze: Brak
