Spēles

Aktuāla informācija Aktuālā informācija par draugiem.lv API jaunumiem ir pieejama Google e-pasta grupā: Draugiem.lv API developer group.
Saņem aktuālāko informāciju savā e-pastā!

API dokumentācija

Integrācijas

Cita informācija

API dokumentācija angliski

Draugiem.lv API PHP library

Table of Contents

1. Introduction
2. User data representation in PHP library
3. Session handling
4. Accessing user data outside the session
5. API library methods

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

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

include 'DraugiemApi.php';//API library include

$app_key = 'd6949661ccde33a65d98653043bc3119';//Application API key
$app_id = 999;//Application ID

//Create API class instance
$draugiem = new DraugiemApi($app_id, $app_key);

//Starts PHP session
session_start();

if($draugiem->getSession()){

        //Authentication successful
        //Application can now access user data via API

        $user = $draugiem->getUserData();//Basic profile info

        //Print a greeting
        if($user['img']){
                echo '<img src="'.$user['img'].'" alt="" /><br />';
        }
        echo 'Hi, '.$user['name'].' '.$user['surname'].'!<br />';

        $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.:

$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} <a href="{$link}">{text}</a>. 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} <a href="{$link}">{text}</a>. 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 <head> 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 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.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