Draugiem.lv lapu aplikāciju izstrāde

Draugiem.lv lapas ir modulārs un viegli paplašināms risinājums, kas ļauj katram draugiem.lv lietotājam veidot mājas lapas, kas atbilst viņa vajadzībām. Līdz šim draugiem.lv lapās lietotāji varēja izmantot tikai draugiem.lv programmētāju izstrādātus rīkus, kas diezgan ierobežoja lapu veidotājus. Šobrīd ir izveidota iespēja ārējiem izstrādātājiem veidot savas aplikācijas un tās integrēt draugiem.lv lapās kā lapas sadaļas vai kā pirmās lapas blokus.

1.   Ievads

Draugiem.lv aplikācijas tiek veidotas uz tieši tādiem pašiem principiem, kā citas draugiem.lv portālā integrētās aplikācijas, tajā skaitā spēles. Ja jūs esat spēļu izstrādātājs, tad jums būs jāapgūst tikai pāris nianses, kas ir specifiskas lapām, visa pārējā zināšanu bagāža ir izmantojama atkārtoti.

Draugiem.lv integrēto aplikāciju izstrādes dokumentācija ir pieejama http://www.draugiem.lv/applications/dev/docs/iframe/

Viena no būtiskajām draugiem.lv aplikāciju niansēm ir iespēja tikt pie lietotāju datiem, kas konkrētajā brīdī skatās draugiem.lv lapu. Lai šos datus mēs varētu nodot aplikācijai, mums ir nepieciešams lietotāja akcepts. Tas nozīmē, ka ir iespējama situācija, ka lietotājs atver lapu, sākumlapā ir ievietota aplikācija, kā rezultātā lietotājam uzreiz tiek prasīts, vai viņš ir gatavs dot savus datus ārējam izstrādātājam. Lai no šīs situācijas izvairītos, draugiem.lv lapu aplikācijas būtu ieteicams veidot kā anonīmas aplikācijas, kuras lietotāja datus var iegūt tad, kad tām tas ir nepieciešams. Tas nozīmē, ka sākotnēji aplikācija var rādīt informāciju, kurai nav nepieciešami lietotāja dati. Ja aplikācijai kādā brīdī ir nepieciešami autorizētā lietotāja dati un viņa saite ar lapu, tad izstrādātājs to var pieprasīt izmantojot JavaScript autorizācijas izsaukšanas funkcionalitāti: http://www.draugiem.lv/applications/dev/docs/iframe/#aplikacijas-autorizacijas-loga-atversana

Blokiem, kas atrodas primajā lapā šī ir obligāta prasība. Lapas sadaļām tā nav obligāta prasība.

2.   Paplašināšanas iespējas

Aplikāciju izstrādātājiem ir iespējas savas aplikācijas ievietot lapās gan kā pirmās lapas blokus, gan arī kā atsevišķu lapas sadaļu.

2.1.   Sākumlapa

Sākumlapa sastāv no trīs kolonām. Kreisā kolona nav modificējama, centrālā kolona un labās puses kolona ir izmantojama, lai tajā ievietotu dažāda veida blokus. Šajā brīdī pat nav svarīgi, vai tie ir standarta draugiem.lv lapu bloki, vai arī tie ir kāda ārēja izstrādātāja radīti bloki ar funkcionalitāti, ko nenodrošina draugiem.lv. Attēlā ir iekrāsots katrs atsevišķais bloks draugiem.lv sākumlapā. Izstrādātājs pats var ievietot bloku vajadzīgajā vertikālajā izmērā. Horizontālais izmērs ir fiksēts, centrālajai kolonai tie ir 480px platumā, labās puses kolonai - 240px platumā.

img/pages-firstpage.png

2.2.   Lapas sadaļas

Lapas sadaļās situācija ir vēl vienkāršāka par sākumlapu, jo izstrādātājam ir pieejama visa sadaļai paredzētā vieta - visa centrālā kolona 730px platumā, skatīt attēlu.

img/pages-section.png

3.   Izstrādes informācija

Tā kā vienu un to pašu aplikāciju var ievietot dažādās lapās, tad programmētājiem ir jāvar identificēt, kura no lapām konkrēto aplikāciju šobrīd izsauc. Šim mērķim pie katra aplikācijas iframe izsaukuma tiek padots papildus GET mainīgais api_page_id, kas ir parasts integer tipa mainīgais.

Ja jūsu veidotā aplikācija ir paredzēta tikai vienai lapai, varat šo parametru ignorēt.

3.1.   Aplikācijas iframe URL parametri

Atverot draugiem.lv lapu aplikāciju tai papildus tiek padoti vairāki GET parametri, pēc kuriem ir iespējams noskaidrot vairākus aplikācijām bieži vien būtiskus faktus:

3.1.1.   api_page_id

Atveramās lapas identifikators, katrai lapai unikāls, parasti lielāks par 13 000 000. Atsevišķos API pieprasījumos šī vērtība ir jāpadod kā parametrs, tāpēc būtu vēlams to saglabāt sesijā vai kā citādi.

3.1.2.   api_user_auth

Parametrs, ar kura palīdzību ir iespējams noteikt lietotāja statusu lapā, neprasot pieeju lietotāja datiem. Iespējamās vērtības:

  • fan - lietotājs ir autorizējies draugiem.lv un ir lapas sekotājs
  • user - lietotājs ir autorizējies draugiem.lv, bet nav lapas sekotājs
  • false - lietotājs nav autorizējies draugiem.lv, nav informācijas par sekošanas statusu
  • admin - lietotājs ir lapas administrators

3.1.3.   dr_appw

Parametrs, kas ļauj noskaidrot, kurā vietā aplikācija ir ievietota lapā. Iespējamās vērtības

  • 240 - aplikācija ir pievienota lapas sākumlapā kā bloks labajā kolonā, pieejamais platums 240px
  • 480 - aplikācija ir pievienota lapas sākumlapā kā bloks centrālajā kolonā, pieejamais platums 480px
  • 730 - aplikācija ir pievienota kā lapas sadaļa, pieejamais platums 730px

3.2.   Pieejamie API izsaukumi

Tā kā draugiem.lv lapu API vēl ir pašā izstrādes sākumposmā, tad ir ļoti grūti paredzēt, kādas iespējas būs nepieciešamas izstrādātājiem. Tas nozīmē, ka gadījumā, ja jums ir nepieciešams kāds API izsaukums, kurš šobrīd netiek piedāvāts, tad varat to droši prasīt rakstot mums privātu ziņu uz e-pastu api@draugiem.lv, vai arī izmantojot kopējo draugiem.lv iztrādātājiem veltīto e-pasta listi draugiemapi@googlegroups.com.

Draugiem.lv lapu aplikācijās darbojas visi portālā integrēto aplikāciju API izsaukumi: http://www.draugiem.lv/applications/dev/docs/iframe/

3.2.1.   pages/userstatus

Izsaukums, kas ļauj noteikt pašreizējā apmeklētāja statusu lapā.

Pieprasījuma parametri:

action:pages/userstatus
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
page_id:lapas identifikators, kuru jūs saņemat iframe GET parametros.

Atbildes

Atbilde Apraksts
USER parasts lietotājs, lapas apmekleātājs
FAN lapas sekotājs
ADMIN lapas administrators

Pieprasījuma atbildes paraugs:

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

Gadījumā, ja aplikācija veiks šo izsaukumu ar lapas identifikatoru page_id, kurš nav uzstādījis šo aplikāciju, tad tiks atgriezts kļūdas statusa kods 150 (access denied).

3.2.2.   pages/adminpages

Izsaukums, kas piekļūt informācijai par lietotāja administrējamām lapām. Šie dati varētu būt aktuāli aplikācijām, kas ir paredzētas vairāk kā vienai lapai.

Pieprasījuma parametri:

action:pages/adminpages
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users>
                <user uid="13000622">
                        <name>Draugiem.lv lapas</name>
                        <surname/>
                        <nick/>
                        <place/>
                        <age>0</age>
                        <adult>0</adult>
                        <img>http://path.to.image/file.jpg</img>
                        <sex/>
                        <url>/pages</url>
                        <official>1</official>
                        <fans>15328</fans>
                </user>
                <user uid="13333333">
                        <name>afdsfdasfdsadfs</name>
                        ...
                </user>
        </users>
</draugiem>

Piezīme: šobrīd tiek atgrieztas ne vairāk kā 100 administrējamās lapas, taču tai normālā gadījumā nevajadzētu bū problēmai.

3.2.3.   pages/userpages

Izsaukums atgriež lapas, kurām lietotājs seko (max 200 gab)

Pieprasījuma parametri:

action:pages/userpages
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users>
                <user uid="13000622">
                        <name>Draugiem.lv lapas</name>
                        <surname/>
                        <nick/>
                        <place/>
                        <age>0</age>
                        <adult>0</adult>
                        <img>http://path.to.image/file.jpg</img>
                        <sex/>
                        <url>/pages</url>
                        <official>1</official>
                        <fans>15328</fans>
                </user>
                <user uid="13333333">
                        <name>afdsfdasfdsadfs</name>
                        ...
                </user>
        </users>
</draugiem>

3.2.4.   pages/info

Pieprasījums atgriež informāciju par konkrētu draugiem.lv lapu

Pieprasījuma parametri:

action:pages/info
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
page_id:lapas identifikators

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users>
                <user uid="13000622">
                        <name>Draugiem lapas</name>
                        <surname></surname>
                        <nick></nick>
                        <place></place>
                        <age></age>
                        <adult>0</adult>
                        <img>http://i2.ifrype.com/business/000/622/v1300780832/sm_13000622.jpg</img>
                        <sex></sex>
                        <url>/pages</url>
                        <official>1</official>
                        <fans>15328</fans>
                </user>
        </users>
</draugiem>

3.3.   Javascript API funkcijas

Draugiem.lv lapu aplikācijām pieejamas vairākas Javascript funkcijas, papildus parastām integrētajām aplikācijām pieejamajām Javascript funkcijām, kas aprakstītas http://www.draugiem.lv/applications/dev/docs/iframe/#javascript-api-funkcijas

3.3.1.   Uzaicinājuma uz lapu sūtīšana draugiem

Izmantojot Javascript funkciju draugiemSendPageInvite(text, callback), iespējams atvērt logu, no kura aplikācijas lietotājs var saviem draugiem nosūtīt uzaicinājumu pievienoties atvērtās lapas sekotājiem. Funkcija darbojas tikai no lietotāja atvērtās lapas, kurā integrēta aplikācija.

Funkcijai var padot divus neobligātus argumentus:

text:uzaicinājuma teksts (lietotājs to var mainīt pirms uzaicinājuma nosūtīšanas)
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.

3.3.2.   Lapas sekošanas dialogloga atvēršana

Izmantojot Javascript funkciju draugiemPagesFan(uri,callback), iespējams atvērt apstiprinājuma logu, kas ļauj lietotajam pievienoties par fanu atvērtajai lapai.

Funkcijai var padot divus argumentus:

uri:lapas adreses daļa pēc portāla adreses ( Piemērs: draugiem.lv - draugiem.lv oficiālā lapa )
callback:neobligāts parametrs, atgriezeniskā JavaScript funkcija, kurai tiks padots viens arguments, atkarībā no tā vai lietotājs sāka sekot lapai ( datu tips number un vērtība 1 ) vai aizvēra logu ( datu tips boolean un vērtība false, ja lietotājs nav lapas fans, un datu tips number un vērtība 2, ja lietotājs jau ir lapas sekotājs ).

3.3.3.   Lietotāja autorizācijas pieprasījums

Pēc noklusējuma visas draugiem.lv lapu aplikācijas darbojas anonīmā režīmā. Tas nozīmē, ka nevienai lapu aplikācijai automātiski netiek prasīta pieeja lietotāja datiem. Programmētājam pašam ir jāparūpējas, lai tiktu pieprasīta pieeja lietotāja datiem izmantojot draugiemAuthorize(object,callback); funkciju. Šo funkciju ir atļauts izsaukt tikai pēc lietotāja klikšķa veikšanas.

//lietotāja datu ieguve ar pāradresāciju
draugiemAuthorize({redirect:'/app-url/?success',followPage:true});

//lietotāja datu ieguve ar callback metodi
draugiemAuthorize({redirect:false,followPage:true},function(data) {
        alert(data);
})

Funkcijai var padot divus neobligātus parametrus:

object:arguments, kuram jābūt ar datu tipu object un var saturēt divas vērtības: redirect ( var saturēt adresi uz kuru tiks pāradresēts lietotājs, piemēram, /app-url/?success, bet ja šo elementu padod false, tad lietotāja piekļuves dati tiks atgriezti callback funkcijai ) un followPage ( padodot vērtību true lietotājam pie datu pieprasījuma tiks piedāvāts automātiski sākt sekot lapai, kurā aplikācija ir ievietota - izlecošajā logā tiks atvērts uzstādījumu saraksts, kurā būs iezīmēta iespēja "sākt sekot lapai". Ja lietotājs nevēlas sekot lapai, viņš var izņemt ķeksi un vienalga piekļūt aplikācijai, dodot piekļuvi saviem datiem ).
callback:neobligāts parametrs, atgriezeniskā JavaScript funcija, kas tiks izsaukta, ja objekta elementa redirect vērtība būs false. Funkcijai tiks padots viens arguments ar tipu object, kurš saturēs sesijas identifikatoru, un atļauju veidus.

4.   Aplikāciju "veikals"

Lapu administratoriem izveidotās aplikācijas būs pieejamas tāpat, kā visi pārējie standarta draugiem.lv lapu bloki. Jau šobrīd pie lapu sadaļām ir pieejama poga "Pievienot jaunu ārējo izstrādātāju sadaļu", uz kuras nospiežot tiek atvērts logs ar visām pieejamām aplikācijām.

img/pages-appstore-button.png

Šī raksta rakstīšanas brīdī vienīgā publiski pieejamā aplikācija ir mūsu pašu veidotais testa modulis, taču jau pavisam drīz tur varētu parādīties arī citu izstrādātāju radītie produkti.

Aplikācijas veikalā var parādīties ar dažādiem statusiem:

  1. Izstrādes aplikācija - veikalā redzama tikai izstrādātājiem, ievietojot to lapā, to redz tikai konkrētās lapas administratori.
  2. Privāta aplikācija - veikalā aplikācija ir redzama tikai izstrādātājiem, taču ievietojot to lapā, tā ir redzama visiem apmeklētājiem. Šāda tipa aplikācijas var izmantot pielāgojot lapu funkcionalitāti konkrēti viena uzņēmuma vajadzībām, piemēram, piedāvājot saskarni ar kādu uzņēmuma iekšējo sistēmu vai uzņēmuma mājas lapu.
  3. Publiska aplikācija - veikalā redzama visu lapu administratoriem un ievietojot to lapā, tā ir redzama arī visiem lapas apmeklētājiem.

4.1.   Kā pievienot savu aplikāciju veikalā?

Šobrīd aplikāciju ievietošana veikalā nenotiek automātiski, lai pievienotu savu aplikāciju, rakstiet e-pastu uz ingus@draugiem.lv. Tuvākajā laikā mēģināsim šo procesu atvieglot un automatizēt.

5.   Lapu aplikācijas un bizness

Draugiem.lv lapu aplikācijas pamatā ir domātas kā rīks, ar kurām konkrētas lapas īpašnieks var papildināt savas lapas funckionalitāti ar sev nepieciešamo.

Draugiem.lv noteikumi neparedz nekādus maksājumus starp aplikācijas izstrādātāju un draugiem.lv, ja:

  1. aplikācija ir izstrādāta konkrētas lapas funkcionalitātes paplašināšanai un tā nav pieejama publiski aplikāciju veikalā.
  2. aplikācijas īpašnieks neiekasē nekāda veida maksu par aplikācijas lietošanu ne no lapas īpašnieka, ne lapas apmeklētājiem.

Gadījumā, ja aplikācija tiek izstrādāta kā maksas rīks citiem lapu īpašniekiem (iekasējot ikmēneša, iknedēļas, apjoma vai vienreizēju maksājumu), tad stājas spēkā visi draugiem.lv integrēto aplikāciju maksājumu noteikumi: http://www.draugiem.lv/applications/dev/docs/iframe/#draugiem-lv-maksajumu-api

6.   Kontakti

Gadījumā, ja rodas jautājumi, varat droši izmantot šādu kontaktinformāciju:

Ingus Rūķis
ingus@draugiem.lv
http://www.draugiem.lv/pages/