VZ-ID JS-Library

From VZ Developer Wiki

(Redirected from JS-Library)
Jump to: navigation, search

VZ offers a JS-Library for easy implementation of VZ features such as Login or Bookmarking on your site.

The Library will be publicly available by mid November.

Contents

How to include the library

Just include the JavaScript at

http://static.pe.studivz.net/Js/id/v4/library.js

or https://secure.studivz.net/Js/id/v4/library.js

into your site.

You also have to specify the target VZ host for your library. Depending on your doctype, this can be done in the data-authority attribute.

The best VZ host values is our PlatformRedirector which tries to direct the user in the current browser to the right platform automatically

  • platform-redirect.vz-modules.net/r

Or you can call the target platform directly

  • www.studivz.net
  • www.meinvz.net
  • www.schuelervz.net

Additionally you have to specify an SSL endpoint in the data-authorityssl attribute. Possible values are:

  • platform-redirect.vz-modules.net/r
  • secure.studivz.net
  • secure.meinvz.net
  • secure.schuelervz.net

The correct protocol is chosen automatically.

Example: 

<script src="http://static.pe.studivz.net/Js/id/v2/library.js" 
data-authority="platform-redirect.vz-modules.net/r"
data-authorityssl="platform-redirect.vz-modules.net/r" type="text/javascript"></script>
<script src="http://static.pe.studivz.net/Js/id/v2/library.js" 
data-authority="www.meinvz.net"
data-authorityssl="secure.meinvz.net" type="text/javascript"></script>

If you want to use the vz/feedBox widget you may also want to include the following CSS file: 

<link rel="stylesheet" type="text/css" 
href="http://static.pe.studivz.net/Js/id/v2/library.css" />

However you can also style the feedbox on your own.

Widgets

The JS-library provides several widgets that you can easily include into your site:

Parameters for all widgets

Optional
id: id attribute for the widget container

Sharing

Type
vz/share
Parameters
Required
url (default: current url)
Optional
title
description
thumbnail
provider
Example 
<script type="vz/share">
   id: shareButton
   title: title of your site
   description : a description
</script>

If optional parameters are not specified VZ tries to retrieve this information through the OpenGraph protocol see Sharing for details.

Login & API Authorization

Type
vz/login
Parameters
Required
client_id
callback
type (default: user_agent)
response_type (default: token)
scope (default: openid)
Optional
redirect_uri
fields
message
state
Example 
<script type="text/javascript">
    function logResponse(c) { console.log(c); }
</script>
<script type="vz/login">
   client_id : 1234567890abcdef
   redirect_uri : http://example.com/callback.html
   callback : logResponse
   fields : name,emails
</script>

Your callback.html has to be on the same domain as the site implementing the Login button and my look like this: 

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title></title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
      <script type="text/javascript">
        opener.vz.id.authStorage.setAuthParameterHash(location.hash.substr(1));
        window.close();
      </script>
  </body>
</html>

The callback method then gets an object with an access token and user identifier passed as a parameter.

From there you can easily call the OpenSocial REST Api: 

function logResponse(c) { 
  if (c.error) {
    return;
  }
  var url = c.user_id;
  vz.id.login.callApi(url, function(data) {
    console.log(data.entry.displayName);
  });
}

The vz.id.login.callApi method adds all necessary OAuth parameters automatically. See VZ-Login for details and APIs that you can access with this access token.

Alternatively you can also transport the retrieved access token and user identifier to your backend, so that you can request the OpenSocial API from there and directly store the user information in your database. The easiest way to do this is through a cookie, that is set in your JavaScript client and retrieved and validated in your backend. 

function logResponse(c) { 
  if (c.error) {
    return;
  }
 
  var parameters = 'access_token=' + c.access_token;
  parameters += '&user_id=' + c.user_id;
  parameters += '&signature=' + c.signature;
  parameters += '&issued_at=' + c.issued_at;
 
  document.cookie = 'vz' + '_' + c.client_id + '=' + encodeURIComponent(parameters);
}

In your backend you then have to verify the cookie like this: 

$cookie = array();
parse_str($_COOKIE['vz' . $clientId], $cookie);
$baseString = $cookie['access_token'] . $cookie['issued_at'] . $cookie['user_id'];
$signature = base64_encode(hash_hmac('sha1', $baseString, $consumerSecret, true));;
if ($signature !== $retrievedSignature) {
    throw new Exception('invalid signature');
}

Post to feed

Type
vz/feed
Parameters
Required
message
Optional
url
Example 
<script type="vz/feed">
   message: your status update message
   url: http://embeddable/url
</script>

The widget behaves similar as the corresponding app method described in Lesson_22:_Posting_a_status_update_for_an_user

Type
vz/feedBox
Parameters
Optional
message
url
Example 
<script type="vz/feedBox">
   message: default message for input box
   url: http://embeddable/url
</script>

See Post_to_feed for details.

Retrieved from "http://developer.studivz.net/wiki/index.php/VZ-ID_JS-Library"
Personal tools