JavaScript SDK

The JavaScript SDK enables you to access all of the features of the Viadeo GRAPH API via JavaScript. Many functions in the JavaScript SDK require an API key. You can create an API key to be used with the JavaScript SDK via the request a Viadeo API key form.

Access GitHub repository : https://github.com/viadeo/api-sdk-js

Usage

Load the SDK using the standard <script> element and calling VD.init() method. Below is an example of initializing the SDK with all the usual options activated:

<script src="http://cdn.viadeo.com/javascript/sdk.js"></script>
<script>
    VD.init({
        apiKey: 'YOUR API KEY',
        status: true,   // check login status
        cookie: true   // enable cookies to allow the server to access the session
    });
</script>

Authentication

The Viadeo JavaScript SDK allows your users to login using their Viadeo account details and authorise your site or app to access their profile information and professional social graph. This will allow them to edit their own content from your site and publish items to Viadeo.

SSL

Please note that all calls made via the Viadeo Javascript SDK must be done over SSL (using https).

Status & Sessions

The first step is figuring out how you identify who the current user is and how to make API calls on their behalf. In fact, almost half of the public API deals directly with Auth:

• VD.getLoginStatus() – get current login status from viadeo.com
• VD.login() – login via the Viadeo platform
• VD.logout() – logout (only if the user is connected with your site)
• VD.getSession() – synchronous accessor for the current session

In addition, there many events that you can subscribe to using VD.Event.subscribe():

• auth.statusChange
• auth.sessionChange
• auth.login
• auth.logout

API Calls

Viadeo provides many server-side APIs to enable you to integrate data from Viadeo into your site, as well as allowing you to submit data into Viadeo. The JavaScript SDK makes all this available to you via VD.api():

VD.api('/me', function(response) {
    alert('Hello ' + response.name);
});

Methods

VD.api

Server-side calls are available via the JavaScript SDK that allow you to build rich applications that can make API calls against the Viadeo servers directly from the user’s browser. This can improve performance in many scenarios, as compared to making all calls from your own server. It can also help reduce or even eliminate the need to proxy the requests through your own servers, freeing them to do other things.

The range of APIs available covers virtually all facets of Viadeo. Public data are available with no specific authentication. Various parts of the API are available depending on the authenticated status and the permissions the user has granted your application.

The VD.api() method is used to call the API ressources. Except the path, all arguments to this method are optional.

If you have an authenticated user, get their User Object:

VD.api('/me', function(response) {
    alert('Hello ' + response.name);
});

Parameters

VD.getSession

Synchronous accessor for the current session. The synchronous nature of this method is what sets it apart from the other login methods. It is similar in nature to VD.getLoginStatus(), but it just returns the session. Many parts of your application already assume the user is connected with your application. In such cases, you may want to avoid the overhead of making asynchronous calls.

NOTE: You should never use this method at page load time. Generally, it is safer to use VD.getLoginStatus() if you are unsure.

Returns

The current session if available, null otherwise.

VD.getLoginStatus

Find out the current status from the server and get a session if the user is connected.

The user’s status or the question of who is the current user is the first thing you will typically start with. For the answer, we ask viadeo.com. Viadeo will answer this question in one of two ways:

• Someone you don’t know.
• Someone you know and have interacted with. Here’s a session for them.

Here’s how you find out:

VD.getLoginStatus(function(response) {
    if (response.session) {
        // logged in and connected user, someone you know
    } else {
        // no user session available, someone you dont know
    }
});

The example above will result in the callback being invoked once on load based on the session from www.viadeo.com. JavaScript applications are typically written with heavy use of events, and the SDK encourages this by exposing various events. These are fired by the various interactions with authentication flows, such as VD.login().

Events

• auth.login This event is fired when your application first notices the user (in other words, gets a session when it didn’t already have a valid one).
• auth.logout This event is fired when your application notices that there is no longer a valid user (in other words, it had a session but can no longer validate the current user).
• auth.sessionChange This event is fired for any auth related change as they all affect the session: login, logout, session refresh. Sessions are refreshed over time as long as the user is active with your application.
• auth.statusChange Typically you will want to use the auth.sessionChange event. But in rare cases, you want to distinguish between these three states: * Connected * Logged into Viadeo but not connected with your application * Not logged into Viadeo at all.

The VD.Event.subscribe and VD.Event.unsubscribe functions are used to subscribe to these events. For example:

VD.Event.subscribe('auth.login', function(response) {
    // do something with response
});

The response object returned to all these events is the same as the response from VD.getLoginStatus, VD.login or VD.logout. This response object contains:

• status The status of the User. One of connected, notConnected or unknown.
• session The session object.

Parameters

VD.login

Once you have determined the user’s status, you may need to prompt the user to login. It is best to delay this action to reduce user friction when they first arrive at your site. You can then prompt and show them the “Connect with Viadeo” button bound to an event handler which does the following:

VD.login(function(response) {
    if (response.session) {
        // user successfully logged in
    } else {
        // user cancelled login
    }
});

You should only call this on a user event as it opens a popup. Most browsers block popups, unless they were initiated from a user event, such as a click on a button or a link.

Depending on your application’s needs, you may need additional permissions from the user. A large number of calls do not require any additional permissions, so you should first make sure you need a permission. This is a good idea because this step potentially adds friction to the user’s process. Another point to remember is that this call can be made even after the user has first connected. So you may want to delay asking for permissions until as late as possible:

VD.login(function(response) {
    if (response.session) {
        if (response.session.scope) {
            // user is logged in and granted some permissions.
            // perms is a comma separated list of granted permissions
        } else {
            // user is logged in, but did not grant any permissions
        }
    } else {
        // user is not logged in
    }
});

Parameters

VD.logout

Logout the user in the background.

Just like logging in is tied to viadeo.com, so is logging out – and this call logs the user out of both Viadeo and your site. This is a simple call:

VD.logout(function(response) {
    // user is now logged out
});

NOTE: You can only log out a user that is connected to your site.

Parameters

VD.Event.subscribe

Subscribe to a given event name, invoking your callback function whenever the event is fired.

For example, suppose you want to get notified whenever the session changes:

VD.Event.subscribe('auth.sessionChange', function(response) {
    // do something with response.session
});

Parameters

VD.Event.unsubscribe

Removes subscribers, inverse of VD.Event.subscribe.

Removing a subscriber is basically the same as adding one. You need to pass the same event name and function to unsubscribe that you passed into subscribe. If we use a similar example to VD.Event.subscribe, we get:

var onSessionChange = function(response) {
    // do something with response.session
};

VD.Event.subscribe('auth.sessionChange', onSessionChange);

// sometime later in your code you dont want to get notified anymore
VD.Event.unsubscribe('auth.sessionChange', onSessionChange);

Parameters