Intégrer Famust sur son site

Préambule

La documentation suivante vous indique comment installer les widgets Famust sur votre propre application web, et comment utiliser l'API Famust.

Ci-contre un exemple de widget Famust. Le widget s'installe en quelques instants et vous permet très rapidement d'afficher sur votre site le Profil Famust de vos utilisateurs.

Famust fournit également une API RESTful qui vous permet de récupérer toutes les informations que vous souhaitez afin de les mettre en forme à votre guise sur votre site.

Sommaire de la doc

  1. Enregistrer votre application
  2. Obtenir le consentement des utilisateurs
    1. Workflow
    2. Installer le script Famust sur vos pages
    3. Installer le Famust Connect
    4. Récupérer un requestCode
    5. Utiliser le request code pour récupérer un jeton d'accès et les informations de l'utilisateur
  3. Installer le widget Profil Famust
  4. API Famust
    1. Utilisation de l'API
    2. Index de l'API

1 - Enregistrer votre application

Avant de pouvoir intégrer les widgets Famust ou de pouvoir faire des requêtes sur l'API Famust, vous devez au préalable enregistrer votre application en envoyant un email à contact@famust.com précisant :

  • Le nom de votre application web,
  • L'url de votre application web,
  • Une image au format carré (minimum 150x150px) représentant votre application,
  • Une adresse email de contact.

Vous recevrez alors votre client_id (Identifiant Client) et votre secret_key (Code secret Client).

Ne divulguez jamais votre secretKey. Si un tiers venait à l'obtenir, il pourrait l'utiliser pour obtenir des informations privées des utilisateurs ayant donné leur accord pour partager leurs informations avec votre application.

2 - Obtenir le consentement des utilisateurs

Pour pouvoir afficher sur votre site le widget Famust contenant le Profil Famust d'un utilisateur, ou pour faire des requêtes à l'API Famust en son nom, vous devez obtenir au préalable l'autorisation de ce dernier.

2-1 - Workflow

L'obtention de l'autorisation d'un utilisateur s'obtient de la manière suivante :

  • Commencez par inclure sur vos pages le bouton Famust Connect.
  • Lorsqu'un de vos utilisateurs clique sur le bouton, une popup s'ouvre lui demandant de se logguer (ou, le cas échéant de s'inscrire) sur Famust.com, puis d'autoriser votre application à accéder à son compte Famust.
  • La popup se referme et un request code est transmis à votre application.
  • Votre serveur peut alors échanger ce request code contre un jeton d'accès qui vous permettra par la suite d'interroger l'API de Famust au nom de cet utilisateur. Vous récupérez également l'identifiant de l'utilisateur qui vous sera nécessaire pour installer les widgets Famust.

workflow API Famust

2-2 - Inclure le script Famust sur vos pages

Copiez les lignes suivantes juste avant votre balise </body>.

            
    <script>
    var 
ZWS = {
        
clientId'Your clientID',
        
sdk: (function() {
            var 
z   document.createElement('script');
            
z.type  'text/javascript';
            
z.src   '//www.famust.com/js/sdk.js';
            
z.async true;
            var 
document.getElementsByTagName('script')[0];
            
s.parentNode.insertBefore(zs);
            return 
z;
        })()
    };
    
</script>

2-3 - Inclure le bouton Famust Connect

Copiez les lignes suivantes à l'endroit où vous souhaitez que le bouton Famust Connect s'affiche.

            
    <div class="zws-connect-button"
    
data-callback="ZWSSignIn"
    
data-label="Importer mes évaluations avec Famust">
    </
div

Vous pouvez personnaliser les paramètres suivants :

Paramètre Type Par défaut Obligatoire Description
data-callback String - Obligatoire Nom de la fonction javascript de callback qui est définie par vous même et qui est appelée lorsque l'utilisateur a donné son consentement après avoir cliqué sur le bouton Famust Connect.
data-label String "Importer mes évaluations avec Famust" - Intitulé du bouton Famust Connect.

 

Le bouton suivant s'affichera alors :

2-4 - Récupérer un request code

Lorsque vous avez inclus le bouton Famust Connect, vous avez dû définir un nom de fonction de callback. Une fois que l'utilisateur a donné l'autorisation à votre application, cette fonction est appelée. Un objet représentant le résultat de l'autorisation est transmis à la fonction.

Supposons que vous ayiez nommé votre fonction de callback ZWSSignIn :

            
   <script>
   function 
ZWSSignIn(authResult) {
       if(
authResult.requestCode) {
           
// User granted access. Request code value is in authResult.requestCode
           // You should now transmit this request code to your serveur, either by redirecting the
           // user to a page with requestCode in URI, or through an ajax call.
           // Example :
           
var url 'http://yourwebsite.tld/gettoken.php?requestCode=' encodeURIComponent(authResult.requestCode);
           
document.location.href url;
       }
       else if(
authResult.error){
           
// User refused to grant access to your application.
       
}
   }
   
</script> 

2-5 - Utiliser le request code pour récupérer un jeton d'accès et les informations de l'utilisateur

Supposons que le request code soit transmis à la page yourwebste.tld/gettoken.php conformément à l'exemple ci-dessus, cette page pourra récupérer un jeton d'accès en interrogeant l'API Famust de la manière suivante :

            
    <?php
    
if(isset($_GET['requestCode'])) {
        
// Use of Famust library to communicate with Famust API.
        // See section 4.1 to download this library.
        
require 'zws_client.php';

        
$zws = new ZWS_Client('1.0'); // replace 1.0 by the version of the API you want to use.
        
$zws->setClientId('Your Client Id');
        
$zws->setSecretKey('Your Secret Key');

        
$request $zws->get(array( 
            
'endPoint' => '/request_codes/'.$_GET['requestCode'].'/tokens'
            
)
        );

        if(
$request->http_code != 200) {
            
// Handle error here. $request->description contains a description of the error.
            
exit('Request failed : '.$request->description.' (http status code : '.$request->http_code.')');
        } else {
            
// Famust user id is in $request->user_id
            // Access token for this user is in $request->access_token
            // You can now store these values in your database.
        
}
    }
    
?>

3 - Installer le widget Profil Famust

Vous devez au préalable inclure dans vos pages qui contiendront le widget le script défini à la section 2.2. Collez ensuite les lignes suivantes à l'endroit où vous souhaitez que le widget s'affiche.
            
   <div class="zws-zenpass"
   
data-uid="User ID you want to display the Famust Profile"
   
data-width="300"></div

Vous pouvez personnaliser les paramètres suivants :

Paramètre Type Par défaut Obligatoire Description
data-uid Int - Obligatoire Identifiant Famust de l'utilisateur dont vous souhaitez afficher le Profil Famust, obtenu à l'étape 2-5.
data-width Int 300 - Largeur du Profil Famust, en pixels (ne pas préciser d'unité, ex : "300") ou en pourcentage (ex : "100%").
data-username String show - Pour ne pas afficher le pseudo de l'utilisateur sur le Profil Famust, ce paramètre doit valoir "hide".

4 - API Famust

4-1 - Utilisation de l'API

L'API Famust est une API RESTful classique. Commencez par télécharger le client php qui vous servira à passer des appels à l'API Famust.

Les appels vers l'API se font de la manière suivante :

            
    <?php
    
require 'zws_client.php';
    
    
$zws = new ZWS_Client('1.0');
    
$zws->setClientId('Your Client Id');
    
$zws->setSecretKey('Your Secret Key');
    
    
// Example of an API call. This request will get an user id and an access token.
    
$request $zws->get(array(
        
// please refer to API index to have the list of available endpoints.
        
'endPoint' => '/request_codes/'A request code .'/tokens'
        
));
    
    if(
$request->httpStatusCode != 200) {
        
// Handle error here. $request->error contains a description of the error.
        
exit('Request failed : '.$request->error.' (http status code : '.$request->httpStatusCode.')');
    }
    
    echo 
'UserId is '.$request->userId.'<br>';
    echo 
'Access token for this user is '.$request->accessToken;
    
?>

4-2 - Index de l'API

GET /auth

Description:
Permet d'obtenir un jeton d'accès pour votre application, pour les appels vers l'API nécessitant un jeton d'accès d'application.

Remarque : le client php mis à votre disposition pour interagir avec notre API gère lui-même l'obtention des jetons d'accès pour votre application.

Paramètres :

  • client_id : votre identifiant client.
  • secret_key : votre clef secrète.

Valeur de retour :

            {
                app_token : "An application token"
            }
                

GET /request_codes/{requestCode}/tokens

Description :
Retourne un jeton d'accès pour faire des appels à l'API au nom d'un utilisateur. {requestCode} est le code obtenu lorsque l'utilisateur a donné son autorisation pour votre application.

Paramètres :

  • app_token : jeton d'application obtenu via un appel vers /auth. Si vous utilisez le client php mis à votre disposition, il n'est pas nécessaire d'indiquer un app_token, le client s'en charge automatiquement.

Exemple d'utilisation :

            
    <?php
    
...
    
$request $zws->get(array(
        
'endPoint' => "/request_codes/$requestCode/tokens",
        ));
    ...
    
?>

Valeur de retour :

        {
            access_token: "An Access Token",
            user_id: "Id of the user this token grants access to"
        }
            

GET /users/{id}

Description :
Renvoie les informations personnelles de l'utilisateur dont l'identifiant est {id}. Cet appel nécessite d'être en possession d'un jeton d'accès pour cet utilisateur (cf. obtenir le consentement des utilisateurs).

Paramètres :

  • access_token : jeton d'accès pour l'utilisateur.

Exemple d'utilisation :

            
    <?php
    
...
    
$request $zws->get(array(
        
'endPoint' => "/users/$userId",
        
'params' => array(
            
'access_token' => $accessToken
            
)
        ));
    ...
    
?>

Valeur de retour :
Un objet JSON ayant les propriétés suivantes :

Propriété Type Description
email String Adresse email de l'utilisateur.
email_confirmed Bool True si l'utilisateur si l'adresse email a été vérifiée.
first_name String ou NULL Prénom de l'utilisateur. NULL s'il ne l'a pas fourni.
last_name String ou NULL Nom de l'utilisateur. NULL s'il ne l'a pas fourni.
username String Pseudo de l'utilisateur.
photo_url URL ou NULL Adresse de la photo de profil de l'utilisateur. NULL s'il n'a pas uploadé de photo de profil.
profile_count Int Nombre de comptes que l'utilisateur a importé sur son Profil Famust.
comment_count Int Nombre de commentaires que l'utilisateur a sur son Profil Famust.
grade Float between 0 and 5, or NULL Moyenne des évaluations reçues par l'utilisateur. NULL s'il n'a pas eu d'évaluations.
wordcloud Object Liste des mots clés retournés :
Propriété Type Description
word String Mot clé.
relevance Int Niveau de pertinence.

GET /users/{id}/comments

Description :
Renvoie les commentaires reçus par l'utilisateur dont l'identifiant est {id}, du plus récent au plus ancien. Cet appel nécessite d'être en possession d'un jeton d'accès pour cet utilisateur (cf. obtenir le consentement des utilisateurs).

Paramètres :

  • accessToken : jeton d'accès pour l'utilisateur,
  • limit : nombre maximal de commentaire à retourner (par défaut : 100. Max : 100),
  • offset : numéro du commentaire à partir duquel commencer (par défaut : 0).

Exemple d'utilisation : obtenir 10 commentaires à partir du 1er.

            
    <?php
    
...
    
$request $zws->get(array(
        
'endPoint' => "/users/$userId",
        
'params' => array(
            
'access_token' => $accessToken,
            
'offset' => '0',
            
'limit' => '10'
            
)
        ));
        
    ... 
// handle errors if any;
    
    
foreach($request->data as $comment) {
        
// $comment->content : comment itself,
        // $comment->date : the comment's posted date,
        // $comment->grade : grade given by author, if any,
        // $comment->author_url : web url of the author's profile, if any
    
}
    ...
    
?>

Valeur de retour :
Un objet JSON ayant les propriétés suivantes :

Propriété Type Description
offset Int Offset de la réponse.
limit Int Limit de la réponse.
data Object Liste des commentaires retournés :
Propriété Type Description
content String Contenu du commentaire.
grade Float between 0 and 5, or NULL Note rattachée à ce commentaire. NULL si inexistante.
date String (YYYY-MM-DD), or NULL Date du commentaire, NULL is inconnue.
author_url URL, or NULL Url du profil de l'auteur du commentaire, NULL si inconnue.