Spēles

Draugiem.lv integrēto aplikāciju API dokumentācija

Saturs

1.   Portālā integrētās aplikācijas

1.1.   Ievads

Draugiem.lv integrētās aplikācijas sniedz iespēju ievietot ārējas lapas draugiem.lv portālā kā atsevišķas sadaļas tā, ka vizuāli tās gandrīz neatšķiras no citām draugiem.lv sadaļām.

img/iframe.png

Aplikācijas tiek integrētas draugiem.lv dizainā, izmantojot iframe risinājumu. Lapas saturam atvēlēts 1080 pikseļus plats iframe objekts, kurā tiek atvērta izstrādātāja norādītā lapas adrese. Iframe sākotnējo augstumu iespējams norādīt aplikācijas uzstādījumos (noklusētais augstums 700 pikseļi), kā arī regulēt atbilstoši lapas satura izmēram, izmantojot Javascript API. Katrai aplikācijai tiek piesaistīta īsā adrese formā https://www.draugiem.lv/[aplikācijas_nosaukums]/. Īso adresi izvēlas aplikācijas izstrādātājs, izveidojot aplikāciju.

Ja aplikācijas iestatījumos norāda mobile iframe adresi, tad aplikācija ir pieejama arī https://m.draugiem.lv/[aplikācijas_nosaukums].

img/allow.png

Pirmo reizi atverot aplikāciju, lietotājs piekrīt nodot savu profila informāciju trešās puses izstrādātājam. Pēc apstiprināšanas tiek atvērts aplikācijas iframe logs, un lietotājs nonāk aplikācijas vidē.

Pēc piekļuves apstiprināšanas aplikācija iegūst lietotāja API atslēgu, kas dod tai piekļuvi ierobežotam apjomam lietotāja datu (profila pamatinformācija, un informācija par lietotāja draugiem, kas izmanto šo pašu aplikāciju), kā arī iespēju pievienot aktivitātes un profila jaunumus lietotāja profilā (ja šīs iespējas aplikācijai ir pieejamas un lietotājs nav aizliedzis pievienošanu).

Nākamajās aplikācijas lietošanas reizēs lietotājs uzreiz nonāk aplikācijā, bez vajadzības to vēlreiz apstiprināt.

Ja lietotājs pēc kāda laika vēlas pārtraukt aplikācijas izmantošanu, viņš var atteikties no tās, izmantojot funkciju savā draugiem.lv profilā. Kopš atteikšanās brīža lietotāja dati attiecīgajai aplikācijai vairs nav pieejami.

Aplikācijām ir pieejama uzaicinājumu sistēma, kas ļauj to lietotājiem uzaicināt savus draugus kļūt par aplikācijas lietotājiem.

Ja portālā integrēta aplikācija piedāvā maksas pakalpojumus, to nodrošināšanai jāizmanto draugiem.lv piedāvātais maksājumu API, kas piedāvā iespēju apmaksāt pakalpojumus, izmantojot draugiem.lv kredītu sistēmu. Aplikācijas izstrādātājs ar SIA Draugiem slēdz līgumu, kas nosaka ieņēmumu sadalījumu un abu pušu saistības.

1.2.   Autorizācijas koda iegūšana

Līdzīgi kā izmantojot draugiem.lv pasi, arī integrētās aplikācijas izmanto autorizācijas kodu, lai piekļūtu lietotāja API atslēgai. Atverot iframe logu pēc tam, kad lietotājs ir apstiprinājis, ka ļauj aplikācijai piekļūt viņa datiem, iframe adresei tiek pievienoti šādi GET parametri:

dr_auth_status:vērtība ok
dr_auth_code:autorizācijas kods (20 simboli), ar kura palīdzību aplikācija var iegūt lietotāja API atslēgu
session_hash:lietotāja draugiem.lv sesijas identifikators (32 bitu pozitīvs skaitlis), ar kura palīdzību aplikācija var pārbaudīt, vai lietotāja draugiem.lv sesija joprojām ir aktīva
domain:draugiem.lv domēns, kurā ir atvērta aplikācija (parasti www.draugiem.lv)

Kad saņemts autorizācijas kods, aplikācijai jāveic authorize API pieprasījums (nodaļa Lietotāja autorizācija), lai saņemtu lietotāja API atslēgu, kas nepieciešama turpmāku API pieprasījumu veikšanai. Autorizācijas kods vienas draugiem.lv lietotāja sesijas laikā ir nemainīgs, tāpēc, ja aplikācija vienas sesijas laikā vēlreiz saņem to pašu autorizācijas kodu (piemēram, gadījumos, kad lietotājs vairākkārt atver aplikācijas iframe), nav nepieciešams atkārtoti veikt authorize pieprasījumu. Ja saņemts autorizācijas kods, kas atšķiras no iepriekšējā, obligāti jāatkārto authorize pieprasījums - šāda situācija nozīmē, ka aplikāciju sācis lietot cits lietotājs, kas ienācis draugiem.lv no tā paša datora.

1.3.   Papildu parametru nodošana iframe adresei

Noklusēti iframe logā tiek atvērta adrese, kas norādīta aplikācijas uzstādījumos (pievienojot tai galā autorizācijas parametrus). Ir iespējams panākt, ka iframe logā tiek atvērta cita adrese, pievienojot īsajai adresei galā papildu GET parametrus vai mapes ceļu.

Piemērs: aplikācijas īsā adrese ir https://www.draugiem.lv/aplikacija/, bet satura adrese - https://example.com/app/. Pievienojot īsajai adresei papildus datus, iespējams atvērt iframe logā adreses sekojošā veidā:

Adrese, ko atver lietotājs Adrese, kas tiks attēlota iframe logā
https://www.draugiem.lv/aplikacija/ https://example.com/app/
https://www.draugiem.lv/aplikacija/test/123 https://example.com/app/test/123
https://www.draugiem.lv/aplikacija/?a=1&b=2 https://example.com/app/?a=1&b=2
https://www.draugiem.lv/aplikacija/test/?a=1 https://example.com/app/test/?a=1
https://www.draugiem.lv/aplikacija/a.php šāda adrese nedarbosies, atļauts pievienot tikai GET parametrus vai mapes ceļu

Iframe logā atvērtajai adresei galā vienmēr tiks pievienoti arī autorizācijas parametri

1.4.   Lietotāju piekļuve aplikācijai

Tikko izveidotai aplikācijai var piekļūt tikai tās autors, kā arī draugiem.lv darbinieki. Pārējiem lietotājiem tiek parādīts paziņojums, ka aplikācija atrodas izstrādes režīmā un nav pieejama. Aplikācijas autors var piešķirt citiem saviem draugiem piekļuvi aplikācijai kā izstrādātājiem (līdz 30 cilvēkiem) vai administratoriem (līdz 10 cilvēkiem). Aplikācijas izstrādātājiem atļauts piekļūt aplikācijai arī tad, kad tā atrodas izstrādes režīmā vai ir uz laiku slēgta. Aplikācijas administratoriem pieejamas visas tās pašas iespējas kā aplikācijas īpašniekam, izņemot aplikācijas dzēšanu.

Kad aplikācijas iztrāde tuvojas beigām, iespējams aplikāciju iesniegt testēšanai draugiem.lv laboratorijā. Šajā stadijā aplikācijai var piekļūt visi apstiprinātie draugiem.lv laboratorijas lietotāji. Aplikācijas izstrādātājiem un testētājiem ir pieejama domubiedru grupa, kurā apspriest aplikācijas darbību.

Kad aplikācija pabeigta, tā var tikt iesniegta publicēšanai draugiem.lv portālā. Publicētu aplikāciju var sākt lietot jebkurš draugiem.lv lietotājs (iespējams arī ierobežot piekļuvi tikai lietotājiem, kas sasnieguši noteiktu vecumu). Izstrādātājam ir pieejama iespēja aplikāciju uz laiku aizvērt (piemēram, tehniskās apkopes vajadzībām).

Ievērojiet, ka aplikācijas izstrāde negarantē tās publicēšanu portālā. Tāpēc, lai izvairītos no pārpratumiem, ļoti ieteicams pirms aplikācijas izstrādes konsultēties ar draugiem.lv pārstāvjiem, lai noskaidrotu, vai aplikācija būs atbilstoša publicēšanai portālā.

Iframe aplikāciju iespējams lietot arī izmantojot draugiem.lv pasi. Šī iespēja ļauj jums vienu un to pašu aplikāciju gan publicēt draugiem.lv portālā, gan iekļaut ārējā mājas lapā, kas pieejama arī lietotājam neapmeklējot draugiem.lv.

1.5.   Daži ieteikumi izstrādātājiem

Lai maksimāli pareizi un efektīgi izmantotu draugiem.lv API iespējas, vēlams sekot šādiem principiem:

  • Pēc lietotāja autorizācijas iegūto informāciju par lietotāju jāuzglabā sesijā aplikācijas pusē, nevis jāprasa atkārtoti caur draugiem.lv API pie katras lapas atvēršanas.
  • Ja lapā daudzās vietās jāattēlo lietotāju dati, tad arī tos vēlams uzglabāt lokāli un atjaunot ik pēc laika, nevis pie katra pieprasījuma, lai lieki nenoslogotu gan savu, gan draugiem.lv serveri.
  • Ja jūsu lapa izstrādāta PHP valodā, visērtāk to integrēt portālā, izmantojot mūsu sagatavoto PHP koda bibliotēku.
  • Ja vēlaties savu aplikāciju publicēt draugiem.lv lietotājiem vai nodot testēšanai draugiem.lv laboratorijā, vai arī vēlaties pieslēgt aplikācijai maksas pakalpojumus, draugu aktivitātes vai profila jaunumu pievienošanas iespēju, rakstiet e-pastu uz api@draugiem.lv
  • Nodrošiniet, lai neviens cits neuzzinātu Jūsu aplikācijas API atslēgu.
  • Lai palielinātu drošību, ierobežojiet jūsu aplikācijas piekļuvi draugiem.lv API tikai no jūsu servera IP adreses (to var izdarīt aplikācijas uzstādījumos). Nekādā gadījumā neveiciet API pieprasījumus no klienta puses (Javascript vai Flash vidēs) - tā jūsu API atslēga kļūs pieejama visiem.

1.6.   Sesijas izveidošanas problēmas Safari pārlūkā

Safari pārlūks ar noklusētajiem uzstādījumiem neļauj uzstādīt sīkdatnes (cookies) lapās, kas atvērtas iframe logā, un atrodas zem cita domēna kā lapa, kurā tās ievietotas. Sīkdatnes tiek uzstādītas tikai pēc tam, kad lietotājs ir veicis kādas darbības iframe logā atvērtajā lapā. Šī iemesla dēļ Safari pārlūkā atvērtām draugiem.lv iframe aplikācijām var rasties problēmas izveidot lietotāja sesiju, jo pirmajā pieprasījumā izveidotā sesijas sīkdatne netiek saglabāta. Tāpēc aplikācijas izstrādātājiem jānodrošina sesijas ID nodošana nākamajam pieprasījumam, neizmantojot sīkdatnes.

Šo ierobežojumu pagaidām iespējams apiet, nosūtot formu ar Javascript, lai simulētu lietotāja veiktu darbību.

Izmantojot mūsu piedāvāto PHP koda bibliotēku, var izmantot CookieFix funkciju, lai apietu šo ierobežojumu.

1.7.   Sesijas izveidošanas problēmas Internet Explorer pārlūkā

Līdzīgi kā Safari, arī Internet Explorer lietotājiem, kam Privacy uzstādījums ir iestatīts uz līmeni Medium, var būt problēmas ar sīkdatņu (cookies) uzstādīšanu iframe logā. Lai apietu šo problēmu, atvērtajā lapā jāuzstāda šāda HTTP header vērtība (PHP koda paraugs, funkcija header jāizsauc, pirms lapā veikta jebkādu datu izvadīšana):

header('P3P:CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"');

Izmantojot mūsu piedāvāto PHP koda bibliotēku, var izmantot CookieFix funkciju, lai apietu šo ierobežojumu.

2.   API lietošana

2.1.   API pieprasījumu veikšana

Lai iegūtu datus vai veiktu citas darbības ar draugiem.lv API, aplikācijas serveris veic HTTP POST vai GET pieprasījumu uz draugiem.lv serveri, norādot parametros vērtības atbilstoši attiecīgā pieprasījuma specifikācijai. Parametri var tikt padoti, izmantojot HTTP GET, POST un COOKIE mainīgos.

Adrese, uz kuru jāsūta draugiem.lv API pieprasījumi, ir atkarīga no izvēlētā datu apmaiņas formāta. Pieejami šādi datu apmaiņas formāti:

Formāts Paskaidrojums API adrese
XML atbildes uz API pieprasījumiem tiek pārsūtītas XML formātā https://api.draugiem.lv/xml/
PHP atbildes uz API pieprasījumiem tiek pārsūtītas PHP serializēto datu formātā https://api.draugiem.lv/php/
JSON atbildes uz API pieprasījumiem tiek pārsūtītas JSON datu formātā https://api.draugiem.lv/json/
PLIST atbildes uz API pieprasījumiem tiek pārsūtītas Apple Property List XML datu formātā https://api.draugiem.lv/cocoa/

Dokumentācijā aprakstītajos piemēros parādīts, kādas izskatās draugiem.lv API pieprasījumu atbildes, izmantojot XML datu apmaiņas formātu. Draugiem.lv API PHP bibliotēka izmanto PHP serializēto datu apmaiņas formātu.

API pieprasījumam vienmēr jāsatur parametrs action, kas norāda izsaucamo darbību, un parametrs app, kas satur izveidotās aplikācijas API atslēgu (API atslēga tiek piešķirta, izveidojot aplikāciju, un tā tiek izmantota, lai identificētu aplikāciju, kas veic pieprasījumus).

API pieprasījumam gandrīz vienmēr jāsatur arī parametrs apikey, kas identificē draugiem.lv lietotāju,
kura vārdā aplikācija veic pieprasījumus.

Piemērs: Lai iegūtu lietotāja profila pamatinformāciju XML formātā (aplikācijas API atslēga - 52967e99b3c11a755e7635901c23c0cf, lietotāja API atslēga - 208d970441dd5f3e87b965fedabd0738), jāveic šāds API pieprasījums:

https://api.draugiem.lv/xml/?app=52967e99b3c11a755e7635901c23c0cf&apikey=208d970441dd5f3e87b965fedabd0738&action=userdata

Atbilstoši veiktajam pieprasījumam, serveris atbild ar datu struktūru izvēlētajā formātā, kas satur atbildes datus:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users>
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <age/>
                        <adult>1</adult>
                        <img>https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <sex>M</sex>
                </user>
        </users>
</draugiem>

2.2.   Kļūdu statusa kodi

Ja aplikācija veikusi nekorektu API pieprasījumu vai arī notikusi cita kļūda, atbilde uz API pieprasījumu satur kļūdas kodu un aprakstu.

Paraugs XML formātā:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <error code="150">Access denied</error>
</draugiem>

Paraugs PHP formātā:

a:1:{s:5:"error";a:2:{s:11:"description";s:13:"Access denied";s:4:"code";i:150;}}

Paraugs JSON formātā:

{"error":{"description":"Access denied","code":150}}

Iespējamie kļūdu statusa kodi un to atšifrējums:

Kods Kļūdas teksts Paskaidrojums
10 Internal error API sistēmas iekšēja kļūda
20 Service not available API uz laiku nav pieejams
80 Bad request kļūda API pieprasījuma parametros
90 Invalid action norādīta neatļauta action parametra vērtība
101 Invalid user API key norādīta nederīga apikey parametra vērtība (lietotāja API atslēga)
103 Invalid application API key norādīta nederīga app parametra vērtība (aplikācijas API atslēga)
104 IP address not allowed API pieprasījums veikts no datora, kura IP adrese nav starp aplikācijas uzstādījumos atļautajām
105 Max API request limit in 10 minutes reached pārsniegts atļautais API pieprasījumu skaits 10 minūtēs šim lietotājam
106 Invalid or unapproved auth code authorize pieprasījumā izmantots nederīgs vai jau izmantots code parametrs
107 Max activity limit for this user today reached sasniegts maksimālais atļautais nosūtīto profila jaunumu vai aktivitāšu skaits dienā šim lietotājam
120 Data not found pieprasītie dati nav atrasti
130 Spam/Flood detected konstatēta pārāk bieža datu (profila jaunumi, aktivitātes, u.c.) atkārtota sūtīšana
150 Access denied pieprasīti dati, kuriem lietotājam nav piekļuves tiesību

2.3.   Lietotāju dati

Ja API pieprasījumā tiek iegūti dati, kas saistīti ar lietotājiem, tad API atbilde satur bloku users ar iesaistīto lietotāju profilu pamatinformāciju. Katram lietotājam eksistē atribūts uid, kura vērtība ir draugiem.lv lietotāja identifikators, to izmanto lai piesaistītu lietotāja datus citiem objektiem.

Paraugs XML formātā:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        ...
        <users>
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <age/>
                        <adult>1</adult>
                        <img>https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <sex>M</sex>
                </user>
                ...
        </users>
</draugiem>

Paraugs PHP formātā:

a:1:{s:5:"users";a:1:{i:3342174;a:7:{s:3:"uid";i:3342174;s:4:"name";s:6:"Jānis";s:7:"surname";s:9:"Liepiņš";s:3:"age";b:0;s:5:"adult";i:0;s:3:"img";b:0;s:3:"sex";s:1:"F";}}}

Paraugs JSON formātā:

{"users":{"3342174":{"uid":3342174,"name":"J\u0101nis","surname":"Liepi\u0146\u0161","age":false,"adult":0,"img":"https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg","sex":"M"}}}

Par katru lietotāju ir pieejama šādi informācijas atribūti:

name:lietotāja vārds
surname:lietotāja uzvārds
age:vecums (tukšs, ja profilā norādīts slēpt vecumu)
adult:norāda, vai lietotājs ir sasniedzis 18 gadu vecumu (1, ja persona ir pilngadīga, 0, ja nav). Ļauj pārbaudīt, vai lietotājs ir pilngadīgs arī tad, ja viņš izvēlējies nerādīt savu vecumu publiski.
img:profila attēla URL (100x100px). Ja lietotājam nav attēla, šis atribūts ir bez vērtības
imgi:profila attēla URL (50x50px).
imgm:profila attēla URL vidējā izmērā (210px platums, augstums mainīgs)
imgl:profila attēla URL maksimālā izmērā (maksimāli 710px platums un 710px augstums)
sex:dzimums (M - vīrietis, F - sieviete)
deleted:ja lietotājs būs dzēsts no draugiem.lv, tad tiks atgriezta vērtība 1, ja tas ir parasts lietotājs, tad 0

2.4.   Paziņojumu saņemšana par lietotājiem, kas dzēsušies no aplikācijas

Aizpildot aplikācijas uzstādījumos parametru Aplikācijas atteikšanās statusa URL, iespējams panākt, ka draugiem.lv izsauc jūsu norādīto adresi ikreiz, kad kāds lietotājs pārtrauc lietot jūsu aplikāciju (nospiežot Atteikties no šīs aplikācijas), vai dzēš savu profilu no portāla.

Tādā veidā aplikācijai iespējams dzēst lietotāja informāciju vai veikt citas darbības, ko nepieciešams veikt, ja lietotājs pārtraucis aplikācijas izmantošanu.

Adresei tiek pievienoti šādi GET parametri:

status:vērtība delete
uid:dzēstā lietotāja ID
app:aplikācijas ID

Piemērs:

Ja aplikācijai ar ID 1234 uzstādīta dzēšanās statusa adrese https://example.com/delete_profile/, tad dzēšoties lietotājam ar ID 12345, tiks izsaukta adrese https://example.com/delete_profile/?status=delete&uid=12345&app=123

Atbildei uz pieprasījumu jāsatur tikai teksts OK, citādi draugiem.lv sistēma uzskatīs, ka aplikācija paziņojumu nav saņēmusi un mēģinās to piegādāt atkārtoti.

3.   Pieejamie API pieprasījumi

3.1.   Lietotāja autorizācija un profila informācijas iegūšana (pieprasījums authorize)

Pieprasījums ļauj iegūt lietotāja API atslēgu, kas nepieciešama pārējo API pieprasījumu veikšanai, kā arī pamatinformāciju par lietotāka profilu.

Pieprasījuma parametri:

action:authorize
app:aplikācijas API atslēga (32 simboli)
code:dr_auth_code vērtība, kas tika saņemta kā GET parametrs pēc lietotāja pieteikšanās (draugiem.lv Pases aplikācijām) vai atverot aplikācijas iframe (integrētajām aplikācijām)

Atbilde uz šo pieprasījumu saturēs šādus elementus:

apikey:lietotāja API atslēga
uid:draugiem.lv lietotāja ID
language:lietotāja portālā uzstādītās valodas divu burtu kods
inviter:tā cilvēka ID, kurš uzaicinājis šo lietotāju pievienoties aplikācijai (šis elements sastopams tikai tad, ja lietotājs pirmo reizi ienācis aplikācijā pēc apstiprināta uzaicinājuma)
invite_extra:papildu dati, kas bijuši piesaistīti apstiprinātajam uzaicinājumam (šis elements sastopams tikai tad, ja lietotājs pirmo reizi ienācis aplikācijā pēc apstiprināta uzaicinājuma)

API atslēga aplikācijai ļaus turpmāk piekļūt lietotāja datiem caur Draugiem.lv API bez vajadzības atkārtoti veikt autorizācijas procesu. Pēc veiksmīgas autorizācijas aplikācija būs redzama portāla sadaļā Manas aplikācijas. No turienes lietotājs varēs apturēt aplikācijas piekļuvi savam profilam.

Atbilde satur arī lietotāja profila pamatinformāciju atbilstoši nodaļā Lietotāju dati aprakstītajam formātam.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <apikey>09797abfe8e5ea53fd857cc372e3a6f5</apikey>
        <uid>491171</uid>
        <language>lv</language>
        <users>
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <age>21</age>
                        <adult>1</adult>
                        <img>https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <imgi>https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg</imgi>
                        <imgm>https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg</imgm>
                        <imgl>https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg</imgl>
                        <sex>M</sex>
                </user>
        </users>
</draugiem>

Lai aplikācija varētu piekļūt lietotāja datiem, tai jāiegaumē iegūtā apikey vērtība, un jāizmanto visos turpmākajos API pieprasījumos, norādot to kā parametra apikey vērtību.

Ja aplikācija aizmirsusi lietotāja API atslēgu, vai arī lietotājs to dzēsis no profila, autorizācijas procesu iespējams veikt atkārtoti. Lietotāja API atslēga var mainīties, ja lietotājs nomaina draugiem.lv lietotāja paroli vai dzēš aplikāciju no profila un piesakās tai atkārtoti.

3.2.   Konkrētu aplikācijas lietotāju datu iegūšana (pieprasījums userdata)

Pieprasījums ļauj iegūt pamatinformāciju par atsevišķiem draugiem.lv lietotājiem, kas autorizējuši šo aplikāciju. Šim pieprasījumam nav vajadzīga lietotāja API atslēga, pietiek ar aplikācijas atslēgu.

Pieprasījuma parametri:

action:userdata
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli), nav jānorāda obligāti, ja tiek norādīts ids parametrs
ids:neobligāts parametrs, ar komatu atdalīti draugiem.lv lietotāju ID (maksimums 100 dažādi ID vienā pieprasījumā), kuru dati tiek pieprasīti

Ja pieprasījumā norādīts parametrs ids, atbilde saturēs pamatinformāciju par pieprasītajiem lietotājiem atbilstoši nodaļā Lietotāju dati aprakstītajam formātam. Tiek sniegta tikai informācija par lietotājiem, kas autorizējuši šo aplikāciju (ja lietotājs dzēsis aplikāciju no profila, viņa dati vairs nav pieejami).

Ja netiek norādīts parametrs ids un ir norādīts parametrs apikey, tad tiek atgriezta informācija par lietotāju, kam pieder attiecīgā API atslēga, atbilstoši nodaļā Lietotāju dati aprakstītajam formātam.

Atbildē atgrieztie lietotāju dati nav sakārtoti noteiktā secībā.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users>
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <age>21</age>
                        <adult>1</adult>
                        <img>https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <imgi>https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg</imgi>
                        <imgm>https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg</imgm>
                        <imgl>https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg</imgl>
                        <type>User_Default</type>
                        <sex>M</sex>
                </user>
                <user uid="64428">
                        <name>Elīna</name>
                        <surname>Ozoliņa</surname>
                        <age>25</age>
                        <adult>1</adult>
                        <img>https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg</img>
                        <imgi>https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg</imgi>
                        <imgm>https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg</imgm>
                        <imgl>https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg</imgl>
                        <type>User_Business</type>
                        <sex>F</sex>
                </user>
        </users>
</draugiem>

Draugiem.lv pases lietošanas gadījumā lietotāja dati var saturēt arī nevis parasta lietotāja datus, bet oficiālas draugiem.lv lapas (www.draugiem.lv/lapas) datus. Lai noteiktu, vai tas ir parasts lietotājs vai lapa, jāpārbauda type parametrā esošā vērtība. Šobrīd ir iespējamas 2 vērtības:

  • User_Default - parasts lietotājs
  • User_Business - draugiem.lv lapa

3.3.   Aplikācijas lietotāju datu iegūšana (pieprasījums app_users)

Pieprasījums ļauj iegūt pamatinformāciju par visiem draugiem.lv lietotājiem, kas autorizējuši šo aplikāciju. Šim pieprasījumam nav vajadzīga lietotāja API atslēga, pietiek ar aplikācijas atslēgu.

Pieprasījuma parametri:

action:app_users
app:aplikācijas API atslēga (32 simboli)
show:neobligāts parametrs, norādot šo parametru ar vērtību ids, tiks atgriezti tikai atbilstošie draugiem.lv lietotāju ID, nevis pilni lietotāju dati.
page:neobligāts parametrs, lietotāju saraksta lappuse, kas jāatgriež. Nenorādot šo parametru, tiks atgriezta pirmā lappuse.
limit:neobligāts parametrs, lietotāju skaits vienā lappusē, robežās no 1 līdz 200. Nenorādot šo parametru, vienā lappusē būs informācija par 20 lietotājiem.

Ja pieprasījumā nav norādīts parametrs show ar vērtību ids, atbilde saturēs elementu users, kas saturēs lietotāju informāciju atbilstoši nodaļā Lietotāju dati aprakstītajam formātam. Elementam users eksistē atribūts total, kas satur aplikācijas lietotāju skaitu visās lappusēs kopā.

Pieprasījuma atbildes paraugs (ja nav norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users total="2">
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <age>21</age>
                        <adult>1</adult>
                        <img>https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <imgi>https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg</imgi>
                        <imgm>https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg</imgm>
                        <imgl>https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg</imgl>
                        <sex>M</sex>
                </user>
                <user uid="64428">
                        <name>Elīna</name>
                        <surname>Ozoliņa</surname>
                        <age>25</age>
                        <adult>1</adult>
                        <img>https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg</img>
                        <imgi>https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg</imgi>
                        <imgm>https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg</imgm>
                        <imgl>https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg</imgl>
                        <sex>F</sex>
                </user>
        </users>
</draugiem>

Ja pieprasījumā ir norādīts parametrs show ar vērtību ids, atbilde saturēs elementu userids, kas saturēs elementus uid ar atbilstošajiem draugiem.lv lietotāju ID. Elementam userids eksistē atribūts total, kas satur aplikācijas lietotāju skaitu visās lappusēs kopā.

Pieprasījuma atbildes paraugs (ja ir norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <userids total="45">
                <uid>64428</uid>
                <uid>491171</uid>
                <uid>1524905</uid>
                <uid>134564</uid>
                <uid>234561</uid>
        </userids>
</draugiem>

3.4.   Aplikācijas lietotāju skaita iegūšana (pieprasījums app_users_count)

Pieprasījums ļauj iegūt aplikācijas lietotāju skaitu.

Pieprasījuma parametri:

action:app_users_count
app:aplikācijas API atslēga (32 simboli)

Pieprasījuma atbilde satur elementu usercount, kura vērtība ir lietotāju, kas ir autorizējuši aplikāciju, skaits.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <usercount>312</usercount>
</draugiem>

3.5.   Aplikācijas lietotāju savstarpējo draugu iegūšana (pieprasījums app_friends)

Pieprasījums ļauj iegūt informāciju par aplikācijas lietotāja draugiem, kas izmanto šo pašu aplikāciju.

Pieprasījuma parametri:

action:app_friends
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja, kura draugi jāatgriež, API atslēga (32 simboli)
show:neobligāts parametrs, norādot šo parametru ar vērtību ids, tiks atgriezti tikai atbilstošie draugiem.lv lietotāju ID, nevis pilni lietotāju dati.
page:neobligāts parametrs, draugu saraksta lappuse, kas jāatgriež. Nenorādot šo parametru, tiks atgriezta pirmā lappuse.
limit:neobligāts parametrs, draugu skaits vienā lappusē, robežās no 1 līdz 200. Nenorādot šo parametru, vienā lappusē būs informācija par 20 draugiem.

Ja pieprasījumā nav norādīts parametrs show ar vērtību ids, atbilde saturēs elementu users, kas saturēs lietotāju informāciju atbilstoši nodaļā Lietotāju dati aprakstītajam formātam. Elementam users eksistē atribūts total, kas satur atbilstošo draugu skaitu visās lappusēs kopā.

Pieprasījuma atbildes paraugs (ja nav norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users total="2">
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <age>21</age>
                        <adult>1</adult>
                        <img>https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <imgi>https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg</imgi>
                        <imgm>https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg</imgm>
                        <imgl>https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg</imgl>
                        <sex>M</sex>
                </user>
                <user uid="64428">
                        <name>Elīna</name>
                        <surname>Ozoliņa</surname>
                        <age>25</age>
                        <adult>0</adult>
                        <img>https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg</img>
                        <imgi>https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg</imgi>
                        <imgm>https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg</imgm>
                        <imgl>https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg</imgl>
                        <sex>F</sex>
                </user>
        </users>
</draugiem>

Ja pieprasījumā ir norādīts parametrs show ar vērtību ids, atbilde saturēs elementu userids, kas saturēs elementus uid ar atbilstošajiem draugiem.lv lietotāju ID. Elementam userids eksistē atribūts total, kas satur atbilstošo draugu skaitu visās lappusēs kopā.

Pieprasījuma atbildes paraugs (ja ir norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <userids total="45">
                <uid>64428</uid>
                <uid>491171</uid>
                <uid>1524905</uid>
                <uid>134564</uid>
                <uid>234561</uid>
        </userids>
</draugiem>

3.6.   Aplikācijas lietotāja draugu skaita iegūšana (pieprasījums app_friends_count)

Pieprasījums ļauj iegūt aplikācijas lietotāja draugu skaitu, kas izmanto šo pašu aplikāciju.

Pieprasījuma parametri:

action:app_friends_count
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja, kura draugu skaits jāatgriež, API atslēga (32 simboli)

Pieprasījuma atbilde satur elementu friendcount, kura vērtība ir lietotāja draugu skaits, kas lieto aplikāciju.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
    <draugiem>
            <friendcount>16</friendcount>
    </draugiem>

3.7.   Aplikācijas lietotāju online draugu iegūšana (pieprasījums app_friends_online)

Pieprasījums ļauj iegūt informāciju par aplikācijas lietotāja draugiem, kas izmanto šo pašu aplikāciju un šobrīd ir ienākuši draugiem.lv portālā. Pieprasījums ir pieejams tikai draugiem.lv integrētajām aplikācijām un darbojas tikai laikā, kad lietotājs pats ir ienācis portālā.

Pieprasījuma parametri:

action:app_friends_online
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja, kura draugi jāatgriež, API atslēga (32 simboli)
show:neobligāts parametrs, norādot šo parametru ar vērtību ids, tiks atgriezti tikai atbilstošie draugiem.lv lietotāju ID, nevis pilni lietotāju dati.
in_app:neobligāts parametrs, norādot šo parametru ar vērtību 1, tiks atgriezti dati par lietotāja draugiem, kas tieši šobrīd lieto aplikāciju (ir bijuši aplikācijā pēdējo 5 minūšu laikā). Nenorādot šo parametru, tiks atgriezti dati par lietotāja draugiem, kas šobrīd atrodas portālā un ir reģistrēti aplikācijas lietotāji.
limit:neobligāts parametrs, maksimālais atgriežamo draugu skaits robežās no 1 līdz 100. Nenorādot šo parametru, tiks atgriezti līdz 20 online draugi.

Ja pieprasījumā nav norādīts parametrs show ar vērtību ids, atbilde saturēs elementu users, kas saturēs lietotāju informāciju atbilstoši nodaļā Lietotāju dati aprakstītajam formātam.

Pieprasījuma atbildes paraugs (ja nav norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users>
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <age/>
                        <adult>1</adult>
                        <img>https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <sex>M</sex>
                        <friends_only_msg>1</friends_only_msg>
                </user>
                <user uid="64428">
                        <name>Elīna</name>
                        <surname>Ozoliņa</surname>
                        <age>16</age>
                        <adult>0</adult>
                        <img>https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg</img>
                        <sex>F</sex>
                        <friends_only_msg></friends_only_msg>
                </user>
        </users>
</draugiem>

Ja pieprasījumā ir norādīts parametrs show ar vērtību ids, atbilde saturēs elementu userids, kas saturēs elementus uid ar atbilstošajiem draugiem.lv lietotāju ID.

Pieprasījuma atbildes paraugs (ja ir norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <userids>
                <uid>64428</uid>
                <uid>491171</uid>
                <uid>1524905</uid>
                <uid>134564</uid>
                <uid>234561</uid>
        </userids>
</draugiem>

3.8.   Visu online draugu iegūšana (pieprasījums app_all_friends_online)

Pieprasījums ļauj iegūt informāciju par lietotājiem, kuri šobrīd ir ienākuši draugiem.lv portālā. Pieprasījums ir pieejams tikai draugiem.lv integrētajām aplikācijām.

Pieprasījuma parametri:

action:app_all_friends_online
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja, kura draugi jāatgriež, API atslēga (32 simboli)
show:neobligāts parametrs, norādot šo parametru ar vērtību ids, tiks atgriezti tikai atbilstošie draugiem.lv lietotāju ID, nevis pilni lietotāju dati.
page:neobligāts parametrs, draugu saraksta lappuses numurs. Pēc noklusējuma tas ir 1.
limit:neobligāts parametrs, maksimālais atgriežamo draugu skaits robežās no 1 līdz 100. Nenorādot šo parametru, tiks atgriezti līdz 20 online draugi.

Ja pieprasījumā nav norādīts parametrs show ar vērtību ids, atbilde saturēs elementu users, kas saturēs lietotāju informāciju atbilstoši nodaļā Lietotāju dati aprakstītajam formātam.

Pieprasījuma atbildes paraugs (ja nav norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <total>2</total>
        <users>
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <age/>
                        <adult>1</adult>
                        <img>https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <sex>M</sex>
                        <friends_only_msg>1</friends_only_msg>
                </user>
                <user uid="64428">
                        <name>Elīna</name>
                        <surname>Ozoliņa</surname>
                        <age>16</age>
                        <adult>0</adult>
                        <img>https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg</img>
                        <sex>F</sex>
                        <friends_only_msg></friends_only_msg>
                </user>
        </users>
</draugiem>

Ja pieprasījumā ir norādīts parametrs show ar vērtību ids, atbilde saturēs elementu userids, kas saturēs elementus uid ar atbilstošajiem draugiem.lv lietotāju ID.

Pieprasījuma atbildes paraugs (ja ir norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <total>2</total>
        <userids>
                <uid>491171</uid>
                <uid>64428</uid>
        </userids>
</draugiem>

3.9.   Divu lietotāju savstarpējās draudzības pārbaude (pieprasījums check_friendship)

Pieprasījums ļauj pārbaudīt, vai divi aplikācijas lietotāji savā starpā ir draugi.

Pieprasījuma parametri:

action:check_friendship
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli). Šis parametrs nav obligāts, ja tiek norādīts uid2 parametrs
uid:pirmā lietotāja ID
uid2:otrā lietotāja ID. Šis parametrs nav obligāts, ja tiek norādīts apikey parametrs
  • Ja norādīts gan uid, gan uid2 parametrs, tiek atgriezts draudzības statuss starp šiem abiem lietotājiem.
  • Ja nav norādīta uid2 vērtība, bet ir norādīta apikey vērtība, tiek atgriezts draudzības statuss starp apikey īpašnieku un lietotāju ar uid parametrā norādīto ID.
  • API pieprasījuma atbilde satur elementu status, kura vērtība ir OK, ja starp lietotājiem pastāv draudzības saite.
  • Ja starp lietotājiem nepastāv draudzība, status vērtība ir NOT_FRIENDS.
  • Ja kāds no pieprasītajiem lietotājiem nav apstiprināts aplikācijas lietotājs, elementa status vērtība ir NOT_USERS.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <status>OK</status>
</draugiem>

3.10.   Informācijas pievienošana lietotāja profila aktivitātēs (pieprasījums add_activity)

Pieprasījums ļauj pievienot ierakstu ar saiti uz ārēju resursu draugiem.lv lietotāja profila aktivitāšu sarakstā.

Šis pieprasījums nav atļauts visām aplikācijām. Lai iegūtu savai aplikācijai iespēju pievienot informāciju profila aktivitātēs, rakstiet e-pastu uz api@draugiem.lv, kurā pastāstiet par savu aplikāciju un to, kādas profila aktivitātes tā veidos. Integrētajām aplikācijām izstrādes režīmā aktivitāšu pievienošana ir pieejama testēšanas režīmā (tās redzēs tikai aplikācijas izstrādātāji un administratori), bet lai turpinātu aktivitāšu pievienošanu pēc tam, kad aplikācija publicēta, tās jāatļauj no draugiem.lv puses.

Pievienotajai saitei jāved uz to pašu domēnu, kas reģistrēts aplikācijas uzstādījumos.

Pie aktivitātes būs redzama aplikācijas ikona, kas pievienota aplikācijas uzstādījumos. Viena aplikācija var izveidot ne vairāk kā vienu aktivitāti diennaktī katram lietotājam.

img/events.png

Aktivitātēm jābūt atbilstošām šādiem principiem:

  • Aktivitātei jāinformē par konkrētu attiecīgā lietotāja veiktu darbību ārējā resursā.
  • Aktivitāšu sistēmu nedrīkst izmantot reklāmai.
  • Vēlams pirms jauna veida aktivitāšu pievienošanas konsultēties ar draugiem.lv par to atbilstību noteikumiem.
  • Integrētajām aplikācijām saitē jānorāda adrese, kas jāatver iframe logā, nevis aplikācijas adrese draugiem.lv portālā - tā tiks automātiski pārveidota uz pareizo. Jāatceras, ka iframe attēlojamā adrese drīkst saturēt mapes ceļu un GET parametrus, bet ne faila nosaukumu.

Ja tiks konstatēts, ka aplikācija veido neatbilstošas aktivitātes, tai tiks liegta piekļuve aktivitāšu pievienošanai.

Pieprasījuma parametri:

action:add_activity
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
prefix:neobligāts parametrs, teksts, kas redzams profila aktivitātes sākumā, pirms klikšķināmās saites. Maksimālais atļautais garums 50 simboli, garāki teksti tiks saīsināti.
text:klikšķināmās saites teksts profila aktivitātē. Maksimālais atļautais garums 100 simboli, garāki teksti tiks saīsināti.
link:neobligāts parametrs, saite, uz kuru lietotājs aiziet, noklikšķinot uz aktivitātes. Ja šis parametrs nav norādīts, saite vedīs uz aplikācijas uzstādījumos norādīto lapas adresi. Atļauts norādīt tikai saites, kuru domēns ir vienāds ar aplikācijas uzstādījumos norādītās adreses domēnu. Maksimālais garums 100 simboli.
page_id:papildus parametrs lapu aplikācijām, kurā jāpadod lapas identifikators, kurā aplikācija ir ievietota
  • Ja aktivitāte veiksmīgi pievienota, API pieprasījuma atbilde satur elementu status, kura vērtība ir OK.
  • Ja aplikācijai, kas veic pieprasījumu, nav tiesību pievienot aktivitātes, vai arī lietotājs liedzis aplikācijai piekļuvi aktivitātēm, pieprasījums atgriezīs kļūdas kodu 150 (Access denied).
  • Ja jau ir sasniegts lietotājam dienā pievienojamo aktivitāšu limits, pieprasījums atgriezīs kļūdas kodu 107 (Max activity limit for this user today reached)

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <status>OK</status>
</draugiem>

3.11.   Paziņojuma attēlošana lietotāja profila jaunumos (pieprasījums add_notification)

Pieprasījums ļauj pievienot paziņojumu ar saiti lietotāja profila jaunumu blokā, kas atrodas sākumlapā. Šis pieprasījums nav atļauts visām aplikācijām. Lai iegūtu savai aplikācijai iespēju pievienot informāciju profila jaunumos, rakstiet e-pastu uz api@draugiem.lv, kurā pastāstiet par savu aplikāciju un to, kādus paziņojumus tā rādīs. Integrētajām aplikācijām izstrādes režīmā profila jaunumu pievienošana ir pieejama testēšanas režīmā (tos redzēs tikai aplikācijas izstrādātāji un administratori), bet lai turpinātu jaunumu pievienošanu pēc tam, kad aplikācija publicēta, tā jāatļauj no draugiem.lv puses.

Pievienotajai saitei jāved uz to pašu domēnu, kas reģistrēts aplikācijas uzstādījumos.

Pie jaunuma būs redzama aplikācijas ikona, kas pievienota aplikācijas uzstādījumos. Viena aplikācija var pievienot ne vairāk kā piecus profila jaunumus diennaktī katram lietotājam, ne ātrāk kā stundu pēc iepriekšējā jaunuma pievienošanas.

img/profileNews.png

Paziņojumiem jābūt atbilstošām šādiem principiem:

  • Paziņojumam jāinformē par konkrētu notikumu attiecīgā lietotāja aplikācijas profilā, vēlams, lai saite ved uz paziņojuma saturam atbilstošu vietu aplikācijā nevis uz sākumlapu.
  • Paziņojumu sistēmu nedrīkst izmantot, lai bez iemesla reklamētu savu aplikāciju.
  • Vēlams pirms jauna veida paziņojumu izmantošanas konsultēties ar draugiem.lv par to atbilstību noteikumiem.
  • Integrētajām aplikācijām saitē jānorāda adrese, kas jāatver iframe logā, nevis aplikācijas adrese draugiem.lv portālā - tā tiks automātiski pārveidota uz pareizo. Jāatceras, ka iframe attēlojamā adrese drīkst saturēt mapes ceļu un GET parametrus, bet ne faila nosaukumu.

Ja tiks konstatēts, ka aplikācija veido neatbilstošus profila jaunumus, tai tiks liegta piekļuve jaunumu pievienošanai.

Iespējams pievienot gan paziņojumu, kurš nācis no konkrēta lietotāja, gan tādu, kuram kā izraisītājs tiek rādīta pati aplikācija.

Svarīgi: jāatceras, ka paziņojums parādās tam lietotājam, kuram pieder pieprasījumā norādītā API atslēga. Tāpēc, lai parādītu paziņojumu cilvēkam, kurš dotajā brīdī nelieto aplikāciju, aplikācija jāuzglabā viņa API atslēga izmantošanai profila jaunumu pievienošanā.

Pieprasījuma parametri:

action:add_notification
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
prefix:neobligāts parametrs, teksts, kas redzams paziņojuma sākumā, pirms klikšķināmās saites. Maksimālais atļautais garums 50 simboli, garāki teksti tiks saīsināti.
text:klikšķināmās saites teksts profila jaunumos. Maksimālais atļautais garums 100 simboli, garāki teksti tiks saīsināti.
link:neobligāts parametrs, adrese, uz kuru lietotājs aiziet, noklikšķinot uz saites. Ja šis parametrs nav norādīts, saite vedīs uz aplikācijas uzstādījumos norādīto lapas adresi. Atļauts norādīt tikai saites, kuru domēns ir sakrīt ar aplikācijas uzstādījumos norādītās adreses domēnu. Maksimālais garums 100 simboli.
creator:neobligāts parametrs, lietotāja ID, kurš tiek attēlots kā profila jaunuma izraisītājs. Šim lietotājam jābūt aktīvam aplikācijas lietotājam. Ja šis parametrs nav norādīts, kā jaunuma autors tiks attēlota aplikācija.
  • Ja paziņojums ir pievienots, API pieprasījuma atbilde satur elementu status, kura vērtība ir OK.
  • Ja aplikācijai, kas veic pieprasījumu, nav tiesību pievienot profila jaunumus, vai arī lietotājs liedzis aplikācijai piekļuvi profila jaunumiem, pieprasījums atgriezīs kļūdas kodu 150 (Access denied).
  • Ja jau ir sasniegts lietotājam dienā pievienojamo profila jaunumu limits, pieprasījums atgriezīs kļūdas kodu 107 (Max activity limit for this user today reached)
  • Ja kopš iepriekšējāp ievienotā jaunuma nav pagājusi vismaz stunda, pieprasījums atgriezīs kļūdas kodu 130 (Spam/Flood detected)

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <status>OK</status>
</draugiem>

3.12.   Draugiem.lv aktīvās lietotāja sesijas statusa pārbaude (pieprasījums session_check)

Pieprasījums ļauj integrētajām aplikācijām pārliecināties, vai lietotāja draugiem.lv sesija, no kuras ir ieiets aplikācijā, ir joprojām aktīva.

Lietotāja sesijas pārbaudi nav jāveic pie katra pieprasījuma, vēlams to darīt ne biežāk kā reizi 3-5 minūtēs.

Pieprasījuma parametri:

action:session_check
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
hash:lietotāja sesijas identifikators (vesels pozitīvs 32 bitu skaitlis), kas saņemts ar session_hash parametru, atverot aplikācijas iframe

API pieprasījuma atbilde satur elementu status. Ja šī elementa vērtība ir OK, lietotāja draugiem.lv sesija joprojām ir aktīva.

Ja šī elementa vērtība ir FAILED, lietotāja sesija vairs nav derīga, un arī aplikācijas pusē tā būtu jāpārtrauc.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <status>OK</status>
</draugiem>

3.13.   Aplikācijas statistikas datu iegūšana (pieprasījums app_status)

Pieprasījums ļauj iegūt statistisku informāciju par aplikācijas darbību.

Pieprasījuma parametri:

action:app_status
app:aplikācijas API atslēga (32 simboli)

Pieprasījuma atgriež šādus statistikas parametrus

users:Kopējais aplikācijā reģistrēto lietotāju skaits
users24h:Aplikācijas aktīvo lietotaju skaits pēdējā diennaktī (atjaunojas reizi stundā)
online:Aplikācijas online lietotāju skaits pēdējās 5 minūtēs
api_rq:Aplikācijas API pieprasījumu skaits sekundē (vidējā vērtība pēdējās 20 sekundēs)
activities:Aplikācijas pievienotās draugu aktivitātes pēdējā minūtē
notifications:Aplikācijas pievienotie profila jaunumi pēdējā minūtē

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <status>
                <users>159552</users>
                <users24h>42872</users24h>
                <online>1340</online>
                <api_rq>33.25</api_rq>
                <activities>15</activities>
                <notifications>8</notifications>
        </status>
</draugiem>

3.14.   Aplikācijas lietotājam nosūtīto uzaicinājumu iegūšana (pieprasījums invitations)

Pieprasījums ļauj iegūt informāciju par lietotājam nosūtītajiem uzaicinājumiem lietot šo aplikāciju.

Pieprasījuma parametri:

action:invitations
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja, kura saņemtie uzaicinājumi jāatgriež, API atslēga (32 simboli)

Atbilde uz šo pieprasījumu saturēs elementus "invitation", kas ietver sevī šādas vērtības:

inviter:lietotāja ID, kas nosūtījis uzaicinājumu
invite_extra:papildu dati, kas bijuši piesaistīti apstiprinātajam uzaicinājumam
sent:uzaicinājuma nosūtīšanas laiks Unix Timestamp formātā
deleted:uzaicinājuma apstiprināšanas/dzēšanas laiks Unix Timestamp formātā
accepted:vai ielūgums ticis apstiprināts (1 - apstiprināts, 0 - noraidīts vai dzēsts). Ja lietotājs saņēmis vairākus uzaicinājumus uz vienu aplikāciju, tad apstiprinot vienu, pārējie tiek dzēsti.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
<invitations>
        <invitation>
                <inviter>12345</inviter>
                <invite_extra></invite_extra>
                <sent>1290899622</sent>
                <deleted>1303814320</deleted>
                <accepted>0</accepted>
        </invitation>
        <invitation>
                ..
        </invitation>
</invitations>
</draugiem>

3.15.   Aplikācijas lietotāja nosūtīto uzaicinājumu iegūšana (pieprasījums sent_invitations)

Pieprasījums ļauj iegūt informāciju par lietotāja nosūtītajiem uzaicinājumiem lietot šo aplikāciju.

Pieprasījuma parametri:

action:sent_invitations
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja, kura izsūtītie uzaicinājumi jāatgriež, API atslēga (32 simboli)

Atbilde uz šo pieprasījumu saturēs elementus "invitation", kas ietver sevī šādas vērtības:

user:lietotāja ID, kas saņēmis uzaicinājumu
invite_extra:papildu dati, kas bijuši piesaistīti apstiprinātajam uzaicinājumam
sent:uzaicinājuma nosūtīšanas laiks Unix Timestamp formātā
deleted:uzaicinājuma apstiprināšanas/dzēšanas laiks Unix Timestamp formātā
accepted:vai ielūgums ticis apstiprināts (1 - apstiprināts, 0 - noraidīts vai dzēsts). Ja lietotājs saņēmis vairākus uzaicinājumus uz vienu aplikāciju, tad apstiprinot vienu, pārējie tiek dzēsti.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
<invitations>
        <invitation>
                <user>12345</user>
                <invite_extra></invite_extra>
                <sent>1290899622</sent>
                <deleted>1303814320</deleted>
                <accepted>0</accepted>
        </invitation>
        <invitation>
                ..
        </invitation>
</invitations>
</draugiem>

4.   Javascript API funkcijas

Lai uzlabotu integrēto aplikāciju sadarbību ar portālu, izstrādātājiem iespējams izmantot vairākas Javascript funkcijas.

Lai padarītu pieejamas Javascript API funkcijas, aplikācijas lapai jāpievieno Javascript fails https://ifrype.com/applications/external/draugiem.js

Vēlams draugiem.js failu iekļaut kā pašu pēdējo, lai nodrošinātu, ka pareizā secībā tiek izpildītas window.onload funkcijas.

Lai nodrošinātu iespēju saņemt atbildes datus no izsauktajām funkcijām, uz aplikācijas servera jāizveido fails callback.html ar šādu saturu:

<html>
<head>
<script type="text/javascript">
        var lastHash = '';
        function watchHash() {
                var arr = window.location.hash.split('#');
                var hash = arr[1];
                if (typeof hash != "undefined") {
                         if (hash !== lastHash) {
                                window.parent.parent.draugiemProcessCallback(decodeURIComponent(hash));
                                lastHash = hash;
                        }
                }
                setTimeout(watchHash, 100);
        };
        watchHash();
</script>
</head>
<body></body>
</html>

Šāds fails nepieciešams, lai varētu notikt divvirzienu datu apmaiņa starp dažādiem domēniem, izmantojot JavaScript. Neizveidojot šo failu, aplikācija varēs izsaukt API funkcijas, bet nesaņems nekādu informāciju par to izpildes rezultātu.

Kad fails izveidots, aplikācijas kodā jānorāda mainīgais draugiem_callback_url, kas satur pilnu faila adresi ar visu domēnu.

<script type="text/javascript" src="https://ifrype.com/applications/external/draugiem.js"></script>
<script type="text/javascript">
        var draugiem_callback_url='https://example.com/callback.html';
</script>

Lai Javascript API zinātu, zem kāda domēna lietotājs šobrīd izmanto draugiem.lv, kodā jānorāda mainīgais draugiem_domain, kas satur domēna adresi, kas saņemta ar domain GET parametru, atverot aplikācijas iframe (ieteicams to saglabāt sesijā, lai varētu attēlot arī turpmākos pieprasījumos).

<script type="text/javascript" src="https://ifrype.com/applications/external/draugiem.js"></script>
<script type="text/javascript">
        var draugiem_domain='www.draugiem.lv';
</script>

Ievērojiet, ka Javascript izpildās lietotāja pusē, tāpēc pastāv iespēja, ka lietotājs ietekmē tām padoto vai atgriezto parametru vērtības!

4.1.   Iframe loga vertikālā izmēra maiņa

Lai iframe vertikālais izmērs mainītos automātiski, atverot lapu, jāizveido Javascript mainīgais draugiem_container, kura vērtībā jānorāda tā lapas DOM elementa ID, kurā ietilpst viss pārējais saturs. Norādot arī mainīgā draugiem_container_offset vērtību, tā tiks pieskaitīta norādītā draugiem_container elementa augstumam, lai noteiktu vajadzīgo rāmja augstumu.

<script src="https://ifrype.com/applications/external/draugiem.js" type="text/javascript"></script>
<script type="text/javascript">
                var draugiem_container = 'main_div';
</script>

Lai nomainītu rāmja augstumu, nepārlādējot lapu (piemēram, pēc Ajax pieprasījumiem), jāizsauc Javascript funkcija draugiemResizeIframe(). Izsaucot šo funkciju bez argumentiem, vajadzīgais augstums tiek noteikts pēc draugiem_container mainīgajā norādītā elementa augstuma. Funkcijai arī iespējams padot argumentu, kurā norādīta precīza vajadzīgā augstuma vērtība pikseļos.

<script src="https://ifrype.com/applications/external/draugiem.js" type="text/javascript"></script>

<div id="main_div" style="height:700px">test</div>

<script type="text/javascript">
        var draugiem_container = 'main_div';//Elements, pēc kā nosaka augstumu
        draugiemResizeIframe(); //uzstāda rāmja augstumu 700px

        var draugiem_container_offset = 50;//Izmēram pieskaitāmā vērtība
        draugiemResizeIframe(); //uzstāda rāmja augstumu 750px

        draugiemResizeIframe(800); //uzstāda rāmja augstumu 800px
</script>

Iframe izmēru vēlams pēc iespējas precīzāk pielāgot aplikācijas satura izmēram - ja logs būs pārāk mazs, lietotājiem nebūs redzams viss aplikācijas saturs.

m.draugiem.lv gan rāmja augstums, gan platums mainās automātiski un ir viss pieejamais brīvais ekrāns.

4.2.   Draugiem.lv modālā loga attēlošana

Izmantojot Javascript funkciju draugiemWindowOpen(address, width, height, callback), iespējams atvērt modālo Javascript logu ar savu saturu.

img/infobox.png

Funkcijai jāpadod četrus argumentus:

address:logā atveramā adrese
width:vajadzīgais loga platums pikseļos
height:vajadzīgais loga augstums pikseļos
callback:neobligāts parametrs, atgriezeniskā Javascript funkcija, kas tiks izsaukta, kad lietotājs aizvērs logu, padodot vienu argumentu ar vērtību true 
<script src="https://ifrype.com/applications/external/draugiem.js" type="text/javascript"></script>
<script type="text/javascript">
        //Atver 300px platu un 200 px augstu modālo logu
        draugiemWindowOpen('https://example.com/modal_window.php',300,200, function(){alert('Closed!');});
</script>

Lai modālo logu aizvērtu, jāizsauc draugiemWindowClose() funkcija bez argumentiem. Logs aizveras arī tad, ja lietotājs noklikšķina uz krustiņa tā augšējā stūrī.

m.draugiem.lv width un height argumentu vērtības var norādīt gan pikseļos (piem. "200") vai procentos (piem. "50%")

4.3.   Uzaicinājuma sūtīšana lietotāja draugiem

Izmantojot Javascript funkciju draugiemSendInvite(text, extra, callback), iespējams atvērt logu, no kura aplikācijas lietotājs var saviem draugiem nosūtīt uzaicinājumu pievienoties aplikācijas lietotājiem. Uzaicinājumu var nosūtīt tikai aplikācijas, kas ir publicētas portālā - citām aplikācijām var piekļūt tikai to izstrādātāji.

img/invite.png

Funkcijai var padot trīs neobligātus argumentus:

text:uzaicinājuma teksts (lietotājs to var mainīt pirms uzaicinājuma nosūtīšanas)
extra:papildu dati (līdz 150 simboliem), kas tiks aplikācijai padoti atpakaļ authorize un invitations pieprasījumos, ja lietotājs apstiprinās šo uzaicinājumu. Šo parametru var izmantot, lai identificētu konkrētu uzaicinājumu.
callback:neobligāts parametrs, atgriezeniskā Javascript funkcija, kas tiks izsaukta, kad lietotājs aizvērs logu, padodot vienu argumentu, kura vērtība būs nosūtīto uzaicinājumu skaits vai false, ja neviens uzaicinājums nebūs nosūtīts.

Uzaicinājuma logā lietotājs varēs izvēlēties, kuriem no saviem draugiem nosūtīt uzaicinājumu.

<script src="https://ifrype.com/applications/external/draugiem.js" type="text/javascript"></script>
<script type="text/javascript">
        draugiemSendInvite('Sveiks, lūdzu pievienojies šai spēlei! :)');//Parāda uzaicinājuma logu
</script>

4.4.   Vēstules sūtīšana draugiem.lv lietotājam

Izmantojot Javascript funkciju draugiemSendMessage(uid, topic, text, callback), iespējams atvērt logu, no kura aplikācijas lietotājs var nosūtīt vēstuli citam aplikācijas lietotājam.

img/mail.png

Funkcijai var padot četrus argumentus:

uid:lietotāja id, kam adresēta vēstule, nenorādot uid lietotājs pats varēs izvēlēties saņēmēju
topic:vēstules virsraksts
text:vēstules sākotnējais teksts
callback:neobligāts parametrs, atgriezeniskā Javascript funkcija, kas tiks izsaukta, kad lietotājs aizvērs logu. Funkcijai tiks padots viens arguments ar tipu string, kurš saturēs visu lietotāju identifikatorus,kuriem tika nosūtīta vēstule, atdalītus ar komatu. Ja vēstule netika nosūtīta nevienam lietotājam, funkcijai tiks padots viens arguments ar tipu object un vērtību null. 
<script src="https://ifrype.com/applications/external/draugiem.js" type="text/javascript"></script>
<script type="text/javascript">
        draugiemSendMessage(999999, 'Sveiks', 'Kā iet?', function(data){alert('Ziņa tika nosūtīta! Saņēmēji:' + data);});
</script>

4.5.   Saites ieteikšana draugiem.lv Runā

Izmantojot Javascript funkciju draugiemSay(title, url, titlePrefix, text, callback), iespējams atvērt logu, no kura aplikācijas lietotājs var pievienot ierakstu ar saiti savam Runā profilam.

img/say.png

Funkcijai iespējams padot četrus argumentus, no kuriem pirmie divi ir obligāti:

title:klikšķināmās saites teksts (maks. 70 simboli)
url:WEB adrese, uz ko vedīs saite (maks. 140 simboli)
titlePrefix:teksts, kas rādās pirms klikšķināmās saites (maks. 25 simboli)
text:ieraksta teksts, ko lietotājs var mainīt pirms publicēšanas (maks. 140 simboli)
callback:neobligāts parametrs, atgriezeniskā Javascript funkcija, kas tiks izsaukta, kad lietotājs aizvērs logu, padodot vienu argumentu, kura vērtība būs true, ja lietotājs pievienojis ierakstu vai false, ja vienkārši aizvēris logu. 
<script src="https://ifrype.com/applications/external/draugiem.js" type="text/javascript"></script>
<script type="text/javascript">
        draugiemSay('Dienas joki','https://www.draugiem.lv/mana_aplikacija/','Interesanti','Šie man ļoti patika!');
</script>

Pievienots Runā ieraksts izskatīsies šādi:

img/say2.png

m.draugiem.lv šī funkcija šobrīd nav pieejama.

4.6.   Draugiem.lv satura ritināšana uz augšu

Lapu aplikācijās nereti gadās situācija, kad aplikācijas saturs izraisa ritjoslas parādīšanos, taču pēc lietotāja veiktajām darbībām atliek vairs tikai neliela daļa satura. Lai šādā situācijā paritinātu draugiem.lv lapu līdz augšai, var izmantot JS funkciju draugiemScrollTop().

4.7.   Attēlu pievienošana lietotāja galerijā

Izmantojot Javascript funkciju draugiemGalleryAdd(title, url, description, callback), iespējams atvērt logu, kas ļauj lietotājam pievienot aplikācijas norādītus attēlus savai draugiem.lv galerijai.

img/gallery.png

Funkcijai jāpadod divus argumentus:

title:izveidojamās galerijas nosaukums (maks. 50 simboli). Lietotājs var nosaukumu mainīt vai arī pievienot attēlus esošai galerijai
url:pievienojamā attēla adrese vai masīvs ar vairākām attēlu adresēm (līdz 9 attēliem), kas jāpievieno galerijai
description:neobligāts parametrs, pievienojamā attēla paraksts
callback:neobligāts parametrs, atgriezeniskā Javascript funkcija, kas tiks izsaukta, kad lietotājs aizvērs logu, padodot vienu argumentu, kura vērtība būs true, ja lietotājs pievienojis attēlus vai false, ja vienkārši aizvēris logu. 
<script src="https://ifrype.com/applications/external/draugiem.js" type="text/javascript"></script>
<script type="text/javascript">
        draugiemGalleryAdd('Dabas skati',['https://example.com/img/1.jpg', 'https://example.com/img/2.jpg']);
</script>

Šo funkcionalitāti ir AIZLIEGTS izmantot draugiem.lv lapu aplikācijās.

m.draugiem.lv šī funkcija šobrīd nav pieejama.

4.8.   Attēlu atlasīšana no lietotāja galerijas

Izmantojot Javascript funkciju draugiemGalleryChoose(count, callback), iespējams atvērt logu, kas ļauj lietotājam izvēlēties attēlus no savām draugiem.lv galerijām un nodot tos aplikācijai.

img/gallery_choose.png

Funkcijai jāpadod divus argumentus:

count:vienā paņēmienā atlasāmo attēlu maksimālais skaits (1-10)
callback:atgriezeniskā Javascript funkcija, kas tiks izsaukta, kad lietotājs aizvērs logu, padodot vienu argumentu, kas saturēs informāciju par attēliem, ja lietotājs atlasījis attēlus vai false, ja vienkārši aizvēris logu. 
<script src="https://ifrype.com/applications/external/draugiem.js" type="text/javascript"></script>
<script type="text/javascript">
        draugiemGalleryChoose(1,function(obj){if(obj){alert(obj.thumb)}});
</script>

Informācija par katru izvēlēto attēlu tiek padota callback parametrā norādītajai funkcijai Javascript objekta formā

{
        pid:78443473 //Attēla ID
        thumb:'https://i3.ifrype.com/gallery/ff57173f4/443/473/sm_78443473.jpg', //Mazs attēls (100x100)
        medium:'https://i3.ifrype.com/gallery/f2af6acf/443/473/m_78443473.jpg', //Vidējs attēls (215px plats)
        large:'https://i3.ifrype.com/gallery/5feacb47/443/473/l_78443473.jpg' //Liels attēls (max 710px platums/augstums)
}

Ja parametrā count norādīta vērtība 1, tiek atgriezts viens šāds objekts. Ja norādīta lielāka vērtība, tiek atgriezta datu struktūra, kas satur vienu vai vairākus šādus objektus, atkarībā no lietotāja izvēlēto attēlu skaita.

m.draugiem.lv šī funkcija šobrīd nav pieejama.

4.9.   Aplikācijas autorizācijas loga atvēršana

Atsevišķām integrētajām aplikācijām iespējams pieslēgt iespēju attēlot saturu lietotājam, pirms viņš apstiprinājis aplikācijas piekļuvi saviem datiem. Šādos gadījumos lietotājs var anonīmi aplūkot aplikācijas saturu, bet aplikācija nevar piekļūt lietotāja datiem, pirms viņš apstiprinājis piekļuvi tiem. Kad aplikācijai pirmo reizi nepieciešams piekļūt lietotāja datiem, tā var izsaukt piekļuves apstiprinājuma logu, izsaucot JavaScript funkciju draugiemAuthorize().

Lai pieslēgtu savai aplikācijai iespēju attēlot saturu pirms autorizācijas, sazinieties ar api@draugiem.lv.

<script src="https://ifrype.com/applications/external/draugiem.js" type="text/javascript"></script>
<script type="text/javascript">
        draugiemAuthorize({ redirect:'/app-url/?success', followPage:true }, callback);
</script>

Izstrādājot lapu aplikācijas draugiemAuthorize() var padot papildus parametru followPage: true, kas autorizācijas logā pievienos papildus iespēju sākt sekot lapai, kurā aplikācija ir ievietota. Pēc noklusējuma lietotājam tiks piedāvāts sekot lapai. Papildus šim parametram, iespējams padod arī {'redirect', 'app-url/?success'}. Padodot šādu parametru, lietotājs pēc veiksmīgas autorizācijas tiks pāradresēts uz norādīto adresi https://draugiem.lv/app-url/?success. Ir iespēja padot parametru redirect: false, un kā otro argumentu padot callback funkciju, un lietotāja autorizācijas dati tiks atgriezti funkcijai ar tipu object, kurš saturēs sesijas identifikatoru, un atļaujas ( atļauju veidus skatīt 4.10 ). Šāds veids nodrošina piekļuvi lietotāja datiem bez lapas pārlādes. Ja lietotājs aizvērs logu, callback funkcijai tiks padots arguments ar datu tipu boolean un vērtību false.

m.draugiem.lv šī funkcija šobrīd nav pieejama.

4.10.   Aplikācijas atļauju loga atvēršana

Izmantojot JavaScript funkciju draugiemSettings(callback), ir iespējams atvērt logu, kurš lietotājam tiek parādīts pirmo reizi atverot aplikāciju. Logā lietotājam ir iespēja mainīt aplikācijas piekļuves tiesības saviem datiem.

img/draugiemSettings.PNG

Funkcijai jāpadod vienu argumentu:

callback:atgriezeniskā JavaScript funkcija, kas tiks izsaukta pēc loga aizvēršanas. Funkcijai tiks padots viens arguments ar tipu object, kurš saturēs visus atļauju veidus ar vērtībām true vai false.

Iespējamie atļauju veidi:

Atļaujas atslēgas vārds Atļaujas apraksts
perm_events Ļaut publicēt ierakstus lietotāja profila aktivitātēs
perm_news Ļaut rādīt paziņojumus lietotāja profila jaunumos
perm_say Ļaut publicēt ierakstus lietotāja Runā plūsmā

m.draugiem.lv šī funkcija šobrīd nav pieejama.

4.11.   Draugu izvēlēšanās loga atvēršana

Izmantojot JavaScript funkciju draugiemFriends(maxlength,callback) aplikācijai ir iespējams atvērt logu, kurā lietotājam tiks piedāvāts izvēlēties noteiktu skaitu lietotāju.

img/draugiemFriends.PNG

Funkcijai jāpadod divi argumenti:

maxlength:maksimālais lietotāju skaits, cik lietotājs var izvēlēties. Lai piedāvātu neierobežotu skaitu, argumenta vērtībai jābūt 0.
callback:atgriezeniskā JavaScript funkcija, kas tiks izsaukta pēc loga aizvēršanas. Funkcijai tiks padots viens arguments ar tipu string, kurš saturēs visu atzīmēto lietotāju identifikatorus atdalītus ar komatu. Ja netiks izvēlēts neviens lietotājs, tiks atgriezts arguments ar tipu object un vērtību null.

m.draugiem.lv šī funkcija šobrīd nav pieejama.

5.   Draugiem.lv API PHP bibliotēka

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.

PHP bibliotēkas dokumentācija

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

6.   Draugiem.lv maksājumu API

Lai nodrošinātu maksas pakalpojumus portālā integrētajām aplikācijām, izstrādātājam jāizmanto draugiem.lv maksājumu API. Tas piedāvā daudzveidīgas pakalpojumu apmaksas iespējas.

6.1.   Maksas pakalpojuma izveidošana

Lai piekļūtu maksājumu API iespējām, aplikācijai vispirms nepieciešams pieslēgt maksājumu API. To var izdarīt, sazinoties ar draugiem.lv pārstāvjiem, izmantojot e-pastu api@draugiem.lv

Kad maksājumu API pieslēgts, aplikācijas administrācijas panelī parādās iespēja izveidot maksas pakalpojumus. Izveidojot pakalpojumu, jānorāda šādi parametri:

Tips:SMS, bankas vai draugiem.lv kredītu maksājumi (draugiem.lv kredīti tiek piedāvāta kā papildus maksājuma iespēja arī izmantojot SMS un bankas maksājumus)
Cena:Pakalpojuma SMS cena (tikai SMS maksājumiem)
Nosaukums:pakalpojuma nosaukums, kas tiks attēlots lietotājam maksāšanas logā un maksājumu statistikā
Apraksts:pakalpojuma īss apraksts, kas tiks attēlots lietotājam maksāšanas logā
SMS atbildes teksts:
 Teksts, ko lietotājs saņems atbildes īsziņā (tikai SMS maksājumiem)
Statusa atskaites URL:
 Aplikācijas servera URL, kas tiks izsaukta, lai informētu aplikāciju par veiksmīgu maksājumu

Kad pakalpojums izveidots, tas ir gatavs lietošanai. Maksas pakalpojumu administrācijas panelī ir attēlots maksas pakalpojuma ID, kas jāizmanto, izveidojot maksājumu ar draugiem.lv API.

Vienai aplikācijai vēlams izveidot ne vairāk kā 12 maksas pakalpojumus, lai nodrošinātu pārskatāmību maksājumu atskaitēs un ieņēmumu grafikos.

6.2.   Maksājuma transakcijas izveidošana

Lai izveidotu maksājuma transakciju un iegūtu tās ID, aplikācijai jāveic API pieprasījums.

Pieprasījuma parametri:

action:transactions/create
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja, kurš veic maksājumu, API atslēga (32 simboli)
service:pakalpojuma ID, kas iegūts, izveidojot maksas pakalpojumu
price:pakalpojuma cena eiro centos/draugiem.lv kredītos (maksimālā vērtība 15000, SMS maksājumiem šis parametrs nav jānorāda, jo cena ir fiksēta)

Atbildē tiks atgriezts transakcijas ID (elements id) un maksāšanas lapas adrese, kurā jānogādā lietotājs (elements link).

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <transaction>
                <id>1935</id>
                <link>https://www.draugiem.lv/services/iframe.php?id=1935</link>
        </transaction>
</draugiem>

Adrese, kas saņemta link elementā, jāattēlo lietotājam (kā iframe objekts, popup logs vai modālais logs, izmantojot draugiemWindowOpen funkciju). Ieteicamais atvērtā loga izmērs ir vismaz 350x400 pikseļi. Atvērtais logs satur visu informāciju, kas nepieciešama lietotājam pakalpojuma apmaksai.

Saņemtais id elements aplikācijai jāsaglabā - pēc tā vēlāk varēs noteikt, vai transakcija bijusi veiksmīga.

Lai neģenerētu liekas transakcijas, ieteicams tās veidot tad, kad lietotājs jau izlēmis, ka vēlas maksāt.

6.3.   Maksājuma statusa pārbaude

Pēc veiksmīgas pakalpojuma apmaksas, draugiem.lv serveris izsauks jūsu norādīto statusa atskaites URL, pievienojot galā šādus HTTP GET parametrus:

id:transakcijas ID
service:maksas pakalpojuma ID
uid:lietotāja ID
price:maksājuma cena eiro centos
status:vērtība ok

Uz šo pieprasījumu aplikācijai jāatbild ar precīzu tekstu OK, citādi draugiem.lv sistēma uzskatīs, ka atskaiti nav izdevies piegādāt un mēģinās to izdarīt atkārtoti (līdz 20 reizēm pieaugošos laika intervālos). Aplikācijai jāatbild ar OK arī ja tā saņem atskaiti, kas jau ir apstrādāta, vai atskaiti, kam nav atrodams atbilstošs transakcijas ID. Vienīgais gadījums, kad nevajag atbildēt ar OK, ir ja aplikācijai ir tehniskas problēmas, kas liedz apstrādāt atskaiti (piemēram, nedarbojas datubāze).

Ja atskaite nav saņemta, iespējams pārbaudīt apmaksas statusu manuāli, veicot šādu API pieprasījumu:

action:transactions/check
app:aplikācijas API atslēga (32 simboli)
id:maksājuma transakcijas ID

Atbildē saņemsiet kādu no šiem statusiem:

OK:Maksājums veiksmīgs
UNKNOWN:Maksājums vispār nav veikts vai vēl nav pabeigts
SMS_SENT:Atbildes SMS nosūtīta, bet vēl nav saņemts statuss par tarifikāciju
FAILED:Maksājums neveiksmīgs

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
   <status>OK</status>
</draugiem>