Aplikācijas

Draugiem.lv API PHP bibliotēka

1.   Ievads

Lai aplikāciju izstrādi padarītu ātrāku un vienkāršāku, esam izveidojuši PHP bibliotēku, kas veic API izsaukumus un automātiski pārveido pieprasītos datus uz PHP datu struktūrām. PHP bibliotēka var tikt izmantota gan portālā integrētajām aplikācijām, gan draugiem.lv Pases aplikācijām.

Bibliotēka darbojas PHP5 vidē un tiek izmantots PHP sesiju mehānisms, lai uzglabātu lietotāja datus sesijā. Lai darbotos API izsaukumi, PHP konfigurācijā jābūt atļautai iespējai atvērt tīmekļa adreses, izmantojot file_get_contents funkciju (jābūt ieslēgtam allow_url_fopen konfigurācijas uzstādījumam).

Draugiem.lv API PHP bibliotēka un tās izmantošanas paraugi

Lai varētu savā aplikācijā izmantot API bibliotēku, tajā ir jāiekļauj fails DraugiemApi.php.

2.   Lietotāju dati PHP bibliotēkā

API bibliotēkas funkcijas, kas atgriež lietotāju datus, tos atgriež kā PHP masīvu, kura struktūra ir šāda:

array (
        'uid' => 491171,        //Draugiem.lv lietotāja ID
        'name' => 'Jānis',      //Vārds
        'surname' => 'Bērziņš', //Uzvārds
        'nick' => 'Jancis',     //Iesauka
        'place' => 'Rīga',      //Dzīvesvieta
        'age' => 26,    //Vecums (vai false, ja vecums slēpts)
        'adult' => true,//true, ja lietotājs sasniedzis 18 g.vecumu(arī ja vecums slēpts)
        //lietotāja profila attēla URL vai false, ja tas nav pievienots
        'img' => 'http://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg',
        'sex' => 'M',   //dzimums - M-vīrietis, F-sieviete
)

Ja funkcija atgriež informāciju par vairākiem lietotājiem (piemēram, draugu sarakstu), tad atgrieztie dati ir masīvs no vairākiem lietotāju datu masīviem, kurā katra elementa atslēga ir lietotāja ID. Ja pieprasīti tikai viena lietotāja profila dati, tiek atgriezts tikai atbilstošā lietotāja datu masīvs.

3.   Sesijas izveidošana un uzturēšana

API bibliotēka izmanto PHP sesiju mehānismu, lai sesijas ietvaros uzglabātu informāciju par aktīvo draugiem.lv lietotāju. Lai sāktu izmantot draugiem.lv API bibliotēku, jāizveido DraugiemApi objekts, konstruktoram padodot aplikācijas ID un API atslēgu. Pēc tam jāizsauc metode getSession, kas caur draugiem.lv API veic lietotāja autentifikāciju un iegūst lietotāja datus.

Aplikācijām, kas integrētas draugiem.lv, šī funkcija arī pārbauda, vai lietotāja draugiem.lv sesija joprojām ir aktīva (tāpēc aplikācijas pašai nav nepieciešams veikt session_check pieprasījumus).

Draugiem.lv Pases aplikācijām metode tikai veic autentifikāciju un datu iegūšanu, bet lietotāja sesija netiek sasaistīta ar draugiem.lv sesiju.

Ja metode atgriež true, tad sesijas izveidošana ir bijusi veiksmīga un lietotājs ir ienācis aplikācijā.:

<?php

include 'DraugiemApi.php';//API bibliotēka

$app_key = 'd6949661ccde33a65d98653043bc3119';//API atslēga
$app_id = 999;//Aplikācijas ID

//Izveido API objektu
$draugiem = new DraugiemApi($app_id, $app_key);

//Sāk sesiju (ja netiek sākta šeit, tad tā tiek automātiski
//izveidota getSession izsaukuma laikā).
session_start();

if($draugiem->getSession()){

        //Autorizācija sekmīga
        //Lietotāja dati ir pieejami pārējām API funkcijām

        $user = $draugiem->getUserData();//Lietotāja profila datu iegūšana

        //Izdrukājam sveicienu lietotājam
        if($user['img']){
                echo '<img src="'.$user['img'].'" alt="" /><br />';
        }
        echo 'Sveiki, '.$user['name'].' '.$user['surname'].'!<br />';

        $uid = $draugiem->getUserId(); //Iegūst draugiem.lv lietotāja ID

        $count = $draugiem->getFriendCount();//Iegūst lietotāja draugu skaitu šajā aplikācijā

        echo 'Šo aplikāciju lieto vēl '.$count.' tavi draugi.';

} else {
        echo 'Authorization failed';
        //Sesijas izveidošana neveiksmīga.
        //Lietotājs vai nu izgājis no draugiem.lv vai
        //nav izdevies aplikācijas autorizācijas pieprasījums.

        //Draugiem.lv Pases aplikācijai šādā situācijā būtu jāattēlo
        //saite uz pieteikšanās logu.
}

4.   Piekļuve lietotāju datiem ārpus sesijas

Ja nepieciešams izsaukt API funkcijas, kādam lietotājam, kas nav aktīvais sesijas lietotājs (piemēram, lai ievietotu paziņojumu lietotāja profila jaunumos, kamēr viņš nelieto aplikāciju), jāizveido jauns DraugiemApi objekts, konstruktoram padodot trešo parametru - lietotāja API atslēgu. Šim objektam iespējams izsaukt tās pašas metodes ko objektam, kas pieder aktīvajam sesijas lietotājam.:

$draugiem2 = new DraugiemApi($app_id, $app_key, $user_key);
$draugiem2 -> addNotification('Tev ir jauna vēstule');

Lietotāja API atslēgu iespējams iegūt ar metodi getUserKey pēc tam, kad viņš ir veiksmīgi autentificēts aplikācijā ar getSession metodi. Lai varētu atslēgu izmantot, kamēr lietotājs neizmanto aplikāciju, aplikācijai tā ir jāuzglabā pie sevis.

Lietotāja API atslēga nemainās, kamēr lietotājs neizdzēš aplikāciju no profila vai arī nenomaina savu draugiem.lv lietotāja paroli. Lai nodrošinātu, ka aplikācijai vienmēr pieejama pareizā atslēga, vēlams pēc sesijas izveidošanas pārliecināties, ka atslēga nav mainījusies, un vajadzības gadījumā saglabāt jauno atslēgu.

5.   API klases metožu apraksts

5.3.   apiCall($action, $args, $method = 'GET')

Izsauc draugiem.lv API pieprasījumu un atgriež atbildi kā PHP datu struktūru. Pārsvarā šo metodi izmanto citas draugiem.lv PHP bibliotēkas metodes, tāpēc tiešā veidā to vajadzīgs izsaukt tikai tad, ja jāizsauc kāds API pieprasījums, kam PHP bibliotēkā nav paredzēta atsevišķa metode. Noklusētā REQUEST metode ir 'GET', bet vajadzības gadījumā iespējams padot arī 'POST'.

$action
Veicamā API pieprasījuma nosaukums (API pieprasījuma action parametra vērtība)
$args
Asociatīvais masīvs ar pieprasījumam padodamajiem parametriem un tiem atbilstošajām vērtībām (masīvā nav jāiekļauj action, app un apikey parametri, kas pieliekas automātiski)
$method
Veicamā API pieprasījuma tips. Pēc noklusējuma tas ir 'GET', bet to var nomainīt uz 'POST'.
Atgriežamā vērtība
Metode atgriež PHP masīvu ar API pieprasījuma atbildes datiem vai false, ja pieprasījums nav izdevies, vai atgriezta API kļūda.

5.4.   checkFriendship($uid, $uid2)

Pārbauda, vai divi aplikācijas lietotāji savā starpā ir draugi.

$uid
Pirmā lietotāja ID
$uid2
Otrā lietotāja ID (neobligāts, nenorādot šo parametru, tiks pārbaudīta $uid un aktīvā aplikācijas lietotāja draudzība)
Atgriežamā vērtība
true, ja lietotāji savā starpā ir draugi, false, ja pieprasījums nav izdevies, lietotāji nav draugi vai kāds no viņiem nav aplikācijas lietotājs.

5.5.   cookieFix()

Mēģina apiet sīkdatņu (cookies) izveidošanas ierobežojumus Internet Explorer un Safari pārlūkprogrammās. Šī metode jāizsauc pašā koda sākumā, pirms getSession(). Metode automātiski nosaka lietotāja pārlūkprogrammas versiju, tāpēc var tikt izsaukta nepārbaudot, kādu pārlūku lietotājs izmanto.

Metode neko neatgriež un nesaņem nekādus papildu parametrus. Tā jālieto tikai portālā integrētajām aplikācijām, kas izmanto iframe.

5.6.   getAppUsers ($page, $limit, $return_ids)

Atgriež lappusi ar aplikācijas lietotājiem (saraksta sākumā būs tie, kas pēdējie pievienojušies aplikācijai). Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus.

$page
Atgriežamās lietotāju lappuses numurs, kas jāatgriež (numerācija sākas ar 1)
$limit
Vajadzīgais lietotāju skaits vienā lapā (maksimālā atļautā vērtība 200)
$return_ids
true, ja vajadzīgs atgriezt tikai lietotāju ID vai false (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati.
Atgriežamā vērtība
Masīvs ar lietotāju ID vai profila datiem vai false, ja pieprasījums nav izdevies.

5.7.   getFriendCount()

Iegūst lietotāja draugu skaitu starp aplikācijas lietotājiem. Atgriež draugu skaitu vai false, ja pieprasījums nav izdevies.

5.8.   getInviteInfo()

Iegūst informāciju par uzaicinājumu, ko lietotājs apstiprinājis, kad sācis lietot aplikāciju. Darbojas tikai jauna lietotāja pirmās sesijas laikā. Metode jāizsauc pēc getSession izsaukuma.

Ja informācija par uzaicinājumu ir atrasta, metode atgriež datus ar šādu struktūru:

array(
        'inviter' => 123, //Lietotāja ID, kas sūtījis uzaicinājumu
        'extra' => '' //Papildu dati, kas ļauj identificēt uzaicinājumu, ja aplikācijas izstrādātājs tādus pievienojis.
)

Ja informācija nav atrasta, metode atgriež false

5.9.   getJavascript($resize_container, $callback_html)

Atgriež HTML kodu, kas jāizvada lapā, lai tajā būtu pieejamas draugiem.lv Javascript API funkcijas. Šī iespēja attiecas tikai uz portālā integrētajām aplikācijām. Metode jāizsauc pēc getSession izsaukšanas un atgrieztais kods jāizvada starp lapas <head> tagiem.

$resize_container
Lapas HTML elementa ID, pēc kura izmēriem jāveic automātiska draugiem.lv iframe loga vertikālā izmēra maiņa. Nenorādot šo parametru, automātiska izmēra maiņa netiks veikta.
$callback_html
callback.html faila adrese uz aplikācijas servera, norādot pilnu domēnu. Šis parametrs ir neobligāts, bet, nenorādot to, aplikācija nevarēs saņemt atbildes vērtības no izsauktajām Javascript API funkcijām.
Atgriežamā vērtība
HTML kods, kas jāizvada aplikācijas lapā.

5.10.   getLoginButton($redirect_url, $popup)

Atgriež HTML kodu, kas ļauj izvadīt lapā draugiem.lv pases pieteikšanās pogu. Metode attiecas tikai uz draugiem.lv pases aplikācijām.

$redirect_url
Adrese, uz kuru jāpārsūta lietotājs pēc pieteikšanās ar draugiem.lv pasi
$popup
Vai draugiem.lv pases pietiekšanās logu jāatver jaunā izlecošajā logā. (true - jā, false - nē)
Atgriežamā vērtība
HTML kods, kas jāizvada lapā vietā, kur nepieciešama pieteikšanās poga.

5.11.   getLoginUrl($redirect_url)

Atgriež WWW adresi draugiem.lv pases pieteikšanās logam ar norādīto atpakaļpārsūtīšanas adresi.

$redirect_url
Adrese, uz kuru jāpārsūta lietotājs pēc pieteikšanās ar draugiem.lv pasi
Atgriežamā vērtība
Draugiem.lv pases pieteikšanās loga adrese.

5.12.   getSession()

Veic draugiem.lv lietotāja autentifikāciju un iegūst pamatinformāciju par lietotāju. Vienmēr jāizsauc pirms pārējām klases metodēm, izņemot gadījumus, kad bibliotēka tiek izmantota, norādot lietotāja API atslēgu konstruktorā. Darbībai tiek izmantots PHP iebūvētais sesiju mehānisms. Integrētajām aplikācijām šī metode arī periodiski veic sesijas pārbaudi ar session_check pieprasījumu.

Atgriežamā vērtība
true, ja autentifikācija veiksmīga un iegūti derīgi lietotāja dati, false, ja autentifikācija nav veiksmīga vai lietotāja sesija beigusies.

5.13.   getSessionDomain()

Atgriež draugiem.lv domēna adresi, no kura lietotājs ienācis aplikācijā. Metode attiecas tikai uz integrētajām aplikācijām. Aplikācijai var būt vajadzīgs zināt domēnu, piemēram, lai korekti attēlotu saites uz lietotāja profiliem. Tipiskā gadījumā domēna vērtība būs www.draugiem.lv, taču iespējamas arī citas vērtība, piemēram, ja lietotājs lieto draugiem.lv citā valodā.

5.14.   getUserCount()

Iegūst aplikācijas reģistrēto lietotāju skaitu. Atgriež lietotāju skaitu vai false, ja pieprasījums nav izdevies.

5.15.   getUserData($ids)

Atgriež pieprasīto lietotāju profila informāciju.

$ids
Norāda, kuru lietotāju datus atgriezt. Ja norādīts masīvs ar lietotāju ID (maksimāli 100 vērtības), tiek atgriezts masīvs ar norādīto lietotāju datiem (satur tikai to lietotāju datus, kas ir reģistrēti aplikācijas lietotāji). Ja parametrā padots viens lietotāja ID, tad tiek atgriezti tikai šī lietotāja dati vai false, ja tie nav pieejami. Ja parametra vērtība ir false, tad atgriezti tiek dati par aktīvo aplikācijas lietotāju.

5.16.   getUserFriends($page, $limit, $return_ids)

Atgriež lappusi ar aplikācijas lietotāja draugiem, kas arī lieto aplikāciju. Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus.

$page
Atgriežamās draugu lappuses numurs, kas jāatgriež (numerācija sākas ar 1)
$limit
Vajadzīgais lietotāju skaits vienā lapā (maksimālā atļautā vērtība 200)
$return_ids
true, ja vajadzīgs atgriezt tikai lietotāju ID vai false (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati.
Atgriežamā vērtība
Masīvs ar lietotāja draugu ID vai profila datiem vai false, ja pieprasījums nav izdevies.

5.17.   getAllUserFriends($page, $limit, $return_ids)

Atgriež lappusi ar aplikācijas lietotāja draugiem. Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus. Ja draugs nav aplikācijas lietotājs, tad par viņu pieejama informācija tikai par vārdu, uzvārdu, dzimumu un profila attēlu.

$page
Atgriežamās draugu lappuses numurs, kas jāatgriež (numerācija sākas ar 1)
$limit
Vajadzīgais lietotāju skaits vienā lapā (maksimālā atļautā vērtība 200)
$return_ids
true, ja vajadzīgs atgriezt tikai lietotāju ID vai false (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati.
Atgriežamā vērtība
Masīvs ar lietotāja draugu ID vai profila datiem vai false, ja pieprasījums nav izdevies.

5.18.   getOnlineFriends($limit, $in_app, $return_ids)

Atgriež sarakstu ar aplikācijas lietotāja draugiem, kas arī lieto aplikāciju un šobrīd ir ienākuši draugiem.lv. Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus.

Funkcija pieejama tikai integrētajām aplikācijām brīdī, kad lietotājs pats atrodas online.

$limit
Vajadzīgais lietotāju skaits (maksimālā atļautā vērtība 100)
$in_app
true, ja vajadzīgs to draugu saraksts, kas tieši šobrīd lieto aplikāciju, false, ja vajadzīgs to draugu saraksts, kas atrodas portālā un ir reģistrēti aplikācijas lietotāji.
$return_ids
true, ja vajadzīgs atgriezt tikai lietotāju ID vai false (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati.
Atgriežamā vērtība
Masīvs ar lietotāja draugu ID vai profila datiem vai false, ja pieprasījums nav izdevies.

5.19.   getUserId ()

Atgriež aktīvā lietotāja ID vai false, ja tas nav pieejams.

5.20.   getUserKey ()

Atgriež aktīvā lietotāja API atslēgu vai false, ja tā nav pieejama.

5.21.   getUserLanguage ()

Atgriež aktīvā lietotāja portālā uzstādītajai valodai atbilstošo divu burtu kodu (lv/ru/en/de/hu/lt).

5.22.   imageForSize($img, $size)

Atgriež lietotāja profila attēla adresi vajadzīgajā izmērā.

$img
Lietotāja profila attēla adrese standarta izmērā (adrese, kas iegūta no API)
$size
Vajadzīgais attēla izmērs (icon - 50x50px / small - 100x100px / medium - 215px plats / large - 710px plats)
Atgriežamā vērtība
Lietotāja profila attēla adrese prasītajā izmērā.