# Draugiem.lv developer documentation > API and integration documentation for Draugiem.lv (Latvian social network): integrated iframe applications, Draugiem.lv Passport (OAuth-like login), Draugiem ID, PHP API library, recommend ("say") widgets, business page apps and payments. Every document is available as Markdown by appending `?format=md` to its URL. Most documents are in Latvian; English versions have the `_en` suffix. API base URL: `https://api.draugiem.lv/{format}/` where format is `json`, `php` or `xml`. Full concatenated documentation: https://draugiem.eu/applications/dev/docs/llms-full.txt ## English documentation - [Integrated applications](https://draugiem.eu/applications/dev/docs/iframe_en/?format=md) - [Page applications](https://draugiem.eu/applications/dev/docs/pages_en/?format=md) - [Draugiem.lv Passport](https://draugiem.eu/applications/dev/docs/passport_en/?format=md) - [Draugiem.lv API PHP library](https://draugiem.eu/applications/dev/docs/php_en/?format=md) - [Draugiem.lv recommend widgets](https://draugiem.eu/applications/dev/docs/say_en/?format=md) ## Latvian documentation (dokumentācija latviski) - [Portālā integrētās aplikācijas](https://draugiem.eu/applications/dev/docs/iframe/?format=md) - [Draugiem.lv pase](https://draugiem.eu/applications/dev/docs/passport/?format=md) - [Draugiem ID](https://draugiem.eu/applications/dev/docs/draugiemid/?format=md) - [Draugiem.lv API PHP bibliotēka](https://draugiem.eu/applications/dev/docs/php/?format=md) - ["Ieteikt draugiem" funkcija](https://draugiem.eu/applications/dev/docs/say/?format=md) - [Draugiem.lv lapu aplikācijas](https://draugiem.eu/applications/dev/docs/pages/?format=md) - [Lapu administrēšanas API](https://draugiem.eu/applications/dev/docs/pages_admin/?format=md) - [Pasākumu sadaļas datu API](https://draugiem.eu/applications/dev/docs/events/?format=md) - [Aplikāciju API](https://draugiem.eu/applications/dev/docs/api/?format=md) - [Draugiem.lv pase priekš Wordpress](https://draugiem.eu/applications/dev/docs/wordpress/?format=md) - [Draugiem.lv biznesa lapu fanu spraudnis priekš Wordpress](https://draugiem.eu/applications/dev/docs/pages_fans_wordpress/?format=md) - [Draugiem.lv pase priekš Drupal](https://draugiem.eu/applications/dev/docs/drupal/?format=md) - [Aplikāciju sadaļas noteikumi](https://draugiem.eu/applications/dev/docs/rules/?format=md) - [Izstrādes vadlīnijas](https://draugiem.eu/applications/dev/docs/guidelines/?format=md) - [Spēļu analītika ar GA](https://draugiem.eu/applications/dev/docs/analytics/?format=md) - [Draugiem.lv logo](https://draugiem.eu/applications/dev/docs/logos/?format=md) --- # Draugiem.lv Integrated Application API Documentation ## 1. Integrated application API ### 1.1. Introduction Draugiem.lv integrated applications allow developers to embed an external page as separate section of draugiem.lv, so that visually it looks and feels almost the same as other draugiem.lv sections. ![img/iframe.png](https://draugiem.eu/applications/img/iframe.png) Applications are integrated into draugiem.lv layout by using an iframe solution. Content is placed into 1080 pixels wide iframe window that opens an URL provided by the developer. The initial height of the iframe can be set in the application settings (default value 700 pixels). Iframe can also be resized dynamically by using Javascript API. Each application is given a short address in form `https://www.draugiem.lv/app_name/`. Short address can be chosen when the application is created. If you specify a mobile iframe address in the application settings, then the application is also available at `https://m.draugiem.lv/[app_name]`. ![img/allow.png](https://draugiem.eu/applications/img/allow.png) First time when the user opens application, he has to agree to give his personal information to third party developers. After agreement, iframe window is opened and user can start to use the application. After approval process, application receives user's API key that gives it a limited access to user's data and ability to post messages to user activity feed or profile news (if the application has permission to use these functions). Next times when the user opens the application, he can use it directly, without further approval. If the user wants to discontinue use of the application, he can delete if from his profile. After deletion, application no more has access to the user's data. Applications also can use an invitation system that allow users to invite their friends to join the application. If the application offers paid services it has to use payment API provided by draugiem.lv, to ensure payments. Developer together with SIA Draugiem signs an agreement that determines the revenue share between both parties. ### 1.2. Acquiring authorization code Similar with draugiem.lv Passport, integrated applications also use an authorization code to access user's API key. After the user has agreed to give his data to third party, iframe window is opened with these GET parameters added: - `dr_auth_status`: value `ok` - `dr_auth_code`: authorization code (20 characters), that allows application to acquire user's API key - `session_hash`: user's draugiem.lv session identification (32 bit positive integer), that allows the application to check if the user's draugiem.lv session is still active - `domain`: draugiem.lv domain, that the user has opened (usually `www.draugiem.lv`) After receiving authorization code, the application has to perform `authorize` API call (Section User authentication) to acquire user's API key that is necessary for further API requests. Authorization code doesn't change during the session so if the application receives the same authorization code again (e.g. when the user reloads the iframe), application does not have to perform another `authorize` request. If application receives authorization code that is different from the previous, it must perform another `authorize` request - this situation means that another user has logged in draugiem.lv and started to use the application from the same computer. ### 1.3. Passing additional parameters to the address in iframe By default iframe window opens address that is given in the application settings (with authorization parameters added). However, it is possible to open another address by adding extra GET parameters or directory path to the short URL. **Example:** application's short URL is `https://www.draugiem.lv/myapp/`, and content URL - `https://example.com/app/`. It is possible to change the address in the iframe in following ways: | Adress that is opened by the user | Address that is displayed in the iframe | | --- | --- | | `https://www.draugiem.lv/myapp/` | `https://example.com/app/` | | `https://www.draugiem.lv/myapp/test/123` | `https://example.com/app/test/123` | | `https://www.draugiem.lv/myapp/?a=1&b=2` | `https://example.com/app/?a=1&b=2` | | `https://www.draugiem.lv/myapp/test/?a=1` | `https://example.com/app/test/?a=1` | | `https://www.draugiem.lv/myapp/a.php` | this address won't work since it ends with a file extension | The URL that is opened in the iframe will always contain authorization parameters as well. ### 1.4. Accessing the application Newly created integrated application can be accessed only by its owner and draugiem.lv employees. Other users will see a notification that application is in development mode and can't be accessed. Application owner can provide up to 30 of his friends a permission to access application as developers and assign up to 10 friends as application administrators. Developers can use the application even when it is under development or is closed. Administrators are provided with full control over the application except deleting it. When application's development comes to an end, developers can submit the application to draugiem.lv Labs. On this phase application can be accessed and tested by users who are members of the draugiem.lv Labs team. A discussion group where developers and testers can discuss application's issues, is also created. When application is finished, it can be published in draugiem.lv application section. Published application can be used by any of the users of draugiem.lv (however, it is possible to limit the access to a certain age). Developers also have an option to temporarily close the application for maintenance. Keep in mind that developed application does not guarantee publishing it in draugiem.lv. So, in order to avoid confusion, it is highly recommended to consult with draugiem.lv whether the application suits for publishing before development. Integrated application can also work as Draugiem.lv Passport application. This feature allows you to display the same application both in draugiem.lv or on its own domain outside draugiem.lv. ### 1.5. Some suggestions for developers - After authorization, user profile data should be kept within the session instead of requesting them repeatedly in every request. - If user data are displayed in many places in the page, they should be cached on application's side to prevent unnecessary load both on draugiem.lv and application's servers. - If your application uses PHP, it is best to use our provided [PHP library](https://draugiem.eu/applications/dev/php_en/) for the integration. - If you need to contact us, please write email to [api@draugiem.lv](mailto:api@draugiem.lv), - Ensure that nobody can access your application's API key. - To increase security, you can add IP limit to your servers in the application settings. Never perform API requests from the client side (Javascript or Flash) - that wil make your API key exposed to everyone. ### 1.6. Session cookie creation problems in Safari browser Safari browser with the default security settings does not allow to set cookies in the iframe if the parent domain is different from the iframe domain. Cookies are allowed only after the user has performed an action within iframe. This can lead to problems in creation of user session within the iframe since the cookie that is created in the first request won't be stored. Developers have to ensure that session ID gets passed to the second request even when the cookie fails to be set. This limitation can be avoided by posting a form with Javascript to simulate user's input. If you use our provided [PHP library](https://draugiem.eu/applications/dev/php_en/), you can use `CookieFix` method, to avoid this limitation. ### 1.7. Session cookie creation problems in Internet Explorer browser Similar with Safari, IE users with *Medium* level of *Privacy* setting can face problems with cookie creation inside the iframe. To overcome this limitation, the application has to send this HTTP header to the user (code example in PHP): ``` header('P3P:CP="IDC DSP COR ADM DEVi TAIi PSA PSD IVAi IVDi CONi HIS OUR IND CNT"'); ``` If you use our provided [PHP library](https://draugiem.eu/applications/dev/php_en/), you can use `CookieFix` method, to avoid this limitation. ## 2. How to use draugiem.lv API ### 2.1. API requests To acquire data or perform other actions with draugiem.lv API, application server has to perform HTTP POST or GET requests to draugiem.lv server, providing necessary request parameters according to API specification. Parameters can be passed as HTTP GET, POST or COOKIE variables (however, POST is recommended). API request URL depends on chosen data format. Draugiem.lv API provides following formats: | Format | Description | API address | | --- | --- | --- | | **XML** | API response will be encoded in in XML format | | | **PHP** | API response will be encoded in PHP serialized data format | | | **JSON** | API response will be encoded in JSON format | | | **PLIST** | API response will be encoded in Apple Property List XML format | | Examples provided by this documentation will show API responses in XML format. Our provided *PHP library * uses PHP serialized format. API request always must contain parameter `action` that contains required API action, and parameter `app` that contains the API key of the application (API key is created when you create the application and it is used to identify the application that performs API requests). Almost always API request will contain parameter `apikey`, that identifies draugiem.lv user that has authorized the application. **Example:** To obtain basic profile info in XML format (application API key - `52967e99b3c11a755e7635901c23c0cf`, user API key - `208d970441dd5f3e87b965fedabd0738`), you have to perform this request: `https://api.draugiem.lv/xml/?app=52967e99b3c11a755e7635901c23c0cf&apikey=208d970441dd5f3e87b965fedabd0738&action=userdata` According to this request, server will respond with data structure in chosen format: ```xml Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M ``` ### 2.2. Error codes If application has performed invalid API request or any other error has occured, API response will contain error code and description. **XML example:** ```xml Access denied ``` **PHP serialized format example:** ``` a:1:{s:5:"error";a:2:{s:11:"description";s:13:"Access denied";s:4:"code";i:150;}} ``` **JSON example:** ```json {"error":{"description":"Access denied","code":150}} ``` **Possible error codes:** | Code | Error description | Explanation | | --- | --- | --- | | 10 | Internal error | API internal error | | 20 | Service not available | API is temporarily unavailable | | 80 | Bad request | Error in request parameters | | 90 | Invalid action | Invalid value of `action` parameter | | 101 | Invalid user API key | Invalid value of `apikey` parameter (user API key) | | 103 | Invalid application API key | Invalid value of `app` parameter (application API key) | | 104 | IP address not allowed | API request was performed from address that is not within allowed addreses in application settings | | 105 | Max API request limit in 10 minutes reached | Application has reached max request limit in 10 minutes per user. | | 106 | Invalid or unapproved auth code | `code` parameter that was used in `authorize` request was invalid or already used. | | 107 | Max activity limit for this user today reached | Max activity or notification count for this user per day has been reached | | 120 | Data not found | Requested data not found | | 130 | Spam/Flood detected | Too frequent sending of data (activities/notifications) | | 150 | Access denied | Application does not have access to the requested data. | ### 2.3. User data If API request requests information related with user data, API answer will contain block `users` with basic profile information of users. Every user element contains attribute `uid` that uniquely identifies draugiem.lv user and can be used to create relations between user and other objects. **XML example:** ```xml ... Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M ... ``` **PHP example:** ``` 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";}}} ``` **JSON example:** ```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"}}} ``` Every user data item contins these values: - `name`: First name - `surname`: Last name - `age`: age (empty, if user wants to hide his age) - `adult`: indicates if user has reached age 18 (1 - adult, 0 - not adult). Allows to check if user is adult even if he wants to hide his age. - `img`: Profile image URL (100x100px). Empty if user has no image. - `sex`: gender (M - male, F - female) To get user profile image in different sizes, simply replace in URL part `sm_` with another prefix: - `i_`: 50x50px icon - `sm_`: 100x100px icon - `m_`: 215px wide image - `l_`: large image (max. 710x710px) **Example:** If profile image URL is `https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg`, then URL of middle sized version of this image will be `https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg`. ### 2.4. Notifications about deleted users If you fill field *Delete status callback URL* with your URL in application settings, draugiem.lv will notify you about users that have deleted themself from your application or deleted their profile entirely. That allows you to remove user information from you database or perform other actions that are necessary to perform if user ceases to use the application. Our server will call your URL with these parameters added: - `status`: value `delete` - `uid`: User ID of deleted user - `app`: Application ID **Example:** Application with ID 1234 has configured address `https://example.com/delete_profile/` as delete callback URL. When user with ID 12345 deletes from application, draugiem.lv server will call URL `https://example.com/delete_profile/?status=delete&uid=12345&app=123` Response to this request must contain only text `OK`, otherwise draugiem.lv system will try to resend status report. ## 3. Available API requests ### 3.1. User authentication process (request authorize) Request allows application to acquire user's API key that is neccessary to perform other API requests on behalf of the user. The request also returns user's basic profile information so that no additional requests are needed to get this data. **Request parameters:** - `action`: `authorize` - `app`: application API key (32 characters) - `code`: `dr_auth_code` value that was received as GET variable after user login (for draugiem.lv Passport applications) or when the iframe was opened (for integrated applications) **Response will contain these parameters:** - `apikey`: user's API key - `uid`: user ID - `language`: 2 letter code of the language that the user has selected in draugiem.lv - `inviter`: user ID of the person who has invited this user to the application (this element is present only when user opens application for the first time after accepting invitation) - `invite_extra`: extra data that were attached to the accepted invitation by the application (this element is present only when user opens application for the first time after accepting invitation) User's API key allows application to access user's data via API wthout repeating authorization. After authorization application will be added to the *My Applications* section of the user's profile. From there user will be able to discontinue application's permission to access his data. Response also contains user's profile information according to the format described in section User data. **Example response:** ```xml 09797abfe8e5ea53fd857cc372e3a6f5 491171 lv Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M ``` To be able to access user's data again, application has to store the `apikey` value and use it in all further API requests. If application has lost user's API key or if the user has deleted if from the profile, authorization process can be repeated. User's API key can change if the user change his password or deletes application from the profile and joins repeatedly. ### 3.2. Getting user data of specific users (request userdata) This request allows to get basic profile information of specific draugiem.lv users who have authorized the application. This request doesn't require user's API key, just the application's key. **Request parameters:** - `action`: `userdata` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters), optional, if `ids` parameter is provided - `ids`: optional, comma separated list of draugiem.lv user IDs (max 100 IDs per request) If request contains parameter `ids`, response will contain profile information of requested users according to format described in section User data. Only information about users that are registered in application will be returned (if the user has deleted from the application, data will not be available anymore) If `ids` parameter is not given, then API will return information about user who owns the API key passed in `apikey` parameter according to format described in section User data. The order of returned user data is not strictly defined. **Example response:** ```xml Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg User_Default M Elīna Ozoliņa 25 1 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg User_Business F ``` In case of using Draugiem.lv passport, the user data may also contain official draugiem.lv pages ( www.draugiem.lv/lapas ) data instead of the regular user data. To determine if this is a regular user or page, you need to check the value in the `type` parameter. Currently 2 values are possible: - User_Default - ordinary user - User_Business - business page ### 3.3. Getting list of application users (request app_users) Request allows to get a list of all users that use the application. This request doesn't require user's API key, just the application's key. **Request parameters:** - `action`: `app_users` - `app`: application API key (32 characters) - `show`: optional, if this parameter is given with value `ids`, only list of user IDs will be returned instead of full profile data. - `page`: optional, number of the page that needs to be returned. By default, first page will be returned. - `limit`: optional, number of users per page (allowed range 1-200). By default one page contains 20 users. If request does not contain parameter `show` with value `ids`, response will contain element `users`, filled with information according to format described in section User data. Element `users` will have an attribute `total` that contains total number of users. **Example response (show=ids is not given):** ```xml Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M Elīna Ozoliņa 25 1 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg F ``` If request contains parameter `show` with value `ids`, response will contain element `userids`, that will hold a list of draugiem.lv user IDs. Element `users` will have an attribute `total` that contains total number of users. **Example response (show=ids is given):** ```xml 64428 491171 1524905 134564 234561 ``` ### 3.4. Getting number of application users (request app_users_count) Request allows to get count of currently registered users in the application. **Request parameters:** - `action`: `app_users_count` - `app`: application API key (32 characters) Response contains element `usercount`, that contains the number of users that have authorized the application. **Example response:** ```xml 312 ``` ### 3.5. Getting list of user's friends that use the application (request app_friends) Request allows to get information about user's friends that use the application. **Request parameters:** - `action`: `app_friends` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) - `show`: optional, if this parameter is given with value `ids`, only list of user IDs will be returned instead of full profile data. - `page`: optional, number of the page that needs to be returned. By default, first page will be returned. - `limit`: optional, number of users per page (allowed range 1-200). By default one page contains 20 users. If request does not contain parameter `show` with value `ids`, response will contain element `users`, filled with information according to format described in section User data. Element `users` will have an attribute `total` that contains total number of friends. **Example response (show=ids is not given):** ```xml Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M Elīna Ozoliņa 25 0 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg F ``` If request contains parameter `show` with value `ids`, response will contain element `userids`, that will hold a list of draugiem.lv user IDs. Element `users` will have an attribute `total` that contains total number of friends. **Example response (show=ids is given):** ```xml 64428 491171 1524905 134564 234561 ``` ### 3.6. Getting number of user's friends that use the application (request app_friends_count) Request allows to get the number of active user's friends that also use the application. **Request parameters:** - `action`: `app_friends_count` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) Response contains element `friendcount`, that contains the number of user's friends that have authorized the application. **Example response:** ```xml 16 ``` ### 3.7. Getting list of user's online friends that use the application (request 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ā. **Request parameters:** - `action`: `app_friends_online` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) - `show`: optional, if this parameter is given with value `ids`, only list of user IDs will be returned instead of full profile data. - `in_app`: optional, if this parameter is given with value `1`, request will return information about user's friends that use the application right now (have been in the application during last 5 minutes). If this parameter is not given, response will contain list of user's friends that are currently online in draugiem.lv and are registered in the application. - `limit`: optional, number of users to return (allowed range 1-100). By default up to 20 users will be returned. If request does not contain parameter `show` with value `ids`, response will contain element `users`, filled with information according to format described in section User data. **Example response (show=ids is not given):** ```xml Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M Elīna Ozoliņa 16 0 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg F ``` If request contains parameter `show` with value `ids`, response will contain element `userids`, that will hold a list of draugiem.lv user IDs. **Example response (show=ids is given):** ```xml 64428 491171 1524905 134564 234561 ``` ### 3.8. Getting list of user's online friends (request app_all_friends_online) Request allows you to get information about your friends who are currently online. **Request parameters:** - `action`: `app_all_friends_online` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) - `show`: optional, if this parameter is given with value `ids`, only list of user IDs will be returned instead of full profile data. - `page`: optional, page number of friends list. Default value is 1. - `limit`: optional, number of users to return (allowed range 1-100). By default up to 20 users will be returned. If request does not contain parameter `show` with value `ids`, response will contain element `users`, filled with information according to format described in section User data. **Example response (show=ids is not given):** ```xml Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M 1 Elīna Ozoliņa 16 0 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg F 1 ``` If request contains parameter `show` with value `ids`, response will contain element `userids`, that will hold a list of draugiem.lv user IDs. **Example response (show=ids is given):** ```xml 491171 64428 ``` ### 3.9. Getting friendship status between two users (request check_friendship) Request allows to check if two application users are friends. **Request parameters:** - `action`: `check_friendship` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters), optional, if `uid2` parameter is provided - `uid`: user ID of the first user - `uid2`: user ID of the second user. Optional if `apikey` value is given. - If both `uid` and `uid2` values are given, friendship status among these two users will be returned. - If `uid2` balue is not given, but `apikey` value is provided, friendship status between API key owner and user `uid` will be returned. - Response contains element `status`, that has value `OK` if there is a friendship between these two users. - If there is no friendship, `status` value will be `NOT_FRIENDS`. - If any of provided users is not registered application's user, `status` value will be `NOT_USERS`. **Example response:** ```xml OK ``` ### 3.10. Posting entries to user's profile activity feed (request add_activity) Request allows to add entry with a link to user's profile activity feed (entry will be visible to all of his friends) **This feature is not enabled by default. To get permission for your application to post items to activity feed, contact api@draugiem.lv and tell us about your application and what kind of activities it will create.** Integrated applications during the development phase are allowed to post activities in test mode (they will be visible only to the developers). To continue posting activities after publishing, they have to be enabled by draugiem.lv staff. Activity link must point to the same domain that is configured as application URL in application settings. Application's icon will be shown next to the created entry. Only one activity per day can be created for each user. ![img/events.png](https://draugiem.eu/applications/img/events.png) Activities must comply with these principles: - Activity informs about actual user's action in the application. - Activity system can't be used for advertising. - Before starting to add new types of activities, it is highly recommended to consult with us before. - For integrated applications activity URL has to contain address that will be displayed in the iframe, not the application address in draugiem.lv - it will automatically converted to internal address. Address opened in iframe can contain directory path and GET variables, but might not work if it contains file name with common extensions (php/css/jpg etc.) will not work If application will create activities that do not follow the rules, we can deny application to post new activities. **Request parameters:** - `action`: `add_activity` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) - `prefix`: optional, text that will be displayed before the clickable link. Max length 50 characters. - `text`: text of clickable activity link. Max length 100 characters. - `link`: optional, URL, where the activity link will point to. If not given, link will point to application start page. URL domain must be the same as given in the application settings. Max length 100 characters. - If activity was successfuly created, response will contain element `status` with value `OK`. - - **If application has no permission to post activities or if the user has blocked activities from this application,**: API will respond with error `150 (Access denied)`. - If daily activity limit for user has been reached, API will respond with error `107 (Max activity limit for this user today reached)` **Example response:** ```xml OK ``` ### 3.11. Posting notifications to user's profile news feed (request add_notification) Request allows to add notification with a link to user's profile news feed (it will be visible only to the user) **This feature is not enabled by default. To get permission for your application to post inotifications, contact api@draugiem.lv and tell us about your application and what kind of notifications it will create.** Integrated applications during the development phase are allowed to post notifications in test mode (they will be visible only to the developers). To continue posting notifications after publishing, they have to be enabled by draugiem.lv staff. Notification link must point to the same domain that is configured as application URL in application settings. Application's icon will be shown next to the created entry. Application can create up to 5 notifications per day for every user, no sooner than an hour after previous one. ![img/profileNews.png](https://draugiem.eu/applications/img/profileNews.png) Notifications must comply with these principles: - Notification informs about something that has happened with user's profile in the application. It is recommended that the notification link goes to a specific place in the application if it is possible. - Notifications can't be used to advertise application with no reason. - Before starting to add new types of notifications, it is highly recommended to consult with us before. - For integrated applications notification URL has to contain address that will be displayed in the iframe, not the application address in draugiem.lv - it will automatically converted to internal address. Address opened in iframe can contain directory path and GET variables, but might not work if it contains file name with common extensions (php/css/jpg etc. will not work) If application will create notifications that do not follow the rules, we can deny application to post new notifications. It is possible to show both notifications that come from a specific user or notifications that are displayed as created by the application. **Important:** Remember that notification is displayed to user that owns the API key that is used in request.So in order to send notification to user that currently is not online, application has to store user's API key for offline use. **Request parameters:** - `prefix`: optional, text that will be displayed before the clickable link. Max length 50 characters. - `text`: text of clickable activity link. Max length 100 characters. - `link`: optional, URL, where the activity link will point to. If not given, link will point to application start page. URL domain must be the same as given in the application settings. Max length 100 characters. - `action`: `add_notification` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) - `prefix`: optional, text that will be displayed before the clickable link. Max length 50 characters. - `text`: text of clickable notification link. Max length 100 characters. - `link`: optional, URL, where the notification link will point to. If not given, link will point to application start page. URL domain must be the same as given in the application settings. Max length 100 characters. - `creator`: Optional, Draugiem.lv user ID that will be displayed as sender of the notification (user ID has to belong to a registrated user of the application; if this parameter is not given, application name will be displayed as the sender of the notification) - If notification was successfuly created, response will contain element `status` with value `OK`. - - **If application has no permission to post notifications or if the user has blocked notifications from this application,**: API will respond with error `150 (Access denied)`. - If daily notification limit for user has been reached, API will respond with error `107 (Max activity limit for this user today reached)` - If there is less then an hour since last added notification, request will return error `130 (Spam/Flood detected)` **Example response:** ```xml OK ``` ### 3.12. Checking user's draugiem.lv session state (request session_check) Request allows integrated applications to check if user's draugiem.lv session that user used to open the application is still active. Applications should not check in every request - it is recommended to do it no more often then every 3-5 minutes. **Request parameters:** - `action`: `session_check` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) - `hash`: session identification (positive 32 bit integer), that was received as `session_hash` parameter, when application iframe was opened. API response contains element `status`. If its value is `OK`, user's session is still valid. If the value is `FAILED`, user's session is no more valid and application should log out the user. **Example response:** ```xml OK ``` ### 3.13. Getting application status information (request app_status) Request allows to get statistical information about application's status. **Request parameters:** - `action`: `app_status` - `app`: application API key (32 characters) Response will contain these information fields: - `users`: Total number of users registered in application - `users24h`: Number of users that have used application during last 24 hours (updated once every hour) - `online`: Number of online users in the application during the last 5 minutes - `api_rq`: Number of application's API requests per second (average value during the last 20 seconds) - `activities`: Number of profile activities posted during the last minute - `notifications`: Number of profile news notifications posted during the last minute **Example response:** ```xml 159552 42872 1340 33.25 15 8 ``` ### 3.14. Get invitations sent to the application user (request invitations) The request allows to get information about invitations sent to the user to use this application. **Request parameters:** - `action`: `invitations` - `app`: application API key (32 characters) - `apikey`: the user whose invitations must be returned, API key (32 characters) **Response to this request will contain "invitation" elements that include the following values:** - `inviter`: user ID who sent invitation - `invite_extra`: additional data attached to the accepted invitation - `sent`: invitation sent time (unix timestamp) - `deleted`: invitation acceptance/deletion time (unix timestamp) - `accepted`: whether invitation has been accepted (1 - accepted, 0 - rejected or deleted). If a user has received multiple invitations to one application, confirming one will delete the others. **Example response:** ```xml 12345 1290899622 1303814320 0 .. ``` ### 3.15. Get invitations sent by the application user (request sent_invitations) The request allows to get information about user-sent invitations to use this application. **Request parameters:** - `action`: `sent_invitations` - `app`: application API key (32 characters) - `apikey`: the user whose sent invitations must be returned, API key (32 symbols) **Response to this request will contain "invitation" elements that include the following values:** - `user`: user ID who received invitation - `invite_extra`: additional data attached to the accepted invitation - `sent`: invitation sent time (unix timestamp) - `deleted`: invitation acceptance/deletion time (unix timestamp) - `accepted`: whether invitation has been accepted (1 - accepted, 0 - rejected or deleted). If a user has received multiple invitations to one application, confirming one will delete the others. **Example response:** ```xml 12345 1290899622 1303814320 0 .. ``` ## 4. Javascript API functions To ensure better integration with draugiem.lv, we provide some Javascript functions for integrated application development. To access Javascript functions, you need to add this script to your page: `https://ifrype.com/applications/external/draugiem.js` To provide possibility to get return data from Javascript API calls, create a file [callback.html](https://draugiem.eu/applications/external/callback.html) on the application's server with this content: ```html ``` This file is required to enable two way Javascript data communication between pages on different domains. Without this function, your application will be able to call Javascript functions but won't receive any response. When the file is created, application should create Javascript variable `draugiem_callback_url`, that contains full file address including domain. ```html ``` To let Javascript API to know under which draugiem.lv domain the application is running, application should define variable `draugiem_domain`, that contains address that was passed to the application via the `domain` GET parameter when the application iframe was opened (it is recommended to store this value in the session for further requests). ```html ``` **Remember that Javascript executes on client side, so any function parameters or return values can be easily modified by the user!** ### 4.1. Vertical resizing of the iframe To enable automatic resizing of the iframe, when the page is opened, you need to create Javascript variable `draugiem_container` that contains ID of the DOM element that includes all the content of the page. Height of this element will be used to calculate necessary iframe height. If you also create variable `draugiem_container_offset`, its value will be added to the height of the `draugiem_container` element. ```html ``` To change iframe height without reloading page (e.g. after Ajax requests), you need to call Javascript function `draugiemResizeIframe()`. If the function is called without arguments, height will be calculated based on height of the element specified by `draugiem_container` value. It is also possible to pass required height in pixels to this function directly as first argument. ```html
test
``` It is very important to correctly adjust iframe size to fit all the content - if the iframe will be too small, users will not be able to see all content. m.draugiem.lv iframe width and height changes automatically (within all available free screen). ### 4.2. Displaying draugiem.lv modal window It is possible to display modal window with your own content if you call function `draugiemWindowOpen(address, width, height, callback)`. ![img/infobox.png](https://draugiem.eu/applications/img/infobox.png) **Function takes four arguments:** - `address`: address that needs to be opened in the window - `width`: required window width in pixels - `height`: required window height in pixels - `callback`: optional argument, Javascript callback function that will be called when the user closes the modal window. ```html ``` To close the modal window, call `draugiemWindowClose()` function. Window can also be closed manually by the user. m.draugiem.lv `width` and `height` argument values can be set in pixels (example: "200") or percents (example: "50%") ### 4.3. Sending invitations to user's friends By calling Javascript function `draugiemSendInvite(text, extra, callback)`, application can open window that lets user to invite some of his friends to join the application. Invitation feature is available only for approved and published applications - others can be accessed only by developers. ![img/invite.png](https://draugiem.eu/applications/img/invite.png) **Function can take three optional parameters:** - `text`: invitation text (user can change the text before sending) - `extra`: extra data (up to 150 characters), that will be passed back to the application in `authorize` request, if the new user has accepted the invitation. Application can use this value to identify specific invitation. - `callback`: optional argument, Javascript callback function that will be called when the user closes the modal window with one argument - the number of sent invitations or *false* if no invitation was sent. Invite dialog allows user to select which friends to send the invitation to. ```html ``` ### 4.4. Sending message to draugiem.lv user Calling Javascript function `draugiemSendMessage(uid, topic, text, callback)`, will open a window that allows user to compose message to another draugiem.lv user. ![img/mail.png](https://draugiem.eu/applications/img/mail.png) **Function has 4 arguments:** :uid: ID of person that will receive the message. :topic: message topic :text: message text :callback: optional argument, Javascript callback function that will be called when the user closes the modal window ```html ``` ### 4.5. Sharing links in draugiem.lv/say Javascript function `draugiemSay(title, url, titlePrefix, text, callback)` open window that allows user to share a link with his friends. ![img/say.png](https://draugiem.eu/applications/img/say.png) **Function takes four arguments, first two of them are mandatory:** - `title`: clickable text of the link (max 70 characters) - `url`: URL where the post will link to (max 140 characters) - `titlePrefix`: text that is shown before the clickable link (max 25 characters) - `text`: post text that the user can change before publishing (max 140 characters) - `callback`: optional argument, Javascript callback function that will be called when the user closes the modal window with one argument - *true* if the post was added or *false* if the user just has closed the window without posting. ```html ``` Published post will look like this: ![img/say2.png](https://draugiem.eu/applications/img/say2.png) m.draugiem.lv this function currently is not available. ### 4.6. Scrolling up content In page applications, there is often a situation where the content of the application causes the scrollbar to appear, but only a small portion of the content remains after user actions. In this situation, you can use the `draugiemScrollTop()` function to scroll to the top of page. ### 4.7. Posting images in user's gallery Javascript function `draugiemGalleryAdd(title, url, description, callback)`, allows to open a window that lets user to add to his gallery images provided by application. ![img/gallery.png](https://draugiem.eu/applications/img/gallery.png) **Function takes two arguments:** - `title`: title of newly created album (max 50 characters). User can change the title or add pictures to already existing album. - `url`: URL of the image that will be added to gallery or array of image URLs (up to 9 images can be added at a time). - `description`: optional argument, description text that will be displayed below the image. - `callback`: optional argument, Javascript callback function that will be called when the user closes the modal window with one argument - *true* if the pictures were added or *false* if the user just has closed the window without posting. ```html ``` **It is NOT ALLOWED to use this function in page applications!** m.draugiem.lv this function currently is not available. ### 4.8. Selecting images from user gallery By using Javascript function `draugiemGalleryChoose(count, callback)`, it is possible to open a window that allows the user to select images from his draugiem.lv galleries and pass them to the application. ![img/gallery_choose.png](https://draugiem.eu/applications/img/gallery_choose.png) **Function takes two arguments:** - `count`: max number of the selected images (1-10) - `callback`: Javascript callback function that will be called when the user closes the modal window with one argument - image data if images were selected or *false* if the user just has closed the window without choosing images. ```html ``` Information about every selected image is passed to the function provided by the `callback` parameter as Javascript object ``` { pid:78443473 //Picture ID thumb:'https://i3.ifrype.com/gallery/ff57173f4/443/473/sm_78443473.jpg', //Small picture (100x100) medium:'https://i3.ifrype.com/gallery/f2af6acf/443/473/m_78443473.jpg', //Medium picture (215px wide) large:'https://i3.ifrype.com/gallery/5feacb47/443/473/l_78443473.jpg' //Large picture (max 710px width/height) } ``` If parameter `count` contained value `1`, one such object will be returned. If a larger limit was provided, return value will contain a data structure that contains one or more such objects, depending on the number of the selected pictures. m.draugiem.lv this function currently is not available. ### 4.9. Opening the application authorization window For some integrated applications, it is possible to enable the ability to display content to the user before approving the application access to your data. In such cases, the user can view the content of the application anonymously, but the application cannot access the user before he approved access to them. When an application first needs to access user data, it can call access confirmation window by calling the JavaScript function `draugiemAuthorize()`. To enable your application to display content before authorization, contact [api@draugiem.lv](mailto:api@draugiem.lv). ```html ``` When developing page applications `draugiemAuthorize()` you can set an additional parameter `followPage: true`, which will add an additional option in the authorization window to start following the page where the application is placed. By default, the user will be prompted to follow the page. In addition to this parameter, `{'redirect', 'app-url/?success'}` may be passed. Setting this parameter will redirect the user to the following address after successful authorization: . It is possible to set the `redirect: false` parameter and as a second argument to set the `callback` function, and the user authorization data will be returned to a function of type `object` containing a session identifier and permissions (see permissions types 4.10). This way provides access to user data without reloading the page. If the user closes the window, the callback function will be passed an argument with data type `boolean` and value `false`. m.draugiem.lv this function currently is not available. ### 4.10. Opening the application permissions window Using the `draugiemSettings(callback)` function, it is possible to open the window that is displayed to the user the first time the application is opened. In the window the user has the possibility to change the access rights of the application to his data. ![img/draugiemSettings.PNG](https://draugiem.eu/applications/img/draugiemSettings.PNG) **Function takes one argument:** - `callback`: a JavaScript function that will be called when the window is closed. The function will be provided with one argument of type object, which will contain all types of permissions with values `` true`` or `false`. **Possible types of permits:** | Permission keyword | Permission description | | --- | --- | | perm_events | Allow posting to user profile activities | | perm_news | Allow notifications to appear in user profile news | | perm_say | Allow posting to the user's Say feed | m.draugiem.lv this function currently is not available. ### 4.11. Open the Friends Selection window Using the `draugiemFriends(maxlength,callback)` JavaScript function, it is possible to open a window that prompts the user to select a certain number of users. ![img/draugiemFriends.PNG](https://draugiem.eu/applications/img/draugiemFriends.PNG) **Function takes two arguments:** - `maxlength`: the maximum number of users a user can select. To offer an unlimited number the value of the argument must be 0. - `callback`: a JavaScript function that will be called when the window is closed. The function will be called with one argument of type string, which will contain the comma-separated identifiers of all selected users. If no user is selected, an argument of type object and value `null` will be returned. m.draugiem.lv this function currently is not available. ## 5. Draugiem.lv API PHP library To make application development faster and easier, we've created a PHP library that performs API calls and automatically converts the requested data to the PHP data structures. PHP library can be used both for integrated applications and draugiem.lv Passport applications. [PHP library documentation](https://draugiem.eu/applications/dev/php_en/) [Draugiem.lv PHP library and examples](https://github.com/Draugiem/draugiem-php-sdk) ## 6. Draugiem.lv payment API To provide paid services for integrated applications, developers have to use draugiem.lv Payment API. It offers many different payment options. ### 6.1. Creating paid service To start using paid services, application first has to enable payment API. To enable payments for application, please contact [api@draugiem.lv](mailto:api@draugiem.lv). After the API has been enabled, it becams possible to create paid services through the application's administration panel. When a service is being created, these information fields need to be filled: - `Type`: SMS, bank or draugiem.lv Credit payments (for bank/SMS payments, user will also have an option to pay with draugiem.lv Credits) - `Price`: SMS tariff (only for SMS payments) - `Name`: Name of the service. It will be shown to the user during the payment and in payment statistics. - `Description`: Short description of the service that will be shown to the user. - `SMS response text` - ``: Teksts, that will be sent as a response SMS (SMS payments only) - `Statusa atskaites URL` - ``: Application callback URL, that will be called to report a successful payment to the application Paid service administration panel will display service ID that has to be used to create payment transactions via API. It is recommended that one application creates no more than 12 paid services to keep payment statistics charts and graphs simplier. ### 6.2. Creating a transaction To create payment transaction and retrieve its ID, application has to perform this API call: **Request parameters:** - `action`: `transactions/create` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) - `service`: service ID from the created paid service - `price`: service price in euro cents(0.01 EUR)/draugiem.lv Credits (max value 15000, SMS payment services do not need this parameter since the price is fixed per service) Response will contain transaction ID (element `id`) and the URL of the payment page that has to be displayed to the user (element `link`). **Example response:** ```xml 1935 https://www.draugiem.lv/services/iframe.php?id=1935 ``` URL that is received in the `link` element, has to be displayed to the user (as iframe, popup window or modal window that is opened with *draugiemWindowOpen* function). Recommended size of the payment window is at least 350x400 pixels. Opened window contains all the information that is needed to the user to finish the payment. Received `id` value has to be stored by the application - because transaction success can be determined by this value. To avoid generating unnecessary amount of unused transaction IDs, it is recommended to create the transaction only when the user has decided that he wants to pay. ### 6.3. Determining transaction status After the user has been successfuly charged, draugiem.lv server will call payment status callback URL provided by the application with these HTTP GET parameters added: - `id`: transaction ID - `service`: payment service ID - `uid`: user ID - `price`: transaction price in euro cents - `status`: value `ok` **Application must respond with exact text OK to this request**, otherwise draugiem.lv system will assume that the report was not delivered and will try to deliver it repeatedly (up to 20 attempts with increasing time intervals). Application has to respond with `OK` even if it receives report for transaction that is already processed or is not found. The only situation when the application shouldn't respond with `OK` is when the application has technical difficulties to process the payment (e.g. the database is down), and it wants the report to be resent later. If status notification was not received, it is possible to check the status manually by using API: - `action`: `transactions/check` - `app`: application API key (32 characters) - `id`: payment transaction ID Response will contain one of these statuses: - `OK`: Transaction was paid successfuly - `UNKNOWN`: Transaction was not paid at all or is not finished yet - `SMS_SENT`: Response SMS was sent, but there is no information about charging status from the operator yet. - `FAILED`: Transaction payment has failed **Example response:** ```xml OK ``` --- # 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: ## 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](https://draugiem.eu/applications/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](https://draugiem.eu/applications/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: #### 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 ADMIN ``` 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 Draugiem.lv lapas 0 0 https://path.to.image/file.jpg /pages 1 15328 afdsfdasfdsadfs ... ``` 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 Draugiem.lv lapas 0 0 https://path.to.image/file.jpg /pages 1 15328 afdsfdasfdsadfs ... ``` #### 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 Draugiem lapas 0 https://i2.ifrype.com/business/000/622/v1300780832/sm_13000622.jpg /pages 1 15328 ``` ### 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: #### 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 ## 4. Application store Page administrators will have access to applications just like all other Draugiem.lv Page widgets. ![img/pages-appstore-button.png](https://draugiem.eu/applications/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](mailto: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: ## 6. Contacts Should you have any questions, please contact us: ``` api@draugiem.lv https://www.draugiem.lv/pages/ ``` --- # Draugiem.lv Passport API documentation ## 1. Draugiem.lv Passport ### 1.1. Introduction Draugiem.lv Passport allows external websites to introduce functions that use the profile information of draugiem.lv users. That allows projects that are not created by draugiem.lv to access friendship links between their users and improve their functionality based on this information. Draugiem.lv Passport can be used in various ways. It can fully replace website registration and login system to remove the need for every user to perform difficult registration. If the website already has a registration system, it can use draugiem.lv Passport to link user's profile in the website with the profile in draugiem.lv. When the user accesses a page with draugiem.lv Passport, he agrees to give his personal data to thrd party developers. After approval process, application receives user's API key that gives it a limited access to user's data and ability to post messages to user activity feed or profile news (if the application has permission to use these functions). If the user wants to discontinue use of the application, he can delete if from his profile. After deletion, application no more has access to the user's data. ### 1.2. Opening draugiem.lv Passport login window To allow the user to login to a website by draugiem.lv Passport, you have to place in the site a button or a link that opens the login window. When the user clicks on this button, a webpage or new window is opened: 1. it allows the user to enter his username and password, if the user is currently not logged into draugiem.lv, 2. it displays user's name, picture and an *Allow* button - if user is logged into draugiem.lv ![img/pase1.png](https://draugiem.eu/applications/img/pase1.png) Authorization page URL is created in this format: `https://api.draugiem.lv/authorize/?app=[app_id]&hash=[control_hash]&redirect=[redirect_url]` - `app`: application ID that was created when the app was created - `redirect`: URL where to redirect the user after the login - `hash`: 32 symbol hash, MD5 function result from the application API key and the redirect URL (e.g. if the API key is `7c437d28be62b492151788f6c827afd6` and redirect URL IS `https://example.com/draugiem_auth/`, then the hash is created by calling `md5('7c437d28be62b492151788f6c827afd6https://example.com/draugiem_auth/')` ). ### 1.3. Acquiring authorization code After the login, user will be redirected to the URL that was given in the `redirect` parameter, with GET variable `dr_auth_status` added. If the value of `dr_auth_status` is `failed`, user has denied the application to access his data. If its value is `ok`, then the authorization has been successful and another GET parameter `dr_auth_code` is added - it is authorization code that the application can use to obtain user's API key that is required for further use of the API. When the application has received `dr_auth_code` value, it an finalize the authentication process and acquire user's API key, by performing API request `authorize` (described in the section User authentication). **Some suggestions for developers** - After authorization, user profile data should be kept within the session instead of requesting them repeatedly in every request. - If user data are displayed in many places in the page, they should be cached on application's side to prevent unnecessary load both on draugiem.lv and application's servers. - If your application uses PHP, it is best to use our provided [PHP library](https://draugiem.eu/applications/dev/php_en/) for the integration of draugiem.lv Passport. - Passport login window has to be opened so that the address bar is visible and the user can confirm that he is entering is pasword in a web page that belongs to draugiem.lv. - After user login, the page has to display user name that has entered the page and provide an option to log out. - For login buttons, it is recommended to use one of our [draugiem.lv Passport logos](https://draugiem.eu/development/passport_logos.zip) - If you need to contact us, please write email to [api@draugiem.lv](mailto:api@draugiem.lv), - Ensure that nobody can access your application's API key. - To increase security, you can add IP limit to your servers in the application settings. Never perform API requests from the client side (Javascript or Flash) - that wil make your API key exposed to everyone. ## 2. How to use draugiem.lv API ### 2.1. API requests To acquire data or perform other actions with draugiem.lv API, application server has to perform HTTP POST or GET requests to draugiem.lv server, providing necessary request parameters according to API specification. Parameters can be passed as HTTP GET, POST or COOKIE variables (however, POST is recommended). API request URL depends on chosen data format. Draugiem.lv API provides following formats: | Format | Description | API address | | --- | --- | --- | | **XML** | API response will be encoded in in XML format | | | **PHP** | API response will be encoded in PHP serialized data format | | | **JSON** | API response will be encoded in JSON format | | | **PLIST** | API response will be encoded in Apple Property List XML format | | Examples provided by this documentation will show API responses in XML format. Our provided *PHP library * uses PHP serialized format. API request always must contain parameter `action` that contains required API action, and parameter `app` that contains the API key of the application (API key is created when you create the application and it is used to identify the application that performs API requests). Almost always API request will contain parameter `apikey`, that identifies draugiem.lv user that has authorized the application. **Example:** To obtain basic profile info in XML format (application API key - `52967e99b3c11a755e7635901c23c0cf`, user API key - `208d970441dd5f3e87b965fedabd0738`), you have to perform this request: `https://api.draugiem.lv/xml/?app=52967e99b3c11a755e7635901c23c0cf&apikey=208d970441dd5f3e87b965fedabd0738&action=userdata` According to this request, server will respond with data structure in chosen format: ```xml Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M ``` ### 2.2. Error codes If application has performed invalid API request or any other error has occured, API response will contain error code and description. **XML example:** ```xml Access denied ``` **PHP serialized format example:** ``` a:1:{s:5:"error";a:2:{s:11:"description";s:13:"Access denied";s:4:"code";i:150;}} ``` **JSON example:** ```json {"error":{"description":"Access denied","code":150}} ``` **Possible error codes:** | Code | Error description | Explanation | | --- | --- | --- | | 10 | Internal error | API internal error | | 20 | Service not available | API is temporarily unavailable | | 80 | Bad request | Error in request parameters | | 90 | Invalid action | Invalid value of `action` parameter | | 101 | Invalid user API key | Invalid value of `apikey` parameter (user API key) | | 103 | Invalid application API key | Invalid value of `app` parameter (application API key) | | 104 | IP address not allowed | API request was performed from address that is not within allowed addreses in application settings | | 105 | Max API request limit in 10 minutes reached | Application has reached max request limit in 10 minutes per user. | | 106 | Invalid or unapproved auth code | `code` parameter that was used in `authorize` request was invalid or already used. | | 107 | Max activity limit for this user today reached | Max activity or notification count for this user per day has been reached | | 120 | Data not found | Requested data not found | | 130 | Spam/Flood detected | Too frequent sending of data (activities/notifications) | | 150 | Access denied | Application does not have access to the requested data. | ### 2.3. User data If API request requests information related with user data, API answer will contain block `users` with basic profile information of users. Every user element contains attribute `uid` that uniquely identifies draugiem.lv user and can be used to create relations between user and other objects. **XML example:** ```xml ... Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M ... ``` **PHP example:** ``` 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";}}} ``` **JSON example:** ```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"}}} ``` Every user data item contins these values: - `name`: First name - `surname`: Last name - `age`: age (empty, if user wants to hide his age) - `adult`: indicates if user has reached age 18 (1 - adult, 0 - not adult). Allows to check if user is adult even if he wants to hide his age. - `img`: Profile image URL (100x100px). Empty if user has no image. - `sex`: gender (M - male, F - female) To get user profile image in different sizes, simply replace in URL part `sm_` with another prefix: - `i_`: 50x50px icon - `sm_`: 100x100px icon - `m_`: 215px wide image - `l_`: large image (max. 710x710px) **Example:** If profile image URL is `https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg`, then URL of middle sized version of this image will be `https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg`. ### 2.4. Notifications about deleted users If you fill field *Delete status callback URL* with your URL in application settings, draugiem.lv will notify you about users that have deleted themself from your application or deleted their profile entirely. That allows you to remove user information from you database or perform other actions that are necessary to perform if user ceases to use the application. Our server will call your URL with these parameters added: - `status`: value `delete` - `uid`: User ID of deleted user - `app`: Application ID **Example:** Application with ID 1234 has configured address `https://example.com/delete_profile/` as delete callback URL. When user with ID 12345 deletes from application, draugiem.lv server will call URL `https://example.com/delete_profile/?status=delete&uid=12345&app=123` Response to this request must contain only text `OK`, otherwise draugiem.lv system will try to resend status report. ## 3. Available API requests ### 3.1. User authentication process (request authorize) Request allows application to acquire user's API key that is neccessary to perform other API requests on behalf of the user. The request also returns user's basic profile information so that no additional requests are needed to get this data. **Request parameters:** - `action`: `authorize` - `app`: application API key (32 characters) - `code`: `dr_auth_code` value that was received as GET variable after user login (for draugiem.lv Passport applications) or when the iframe was opened (for integrated applications) **Response will contain these parameters:** - `apikey`: user's API key - `uid`: user ID - `language`: 2 letter code of the language that the user has selected in draugiem.lv - `inviter`: user ID of the person who has invited this user to the application (this element is present only when user opens application for the first time after accepting invitation) - `invite_extra`: extra data that were attached to the accepted invitation by the application (this element is present only when user opens application for the first time after accepting invitation) User's API key allows application to access user's data via API wthout repeating authorization. After authorization application will be added to the *My Applications* section of the user's profile. From there user will be able to discontinue application's permission to access his data. Response also contains user's profile information according to the format described in section User data. **Example response:** ```xml 09797abfe8e5ea53fd857cc372e3a6f5 491171 lv Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M ``` To be able to access user's data again, application has to store the `apikey` value and use it in all further API requests. If application has lost user's API key or if the user has deleted if from the profile, authorization process can be repeated. User's API key can change if the user change his password or deletes application from the profile and joins repeatedly. ### 3.2. Getting user data of specific users (request userdata) This request allows to get basic profile information of specific draugiem.lv users who have authorized the application. This request doesn't require user's API key, just the application's key. **Request parameters:** - `action`: `userdata` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters), optional, if `ids` parameter is provided - `ids`: optional, comma separated list of draugiem.lv user IDs (max 100 IDs per request) If request contains parameter `ids`, response will contain profile information of requested users according to format described in section User data. Only information about users that are registered in application will be returned (if the user has deleted from the application, data will not be available anymore) If `ids` parameter is not given, then API will return information about user who owns the API key passed in `apikey` parameter according to format described in section User data. The order of returned user data is not strictly defined. **Example response:** ```xml Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg User_Default M Elīna Ozoliņa 25 1 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg User_Business F ``` In case of using Draugiem.lv passport, the user data may also contain official draugiem.lv pages ( www.draugiem.lv/lapas ) data instead of the regular user data. To determine if this is a regular user or page, you need to check the value in the `type` parameter. Currently 2 values are possible: - User_Default - ordinary user - User_Business - business page ### 3.3. Getting list of application users (request app_users) Request allows to get a list of all users that use the application. This request doesn't require user's API key, just the application's key. **Request parameters:** - `action`: `app_users` - `app`: application API key (32 characters) - `show`: optional, if this parameter is given with value `ids`, only list of user IDs will be returned instead of full profile data. - `page`: optional, number of the page that needs to be returned. By default, first page will be returned. - `limit`: optional, number of users per page (allowed range 1-200). By default one page contains 20 users. If request does not contain parameter `show` with value `ids`, response will contain element `users`, filled with information according to format described in section User data. Element `users` will have an attribute `total` that contains total number of users. **Example response (show=ids is not given):** ```xml Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M Elīna Ozoliņa 25 1 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg F ``` If request contains parameter `show` with value `ids`, response will contain element `userids`, that will hold a list of draugiem.lv user IDs. Element `users` will have an attribute `total` that contains total number of users. **Example response (show=ids is given):** ```xml 64428 491171 1524905 134564 234561 ``` ### 3.4. Getting number of application users (request app_users_count) Request allows to get count of currently registered users in the application. **Request parameters:** - `action`: `app_users_count` - `app`: application API key (32 characters) Response contains element `usercount`, that contains the number of users that have authorized the application. **Example response:** ```xml 312 ``` ### 3.5. Getting list of user's friends that use the application (request app_friends) Request allows to get information about user's friends that use the application. **Request parameters:** - `action`: `app_friends` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) - `show`: optional, if this parameter is given with value `ids`, only list of user IDs will be returned instead of full profile data. - `page`: optional, number of the page that needs to be returned. By default, first page will be returned. - `limit`: optional, number of users per page (allowed range 1-200). By default one page contains 20 users. If request does not contain parameter `show` with value `ids`, response will contain element `users`, filled with information according to format described in section User data. Element `users` will have an attribute `total` that contains total number of friends. **Example response (show=ids is not given):** ```xml Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M Elīna Ozoliņa 25 0 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg F ``` If request contains parameter `show` with value `ids`, response will contain element `userids`, that will hold a list of draugiem.lv user IDs. Element `users` will have an attribute `total` that contains total number of friends. **Example response (show=ids is given):** ```xml 64428 491171 1524905 134564 234561 ``` ### 3.6. Getting number of user's friends that use the application (request app_friends_count) Request allows to get the number of active user's friends that also use the application. **Request parameters:** - `action`: `app_friends_count` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) Response contains element `friendcount`, that contains the number of user's friends that have authorized the application. **Example response:** ```xml 16 ``` ### 3.7. Getting friendship status between two users (request check_friendship) Request allows to check if two application users are friends. **Request parameters:** - `action`: `check_friendship` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters), optional, if `uid2` parameter is provided - `uid`: user ID of the first user - `uid2`: user ID of the second user. Optional if `apikey` value is given. - If both `uid` and `uid2` values are given, friendship status among these two users will be returned. - If `uid2` balue is not given, but `apikey` value is provided, friendship status between API key owner and user `uid` will be returned. - Response contains element `status`, that has value `OK` if there is a friendship between these two users. - If there is no friendship, `status` value will be `NOT_FRIENDS`. - If any of provided users is not registered application's user, `status` value will be `NOT_USERS`. **Example response:** ```xml OK ``` ### 3.8. Posting entries to user's profile activity feed (request add_activity) Request allows to add entry with a link to user's profile activity feed (entry will be visible to all of his friends) **This feature is not enabled by default. To get permission for your application to post items to activity feed, contact api@draugiem.lv and tell us about your application and what kind of activities it will create.** Integrated applications during the development phase are allowed to post activities in test mode (they will be visible only to the developers). To continue posting activities after publishing, they have to be enabled by draugiem.lv staff. Activity link must point to the same domain that is configured as application URL in application settings. Application's icon will be shown next to the created entry. Only one activity per day can be created for each user. ![img/events.png](https://draugiem.eu/applications/img/events.png) Activities must comply with these principles: - Activity informs about actual user's action in the application. - Activity system can't be used for advertising. - Before starting to add new types of activities, it is highly recommended to consult with us before. - For integrated applications activity URL has to contain address that will be displayed in the iframe, not the application address in draugiem.lv - it will automatically converted to internal address. Address opened in iframe can contain directory path and GET variables, but might not work if it contains file name with common extensions (php/css/jpg etc.) will not work If application will create activities that do not follow the rules, we can deny application to post new activities. **Request parameters:** - `action`: `add_activity` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) - `prefix`: optional, text that will be displayed before the clickable link. Max length 50 characters. - `text`: text of clickable activity link. Max length 100 characters. - `link`: optional, URL, where the activity link will point to. If not given, link will point to application start page. URL domain must be the same as given in the application settings. Max length 100 characters. - If activity was successfuly created, response will contain element `status` with value `OK`. - - **If application has no permission to post activities or if the user has blocked activities from this application,**: API will respond with error `150 (Access denied)`. - If daily activity limit for user has been reached, API will respond with error `107 (Max activity limit for this user today reached)` **Example response:** ```xml OK ``` ### 3.9. Posting notifications to user's profile news feed (request add_notification) Request allows to add notification with a link to user's profile news feed (it will be visible only to the user) **This feature is not enabled by default. To get permission for your application to post inotifications, contact api@draugiem.lv and tell us about your application and what kind of notifications it will create.** Integrated applications during the development phase are allowed to post notifications in test mode (they will be visible only to the developers). To continue posting notifications after publishing, they have to be enabled by draugiem.lv staff. Notification link must point to the same domain that is configured as application URL in application settings. Application's icon will be shown next to the created entry. Application can create up to 5 notifications per day for every user, no sooner than an hour after previous one. ![img/profileNews.png](https://draugiem.eu/applications/img/profileNews.png) Notifications must comply with these principles: - Notification informs about something that has happened with user's profile in the application. It is recommended that the notification link goes to a specific place in the application if it is possible. - Notifications can't be used to advertise application with no reason. - Before starting to add new types of notifications, it is highly recommended to consult with us before. - For integrated applications notification URL has to contain address that will be displayed in the iframe, not the application address in draugiem.lv - it will automatically converted to internal address. Address opened in iframe can contain directory path and GET variables, but might not work if it contains file name with common extensions (php/css/jpg etc. will not work) If application will create notifications that do not follow the rules, we can deny application to post new notifications. It is possible to show both notifications that come from a specific user or notifications that are displayed as created by the application. **Important:** Remember that notification is displayed to user that owns the API key that is used in request.So in order to send notification to user that currently is not online, application has to store user's API key for offline use. **Request parameters:** - `prefix`: optional, text that will be displayed before the clickable link. Max length 50 characters. - `text`: text of clickable activity link. Max length 100 characters. - `link`: optional, URL, where the activity link will point to. If not given, link will point to application start page. URL domain must be the same as given in the application settings. Max length 100 characters. - `action`: `add_notification` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) - `prefix`: optional, text that will be displayed before the clickable link. Max length 50 characters. - `text`: text of clickable notification link. Max length 100 characters. - `link`: optional, URL, where the notification link will point to. If not given, link will point to application start page. URL domain must be the same as given in the application settings. Max length 100 characters. - `creator`: Optional, Draugiem.lv user ID that will be displayed as sender of the notification (user ID has to belong to a registrated user of the application; if this parameter is not given, application name will be displayed as the sender of the notification) - If notification was successfuly created, response will contain element `status` with value `OK`. - - **If application has no permission to post notifications or if the user has blocked notifications from this application,**: API will respond with error `150 (Access denied)`. - If daily notification limit for user has been reached, API will respond with error `107 (Max activity limit for this user today reached)` - If there is less then an hour since last added notification, request will return error `130 (Spam/Flood detected)` **Example response:** ```xml OK ``` ### 3.10. Getting application status information (request app_status) Request allows to get statistical information about application's status. **Request parameters:** - `action`: `app_status` - `app`: application API key (32 characters) Response will contain these information fields: - `users`: Total number of users registered in application - `users24h`: Number of users that have used application during last 24 hours (updated once every hour) - `online`: Number of online users in the application during the last 5 minutes - `api_rq`: Number of application's API requests per second (average value during the last 20 seconds) - `activities`: Number of profile activities posted during the last minute - `notifications`: Number of profile news notifications posted during the last minute **Example response:** ```xml 159552 42872 1340 33.25 15 8 ``` ### 3.11. Adding an entry in calendar Request allows you to add an entry (note) in calendar. **Request parameters:** - `action`: `calendar/add` - `app`: application API key (32 characters) - `apikey`: user API key (32 characters) - `text`: text of your note - `start_time`: start time (numerical value - *timestamp*) - `end_time`: end time (numerical value - *timestamp*) - `allday`: event is actual all day. Not mandatory. Allowed values - *1*, *0* - `repeat`: repeating frequency of your note. Not mandatory. Allowed values - *daily*, *workdays*, *weekly*, *monthly*, *yearly* **Example response after successfully added note:** ```xml OK ``` ## 4. Draugiem.lv API PHP library To make application development faster and easier, we've created a PHP library that performs API calls and automatically converts the requested data to the PHP data structures. PHP library can be used both for integrated applications and draugiem.lv Passport applications. [PHP library documentation](https://draugiem.eu/applications/dev/php_en/) [Draugiem.lv PHP library and examples](https://github.com/Draugiem/draugiem-php-sdk) --- # Draugiem.lv API PHP library ## 1. Introduction To make application development faster and easier, we've created a PHP library that performs API calls and automatically converts the requested data to the PHP data structures. PHP library can be used both for integrated applications and draugiem.lv Passport applications. The library requires PHP5 environment and uses PHP session mechanism for storing user data during sessions. To be able to perform API calls, PHP configuration you have to enable access to HTTP URLs for `file_get_contents` function (enable `allow_url_fopen` setting in PHP configuration). [Draugiem.lv API PHP library and examples](https://github.com/Draugiem/draugiem-php-sdk) In order to use PHP library, you have to include file `DraugiemApi.php` in your application. ## 2. User data representation in PHP library PHP library functions return user data as a PHP array, which is structured as follows: ``` array ( 'uid' => 491171, //Draugiem.lv user ID 'name' => 'Jānis', //First name 'surname' => 'Bērziņš', //Last name 'age' => 26, //Age (or false, if user is hiding his age) 'adult' => true,//true, if the user is older than 18 years old. (Even if the age is hidden) //user profile picture URl or false if there is no picture uploaded 'img' => 'https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg', 'sex' => 'M', //gender - M-male, F-female ) ``` If the function returns information for multiple users (eg, friends list), then the data is returned as array of user data arrays, where each element key is the user ID. If information about only one user is requested, then the data is returned as a single user data structure. ## 3. Session handling API library uses PHP sessions to store session information for active user. To start using library, create `DraugiemApi` class instance by passing application ID and API key to constructor. After this, call `getSession` method, that authenticates the user and acquires user profile information via draugiem.lv API. For integrated (iframe) applications this method also checks if user session is still active (so the application does not need to perform additional `session_check` requests). For draugiem.lv Passport applications `getSession` method just authenticates user and acquires data, however local session is not connected with user's session in draugiem.lv. If method returns `true`, session creation has been successful and user has accessed the application.: ```php getSession()){ //Authentication successful //Application can now access user data via API $user = $draugiem->getUserData();//Basic profile info //Print a greeting if($user['img']){ echo '
'; } echo 'Hi, '.$user['name'].' '.$user['surname'].'!
'; $uid = $draugiem->getUserId(); //Get active user's ID $count = $draugiem->getFriendCount();//Get number of user's friends in the application echo 'This application is also used by '.$count.' of your friends.'; } else { echo 'Authorization failed'; //Session creation failed //User has been logged out of draugiem.lv or //API authorization request has failed //Draugiem.lv Passport applications should display passport login //button in such situations. } ``` ## 4. Accessing user data outside the session If you need to perform API requests for user that currently is not using the application (e.g. to display a notification in user's profile), you need to create a new API class instance and pass user's API key as third parameter to the constructor. This object will be able to call the same API functions as object that has used normal authentication.: ```php $draugiem2 = new DraugiemApi($app_id, $app_key, $user_key); $draugiem2 -> addNotification('You got a new message'); ``` You can get active user's API key by calling method `getUserKey` after the session has been created by using `getSession` method. In order to use the API key while the user is not online, application has to store the API key. User API key will never change, except when the user deletes application from his profile or changes his draugiem.lv password. To ensure that application always has the right key available, after creation of session application should check if the key has not changed and store the new key if necessary. ## 5. API library methods ### 5.1. addActivity($text, $prefix, $link) Adds entry to user's activity feed in format `{$prefix} {text}`. Application's icon will be shown next to the created entry. For this method to work, application needs to have permission to post activities. Only one activity per day can be created for each user. - **`$text`**: Clickable text of the link (max 100 characters) - **`$prefix`**: Text that will be displayed before the link (optional, max 50 characters) - **`$link`**: Target URL of the link (optional, max 100 characters, if not given, the link will lead to the start page of application) For integrated applications link has to contain address that needs to be displayed in the iframe instead of application's address in draugiem.lv. - **Return value**: `true` if the activity was created, `false` on failure. ### 5.2. addNotification($text, $prefix, $link, $creator) Adds notification to user's profile news in format `{$prefix} {text}`. Application's icon will be shown next to the created entry. For this method to work, application needs to have permission to post notifications. Fore each user application can create up to 4 notifications per day, no sooner than an hour after previous notification. - **`$text`**: Clickable text of the link (max 100 characters) - **`$prefix`**: Text that will be displayed before the link (optional, max 50 characters) - **`$link`**: Target URL of the link (optional, max 100 characters, if not given, the link will lead to the start page of application) For integrated applications link has to contain address that needs to be displayed in the iframe instead of application's address in draugiem.lv. - **`$creator`**: Draugiem.lv user ID that will be displayed as sender of the notification (optional; user ID has to belong to a registrated user of the application; if this parameter is not given, application name will be displayed as sender of the notification) - **Return value**: `true` if the notification was created, `false` on failure. ### 5.3. apiCall($action, $args, $method = 'GET') Performs draugiem.lv API call and returns response as PHP array. Typically this method is used by other metods of the library so direct calling of this method is necessary only for API calls that do not have their own methods defined. Default REQUEST method is 'GET', but if you need, you can change it to 'POST'. - **`$action`**: API method name (*action* parameter value of the API request) - **`$args`**: Associative array with API call parameters and their corresponding values (array does not need to contain *action*, *app* and *apikey* parameters that are added automatically) - **`$method`**: API request type. By default it is set to 'GET', but you can change it to 'POST'; - **Return value**: Method returns PHP array with response data or `false`, if the request has failed or an API error has been returned. ### 5.4. checkFriendship($uid, $uid2) Checks if two users of the application are friends. - **`$uid`**: User ID of the first user - **`$uid2`**: User ID of the second user (optional, if not given, friendship between `$uid` and active user will be checked) - **Return value**: `true` if users are friends, `false` if the request has failed, users are not friends or any of the users is not a valid user of the application. ### 5.5. cookieFix() Tries to execute a workaround for cookie creation restrictions in *Internet Explorer* and *Safari* browsers. This method has to be called in the beginning of the code, before `getSession()`. Method automatically detects, which browser the user is using so there is no need to check the browser before calling this method. There is no return value and the method does not need to require additional parameters. This method is needed only for integrated applications that use *iframe*. ### 5.6. getAppUsers ($page, $limit, $return_ids) Gets a page with application users (newly joined users will be at the beginning of the list). It is possible to return either just user IDs or full profile information. - **`$page`**: Page number that needs to be returned (numbering starts with 1) - **`$limit`**: Number of users per page (max 200) - **`$return_ids`**: `true`, if only user IDs are needed, `false` (default value), if full profile data needs to be returned. - **Return value**: Array of user IDs/profile data or `false` if the request has failed. ### 5.7. getFriendCount() Gets number of user's friends among application users. Returns count or `false` if the request has failed. ### 5.8. getInviteInfo() Gets information about invitation that the user has accepted when started to use application. Works only during the first session of a new user. Method has to be called after `getSession` has been called. If information about invitation is present, method returns this data: ``` array( 'inviter' => 123, //User ID that has invited the current user 'extra' => '' //Extra data to identify the invitation (if provided by application when the invitation was sent) ) ``` If invitation data is not found, method returns `false` ### 5.9. getJavascript($resize_container, $callback_html) Returns HTML code that needs to be output in page to enable access to draugiem.lv Javascript API. This feature works only for integrated applications. Method has to be called after `getSession` has been called, and returned code should be placed in the `` section of the page. - **`$resize_container`**: DOM element ID, that has to be used to detect page height for automatic resizing of the iframe. If not given, no automatic resizing will be performed. - **`$callback_html`**: URL of [callback.html](https://draugiem.eu/applications/external/callback.html) file instance on application's server, with full domain path. This parameter is required only if you need to receive return values from Javascript calls. - **Return value**: HTML code, that needs to be placed in the page. ### 5.10. getLoginButton($redirect_url, $popup) Returns HTML code that allows to display draugiem.lv Passport login button. This feature is needed only for draugiem.lv Passport applications. - **`$redirect_url`**: URL where the user needs to be redirected after the login. - **`$popup`**: Whether the login window needs to be opened in a popup window. (`true` - yes, `false` - no) - **Return value**: HTML code, that has to be placed in the page. ### 5.11. getLoginUrl($redirect_url) Returns URL of draugiem.lv Passport login window with a specified redirect URL. - **`$redirect_url`**: URL where to redirect the user after login - **Return value**: Draugiem.lv Passport login URL ### 5.12. getSession() Authenticates the user and gets basic profile information. **This method always has to be called before other methods**, except cases when PHP library is used to work with person that is not currently online. Uses PHP built-in session system. For integrated applications this method periodically checks if the user is still logged in draugiem.lv by calling `session_check` API call. - **Return value**: `true`, if authentication is successful, `false`, if authentication has failed or user's draugiem.lv session has ended. ### 5.13. getSessionDomain() Gets draugiem.lv domain name from which the user is accessing the application. This method works only for integreated applications. Applications sometimes need to know the active domain, e.g. to correctly display links to user profiles. Typically domain name will be `www.draugiem.lv`, but sometimes it can be different, e.g. when the user uses international versions of draugiem.lv. ### 5.14. getUserCount() Returns number of currently registered users in the application. Returns number or `false` if the request has failed. ### 5.15. getUserData($ids) Returns profile information for specified users. - **`$ids`**: Indicates which user data needs to be returned. If this value contains an array of user IDs (max 100 values), API will return an array of user data arrays (only for users that are registered application users). If this value contains a single user ID, a single user data array will be returned (or `false` if information is not available). If this parameter is left empty, function will return information about currently logged in user. ### 5.16. getUserFriends($page, $limit, $return_ids) Gets a page with friends of currently logged in user that also use the application. It is possible to return either just user IDs or full profile information. - **`$page`**: Page number that needs to be returned (numbering starts with 1) - **`$limit`**: Number of friends per page (max 200) - **`$return_ids`**: `true`, if only user IDs are needed, `false` (default value), if full profile data needs to be returned. - **Return value**: Array of user IDs/profile data or `false` if the request has failed. ### 5.17. getAllUserFriends($page, $limit, $return_ids) Gets a page with friends of currently logged in user. It is possible to return either just user IDs or full profile information. If current friend does not use the application we get information only about his name, surname, gender and profile image. - **`$page`**: Page number that needs to be returned (numbering starts with 1) - **`$limit`**: Number of friends per page (max 200) - **`$return_ids`**: `true`, if only user IDs are needed, `false` (default value), if full profile data needs to be returned. - **Return value**: Array of user IDs/profile data or `false` if the request has failed. ### 5.18. getOnlineFriends($limit, $in_app, $return_ids) Gets a page with friends of currently logged in user that also use the application and are currently logged in draugiem.lv. It is possible to return either just user IDs or full profile information. This function is available only for integrated applications while the user is online. - **`$limit`**: Number of friends to be returned (max 100) - **`$in_app`**: `true` to return only friends that are currently in the application, `false` to return friends that are currently in draugiem.lv and are registered application users. - **`$return_ids`**: `true`, if only user IDs are needed, `false` (default value), if full profile data needs to be returned. - **Return value**: Array of user IDs/profile data or `false` if the request has failed. ### 5.19. getUserId () Returns user ID of the active user or `false`, if it is not available. ### 5.20. getUserKey () Returns user API key of the active user or `false`, if it is not available. ### 5.21. getUserLanguage () Gets language setting of the active user (`lv/ru/en/de/hu/lt`). ### 5.22. imageForSize($img, $size) Returns user profile picture URL for specified size. - **`$img`**: Standard size profile image URL (address that has been returned by API) - **`$size`**: Required image size (`icon` - 50x50px / `small` - 100x100px / `medium` - 215px wide / `large` - 710px wide) - **Return value**: Profile picture URL for specified size --- # Draugiem.lv recommend widgets ## Recommend button with recommendation count Draugiem recommend button is a solution you can easily integrate into your website to allow your users share content on draugiem.lv social network. In order to add the recommend button to your site, use this code: ```xml ``` Please replace these arguments in urlencoded form: - **`title`**: The title of the link to display in the Runā stream - **`url`**: The URL to recommend - **`titlePrefix`**: Optional argument, which will be shown in orange bold color before the clickable link (if you omit this argument, the domain name of the url argument will be used) The button will be displayed as follows: ![img/say_like.png](https://draugiem.eu/applications/img/say_like.png) ## List of news recommended by other users If you own a website (most likely a news portal) where users can share multiple articles, you can use a widget that lists news stories recommended by other users. In order to insert the widget use this code: ```xml ``` In the code please insert the arguments in an urlencoded form: - **`url`**: Website address (ommiting this argument will use the HTTP referer as the base url) - **`count`**: Number of articles to show. (2-15) - **`scrollable`**: Optional argument. Whether the content should be scrollable or not. Works together with the height argument. If the inner height exceeds the defined height a scrollbar will appear. You can disable it using this argument. - **`height`**: Optional argument. Defines the height of the block. In case you omit the argument content will be resized automatically. If you wish to show images near the article titles, you should add a couple of meta tags to the article content. The image dimensions are 50x50. In case you don't have an image for the article, please pass the logo of your site. Meta tags to add: ```xml ``` The widget will look like this: ![img/say_box.png](https://draugiem.eu/applications/img/say_box.png) ## Simple recommendation function In order to allow your page users to recommend the content of your page you can add this simple JavaScript function to your code and call it with the arguments of your choice: ``` function DraugiemSay( title, url, titlePrefix ){ window.open( 'https://www.draugiem.lv/say/ext/add.php?title=' + encodeURIComponent( title ) + '&link=' + encodeURIComponent( url ) + ( titlePrefix ? '&titlePrefix=' + encodeURIComponent( titlePrefix ) : '' ), '', 'location=1,status=1,scrollbars=0,resizable=0,width=530,height=400' ); return false; } ``` Example usage: ``` DraugiemSay('Link title text', 'https://www.full.site.domain/and/path/to/file.html', 'Red colored Prefix'); ``` We would highly recommend to use this icon: ![/i/icons/ieteikt.png](https://draugiem.eu/i/icons/ieteikt.png) The result will be something like you can see in the picture below: ![img/picture-12.png](https://draugiem.eu/applications/img/picture-12.png) You can also get a Draugiem recommendation button by using www.addthis.com service ## Draugiem recommendation JavaScript bookmarklet If some page you would like to recommend does not have a Draugiem recommendation button, you can use this JavaScript bookmarklet to recommend the site: ```html Recommend to friends ``` The bookmarklet works very simple - if the page has higlhlighted text, it will be used as title text (if there's no text selected page title will be used), the currently opened page will be used as link and the domain name part will be used as the title prefix. --- # 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ā | | | **PHP** | atbildes uz API pieprasījumiem tiek pārsūtītas PHP serializēto datu formātā | | | **JSON** | atbildes uz API pieprasījumiem tiek pārsūtītas JSON datu formātā | | | **PLIST** | atbildes uz API pieprasījumiem tiek pārsūtītas Apple Property List XML datu formātā | | 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 Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M ``` ### 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 Access denied ``` **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 ... Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M ... ``` **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 09797abfe8e5ea53fd857cc372e3a6f5 491171 lv Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M ``` 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 Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg User_Default M Elīna Ozoliņa 25 1 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg User_Business F ``` 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 Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M Elīna Ozoliņa 25 1 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg F ``` 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 64428 491171 1524905 134564 234561 ``` ### 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 312 ``` ### 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 Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M Elīna Ozoliņa 25 0 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg F ``` 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 64428 491171 1524905 134564 234561 ``` ### 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 16 ``` ### 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 Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M 1 Elīna Ozoliņa 16 0 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg F ``` 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 64428 491171 1524905 134564 234561 ``` ### 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 2 Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M 1 Elīna Ozoliņa 16 0 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg F ``` 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 2 491171 64428 ``` ### 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 OK ``` ### 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 OK ``` ### 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 OK ``` ### 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 OK ``` ### 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 159552 42872 1340 33.25 15 8 ``` ### 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 12345 1290899622 1303814320 0 .. ``` ### 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 12345 1290899622 1303814320 0 .. ``` ## 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 ``` Šā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 ``` 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 ``` **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 ``` 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
test
``` 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 ``` 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 ``` ### 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 ``` ### 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 ``` 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 ``` **Š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 ``` 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 ``` 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 . 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 1935 https://www.draugiem.lv/services/iframe.php?id=1935 ``` 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 OK ``` --- # Draugiem.lv Passport API documentation ## 1. Draugiem.lv pase ### 1.1. Ievads Draugiem.lv pase sniedz iespēju ar draugiem.lv nesaistītās tīmekļa lapās ieviest funkcijas, kas izmanto draugiem.lv lietotāju informāciju. Tādā veidā dažādi draugiem.lv neizstrādāti projekti var piekļūt savu lietotāju savstarpējām draudzības saitēm un piedāvāt uz tām balstītu funkcionalitāti. Draugiem.lv pasi var izmantot dažādi. Tā var pilnībā aizstāt mājas lapas reģistrācijas un pieteikšanās sistēmu, ļaujot katram draugiem.lv lietotājam sākt izmantot lapas iespējas, neveicot nekādu reģistrāciju. Ja lapai jau eksistē reģistrācijas sistēma, tad draugiem.lv pase var tikt izmantota lai piesaistītu lietotāja draugiem.lv profilu jau eksistējošam ārējās lapas lietotāja kontam. Pirmo reizi ienākot lapā ar draugiem.lv pasi, lietotājs piekrīt nodot savu profila informāciju trešās puses izstrādātājiem. 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). Ja lietotājs pēc kāda laika vēlas pārtraukt lapas piekļuvi saviem datiem, 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. ### 1.2. Draugiem.lv pases pieteikšanās loga atvēršana Lai lietotājs varētu pieteikties lapā, izmantojot draugiem.lv pasi, tajā jāievieto poga vai saite, kas atver draugiem.lv pases pieteikšanās lapu. Noklikšķinot uz šīs saites, tiks atvērta lapa vai logs, kurā: 1. lietotājam piedāvā ievadīt draugiem.lv reģistrācijas datus, ja lietotājs tobrīd nav ienācis draugiem.lv, 2. redzams lietotāja vārds, uzvārds, attēls un poga *Atļaut* - ja lietotājs tobrīd ir ienācis draugiem.lv ![img/pase1.png](https://draugiem.eu/applications/img/pase1.png) Autorizācijas lapas saites adrese veidojas šādā formā: `https://api.draugiem.lv/authorize/?app=[aplikācijas_id]&hash=[kontroles_kods]&redirect=[pāradresācijas_adrese]` - `app`: aplikācijas id, kas redzams draugiem.lv izveidotās aplikācijas uzstādījumos - `redirect`: adrese, uz kuru jāpārsūta lietotājs pēc pieteikšanās - `hash`: 32 simbolu kods, MD5 funkcijas rezultāts no aplikācijas API atslēgas un pāradresācijas adreses apvienojuma (piemēram, ja aplikācijas API atslēga ir `7c437d28be62b492151788f6c827afd6` un adrese, uz kuru jāveic pāradresācija, ir `https://example.com/draugiem_auth/`, tad kontroles kods ir iegūstams, izsaucot `md5('7c437d28be62b492151788f6c827afd6https://example.com/draugiem_auth/')` ). ### 1.3. Autorizācijas koda iegūšana Pēc pieteikšanās lietotājs tiks pāradresēts uz lapu, kuras adrese tika norādīta parametrā `redirect`, pievienojot tai galā GET parametru `dr_auth_status`. Ja `dr_auth_status` vērtība ir `failed`, lietotājs nav ļāvis aplikācijai piekļūt viņa datiem. Ja šī parametra vērtība ir `ok`, tad pieteikšanās ir bijusi veiksmīga, un adresei ir pievienots arī GET parametrs `dr_auth_code` - autorizācijas kods, ar kura palīdzību aplikācija var iegūt lietotāja API atslēgu, kas ir nepieciešama turpmākai API izmantošanai. Kad aplikācija ir saņēmusi `dr_auth_code` vērtību, tā var pabeigt pieteikšanās procesu un iegūt lietotāja API atslēgu, 20 minūšu laikā veicot API pieprasījumu `authorize` (sīkāks šī pieprasījuma apraksts atrodams nodaļā Lietotāja autorizācija). **Daži ieteikumi izstrādātājiem** Lai maksimāli pareizi un efektīgi izmantotu draugiem.lv pases iespējas, vēlams sekot šādiem principiem: - Pēc lietotāja autorizācijas iegūto informāciju par lietotāju vēlams glabāt sesijā, nevis pie katras lapas atvēršanas prasīt atkārtoti caur draugiem.lv API. - 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 draugiem.lv pasi ieviest, izmantojot mūsu sagatavoto [PHP koda bibliotēku](https://draugiem.eu/applications/dev/docs/php/). - Pases pieteikšanās logs jāatver tā, lai būtu redzams adreses lauks, un lietotājs varētu pārliecināties, ka ievada savu paroli lapā, kas atrodas zem draugiem.lv domēna. - Pēc lietotāja pieteikšanās lapā jābūt redzamai informācijai par to, kurš lietotājs ir ienācis lapā, kā arī iespējai iziet no lapas (pārtraukt lietotāja sesiju). - Ja vēlaties, lai jūsu lapa būtu redzama visiem draugiem.lv apmeklētājiem sadaļā *Aplikācijas*, vai arī vēlaties iegūt savai lapai tiesības pievienot informāciju draugiem.lv lietotāju profila aktivitātēs, rakstiet e-pastu uz [api@draugiem.lv](mailto:api@draugiem.lv) - Lai parādītu lietotājiem, ka lapā iespējams pieteikties ar draugiem.lv pasi, vēlams lietot kādu no mūsu piedāvātajiem [draugiem.lv pases logo](https://draugiem.eu/development/passport_logos.zip) - Nodrošiniet, lai neviens cits neuzzinātu Jūsu lapas 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. ## 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ā | | | **PHP** | atbildes uz API pieprasījumiem tiek pārsūtītas PHP serializēto datu formātā | | | **JSON** | atbildes uz API pieprasījumiem tiek pārsūtītas JSON datu formātā | | | **PLIST** | atbildes uz API pieprasījumiem tiek pārsūtītas Apple Property List XML datu formātā | | 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 Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M ``` ### 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 Access denied ``` **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 ... Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M ... ``` **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. Available API requests ### 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 09797abfe8e5ea53fd857cc372e3a6f5 491171 lv Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M ``` 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 Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg User_Default M Elīna Ozoliņa 25 1 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg User_Business F ``` 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 Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M Elīna Ozoliņa 25 1 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg F ``` 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 64428 491171 1524905 134564 234561 ``` ### 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 312 ``` ### 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 Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M Elīna Ozoliņa 25 0 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg F ``` 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 64428 491171 1524905 134564 234561 ``` ### 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 16 ``` ### 3.7. 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 OK ``` ### 3.8. 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 OK ``` ### 3.9. 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 OK ``` ### 3.10. 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 159552 42872 1340 33.25 15 8 ``` ## 4. 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) --- # Draugiem ID API dokumentācija ## 1. Draugiem ID ### 1.1. Ievads Draugiem.lv sadarbībā ar Vides aizsardzības un reģionālās attīstības ministriju un citiem partneriem ir radījuši pirmo sociālo tīklu verifikācijas risinājumu, kurā lietotājs pats var veikt sava profila verifikāciju jeb savas personības īstuma apstiprinājumu. Profilu var verificēt , izmantojot savu personas apliecību jeb elektronisko identifikācijas karti (eID karti), kurā aktivizēts elektroniskais paraksts. Ar verifikāciju iegūtā zaļā ikona pie profila garantē, ka personas vārds un uzvārds ir tāds pats kā eID kartē. Līdz ar verifikācijas ieviešanu radīts jauns bezmaksas risinājums – Draugiem ID, kas ir uz Draugiem.lv Pases bāzes veidota autorizācijas sistēma un autorizācijas internetbankā alternatīva, jo personas identitāte ir apliecināta ar eID karti. Ar Draugiem ID palīdzību tiek veidota uzticama vide interneta pakalpojumu sfērā. Tādā veidā arī projekti, kas nav izstrādāti tieši Draugiem.lv platformā, var uzrunāt savas mērķauditorijas un piedāvāt šo lietotāju interesēm atbilstošus pakalpojumus. Piemēram, lai, abonētu preses izdevumus, apgūtu mācību kursus tiešsaistē un saņemtu oficiālus sertifikātus, izmantotu lojalitātes programmas un citas e-pakalpojumu iespējas valsts un privātajā sektorā. Tā Draugiem.lv lietotāji palīdz veidot drošu un atklātu komunikāciju interneta vidē bez viltus profiliem, turklāt gan uzņēmumi, gan izstrādātāji var būt droši, ka sazinās vai sniedz pakalpojumus reālām personām. Lai izmantotu Draugiem ID aplikāciju, vispirms nepieciešams to publicēt. Lai to izdarītu, izstrādātājam aplikācijas admin rīkos jādodas uz sadaļu “Pieteikumi” un jāiesūta pieteikums par publicēšanu. ### 1.2. Draugiem ID pieteikšanās loga atvēršana Lai lietotājs varētu pieteikties lapā, izmantojot Draugiem ID aplikāciju, tajā jāievieto poga vai saite, kas atver Draugiem ID pieteikšanās lapu. Draugiem ID poga vizuāli izskatās šādi: ![img/draugiemid2.png](https://draugiem.eu/applications/img/draugiemid2.png) Noklikšķinot uz šīs saites, tiks atvērta lapa vai logs, kurā: 1. lietotājam piedāvā ievadīt draugiem.lv reģistrācijas datus, ja lietotājs tobrīd nav ienācis draugiem.lv, 2. redzams lietotāja vārds, uzvārds, attēls un poga *Ienākt* - ja lietotājs tobrīd ir ienācis draugiem.lv ![img/draugiemid1.png](https://draugiem.eu/applications/img/draugiemid1.png) Ja lietotājs nebūs verificējis savu profilu, viņam parādīsies paziņojums par to, ka vispirms jādodas uz verifikācijas sadaļu: ![img/draugiemid3.png](https://draugiem.eu/applications/img/draugiemid3.png) Autorizācijas lapas saites adrese veidojas šādā formā: `https://api.draugiem.lv/authorize/?app=[aplikācijas_id]&hash=[kontroles_kods]&redirect=[pāradresācijas_adrese]` - `app`: aplikācijas id, kas redzams draugiem.lv izveidotās aplikācijas uzstādījumos - `redirect`: adrese, uz kuru jāpārsūta lietotājs pēc pieteikšanās - `hash`: 32 simbolu kods, MD5 funkcijas rezultāts no aplikācijas API atslēgas un pāradresācijas adreses apvienojuma (piemēram, ja aplikācijas API atslēga ir `7c437d28be62b492151788f6c827afd6` un adrese, uz kuru jāveic pāradresācija, ir `https://example.com/draugiem_auth/`, tad kontroles kods ir iegūstams, izsaucot `md5('7c437d28be62b492151788f6c827afd6https://example.com/draugiem_auth/')` ). ### 1.3. Autorizācijas koda iegūšana Pēc pieteikšanās lietotājs tiks pāradresēts uz lapu, kuras adrese tika norādīta parametrā `redirect`, pievienojot tai galā GET parametru `dr_auth_status`. Ja `dr_auth_status` vērtība ir `failed`, lietotājs nav ļāvis aplikācijai piekļūt viņa datiem. Ja šī parametra vērtība ir `ok`, tad pieteikšanās ir bijusi veiksmīga, un adresei ir pievienots arī GET parametrs `dr_auth_code` - autorizācijas kods, ar kura palīdzību aplikācija var iegūt lietotāja API atslēgu, kas ir nepieciešama turpmākai API izmantošanai. Kad aplikācija ir saņēmusi `dr_auth_code` vērtību, tā var pabeigt pieteikšanās procesu un iegūt lietotāja API atslēgu, 20 minūšu laikā veicot API pieprasījumu `authorize` (sīkāks šī pieprasījuma apraksts atrodams nodaļā Lietotāja autorizācija). **Daži ieteikumi izstrādātājiem** Lai maksimāli pareizi un efektīgi izmantotu Draugiem ID aplikācijas iespējas, vēlams sekot šādiem principiem: - Pēc lietotāja autorizācijas iegūto informāciju par lietotāju vēlams glabāt sesijā, nevis pie katras lapas atvēršanas prasīt atkārtoti caur draugiem.lv API. - 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 Draugiem ID būs ieviest, izmantojot mūsu sagatavoto [PHP koda bibliotēku](https://draugiem.eu/applications/dev/docs/php/). - Aplikācijas pieteikšanās logs jāatver tā, lai būtu redzams adreses lauks, un lietotājs varētu pārliecināties, ka ievada savu paroli lapā, kas atrodas zem draugiem.lv domēna. - Pēc lietotāja pieteikšanās lapā jābūt redzamai informācijai par to, kurš lietotājs ir ienācis lapā, kā arī iespējai iziet no lapas (pārtraukt lietotāja sesiju). - Nodrošiniet, lai neviens cits neuzzinātu Jūsu lapas 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. ## 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ā | | | **PHP** | atbildes uz API pieprasījumiem tiek pārsūtītas PHP serializēto datu formātā | | | **JSON** | atbildes uz API pieprasījumiem tiek pārsūtītas JSON datu formātā | | | **PLIST** | atbildes uz API pieprasījumiem tiek pārsūtītas Apple Property List XML datu formātā | | 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 Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M 123456-12345 ``` ### 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 Access denied ``` **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 ... Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M 123456-12345 ... ``` **Paraugs PHP formātā:** ``` a:1:{s:5:"users";a:1:{i:3342174;a:10:{s:3:"uid";i:3342174;s:4:"name";s:6:"Jānis";s:7:"surname";s:10:"Bērziņš";s:3:"age";i:21;s:5:"adult";i:1;s:3:"img";s:53:"https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg";s:4:"imgi";s:52:"https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg";s:4:"imgm";s:52:"https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg";s:4:"imgl";s:52:"https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg";s:3:"sex";s:1:"M";b:0;s:2:"pk";s:12:"123456-12345";}}} ``` **Paraugs JSON formātā:** ```json {"users":{"3342174":{"uid":3342174,"name":"J\u0101nis","surname":"B\u0113rzi\u0146\u0161","age":21,"adult":1,"img":"https:\/\/i1.ifrype.com\/profile\/491\/171\/v3\/sm_491171.jpg","imgi":"https:\/\/i1.ifrype.com\/profile\/491\/171\/v3\/i_491171.jpg","imgm":"https:\/\/i1.ifrype.com\/profile\/491\/171\/v3\/m_491171.jpg","imgl":"https:\/\/i1.ifrype.com\/profile\/491\/171\/v3\/l_491171.jpg","sex":"M","pk":"123456-12345"}}} ``` 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) - `pk`: lietotāja personas kods ### 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 09797abfe8e5ea53fd857cc372e3a6f5 491171 lv Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M ``` 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 Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg User_Default M Elīna Ozoliņa 25 1 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg User_Business F ``` 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 Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M Elīna Ozoliņa 25 1 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg F ``` 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 64428 491171 1524905 134564 234561 ``` ### 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 312 ``` ### 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 Jānis Bērziņš 21 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg https://i1.ifrype.com/profile/491/171/v3/i_491171.jpg https://i1.ifrype.com/profile/491/171/v3/m_491171.jpg https://i1.ifrype.com/profile/491/171/v3/l_491171.jpg M Elīna Ozoliņa 25 0 https://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg https://i1.ifrype.com/profile/491/171/v3/i_64428.jpg https://i1.ifrype.com/profile/491/171/v3/m_64428.jpg https://i1.ifrype.com/profile/491/171/v3/l_64428.jpg F ``` 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 64428 491171 1524905 134564 234561 ``` ### 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 16 ``` ### 3.7. 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 OK ``` ### 3.8. 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 OK ``` ### 3.9. 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 OK ``` ### 3.10. 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 159552 42872 1340 33.25 15 8 ``` ## 4. 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) --- # Draugiem.lv API PHP bibliotēka ## 1. Ievads Lai aplikāciju izstrādi padarītu ātrāku un vienkāršāku, esam izveidojuši PHP bibliotēku, kas veic API izsaukumus un automātiski pārveido pieprasītos datus uz PHP datu struktūrām. PHP bibliotēka var tikt izmantota gan portālā integrētajām aplikācijām, gan draugiem.lv Pases aplikācijām. Bibliotēka darbojas PHP5 vidē un tiek izmantots PHP sesiju mehānisms, lai uzglabātu lietotāja datus sesijā. Lai darbotos API izsaukumi, PHP konfigurācijā jābūt atļautai iespējai atvērt tīmekļa adreses, izmantojot `file_get_contents` funkciju (jābūt ieslēgtam `allow_url_fopen` konfigurācijas uzstādījumam). [Draugiem.lv API PHP bibliotēka un tās izmantošanas paraugi](https://github.com/Draugiem/draugiem-php-sdk) Lai varētu savā aplikācijā izmantot API bibliotēku, tajā ir jāiekļauj fails `DraugiemApi.php`. ## 2. Lietotāju dati PHP bibliotēkā API bibliotēkas funkcijas, kas atgriež lietotāju datus, tos atgriež kā PHP masīvu, kura struktūra ir šāda: ``` array ( 'uid' => 491171, //Draugiem.lv lietotāja ID 'name' => 'Jānis', //Vārds 'surname' => 'Bērziņš', //Uzvārds 'age' => 26, //Vecums (vai false, ja vecums slēpts) 'adult' => true,//true, ja lietotājs sasniedzis 18 g.vecumu(arī ja vecums slēpts) //lietotāja profila attēla URL vai false, ja tas nav pievienots 'img' => 'https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg', 'sex' => 'M', //dzimums - M-vīrietis, F-sieviete ) ``` Ja funkcija atgriež informāciju par vairākiem lietotājiem (piemēram, draugu sarakstu), tad atgrieztie dati ir masīvs no vairākiem lietotāju datu masīviem, kurā katra elementa atslēga ir lietotāja ID. Ja pieprasīti tikai viena lietotāja profila dati, tiek atgriezts tikai atbilstošā lietotāja datu masīvs. ## 3. Sesijas izveidošana un uzturēšana API bibliotēka izmanto PHP sesiju mehānismu, lai sesijas ietvaros uzglabātu informāciju par aktīvo draugiem.lv lietotāju. Lai sāktu izmantot draugiem.lv API bibliotēku, jāizveido `DraugiemApi` objekts, konstruktoram padodot aplikācijas ID un API atslēgu. Pēc tam jāizsauc metode `getSession`, kas caur draugiem.lv API veic lietotāja autentifikāciju un iegūst lietotāja datus. Aplikācijām, kas integrētas draugiem.lv, šī funkcija arī pārbauda, vai lietotāja draugiem.lv sesija joprojām ir aktīva (tāpēc aplikācijas pašai nav nepieciešams veikt `session_check` pieprasījumus). Draugiem.lv Pases aplikācijām metode tikai veic autentifikāciju un datu iegūšanu, bet lietotāja sesija netiek sasaistīta ar draugiem.lv sesiju. Ja metode atgriež `true`, tad sesijas izveidošana ir bijusi veiksmīga un lietotājs ir ienācis aplikācijā.: ```php getSession()){ //Autorizācija sekmīga //Lietotāja dati ir pieejami pārējām API funkcijām $user = $draugiem->getUserData();//Lietotāja profila datu iegūšana //Izdrukājam sveicienu lietotājam if($user['img']){ echo '
'; } echo 'Sveiki, '.$user['name'].' '.$user['surname'].'!
'; $uid = $draugiem->getUserId(); //Iegūst draugiem.lv lietotāja ID $count = $draugiem->getFriendCount();//Iegūst lietotāja draugu skaitu šajā aplikācijā echo 'Šo aplikāciju lieto vēl '.$count.' tavi draugi.'; } else { echo 'Authorization failed'; //Sesijas izveidošana neveiksmīga. //Lietotājs vai nu izgājis no draugiem.lv vai //nav izdevies aplikācijas autorizācijas pieprasījums. //Draugiem.lv Pases aplikācijai šādā situācijā būtu jāattēlo //saite uz pieteikšanās logu. } ``` ## 4. Piekļuve lietotāju datiem ārpus sesijas Ja nepieciešams izsaukt API funkcijas, kādam lietotājam, kas nav aktīvais sesijas lietotājs (piemēram, lai ievietotu paziņojumu lietotāja profila jaunumos, kamēr viņš nelieto aplikāciju), jāizveido jauns `DraugiemApi` objekts, konstruktoram padodot trešo parametru - lietotāja API atslēgu. Šim objektam iespējams izsaukt tās pašas metodes ko objektam, kas pieder aktīvajam sesijas lietotājam.: ```php $draugiem2 = new DraugiemApi($app_id, $app_key, $user_key); $draugiem2 -> addNotification('Tev ir jauna vēstule'); ``` Lietotāja API atslēgu iespējams iegūt ar metodi `getUserKey` pēc tam, kad viņš ir veiksmīgi autentificēts aplikācijā ar `getSession` metodi. Lai varētu atslēgu izmantot, kamēr lietotājs neizmanto aplikāciju, aplikācijai tā ir jāuzglabā pie sevis. Lietotāja API atslēga nemainās, kamēr lietotājs neizdzēš aplikāciju no profila vai arī nenomaina savu draugiem.lv lietotāja paroli. Lai nodrošinātu, ka aplikācijai vienmēr pieejama pareizā atslēga, vēlams pēc sesijas izveidošanas pārliecināties, ka atslēga nav mainījusies, un vajadzības gadījumā saglabāt jauno atslēgu. ## 5. API klases metožu apraksts ### 5.1. addActivity($text, $prefix, $link) Pievieno ierakstu lietotāja profila aktivitātēs formā `{$prefix} {text}`. Pie ieraksta redzama aplikācijas uzstādījumos norādītā ikona. Lai šī metode darbotos, aplikācijai jābūt atļautai aktivitāšu pievienošanai. Katram lietotājam aplikācija var izveidot ne vairāk kā vienu aktivitāti diennaktī. - **`$text`**: Aktivitātes klikšķināmās saites teksts (maksimālais garums 100 simboli) - **`$prefix`**: Teksts, kas redzams pirms klikšķināmās saites (neobligāts, maksimālais garums 50 simboli) - **`$link`**: Adrese, uz ko ved klikšķināmā saite (neobligāts, maksimālais garums 100 simboli, nenorādot saiti, aktivitāte vedīs uz aplikācijas sākumlapu). Integrētajām aplikācijām saitē jānorāda adrese, kas tiks attēlota iframe logā, nevis aplikācijas adrese portālā. - **Atgriežamā vērtība**: `true`, ja aktivitāti izdevies pievienot, `false`, ja nav izdevies. ### 5.2. addNotification($text, $prefix, $link, $creator) Pievieno paziņojumu lietotāja profila jaunumos formā `{$prefix} {text}`. Pie ieraksta redzama aplikācijas uzstādījumos norādītā ikona. Lai šī metode darbotos, aplikācijai jābūt atļautai profila jaunumu pievienošanai. Katram lietotājam aplikācija var izveidot ne vairāk kā četrus profila jaunumus diennaktī, ne ātrāk kā stundu pēc iepriekšējā pievienotā profila jaunuma. - **`$text`**: Paziņojuma klikšķināmās saites teksts (maksimālais garums 100 simboli) - **`$prefix`**: Teksts, kas redzams pirms klikšķināmās saites (neobligāts, maksimālais garums 50 simboli) - **`$link`**: Adrese, uz ko ved klikšķināmā saite (neobligāts, maksimālais garums 100 simboli, nenorādot saiti, tā vedīs uz aplikācijas sākumlapu). Integrētajām aplikācijām saitē jānorāda adrese, kas tiks attēlota iframe logā, nevis aplikācijas adrese portālā. - **`$creator`**: Draugiem.lv lietotāja ID, kas tiks attēlots kā paziņojuma autors (neobligāts; ID īpašniekam jābūt reģistrētam aplikācijas lietotājam; nenorādot ID, kā paziņojuma autors tiks attēlots aplikācijas nosaukums) - **Atgriežamā vērtība**: `true`, ja paziņojumu izdevies pievienot, `false`, ja nav izdevies. ### 5.3. apiCall($action, $args, $method = 'GET') Izsauc draugiem.lv API pieprasījumu un atgriež atbildi kā PHP datu struktūru. Pārsvarā šo metodi izmanto citas draugiem.lv PHP bibliotēkas metodes, tāpēc tiešā veidā to vajadzīgs izsaukt tikai tad, ja jāizsauc kāds API pieprasījums, kam PHP bibliotēkā nav paredzēta atsevišķa metode. Noklusētā REQUEST metode ir 'GET', bet vajadzības gadījumā iespējams padot arī 'POST'. - **`$action`**: Veicamā API pieprasījuma nosaukums (API pieprasījuma *action* parametra vērtība) - **`$args`**: Asociatīvais masīvs ar pieprasījumam padodamajiem parametriem un tiem atbilstošajām vērtībām (masīvā nav jāiekļauj *action*, *app* un *apikey* parametri, kas pieliekas automātiski) - **`$method`**: Veicamā API pieprasījuma tips. Pēc noklusējuma tas ir 'GET', bet to var nomainīt uz 'POST'. - **Atgriežamā vērtība**: Metode atgriež PHP masīvu ar API pieprasījuma atbildes datiem vai `false`, ja pieprasījums nav izdevies, vai atgriezta API kļūda. ### 5.4. checkFriendship($uid, $uid2) Pārbauda, vai divi aplikācijas lietotāji savā starpā ir draugi. - **`$uid`**: Pirmā lietotāja ID - **`$uid2`**: Otrā lietotāja ID (neobligāts, nenorādot šo parametru, tiks pārbaudīta `$uid` un aktīvā aplikācijas lietotāja draudzība) - **Atgriežamā vērtība**: `true`, ja lietotāji savā starpā ir draugi, `false`, ja pieprasījums nav izdevies, lietotāji nav draugi vai kāds no viņiem nav aplikācijas lietotājs. ### 5.5. cookieFix() Mēģina apiet sīkdatņu (*cookies*) izveidošanas ierobežojumus *Internet Explorer* un *Safari* pārlūkprogrammās. Šī metode jāizsauc pašā koda sākumā, pirms `getSession()`. Metode automātiski nosaka lietotāja pārlūkprogrammas versiju, tāpēc var tikt izsaukta nepārbaudot, kādu pārlūku lietotājs izmanto. Metode neko neatgriež un nesaņem nekādus papildu parametrus. Tā jālieto tikai portālā integrētajām aplikācijām, kas izmanto *iframe*. ### 5.6. getAppUsers ($page, $limit, $return_ids) Atgriež lappusi ar aplikācijas lietotājiem (saraksta sākumā būs tie, kas pēdējie pievienojušies aplikācijai). Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus. - **`$page`**: Atgriežamās lietotāju lappuses numurs, kas jāatgriež (numerācija sākas ar 1) - **`$limit`**: Vajadzīgais lietotāju skaits vienā lapā (maksimālā atļautā vērtība 200) - **`$return_ids`**: `true`, ja vajadzīgs atgriezt tikai lietotāju ID vai `false` (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati. - **Atgriežamā vērtība**: Masīvs ar lietotāju ID vai profila datiem vai `false`, ja pieprasījums nav izdevies. ### 5.7. getFriendCount() Iegūst lietotāja draugu skaitu starp aplikācijas lietotājiem. Atgriež draugu skaitu vai `false`, ja pieprasījums nav izdevies. ### 5.8. getInviteInfo() Iegūst informāciju par uzaicinājumu, ko lietotājs apstiprinājis, kad sācis lietot aplikāciju. Darbojas tikai jauna lietotāja pirmās sesijas laikā. Metode jāizsauc pēc `getSession` izsaukuma. Ja informācija par uzaicinājumu ir atrasta, metode atgriež datus ar šādu struktūru: ``` array( 'inviter' => 123, //Lietotāja ID, kas sūtījis uzaicinājumu 'extra' => '' //Papildu dati, kas ļauj identificēt uzaicinājumu, ja aplikācijas izstrādātājs tādus pievienojis. ) ``` Ja informācija nav atrasta, metode atgriež `false` ### 5.9. getJavascript($resize_container, $callback_html) Atgriež HTML kodu, kas jāizvada lapā, lai tajā būtu pieejamas draugiem.lv Javascript API funkcijas. Šī iespēja attiecas tikai uz portālā integrētajām aplikācijām. Metode jāizsauc pēc `getSession` izsaukšanas un atgrieztais kods jāizvada starp lapas `` tagiem. - **`$resize_container`**: Lapas HTML elementa ID, pēc kura izmēriem jāveic automātiska draugiem.lv iframe loga vertikālā izmēra maiņa. Nenorādot šo parametru, automātiska izmēra maiņa netiks veikta. - **`$callback_html`**: [callback.html](https://draugiem.eu/applications/external/callback.html) faila adrese uz aplikācijas servera, norādot pilnu domēnu. Šis parametrs ir neobligāts, bet, nenorādot to, aplikācija nevarēs saņemt atbildes vērtības no izsauktajām Javascript API funkcijām. - **Atgriežamā vērtība**: HTML kods, kas jāizvada aplikācijas lapā. ### 5.10. getLoginButton($redirect_url, $popup) Atgriež HTML kodu, kas ļauj izvadīt lapā draugiem.lv pases pieteikšanās pogu. Metode attiecas tikai uz draugiem.lv pases aplikācijām. - **`$redirect_url`**: Adrese, uz kuru jāpārsūta lietotājs pēc pieteikšanās ar draugiem.lv pasi - **`$popup`**: Vai draugiem.lv pases pietiekšanās logu jāatver jaunā izlecošajā logā. (`true` - jā, `false` - nē) - **Atgriežamā vērtība**: HTML kods, kas jāizvada lapā vietā, kur nepieciešama pieteikšanās poga. ### 5.11. getLoginUrl($redirect_url) Atgriež WWW adresi draugiem.lv pases pieteikšanās logam ar norādīto atpakaļpārsūtīšanas adresi. - **`$redirect_url`**: Adrese, uz kuru jāpārsūta lietotājs pēc pieteikšanās ar draugiem.lv pasi - **Atgriežamā vērtība**: Draugiem.lv pases pieteikšanās loga adrese. ### 5.12. getSession() Veic draugiem.lv lietotāja autentifikāciju un iegūst pamatinformāciju par lietotāju. **Vienmēr jāizsauc pirms pārējām klases metodēm**, izņemot gadījumus, kad bibliotēka tiek izmantota, norādot lietotāja API atslēgu konstruktorā. Darbībai tiek izmantots PHP iebūvētais sesiju mehānisms. Integrētajām aplikācijām šī metode arī periodiski veic sesijas pārbaudi ar `session_check` pieprasījumu. - **Atgriežamā vērtība**: `true`, ja autentifikācija veiksmīga un iegūti derīgi lietotāja dati, `false`, ja autentifikācija nav veiksmīga vai lietotāja sesija beigusies. ### 5.13. getSessionDomain() Atgriež draugiem.lv domēna adresi, no kura lietotājs ienācis aplikācijā. Metode attiecas tikai uz integrētajām aplikācijām. Aplikācijai var būt vajadzīgs zināt domēnu, piemēram, lai korekti attēlotu saites uz lietotāja profiliem. Tipiskā gadījumā domēna vērtība būs `www.draugiem.lv`, taču iespējamas arī citas vērtība, piemēram, ja lietotājs lieto draugiem.lv citā valodā. ### 5.14. getUserCount() Iegūst aplikācijas reģistrēto lietotāju skaitu. Atgriež lietotāju skaitu vai `false`, ja pieprasījums nav izdevies. ### 5.15. getUserData($ids) Atgriež pieprasīto lietotāju profila informāciju. - **`$ids`**: Norāda, kuru lietotāju datus atgriezt. Ja norādīts masīvs ar lietotāju ID (maksimāli 100 vērtības), tiek atgriezts masīvs ar norādīto lietotāju datiem (satur tikai to lietotāju datus, kas ir reģistrēti aplikācijas lietotāji). Ja parametrā padots viens lietotāja ID, tad tiek atgriezti tikai šī lietotāja dati vai `false`, ja tie nav pieejami. Ja parametra vērtība ir `false`, tad atgriezti tiek dati par aktīvo aplikācijas lietotāju. ### 5.16. getUserFriends($page, $limit, $return_ids) Atgriež lappusi ar aplikācijas lietotāja draugiem, kas arī lieto aplikāciju. Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus. - **`$page`**: Atgriežamās draugu lappuses numurs, kas jāatgriež (numerācija sākas ar 1) - **`$limit`**: Vajadzīgais lietotāju skaits vienā lapā (maksimālā atļautā vērtība 200) - **`$return_ids`**: `true`, ja vajadzīgs atgriezt tikai lietotāju ID vai `false` (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati. - **Atgriežamā vērtība**: Masīvs ar lietotāja draugu ID vai profila datiem vai `false`, ja pieprasījums nav izdevies. ### 5.17. getAllUserFriends($page, $limit, $return_ids) Atgriež lappusi ar aplikācijas lietotāja draugiem. Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus. Ja draugs nav aplikācijas lietotājs, tad par viņu pieejama informācija tikai par vārdu, uzvārdu, dzimumu un profila attēlu. - **`$page`**: Atgriežamās draugu lappuses numurs, kas jāatgriež (numerācija sākas ar 1) - **`$limit`**: Vajadzīgais lietotāju skaits vienā lapā (maksimālā atļautā vērtība 200) - **`$return_ids`**: `true`, ja vajadzīgs atgriezt tikai lietotāju ID vai `false` (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati. - **Atgriežamā vērtība**: Masīvs ar lietotāja draugu ID vai profila datiem vai `false`, ja pieprasījums nav izdevies. ### 5.18. getOnlineFriends($limit, $in_app, $return_ids) Atgriež sarakstu ar aplikācijas lietotāja draugiem, kas arī lieto aplikāciju un šobrīd ir ienākuši draugiem.lv. Iespējams atgriezt vai nu sarakstu ar lietotāju ID vai arī pilnus lietotāju profila datus. Funkcija pieejama tikai integrētajām aplikācijām brīdī, kad lietotājs pats atrodas online. - **`$limit`**: Vajadzīgais lietotāju skaits (maksimālā atļautā vērtība 100) - **`$in_app`**: `true`, ja vajadzīgs to draugu saraksts, kas tieši šobrīd lieto aplikāciju, `false`, ja vajadzīgs to draugu saraksts, kas atrodas portālā un ir reģistrēti aplikācijas lietotāji. - **`$return_ids`**: `true`, ja vajadzīgs atgriezt tikai lietotāju ID vai `false` (noklusētā vērtība), ja vajadzīgi pilni lietotāju dati. - **Atgriežamā vērtība**: Masīvs ar lietotāja draugu ID vai profila datiem vai `false`, ja pieprasījums nav izdevies. ### 5.19. getUserId () Atgriež aktīvā lietotāja ID vai `false`, ja tas nav pieejams. ### 5.20. getUserKey () Atgriež aktīvā lietotāja API atslēgu vai `false`, ja tā nav pieejama. ### 5.21. getUserLanguage () Atgriež aktīvā lietotāja portālā uzstādītajai valodai atbilstošo divu burtu kodu (`lv/ru/en/de/hu/lt`). ### 5.22. imageForSize($img, $size) Atgriež lietotāja profila attēla adresi vajadzīgajā izmērā. - **`$img`**: Lietotāja profila attēla adrese standarta izmērā (adrese, kas iegūta no API) - **`$size`**: Vajadzīgais attēla izmērs (`icon` - 50x50px / `small` - 100x100px / `medium` - 215px plats / `large` - 710px plats) - **Atgriežamā vērtība**: Lietotāja profila attēla adrese prasītajā izmērā. --- # "Ieteikt draugiem" funkcija ## Ieteikto ziņu saraksts Esam izveidojuši rīku, kas ļauj jūsu lapā attēlot informāciju par populārākajiem portālā draugiem.lv ieteiktajiem lapas rakstiem un to ieteicējiem (ieteicēji tiek attēloti, ja lietotājs ir ienācis draugiem.lv). Lai ievietotu sarakstu savā lapā, izmantojiet šo kodu: ```xml ``` Kodā atbilstoši atvērtajai lapai jānomaina šie parametri (jāatceras, ka parametri saitē jāievieto *urlencoded* formātā): - **`url`**: Lapas adrese (nenorādot šo parametru, tiks paņemta lapas adrese no HTTP referrer) - **`count`**: Rakstu skaits, kas tiks attēlos rīkā. (2-15) - **`scrollable`**: Ja norādīts šis parametrs ar vērtību "1" un rakstu kopējais augstums pārsniegs rīka augstumu, tad saturs būs ar ritjoslu. - **`height`**: Neobligāts paramets, kur nosaka iekšējā rāmja augstumu (noklusēti satura augstums) Lai rīks spētu attēlot rakstu attēlus, raksta HTML kodā ir nepieciešams *meta* tags ar saiti uz raksta attēlu. Ieteicamais izmērs 50x50, bet der arī citi izmēri, bet tad attēls būs nedaudz saspiests vai izstiepts. Ja rakstam nav attēla, ieteicams padot lapas logo. Pievienojamie *meta* tagi: ```xml ``` Ievietotais saraksts izskatīsies šādi: ![img/say_box.png](https://draugiem.eu/applications/img/say_box.png) ## Vienkārša ieteikšanas funkcija Lai pievienotu iespēju lietotājiem ieteikt savas lapas saturu atliek vien pievienot pavisam vienkāršu JavaScript funkciju savas lapas kodam un izsaukt to ar atbilstošiem parametriem: ``` function DraugiemSay( title, url, titlePrefix ){ window.open( 'https://www.draugiem.lv/say/ext/add.php?title=' + encodeURIComponent( title ) + '&link=' + encodeURIComponent( url ) + ( titlePrefix ? '&titlePrefix=' + encodeURIComponent( titlePrefix ) : '' ), '', 'location=1,status=1,scrollbars=0,resizable=0,width=530,height=400' ); return false; } ``` Atbilstošais funkcijas izsaukuma kods: ``` DraugiemSay('Ieraksta virsraksts, zem kura slēpsies saite', 'https://links.uz.resursu.lv/ar/pilnu/celju/uz/failu.html', 'Mana Lapa'); ``` Ieteikšanas pogai vēlams izmantot draugiem.lv piedāvāto ikonu: ![/i/say/add.png](https://draugiem.eu/i/say/add.png) Rezultāts izskatīsies aptuveni šādi: ![img/picture-12.png](https://draugiem.eu/applications/img/picture-12.png) ## Draugiem.lv "Runā" grāmatzīme Ja kādā no lapām, kurā ir interesants saturs nav saites *ieteikt draugiem*, tad droši var izmantot šādu *bookmarklet* jeb javascript grāmatzīmi: [Pateikt draugiem!](javascript:(function()%7Bwindow.open('https://www.draugiem.lv/say/ext/add.php?title='+encodeURIComponent((document.getSelection%20?%20(document.getSelection().toString()!=''%20?%20document.getSelection()%20:%20document.title):(document.selection.createRange%20?%20(document.selection.createRange().text%20?%20document.selection.createRange().text%20:%20document.title):document.title)))+'&link='+encodeURIComponent(window.location)+(document.domain?'&titlePrefix='+document.domain.replace('www.',%20''):''),'','location=1,status=1,scrollbars=0,resizable=0,width=530,height=400');%7D)();) (lai saglabātu pārlūkā vienkārši var ievilkt saiti grāmatzīmju joslā). Grāmatzīme darbojas pavisam vienkārši - ja lapā ir iezīmēts teksts, tad tas tiks izmantots kā ieraksta virsraksts (ja teksts nav iezīmēts, tad tiks izmantots lapas virsraksts, par saiti tiks paņemta pašlaik atvērtā lapa, bet lapas nosaukums saturēs lapas domēna vārdu bez *www.*. --- # 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 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: 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](https://draugiem.eu/applications/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](https://draugiem.eu/applications/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](mailto:api@draugiem.lv), vai arī izmantojot kopējo draugiem.lv iztrādātājiem veltīto e-pasta listi [draugiemapi@googlegroups.com](mailto:draugiemapi@googlegroups.com). Draugiem.lv lapu aplikācijās darbojas visi portālā integrēto aplikāciju API izsaukumi: #### 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 ADMIN ``` 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 Draugiem.lv lapas 0 0 https://path.to.image/file.jpg /pages 1 15328 afdsfdasfdsadfs ... ``` 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 Draugiem.lv lapas 0 0 https://path.to.image/file.jpg /pages 1 15328 afdsfdasfdsadfs ... ``` #### 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 Draugiem lapas 0 https://i2.ifrype.com/business/000/622/v1300780832/sm_13000622.jpg /pages 1 15328 ``` ### 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 #### 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()`, iespējams atvērt apstiprinājuma logu, kas ļauj lietotajam pievienoties par fanu atvērtajai lapai. **Funkcijai ir jāpadod parametrs ar lapas identifikatoru, kurai lapai sākt sekot. Lapas identifikatoru var atrast atverot lapu kreisajā kolonā zem visa pārējā satura:** #### 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()` funkciju. Šo funkciju ir atļauts izsaukt tikai pēc lietotāja klikšķa veikšanas. **Funkcijai var padot neobligātu parametru objektu:** ``` {'followPage': true} ``` Padodot šādu parametru objektu 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. **Neobligāts parametru objekts, lietotāja pāradresēšanai:** ``` {'redirect': 'app-url/?success'} ``` Padodot šādu parametru, lietotājs pēc veiksmīgas autorizācijas tiks pāradresēts uz norādīto adresi ## 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](https://draugiem.eu/applications/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 [api@draugiem.lv](mailto:api@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: ## 6. Kontakti Gadījumā, ja rodas jautājumi, varat droši izmantot šādu kontaktinformāciju: ``` api@draugiem.lv https://www.draugiem.lv/pages/ ``` --- # Draugiem.lv Lapu Administrācijas API ## 1. Ievads 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 visi draugiem.lv lapu administrēšanas darbi bija jāveic caur draugiem.lv vidi, kas nozīmēja, ka bija visai lielas iespējas palaist garām kādu svarīgu vēstuli, uzdoto jautājumu vai kādu citu niansi. Esam uzbūvējuši Draugiem.lv lapu administrēšanas API, kas ļauj piekļūt lapu pamatinformācijai, ļauj lasīt uzdotos jautājumus, atbildēt uz tiem, pievienot jaunus ierakstus jaunumu plūsmā, u.c. Pēc noklusējuma visām lapām API iespējas ir izslēgtas, katra lapa pati var tās ieslēgt ieslēdzot administrēšanas režīmu un izvēloties sadaļu "Lapas API". Pēc tam, kad API ir pieslēgts, ir iespējams pievienot arī papildus lietotājus, kas varēs darboties lapas API. Tālāk izmantojot ekrānā redzamo lapas aplikācijas ID, lapas atslēgu un attiecīgā lietotāja atslēgu jau var darboties ar konkrētiem API pieprasījumiem, izmantojot [draugiem.lv PHP API bibliotēku](https://www.draugiem.lv/applications/dev/docs/php/): ```php apiCall('pages/dashboard')); ``` **Rezultāts:** ``` array(13) { ["pageviews"]=> string(1) "1" ["pageviews_week"]=> string(2) "23" ["unique_pageviews"]=> string(1) "1" ["unique_pageviews_week"]=> string(2) "14" ["fans"]=> int(2) ["fansdelta"]=> int(0) ["fansdelta_week"]=> NULL ["received_messages"]=> int(5) ["unread_messages"]=> int(0) ["sent_messages"]=> int(0) ["answered_faq"]=> string(1) "0" ["unanswered_faq"]=> string(1) "0" ["oldest_unanswered_faq"]=> bool(false) } ``` ## 2. Pieejamie API pieprasījumi ### 2.1. Lapas aktuālās informācijas iegūšana (pages/dashboard izsaukums) Ar šo izsaukumu iespējams pieprasīt informāciju par lapas statistikas kopsavilkumu. Tas parāda datus par apmeklētājiem, vēstulēm, jautājumiem u.c. **Pieprasījuma parametri:** - `action`: pages/dashboard - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) **Pieprasījuma atbildes paraugs:** ```xml 65 400 3 11 1 0 1 0 0 0 1 3 2011-06-20 11:13:12 ``` **Atbildes parametru skaidrojums:** | pageviews | apmeklējumu skaits šodien | | --- | --- | | pageviews_week | apmeklējumu skaits šonedēļ | | unique_pageviews | unikālo apmeklētāju skaits šodien | | unique_pageviews_week | unikālo apmeklētāju skaits šonedēļ | | fans | sekotāju skaits | | fansdelta | sekotāju izmaiņas šodien | | fansdelta_week | sekotāju izmaiņas šonedēļ | | received_messages | saņemtās vēstules | | unread_messages | nelasītās vēstules | | sent_messages | nosūtītās vēstules | | answered_faq | atbildētie jautājumi | | unanswered_faq | neatbildētie jautājumi | | oldest_unanswered_faq | vecākā neatbildētā jautājuma datums | ### 2.2. Lapu jaunumu administrēšana (izsaukums pages/news) Izsaukums, kas ļauj apskatīt, pievienot un dzēst lapas jaunumus. Izsaukumam ir 4 dažādas metodes - list, add, edit un delete. #### 2.2.1. Metode list **Pieprasījuma parametri:** - `action`: pages/news - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `method`: list - `cat`: jaunumu kategorija, kuras ierakstus atgriezt (neobligāts) **Pieprasījuma atbildes paraugs:** ```xml Jaunuma virsraksts Jaunuma teksts 1 https://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg https://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg https://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg https://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg 13 23 2011-06-17 12:13:46 0 ``` Elements draft norāda uz to, vai jaunums ir melnraksts vai nav. Elements image satur informāciju par jaunuma titulbildes adresi – ja vērtība ir 0, tad titulbildes nav. #### 2.2.2. Metode add **Pieprasījuma parametri:** - `action`: pages/news - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `method`: add - `title`: jaunuma virsraksts - `text`: jaunuma teksts - `draft`: atzīme par to, vai jaunums ir melnraksts (vērtības 0 un 1) - `image_data`: titulbildes attēls. Datus nepieciešams sagatavot base64 kodējumā. (parametrs nav obligāts) - `comments`: atzīme par to, vai atļaut komentārus pie šī jaunuma (vērtības 0 un 1) **Piebilde**: Pieprasījums obligāti jāizpilda kā POST pieprasījums. **Pieprasījuma atbildes paraugs:** ```xml OK ``` Elements status norāda uz to, vai jaunums ir veiksmīgi pievienots. Ja tā ir, tad elementa vērtība ir OK. Pretējā gadījumā vērtība ir ERROR. #### 2.2.3. Metode edit **Pieprasījuma parametri:** - `action`: pages/news - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `method`: edit - `id`: rediģējamās ziņas ID - `title`: jaunuma virsraksts - `text`: jaunuma teksts - `draft`: atzīme par to, vai jaunums ir melnraksts (vērtības 0 un 1) - `image_data`: titulbildes attēls. Datus nepieciešams sagatavot base64 kodējumā. (parametrs nav obligāts) - `delete_image`: Ja parametra vērtība ir 1, tad titulbilde tiks dzēsta - `comments`: atzīme par to, vai atļaut komentārus pie šī jaunuma (vērtības 0 un 1) **Piebilde**: Pieprasījums obligāti jāizpilda kā POST pieprasījums. Vienīgais obligātais parametrs ir ID. Pārējos var norādīt atkarībā no nepieciešamības tos mainīt. **Pieprasījuma atbildes paraugs:** ```xml OK ``` Elements status norāda uz to, vai jaunums ir veiksmīgi pievienots. Ja tā ir, tad elementa vērtība ir OK. Pretējā gadījumā vērtība ir ERROR. #### 2.2.4. Metode get **Pieprasījuma parametri:** - `action`: pages/news - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `method`: get - `id`: jaunuma ID **Pieprasījuma atbildes paraugs:** ```xml Jaunuma virsraksts Jaunuma teksts 1 https://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg https://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg https://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg https://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg 13 23 2011-06-17 12:13:46 ``` #### 2.2.5. Metode delete **Pieprasījuma parametri:** - `action`: pages/news - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `method`: delete - `id`: jaunuma ID **Pieprasījuma atbildes paraugs:** ```xml OK ``` Elements status norāda uz to, vai jaunums ir veiksmīgi izdzēsts. Ja tā ir, tad elementa vērtība ir OK. Pretējā gadījumā vērtība ir ERROR. ### 2.3. Jautājumu un atbilžu administrēšana (izsaukums pages/faq) Izsaukums, kas ļauj apskatīt jautājumus, atbildēt uz tiem un tos dzēst. Izsaukumam ir 3 dažādas metodes - list, answer un delete. #### 2.3.1. Metode list **Pieprasījuma parametri:** - `action`: pages/faq - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `method`: list **Pieprasījuma atbildes paraugs:** ```xml Jautājuma teksts Atbilde uz jautājumu 2011-06-17 12:13:46 1 1 ``` Elements status norāda uz to, vai ir sagatavota atbilde uz jautājumu. Ja atbilde ir, tad statusa vērtība ir 1. Elements uid satur informāciju par draugiem.lv lietotāju, kur uzdevis jautājumu. #### 2.3.2. Metode answer **Pieprasījuma parametri:** - `action`: pages/faq - `app`: Alikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `method`: answer - `question_id`: jautājuma identifikators - `answer`: Atbildes teksts **Pieprasījuma atbildes paraugs:** ```xml OK ``` Elements status norāda uz to, vai atbilde ir veiksmīgi pievienota. Ja tā ir, tad elementa vērtībā ir OK. Pretējā gadījumā vērtība ir ERROR. #### 2.3.3. Metode delete **Pieprasījuma parametri:** - `action`: pages/faq - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `method`: delete - `question_id`: jautājuma identifikators **Pieprasījuma atbildes paraugs:** ```xml OK ``` Elements status norāda uz to, vai jautājums ir veiksmīgi izdzēsts. Ja tā ir, tad elementa vērtībā ir OK. Pretējā gadījumā vērtība ir ERROR. ### 2.4. Lapas statistikas dati (pages/stats izsaukums) Ar šo izsaukumu iespējams pieprasīt informāciju par lapas statistiku dažādos laika periodos. Izsaukumam ir 4 dažādi griezumi, kuri tiek norādīti ar parametru type - unique, fans, pages, genders. #### 2.4.1. Griezums unique Pieprasījums parāda datus par unikālajiem apmeklētājiem. **Pieprasījuma parametri:** - `action`: pages/stats - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `type`: unique - `date_from`: sākuma datums formā YYYY-MM-DD (nav obligāts) - `date_till`: beigu datums formā YYYY-MM-DD (nav obligāts) - `total`: ja tiek padots šis parametrs, tad tiek atgriezts kopējais unikālo lietotāju skaits par norādīto periodu (nav obligāts) Ja netiek norādīti datumi, tad tiek parādīta statistika par tekošo mēnesi. **Pieprasījuma atbildes paraugs:** ```xml 123 33 42 47 77 38 144 299 ``` **Pieprasījuma atbildes paraugs, ja padots "total" parametrs:** ```xml 123 ``` #### 2.4.2. Griezums fans Pieprasījums parāda fanu skaita dinamikas datus. **Pieprasījuma parametri:** - `action`: pages/stats - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `type`: fans - `date_from`: sākuma datums formā YYYY-MM-DD (nav obligāts) - `date_till`: beigu datums formā YYYY-MM-DD (nav obligāts) Ja netiek norādīti datumi, tad tiek parādīta statistika par tekošo mēnesi. **Pieprasījuma atbildes paraugs:** ```xml 22 23 25 33 46 68 132 256 ``` #### 2.4.3. Griezums pages Pieprasījums parāda sadaļu skatījumu datus. **Pieprasījuma parametri:** :action: pages/stats :app: aplikācijas API atslēga (32 simboli) :apikey: lietotāja API atslēga (32 simboli) :type: pages :date_from: sākuma datums formā YYYY-MM-DD (nav obligāts) :date_till: beigu datums formā YYYY-MM-DD (nav obligāts) Ja netiek norādīti datumi, tad tiek parādīta statistika par tekošo mēnesi. **Pieprasījuma atbildes paraugs:** ```xml 324 57 12 7 ``` **Elementu skaidrojumi:** - `firstpage`: pirmā lapa - `fans`: fanu lapa - `faq`: biežāk uzdotie jautājumi - `guestbook`: viesu grāmata - `say`: runā sadaļa - `gallery`: galeriju sadaļa - `news`: jaunumu sadaļa - `pages`: teksta lapas Līdz ar draugiem.lv lapu funkcionalitātes paplašināšanu šiem elementiem var pievienoties jauni. #### 2.4.4. Griezums genders Pieprasījums parāda datus par apmeklētāju vecumu un dzimumu. **Pieprasījuma parametri:** - `action`: pages/stats - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `type`: genders - `date_from`: sākuma datums formā YYYY-MM-DD (nav obligāts) - `date_till`: beigu datums formā YYYY-MM-DD (nav obligāts) Ja netiek norādīti datumi, tad tiek parādīta statistika par tekošo mēnesi. **Pieprasījuma atbildes paraugs:** ```xml 30 38 ``` Tiek atgriezti 100 item elementi – attiecīgi statistika par lietotājiem vecumā no 1 – 100 gadiem. ### 2.5. Lapas runā plūsmas pārvaldība (pages/say izsaukums) Ar šo izsaukumu ir iespējams iegūt lapas runā plūsmu, kā arī pievienot jaunus ierakstus un dzēst esošos #### 2.5.1. Metode list Pieprasījums atgriež lapas runā plūsmu **Pieprasījuma parametri:** - `action`: pages/say - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `method`: list - `filter`: all (neobligāts parametrs) Ja filter parametrs nebūs norādīts, tad tiks atgriezti tikai manuāli pievienotie Runā ieraksti. Ja būs - tiks atgriezti visi ieraksti (t.s. ieraksti par jaunajām galerijām, jaunumu ierakstiem utt.) **Pieprasījuma atbildes paraugs:** ```xml Mans teksts Saites teksts Ieraksta prefikss Ieteikumu skaits Komentāru skaits Izveidošanas laiks Ieraksta links ``` #### 2.5.2. Metode add Pieprasījums jauna runā ieraksta pievienošanai. **Pieprasījuma parametri:** - `action`: pages/say - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `method`: add - `titlePrefix`: ieraksta prefikss (tiek attēlots oranžā krāsā, attēlā #1) - `title`: saites teksts (attēlā 2) - `link`: URL uz kurieni pārsūtīt lietotāju (attēlā 3) - `text`: Ieraksta teksts (attēlā 4) - `age_from`: Minimālais lietotāju vecums, kuriem ieraksts būs redzams (nav obligāts) - `age_to`: Maksimālais lietotāju vecums, kuriem ieraksts būs redzams (nav obligāts un tiks ņemts vērā tikai tad, ja norādīts age_from) - `image_data`: Pievienotais attēls. Datus nepieciešams sagatavot base64 kodējumā. (parametrs nav obligāts) ![img/say_parts.png](https://draugiem.eu/applications/img/say_parts.png) **Piebilde**: ja vēlaties ierakstā pievienot saiti, tad obligāti jānorāda gan title, gan link parametri. **Pieprasījuma atbildes paraugs:** ```xml OK ``` Elements status norāda uz to, vai ieraksts ir veiksmīgi pievienots. Ja tā ir, tad elementa vērtībā ir OK. Pretējā gadījumā vērtība ir ERROR. #### 2.5.3. Metode delete Pieprasījums ļauj dzēst kādu runā ierakstu savā runā plūsmā. **Pieprasījuma parametri:** - `action`: pages/say - `app`: aplikācijas API atslēga (32 simboli) - `apikey`: lietotāja API atslēga (32 simboli) - `method`: delete - `id`: runā ieraksta identifikators **Pieprasījuma atbildes paraugs:** ```xml OK ``` Elements status norāda uz to, vai ieraksts ir veiksmīgi pievienots. Ja tā ir, tad elementa vērtībā ir OK. Pretējā gadījumā vērtība ir ERROR. --- # Pasākumu sadaļas API Pasākumu sadaļas API ļauj iegūt datus par draugiem.lv pasākumu sadaļā esošajiem pasākumiem. ## 1. Pieprasījuma formāts XML ir pieejams adresē *https://www.draugiem.lv/events/api/*, padodot nepieciešamos parametrus kā HTTP GET vērtības. *Pieprasījuma parametri:* - **`feed`**: pieprasījuma veids. Atbalstītie pieprasījumu veidi aprakstīti zemāk. - **`format`**: datu formāts. Atbalastītie datu formāti: *xml*, *json* ## 2. Kļūdu ziņojumi Ja datu apstrādes laikā notikusi kļūda, vai nav iespējams apstrādāt pieprasījumu, tiek atgriezta šāda konstrukcija: ```xml 1 Missing or invalid country identifier. ``` Ja datu apstrāde noritējusi veiksmīgi, atgrieztajā XML struktūrā būs šī konkstrukcija, ar *0*. ## 3. Kļūdu kodu atšifrējums | code | message | | --- | --- | | 2 | Trūkst vai neatbalstāms pieprasījuma veids (vērtība feed) | | 3 | Nav padots pasākuma ID. | | 4 | Pasākums neeksistē. | | 5 | Pieeja liegta. | | 6 | Pieprasīts nekorekts datu formāts | ## 4. Pasākuma ieraksta formāts Lielākā daļa pieprasījumu atgriež konstrukciju, kas apraksta pasākuma ierakstu. Piemērs: ```xml 323504 - draugiem.lv pasākuma ID Ar buru pār jūru - pasākuma nosaukums 1280902762 - pasākuma izveidošanas datums (nav pasākuma norises datums!) https://www.draugiem.lv/events/arburuparjuru/ - saite uz pasākumu https://i4.ifrype.com/business/323/504/v3/p323504.jpg - pasākuma "plakāta" bilde https://i4.ifrype.com/business/323/504/v3/sm_323504.jpg - 50x50 ikona https://i4.ifrype.com/business/323/504/v3/l_323504.jpg - lielā izmēra bilde - pasākuma apraksts Liepājnieks Jānis Preiss, godalgotais latviešu ūdens sportists, ir gatavs pieņemt jaunu izaicinājumu – šķērsot vienatnē Baltijas jūru uz vindsērfinga dēļa (no Liepājas līdz Visbijai)! Šis brauciens būs latviešu spēka, drosmes, izturības un uzņēmības pārbaude un pierādījums, ka latvieši ir tauta, kas seko līdzi jaunajam un gatavi uzņemties aizvien nebijušus izaicinājumus.Seko līdzi Jāņa gaitām un piedalies braucienā ar savām domām un labajiem vēlējumiem! - pasākuma norises datumi un vietas (var būt vairākas) 1282647600 - sākuma laiks Liepāja - norises reģions Viesnīca "Zvejnieks" - norises vieta - pasākuma kategorija Mūzika 126 ``` ## 5. Pieprasījums "actual" *https://www.draugiem.lv/events/api/?feed=actual* Atgriež sarakstu ar "aktuālajiem" pasākumiem. Aktuālie pasākumi ir draugiem.lv administrācijas izvēlēties pasākumi. ## 6. Pieprasījums "item" *https://www.draugiem.lv/events/api/?feed=item&id=323504* Atgriež datus par konkrētu pasākumu. Obligātie lauki: *id* - draugiem.lv pasākuma ID. ## 7. Pieprasījums "categories" *https://www.draugiem.lv/events/api/?feed=categories* Atgriež sarakstu pasākumu kategorijām. ## 8. Pieprasījums "search" *https://www.draugiem.lv/events/api/?feed=search&country=lv* Ļauj meklēt pasākumus pēc kritērijiem. Iespējamie lauki: - **`city`**: pilsēta (piemēram, "Rīga"). - **`catid`**: kategorijas ID. - **`start`**: sākuma datums (unix timestamp). - **`search`**: meklēšanas kritērijs. - **`page`**: lapa (numurācijas sākas no 1). - **`rpp`**: rezultātu skaits lapā (pēc noklusējuma 10). Neviens lauks nav obligāts, taču pieprasījumā jābūt vismaz vienam. Bez pašiem pasākuma ierakstiem, atgriež meklēšanas rezultātu konstrukciju: ```xml 25520 - kopā atrastie rezultāti 10 - rezultātu skaits, kas attēlots 2 - tekošā lapa (sākas no 1) 10 - rezultātu skaits lapā 2552 - kopējais lapu skaits ``` --- # API lietošana ## 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ā | | | **PHP** | atbildes uz API pieprasījumiem tiek pārsūtītas PHP serializēto datu formātā | | | **JSON** | atbildes uz API pieprasījumiem tiek pārsūtītas JSON datu formātā | | | **PLIST** | atbildes uz API pieprasījumiem tiek pārsūtītas Apple Property List XML datu formātā | | 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 Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M ``` ## 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 Access denied ``` **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 | ## 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 ... Jānis Bērziņš 1 https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg M ... ``` **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 ## 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. --- # Draugiem.lv pases spraudnis priekš Wordpress Ja jūsu blogs vai mājaslapa darbojas ar Wordpress sistēmu, tad draugiem.lv pases ieviešana ir pavisam vienkārša, izmantojot gatavu Wordpress spraudni. Spraudni uzinstalēt iespējams, izmantojot Wordpress iebūvēto spraudņu meklēšanas un instalēšanas funkciju (*Wordpress administrācijas panelis* -> *Plugins* -> *Add new*), meklējot pēc teksta *draugiem pase*. Ja servera uzstādījumi liedz šādu instalēšanas metodi, iespējams doties uz , kur iespējams lejupielādēt spraudni, lai pēc tam veiktu instalāciju manuāli. Kad spraudnis instalēts, nepieciešams draugiem.lv izstrādātāju sadaļā izveidot jaunu draugiem.lv pases aplikāciju. Pēc aplikācijas izveidošanas jūs iegūsiet tās ID un API atslēgu, kas jāievada spraudņa konfigurācijas logā (*Wordpress administrācijas panelis* -> *Settings* -> *Draugiem pase*). Turpat iespējams arī nomainīt vairākus citus uzstādījumus. Kad spraudnis ir instalēts un nokonfigurēts, lietotājiem ir iespējams reģistrēties un pievienot komentārus, izmantojot savus draugiem.lv reģistrācijas datus. Blakus viņu veiktajiem komentāriem būs redzami viņu draugiem.lv profila attēli un lietotāja vārdi. ![img/wordpress.png](https://draugiem.eu/applications/img/wordpress.png) --- # Draugiem.lv biznesa lapu fanu spraudnis priekš Wordpress Autors: Rolands Umbrovskis, Ja jūsu blogs vai mājaslapa darbojas ar Wordpress sistēmu, tad draugiem.lv biznesa lapu fanu spraudņa ieviešana ir pavisam vienkārša, izmantojot gatavu Wordpress spraudni. WordPress spraudnis "Draugiem.lv/lapas Fanu lapa" ir paredzēts draugiem.lv biznesa lapu īpašniekiem. Spraudni iespējams lejupielādēt oficiālājā Wordpress vietnē . Draugiem.lv lapu sekotāju WordPress spraudnis ir paredzēts tiem draugiem.lv biznesa lapu īpašniekiem, kuriem ir mājas lapas vai blogs, kas ir veidots uz WordPress platformas. WordPress spraudnis parāda draugiem.lv biznesa lapas nosaukumu, aprakstu, lietotājus, to skaitu, logo un iespēju kļūt par lapas fanu. ![img/pages_fans_wordpress.jpg](https://draugiem.eu/applications/img/pages_fans_wordpress.jpg) --- # Draugiem.lv pases spraudnis priekš Drupal Lai pievienotu draugiem.lv Pases funkcionalitāti lapām, kas darbojas, izmantojot Drupal satura vadības sistēmu, iespējams izmantot *DrConnect* moduli, ko izveidojuši Mārtiņš Zaķis un Miķelis Zaļais. Sīkāka informācija: Uzmanību! Šī moduļa izstrādātājs nav draugiem.lv, tāpēc mēs negarantējam tā korektu un stabilu darbību. --- # Noteikumi 1. Saskaņā ar šiem noteikumiem interneta „Portāla” www.draugiem.lv reģistrētajiem lietotājiem - „Lietotāji”, Portāla sadaļā „Aplikācijas” ir tiesības ievietot personīgi izveidotas datorprogrammas, vai aplikācijas, turpmāk tekstā sauktas „Programmas”. 2. Programma izstrādājama un integrējama Portālā atbilstoši Portālā pieejamajai API dokumentācijai, un draugiem.lv pārstāvju ieteikumiem tehniskajai realizācijai. 3. Pirms programmas publicēšanas Lietotājam ir tiesības ievietot Programmu Portāla API vidē testa veikšanai. Pēc Programmas integrēšanas testa režīmā, draugiem.lv piecu darba dienu laikā, veic pieteiktās Programmas satura un formas apstiprināšanu. Draugiem.lv ir tiesības nepublicēt pieteikto Lietotāja Programmu, ja tiek konstatēts, ka Lietotāja Programma vai tās saturs neatbilst šiem noteikumiem, pārkāpj trešo personu tiesības, piemēram, patentu tiesības, zīmola tiesības, vai autortiesības. 4. Programmu, kas integrēta Portālā, testēšanas režīmā iespējams lietot tikai cilvēkiem, kas ir Programmas izveidotāja draugu lokā, taču ne vairāk kā 30 Lietotājiem. Testa režīmā esošai Programmai iespējams piekļūt arī draugiem.lv pārstāvjiem. Pēc apstiprināšanas Programma pieejama visiem Portāla reģistrētajiem lietotājiem. 5. Lietotājs ir atbildīgs par Programmas saturu un atbilstību Latvijas Republikas normatīvajiem aktiem. Aizliegts Programmas saturā ievietot azartspēles, aizliegtu reklāmu, politiskās aģistācijas materiālus un/vai saturu, piedāvāt informācijas izvietošanu par maksu, vai pārdot reklāmu, bez saskaņošanas ar Draugiem.lv. Lietotājs ir pilnībā atbildīgs par jebkāda veida zaudējumiem, vai trešo personu prasījumiem, kas varētu tikt vērsti pret draugiem.lv, saistībā ar Lietotāja Programmas publicēšanu Portālā. 6. Lietotājs ievietojot Programmu Portālā, kā Programmas autors garantē, ka vienīgi viņš ir tiesīgs rīkoties ar sava darba autortiesībām un, ka tā izstrādē ir ievēroti visi likumiskie nosacījumi, piešķirot draugiem.lv tiesības izmantot un padarīt pieejamu Sabiedrībai, Lietotāja izstrādāto Programmu Portālā. 7. Lietotājam ir pienākums nodrošināt efektīvu un savlaicīgu Portāla lietotāju iesūtīto sūdzību un jautājumu apstrādi, nodrošinot atbildes sniegšanu uz Portāla lietotāju jautājumiem ne vēlāk kā divu darba dienu laikā no pieprasījuma saņemšanas brīža. Programmas informācijas sadaļā jābūt norādītiem: pretenziju tālrunim, e-pastam un forumam. 8. Draugiem.lv ir tiesības, jebkurā brīdī, bez Lietotāja brīdināšanas, pārtraukt Lietotāja Programmas publicēšanu, Portālā, nepaskaidrojot iemeslu Programmas publicēšanas pārtraukšanai. 9. Draugiem.lv ir tiesības, jebkurā laikā, bez iepriekšēja saskaņošanas, neizvietot vai apturēt Programmas darbību, ja tiek atklātas nepilnības Programmas darbībā, koda uzbūvē, vai sadarbspējā ar Portālu, kas rada papildus serveru slodzi. 10. Draugiem.lv nosaka secību kādā Programmas tiek eksponētās (parādītas) citiem Portāla reģistrētajiem lietotājiem. 11. Programma integrējama un tās funkcijas pakārtojamas ekskluzīvi Portāla API platformai. Nav atļauts Programmā, vai tās pieejas nodrošināšanā iekļaut, savienojumus, kas ļauj piekļūt Programmai ar kādā citā sistēmā izveidota lietotāja konta datiem, kas nav Portāla reģistrētie lietotāja dati, vai ved uz jebkuru citu, Portāla API sadaļas platformai līdzīgu vietni, vai konkurējošiem sociāliem tīkliem. 12. Lietotājam ir tiesības jebkurā brīdī pārtraukt savas Programmas publicēšanu, nosūtot rakstveida paziņojumu uz [api@draugiem.lv](mailto:api@draugiem.lv) 13. Draugiem.lv ir tiesības noteikt, kurām Programmām piešķirt tiesības publicēt paziņojumus Portāla lietotāju profila jaunumu joslā un draugu aktivitāšu joslā. Uz šādām tiesībām pretendē tikai Programmas, kas jau ir apstiprinātas un publiski pieejamas Portāla reģistrētajiem lietotājiem. 14. Programmām aizliegts publicēt tādus paziņojumus Portāla lietotāju profila jaunumu joslā un draugu aktivitāšu joslā, kas satur priekšvēlēšanu aģitāciju vai arī satur saites, kas ved uz kādas politiskās organizācijas, politisko organizāciju apvienības vai deputāta kandidāta lapām. 15. Programmas ietvaros, ir atļauts piedāvāt portāla reģistrētajiem lietotājiem maksas pakalpojumus, tos nodrošina, izmantojot draugiem.lv piedāvāto maksājumu sistēmu. Maksas pakalpojumu nodrošināšanai atļauts lietot tikai draugiem.lv piedāvātos maksājumu sistēmas risinājumus, dalot ienākumus ar draugiem.lv. 16. Lietotājs ir atbildīgs par korektu maksājumu apstrādi un pakalpojumu piešķiršanu reģistrētājiem Portāla lietotājam. Nekvalitatīvas maksājumu apstrādes gadījumā Draugiem var pārtraukt piekļuvi maksājumu sistēmai. Ja programmas izstrādātāja kļūdas dēļ nav korekti piešķirts kāds lietotāja apmaksāts pakalpojums, viņam jānodrošina pakalpojuma vai līdzvērtīgas kompensācijas piešķiršana lietotājam. 17. Gadījumā, ja Lietotāja Programmas saturs paredz maksas pakalpojumus, papildus šajos noteikumos noteiktajam, Lietotājam ir jānoslēdz līgumu par Programmas izvietošanu un uzturēšanu portālā, kā arī ieņēmumu sadali. 18. Lietotāja izveidotā Programma nedrīkst uzkrāt Portāla reģistrētos lietotāju datus, izņemot datus ko rada Programma – rezultāti, reitingi, kas ir piesaisti konkrētā lietotāja ID. Programmas izmantošanai atļauts kešot API pieprasījumu rezultātus, ne ilgāk kā uz 12 stundām, lai neradītu lieku slodzi Portāla API serveriem. 19. Lietotājam ir pienākums sniegt draugiem.lv tehnisko informāciju par Programmas darbību, pārskatus, atskaites un jebkāda cita veida informāciju, kas saistīta ar Programmas darbību. 20. Draugiem.lv ir tiesības jebkurā brīdī ieviest izmaiņas šajos noteikumos un šīs izmaiņas stājas spēkā ar brīdi, kad tās ir publicētas Portālā. 21. Lietotājam ir pienākums darīt visu nepieciešamo, lai nodrošinātu draugiem.lv tiesisko interešu aizsardzību („to hold harmless and indemnify”) pret visām trešo personu prasībām vai pretenzijām, zaudējumiem, kuras ir celtas vai varētu tikt celtas pret draugiem.lv un ir jebkādā veidā saistītas ar to, ka Lietotājs izvietojis Programmu Portālā. 22. Ievērojot šos noteikumus, draugiem.lv nevienā atgadījumā nebūs atbildīgs par jebkādiem izrietošiem, tiešiem, netiešiem zaudējumiem, tai skaitā, tādiem zaudējumiem kā ieņēmumu zaudējumi, finansiāli vai zīmola prestiža zaudējumi trešām personām. 23. Visi strīdi, kas saistībā ar šo noteikumu piemērošanu rodas starp draugiem.lv un Lietotāju tiek risināti savstarpējo pārrunu ceļā. Ja strīdus tādā veidā atrisināt neizdodas, tie risināmi saskaņā ar Latvijas Republikas likumdošanu. 24. Lietotājs ievietojot Programmu Portālā, kā Programmas autors, nedrīkst pieprasīt no citiem portālā reģistrētajiem lietotājiem, lai tie uzrāda savu e-pasta adresi vai tālruņa numuru, pievienojoties Programmai vai pašā Programmā. 25. Jebkāda veida sūdzības, ieteikumi un ierosinājumi nosūtāmi uz [api@draugiem.lv](mailto:api@draugiem.lv). --- # Vadlīnijas draugiem.lv aplikāciju izstrādātājiem Daži svarīgi ieteikumi draugiem.lv aplikāciju izstrādātājiem. Viss tālāk rakstītais ir rakstīts ar domu, ka jūs izstrādē izmantojat HTML/JS/CSS/PHP/MySQL, taču praktiski viss tas pats attiecas arī uz citām tehnoloģijām, atliek vien piemeklēt vajadzīgās paralēles un uzstādījumus. ## 1. Servera uzstādījumi ### 1.1. Globāli servera uzstādījumi ``` allow_url_fopen - nepieciešams draugiem.lv PHP bibliotēkas darbībai ``` ### 1.2. Lietotājiem pieejamai aplikācijas versijai nepieciešamie PHP uzstādījumi Parastam lietotājam pilnīgi neko neizsaka jūsu PHP kļūdu ziņojumi: ``` Missing Controller Error: LacistestController could not be found. Error: Create the class LacistestController below in file: app/controllers/lacistest_controller.php Notice: If you want to customize this error message, create app/views/errors/missing_controller.ctp ``` Lietotājiem pieejamā vidē kļūdu ziņojumus ir jāpaslēpj, taču tajā pašā laikā ir jānodrošina, ka jūs saņemat un analizējat informāciju par notikušajām kļūdām: ``` display_errors = Off log_errors = On ``` ## 2. Aplikācijas drošība ### 2.1. Aizsardzība pret CRSF (Cross Site Request Forgery). Aplikācijām ir jānodrošina, ka tās darbības nav iespējams izsaukt bez lietotāja līdzdarbības - gan GET, gan POST pieprasījumiem līdzi jāpadod papildus mainīgie, kas mainās katram lietotājam vienas sesijas ietvaros un tiek pārbaudīti servera pusē. Tas palīdz izvairīties no situācijas, kad lietotāji ievieto slēptus iframe ārpus draugiem.lv vides, kur ar javascript tiek veikta formu datu nosūtīšana uz attiecīgo adresi. Piemēram balsošana par kādu lietotāju konkursā, balsotājam par to nemaz neuzzinot: ```xml
``` Aplikācijas pusē pievienojot šādai balsojuma formai papildus hash mainīgo, kas mainās katram lietotājam sesijas ietvaros, šāda veida balsojumi vairs nav iespējami. Jebkāda veida balsojumiem ir jādarbojas tikai kā POST pieprasījumiem. ## 3. BUJ draugiem.lv lapu aplikāciju izstrādē Šajā nodaļā apkopoti vairāki no biežāk uzdotajiem izstrādātāju jautājumiem. ### 3.1. Aplikācijas novietojums - sākumlapa vai lapas sadaļa Lapu aplikācijas var novietot gan konkrētās lapas sākumlapas vienā no kolonām, gan arī kā lapas sadaļu. Lai aplikācija varētu zināt, kurā no pozīcijām tā ir novietota, var izmantot iframe parametros padoto kolonas platuma mainīgo GET[dr_appw]: | Vērtība | Aplikācijas novietojums | | --- | --- | | 240 | Sākumlapas šaurā (labā) kolona | | 480 | Sākumlapas platā (centrālā) kolona | | 730 | Lapas sadaļa | ### 3.2. Piekļuve lietotāju datiem Atšķirībā no parastajām draugiem.lv aplikācijām, lapu aplikācijas pēc noklusējuma darbojas anonīmā režīmā. Tas nozīmē, ka atverot lapu, kurā būs ievietota aplikācija, lietotājam netiks piedāvāts atļaut piekļuvi saviem datiem. Tā rezultātā - ja lietotājs nebūs jau iepriekš atļāvis piekļuvi saviem datiem, pirmais izsaukums uz sesijas pārbaudi kā likums atgriezīs false: ```php $draugiemApi = new DraugiemApi(APPID, APIKEY); $session = $draugiem->getSession(); ``` Šajā gadījumā jums ir jāparāda aplikācijas "landing" lapa, kurā lietotājs ar JavaScript izsaukuma draugiemAuthorize() palīdzību var atļaut piekļuvi saviem datiem: Draugiem.lv lapu aplikācijas var ievietot arī kā bloku lapas sākumlapā. Šāds solis ir veikts apzināti, lai izvairītos no situācijām, kad lietotājam jau atverot lapu tiek prasīta piekļuve viņa datiem. ### 3.3. Aktivitāšu pievienošana Arī draugiem.lv lapu aplikācijām ir iespēja pieslēgt aktivitātes, taču atšķirībā no parastajām draugiem.lv aplikācijām, pievienojot lapu aktivitāti kā papildus parametrs līdzi ir jāpadod arī lapas identifikators, kuru jūs saņemat pie pirmās lapas atvēršanas GET parametrā api_page_id. Lai to izmantotu vēlāk, visticamāk tas ir jāsaglabā kādā sesijas mainīgajā. Aktivitātes pievienošanas piemērs draugiem.lv lapu aplikācijā: ```php $draugiemApi = new DraugiemAPI(APPID, APIKEY); $response = $draugiemApi->apiCall('add_activity', array('text'=>$text,'prefix'=>$prefix, 'link'=>$link, 'page_id' => $page_id)); ``` Link parametrā ir jāpadod tikai tā daļa, kas seko aiz lapas adreses. Lai savai aplikācijai pieslēgtu aktivitātes, rakstiet uz [api@draugiem.lv](mailto:api@draugiem.lv) ### 3.4. Flash satura ievietošana Lai ievietotais flash saturs (baneri, spēles, u.c.) nekonfliktētu ar draugiem.lv vidi, nepieciešams uzstādīt flash objekta "wmode" parmetram vērtību "transparent". ### 3.5. Manu lapu aplikāciju neredz parasti apmeklētāji Lapu aplikācijām šobrīd ir nepieciešams apstiprinājums, lai to redzētu citi draugiem.lv lietotāji. Lai iegūtu lapu aplikācijas apstiprinājumu, rakstiet uz [api@draugiem.lv](mailto:api@draugiem.lv), vai skype: ingus.rukis ### 3.6. Aplikācijas korekta aizvēršana tehnisku problēmu gadījumā Gadījumā, ja jūsu aplikācijai ir tehniskas problēmas, kuru rezultātā jūs nevarat nodrošināt korekta kļūdas ziņojuma parādīšanu aplikācijas līmenī (piemēram, nestrādā hostings), jāizmanto iespēja aizvērt aplikāciju draugiem.lv pusē: ![img/guidelines-closederror.png](https://draugiem.eu/applications/img/guidelines-closederror.png) Šī iespēja ir pieejama aplikācijas uzstādījumu labošanas skatā. ![img/guidelines-close.png](https://draugiem.eu/applications/img/guidelines-close.png) ## 4. Fināls Šis ir tikai vadlīniju pirmais uzmetums, noteikti to vēl papildināsim. --- # Vienkārša spēļu analītika izmantojot Google Analytics Aptaujājot pāris izstrādātājus secināju, ka draugiem.lv vidē izstrādātāji ļoti maz strādā pie tā, lai novērtētu atdevi no savu aplikāciju aktivitātēm, profila jaunumiem, lietotāju veiktajiem runā ierakstiem, aktivitātēm lapās, utt. Pilnīgi noteikti ir izstrādātāji, kuri nemaz nenojauš kādu atdevi viņiem dod spēles aktivitāšu, profila jaunumu vai runā ierakstu veikšana. Turpinājumā neliels ieskats, kā to vienkārši izmērīt. 1. Uzliekam savai aplikācijai Google Analytics (turpmāk GA) skaitītāju. 2. Iepazīstamies ar nedaudz gudrākas GA uzskaites veikšanu 3. Mēram rezultātus Pirmo punktu domājams nav jāpaskaidro, tāpēc ķeramies uzreiz pie nedaudz gudrākas GA uzskaites veikšanas. ## Gudrāka GA lietošana Ir viena ļoti būtiska GA iespēja, par kuru ļoti daudzi no GA lietotājiem nemaz nenojauš. Tā ir iespēja mērīt ienākošos apmeklētājus un sadalīt viņus pa grupām atkarībā no tā, kā viņi ir atraduši konkrēto resursu. Vienkārši izsakoties savai mājas lapai padodot līdzi pāris parametrus pie adreses, GA sapratīs no kurienes nāk lietotājs. Kopā ir pavisam 5 dažādi GA specifiski parametri, taču mums pietiks ar 3 galvenajiem: - **utm_source**: avots no kurienes lietotājs ir atnācis. Standarta gadījumā šajā parametrā norāda lapas adresi no kuras nāk lietotājs. Piemēram, ja jūs savu spēli reklamējat gan draugiem.lv iekšienē izmantojot aktivitātes, notifikācijas, runā ierakstus un, piemēram, twitter, tad vienā gadījumā utm_source mainīgajā norādiet draugiem.lv, otrā twitter.com - **utm_medium**: medijs, no kura lietotājs ir atnācis uz jūsu lapu. Šajā gadījumā jūs varat brīvi norādīt no kurienes lietotājs ir atnācis. Es ieteiktu šajā parametrā izmantot atslēgvārdus "blog", "say", "activities", "notifications", utt., lai jūs varētu saprast kādā veidā pie jums atnāk apmeklētājs. - **utm_campaign**: kampaņa - iespēja spēlēties ar dažādiem tekstiem un novērtēt kurš no tiem labāk strādā. Piemēram jūs draugu aktivitātēs spēlējaties ar diviem dažādiem tekstiem un atkarībā no tā, kuru no tekstiem jūs izmantojat, jūs padodat atšķirīgus kampaņu identifikatorus. Tā kā aktivitātes atsevišķiem lietotājiem mainās visai lēni, tad droši vien saprātīgi būtu arī pievienot klāt kampaņai datumu, kad šī aktivitāte ir publicēta. Būtībā šis ir veids, kā izveikt vienkāršus A/B testus aktivitāšu ietvaros. Tas, kas jums ir nepieciešams, lai uzsāktu mērījumus - vienkārši pievienojiet šos parametrus savām saitēm. Piemēram: ## Rezultātu mērīšana Ķeramies pie rezultātu mērīšanas - autorizējamies savā GA kontā, dodamies uz spēles profilu, zem "Traffic sources" meklējam Campaigns. Izvēlamies sevi interesējošo laika periodu un skatamies rezultātus. Pēc noklusējuma šajā skatā tiek rādīti kampaņu rezultāti jeb apmeklējums sadalīts pa mūsu utm_campaign mainīgajā norādītajām vērtībām. Kā redzams pievienotajā attēlā, tad šajā testā basictext_20110617 ir sasniedzis stipri lielāku atdevi piesaistīto apmeklētāju skaita ziņā. Te papildus katram izstrādātājam varētu būt vērtīgi arī paanalizēt pārējos parametrus, piemēram, spēlē pavadīto laiku (Time on site), jauno apmeklējumu skaitu (New Visits), atkritušo lietotāju skaitu (Bounce rate).: ![/applications/img/ga/utm_campaign.png](https://draugiem.eu/applications/img/ga/utm_campaign.png) Tālāk varam pārslēgties uz apmeklējumu sadalījumu pa medijiem jeb utm_medium parametrā norādīto vērtību: ![/applications/img/ga/switch.png](https://draugiem.eu/applications/img/ga/switch.png) Kā redzams, tad šajā konkrētajā gadījumā (dati izdomāti) vislielākā atdeve jaunu lietotāju ziņā ir bijusi tieši ierakstam dienasgrāmatā, bet aktivitātes, profila jaunumi un runā plūsma ir devusi vien visai nelielu atdevi. Te tāpat, kā iepriekš ir iespējams papētīt smalkāk rezultātus - no kurienes ir visvairāk iegūti jauni lietotāji, no kurienes atnākušie lietotāji pavada vairāk laika spēlē, utt. ![/applications/img/ga/utm_medium.png](https://draugiem.eu/applications/img/ga/utm_medium.png) Visbeidzot var novērtēt arī sadalījumu pa apmeklētāju avotiem - utm_source norādītās vērtības. Pārslēgšanās tāpat, kā iepriekš uz "utm_medium" parametru, tikai šoreiz jāizvēlas source. ![/applications/img/ga/utm_source.png](https://draugiem.eu/applications/img/ga/utm_source.png) Tā kā mūsu gadījumā vienīgā vieta, kur esam reklamējuši savu spēli ir draugiem.lv, tad nekā diži interesanta šeit nav. Ņemiet vērā, ka šis ir tikai pats pats pamats no tā, ko var dabūt ārā no dažādām analītikas sistēmām un jo vairāk jūs piedomāsiet pie tā, kādas aktivitātes dod īsto atdevi aplikācijai, jo labākus rezultātus jūs sasniegsiet. --- # Draugiem.lv logo ## Draugiem.lv logo - horizontāls ![](https://draugiem.eu/applications/img/logos/draugiem_logo_rgb_small.png) **[Lejupielādēt .pdf (CMYK drukai)](https://draugiem.eu/applications/img/logos/draugiem_logo_cmyk.pdf)** **[Lejupielādēt .pdf (RGB)](https://draugiem.eu/applications/img/logos/draugiem_logo_rgb.pdf)** **[Lejupielādēt .png (RGB)](https://draugiem.eu/applications/img/logos/draugiem_logo_rgb.png)** **[Lejupielādēt .svg (RGB)](https://draugiem.eu/applications/img/logos/draugiem_logo_rgb.svg)** ## Draugiem.lv logo - vertikāls ![](https://draugiem.eu/applications/img/logos/draugiem_logo_v_rgb_small.png) **[Lejupielādēt .pdf (CMYK drukai)](https://draugiem.eu/applications/img/logos/draugiem_logo_v_cmyk.pdf)** **[Lejupielādēt .pdf (RGB)](https://draugiem.eu/applications/img/logos/draugiem_logo_v_rgb.pdf)** **[Lejupielādēt .png (RGB)](https://draugiem.eu/applications/img/logos/draugiem_logo_v_rgb.png)** **[Lejupielādēt .svg (RGB)](https://draugiem.eu/applications/img/logos/draugiem_logo_v_rgb.svg)** ## Draugiem.lv logo - mobilā aplikācija ![](https://draugiem.eu/applications/img/logos/draugiem_logo_ios_small.png) **[Lejupielādēt (PNG)](https://draugiem.eu/applications/img/logos/draugiem_logo_ios.png)** ## "Ieteikt draugiem" pogas ![](https://draugiem.eu/applications/img/logos/say1.png) ![](https://draugiem.eu/applications/img/logos/say2.png) ![](https://draugiem.eu/applications/img/logos/say3.png) ## Draugiem.lv Pases pogas ![](https://draugiem.eu/applications/img/logos/passport/pase1.png) ![](https://draugiem.eu/applications/img/logos/passport/pase2.png) ![](https://draugiem.eu/applications/img/logos/passport/pase3.png) ![](https://draugiem.eu/applications/img/logos/passport/pase4.png) ![](https://draugiem.eu/applications/img/logos/passport/pase5.png) ![](https://draugiem.eu/applications/img/logos/passport/pase6.png) ![](https://draugiem.eu/applications/img/logos/passport/pase7.png) ![](https://draugiem.eu/applications/img/logos/passport/pase8.png) ![](https://draugiem.eu/applications/img/logos/passport/pase9.png) ![](https://draugiem.eu/applications/img/logos/passport/pase10.png) ![](https://draugiem.eu/applications/img/logos/passport/pase11.png) ![](https://draugiem.eu/applications/img/logos/passport/pase12.png)