<!--
source: https://draugiem.eu/applications/dev/docs/iframe/
format: markdown (generated for LLM / machine consumption)
language: lv
index: https://draugiem.eu/applications/dev/docs/llms.txt
-->

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

## 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](https://draugiem.eu/applications/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](https://draugiem.eu/applications/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](https://draugiem.eu/applications/dev/docs/php/).
- 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](mailto: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](https://draugiem.eu/applications/dev/docs/php/), 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](https://draugiem.eu/applications/dev/docs/php/), 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](https://draugiem.eu/applications/dev/docs/php/) 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
<?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
<?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ā:**

```json
{"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
<?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ā:**

```json
{"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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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](https://draugiem.eu/applications/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
<?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](https://draugiem.eu/applications/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
<?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
<?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
<?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
<?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
<?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](https://draugiem.eu/applications/external/callback.html) ar šādu saturu:

```html
<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.

```html
<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).

```html
<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.

```html
<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.

```html
<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](https://draugiem.eu/applications/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`

```html
<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](https://draugiem.eu/applications/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.

```html
<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](https://draugiem.eu/applications/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`.

```html
<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](https://draugiem.eu/applications/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.

```html
<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](https://draugiem.eu/applications/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](https://draugiem.eu/applications/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.

```html
<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](https://draugiem.eu/applications/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.

```html
<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](mailto:api@draugiem.lv).

```html
<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](https://draugiem.eu/applications/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](https://draugiem.eu/applications/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](https://draugiem.eu/applications/dev/docs/php/)

[Draugiem.lv API PHP bibliotēka un izmantošanas paraugi](https://github.com/Draugiem/draugiem-php-sdk)

## 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](mailto: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
<?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
<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
   <status>OK</status>
</draugiem>
```