Aplikācijas

Draugiem.lv page application development

1.   Intro

Draugiem.lv page applications are being built on the same principles as regular iframe applications (games) for draugiem.lv network. If you are a game developer there are only a couple of nuances which are specific to page applications.

You can find draugiem.lv integrated application documentation at: http://www.draugiem.lv/applications/dev/docs/iframe_en/

2.   Extension of pages

Application developers can put their application as blocks on the first page or as a whole section in the page menu.

2.1.   Front page

Front page consists of 3 columns. Left column is static and no applications can be placed here. Applications can be put in central and right columns. You can see highlighted blocks in the picture on how the page might be divided between regular draugiem.lv widgets and applications. Developer can set the vertical size of block, horizontal size is limited depending on the column you are placing your application in. For central column 480px of space is available while 240px is available for the right column.

img/pages-firstpage.png

2.2.   Page sections

Most of the applications are being inserted as page sections. Page sections can occupy whole central column of 730px, see picture.

img/pages-section.png

3.   Development information

3.1.   Application iframe URL parameters

When user opens a draugiem.lv page application, there are some additional GET parameters injected in the iframe URL.

3.1.1.   api_page_id

Page identifier from where the application was opened. Several server side API calls use this identifier. This parameter might be useful if your application can be added to multiple pages.

3.1.2.   api_user_auth

Parameter which you can use to guess user status on the page. Never use this to grant additional permissions based on this information, please validate the user status with a server side call.

  • fan - user is logged in and following this page
  • user - user is logged in and not following this page
  • false - user is not logged in and therefore it is not known whether he is a follower of this page.
  • admin - user is administrator of this page.

3.1.3.   dr_appw

Parameter which you can use to understand the position the application is placed. Possible values:

  • 240 - application is added to front page of page and added to right column. Application width is 240px
  • 480 - application is added to front page of page and added to center column. Application width is 480px
  • 730 - application is added as a section of a page. Application width is 730px. This is the most widely used option.

3.2.   Available API calls

Draugiem.lv page applications can use all regular draugiem.lv application API calls: http://www.draugiem.lv/applications/dev/docs/iframe_en/

3.2.1.   pages/userstatus

Returns current user status in application, used to verify user status on server side.

Request parameters:

action:pages/userstatus
app:application API key (32 simboli)
apikey:user API key (32 simboli)
page_id:page identifier which you receive via GET parameter in application iframe

Response values

Value Description
USER regular user, page visitor
FAN user following a page
ADMIN page administrator

Example response:

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

In case application makes a request with a page_id that user has not installed, a status code 150 (access denied) is returned.

3.2.2.   pages/adminpages

Returns information about pages a specific user is administrator at.

Request parameters:

action:pages/adminpages
app:application API key (32 simboli)
apikey:user API key (32 simboli)

Example response:

<?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: a maximum of 100 pages are returned.

3.2.3.   pages/userpages

Returns pages the user is following (max 200)

Request parameters:

action:pages/userpages
app:application API key(32 simboli)
apikey:user API key (32 simboli)

Example response:

<?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

Returns basic data about a specific page

Request parameters:

action:pages/info
app:application API key (32 simboli)
apikey:user API key (32 simboli)
page_id:page identifier

Example response:

<?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 functions

Draugiem.lv applications have several JavaScript API function calls in addition to regular draugiem.lv JavaScript API available for integrated applications: http://www.draugiem.lv/applications/dev/docs/iframe_en/#javascript-api-functions

3.3.1.   Send an invite to page

JavaScript function draugiemSendPageInvite(text, callback) opens a window where user of the application can sed an invitation to follow a page. Function works only when opened from within a specific page.

You can pass two optional parameters to this function:

text:invite placeholder text (user can change it before he sends an invitation)
callback:callback function to execute when user closes the window. The function can accept one argument, which will include number of invitations sent or false if no invitations are sent.

User will choose friends to invite in the invitation window.

3.3.2.   Open "follow a page" popup window

You can open a popup window asking a user to follow a page with draugiemPagesFan() function.

You should pass a page ID of a page you wish to ask the user to follow

3.3.3.   User authentication request

By default all draugiem.lv page applications work anonymously. It means that no page applications have access to user data. Developers should take care of this by using draugiemAuthorize() function. You can call this function only after user interaction. e.g. no automatic calls within "onLoad" or similar events.

You can pass an optional argument as object:

{'followPage': true}

If you pass this parameter, user will have an option to start following the page within the same window where access to user data is granted.

Optional parameter to redirect user after successful authorization:

{'redirect': 'app-url/?success'}

By passing this parameter, user will be redirected to http://draugiem.lv/app-url/?success

4.   Application store

Page administrators will have access to applications just like all other Draugiem.lv Page widgets.

img/pages-appstore-button.png

Page applications have 3 different statuses:

  1. Development application - only application developers can see the application in the application store. If the application is added to a page, regular users don't have access to that application.
  2. Private application - application developers can see the application in the application store. If the application is added to a page, regular users can open and use the application.
  3. Public application - application can be seen in application store by all administrators of all pages. If the application is added to a page, regular users can open and use the application.

4.1.   How to add your application to store?

The applications available in store are pre-moderated. In order to publish your application please contact us at api@draugiem.lv.

5.   Page applications and business

Page applications of Draugiem.lv pages are a tool which can be used to extend the functionality of your page.

There are no costs associated with publishing your application if these two rules are complied with:

  1. application is developed for a specific page and is not meant for public use.
  2. the owner of the application is not asking any payments from end users or other page owners that use the application

If application is developed as a paid tool for other page owners, all rules of paid services within draugiem.lv network are applied: http://www.draugiem.lv/applications/dev/docs/iframe_en/#draugiem-lv-payment-api

6.   Contacts

Should you have any questions, please contact us:

api@draugiem.lv
http://www.draugiem.lv/pages/