JSApi v0.6

SDK du Répertoire des applis

JSApi (v0.6, obsolète)

Fonctionnement

JSApi est le portail de communication SDK du Répertoire des applis entre votre appli et le tableau de bord Hootsuite. L'API permet aux développeurs d'applis d'appeler des fonctions qui envoient des événements au tableau de bord Hootsuite et de recevoir des notifications spécifiques aux événements du tableau de bord Hootsuite directement depuis une appli.

Les interactions entre Hootsuite et votre appli sont permises par deux fichiers :

  • Api JS : la bibliothèque Javascript SDK, hsp.jc, fournit des fonctions qui apporteront des fonctionnalités spécifiques au tableau de bord Hootsuite. hsp.js permet également d'initialiser et d'enregistrer votre appli pour recevoir des événements depuis le tableau de bord Hootsuite via un récepteur d'applis hébergé par votre appli.
  • Récepteur d'applis : le récepteur d'applis permet à votre application de recevoir des événements depuis le tableau de bord Hootsuite. De façon plus spécifique, le récepteur est obligatoire pour le bon fonctionnement de la fonction hsp.bind() décrite ci-dessous.

Configuration

 
Les fichiers suivants sont obligatoire pour utiliser l'API JS :

  • Bibliothèque JS : la bibliothèque hsp.js permet une communication bidirectionnelle entre votre appli et le tableau de bord Hootsuite. Ajoutez ce fichier dans la page principale de votre appli : https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/hsp.js
     
    Par exemple, la référence vers ce fichier dans votre page principale peut apparaître comme suit :
    <script src="https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/hsp.js"></script>
  • Récepteur d'applis : le récepteur d'applis permet à votre application de recevoir des événements depuis le tableau de bord Hootsuite. De façon plus spécifique, le récepteur est obligatoire pour le bon fonctionnement des fonctions hsp.bind() et hsp.updatePlacementSubtitle(). Ce fichier doit être téléchargé, placé à la racine du répertoire racine de l'appli hébergée, puis référencé par la fonction hsp.init() dans les paramètres receiverPath (URL HTTPS).https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/my_receiver.html

Fonctions d'API & Événements

La communication de votre appli vers le tableau de bord Hootsuite se fait en utilisant les fonctions disponibles dans hsp.js.
 
La communication du tableau de bord Hootsuite vers votre appli s'effectue au moyen des événements. Les événements pour lesquels votre appli souhaite recevoir des notifications sont enregistrés avec des appels à la fonction hsp.bind() indiquant l'événement d'intérêt et la fonction callback que votre appli va exécuter lorsque l'événement sera déclenché.

Fonctions

  • init : initialise l'API JS
  • bind : inscrit un événement du tableau de bord Hootsuite qui doit être géré avec l'appli et un gestionnaire d'événement associé
  • clearStatusMessage : supprime tous les messages de statut actuellement visibles
  • composeMessage : ouvre la boîte de dialogue Partager sur les réseaux sociaux
  • retweet : débute le processus de boîte de dialogue de retweet
  • customUserInfo : ouvre une fenêtre pop-up d'information sur l'utilisateur
  • getTwitterAccounts : obtient une liste de tous les profils Twitter pour l'utilisateur connecté
  • showCustomPopup : affiche une boîte de dialogue pop-up modale contenant une iFrame avec du contenu spécifique à l'appli
  • closeCustomPopup : ferme la boîte de dialogue pop-up modale
  • showFollowDialog : ouvre une boîte de dialogue pour s'abonner ou se désabonner d'un compte Twitter
  • showImagePreview : affiche une image dans une fenêtre pop-up
  • showStatusMessage : affiche une notification
  • showUser : ouvre un pop-up d'information sur l'utilisateur
  • updatePlacementSubtitle : met à jour le sous-titre du flux d'application
  • assignItem : attribue du contenu sous forme de texte à un utilisateur Hootsuite

Événements

  • closepopup : se lance lorsqu'un pop-up personnalisé, ouvert par votre flux d'application, est refermé
  • dropuser : se lance lorsqu'un utilisateur fait un glisser & déposer avec un avatar de compte Twitter depuis le tableau de bord Hootsuite vers votre flux d'application
  • refresh : se lance lorsque la colonne de l'appli est actualisée, soit par l'utilisateur au sein du flux, soit lors de l'actualisation du tableau de bord
  • sendtoapp : l'inscription à cet événement permettra aux utilisateurs d'accéder à un item de menu Send to <app stream>… dans les menus de message de flux de LinkedIn, Facebook et Twitter. Cet événement se lance lorsque l'utilisateur clique sur l'item de menu
  • sendcomposedmsgtoapp : ajoute un plug-in d'application au sélecteur de profil natif du réseau social Hootsuite. L'utilisateur peut envoyer des messages au plug-in directement depuis la zone de composition de message d'Hootsuite
  • sendprofiletoapp : l'inscription à cet événement permettra aux utilisateurs d'accéder à un item de menu dans les menus de profil des pages Google+, LinkedIn, Facebook et Twitter. L'événement se lance lorsque l'utilisateur clique sur l'item de menu
  • sendassignmentupdates : l'inscription à cet événement permettra à une appli d'être notifiée des mises à jour qui lui sont attribuées

hsp.init(params)

Initialise l’API JS et charge les fichiers CSS de thème.

params : object :

  • apiKey : (string)
  • receiverPath: (string, facultatif)
     L'URL absolue de votre fichier app_receiver.html. Doit obligatoirement commencer par https://
  • subtitle : (string, facultatif)
     Le sous-titre de votre appli qui sera affiché dans le titre du flux.
  • callBack : (function, facultatif)
     Init renverra un message d'erreur à la fonction callBack à l'issue de l'initialisation. Le message est : Pas d'erreur, si l'initialisation est réussie.

Exemple :

hsp.init({ apiKey: 'abcd123', receiverPath: 'https://app.domain.com/my_receiver.html', callBack: function( message ){ console.log('Error: ' + message); } });

hsp.bind(eventName, callback)

Consigne un gestionnaire d'événement pour un événement spécifique.

Remarque : nécessite que le récepteur d'applis soit configuré.

eventName : (string)

Le nom de l'événement à gérer peut être l'un des suivants :

  • closepopup : se lance lorsqu'un pop-up personnalisé, ouvert par votre flux d'application, est refermé
  • dropuser : se lance lorsqu'un utilisateur fait un glisser & déposer avec un avatar de compte Twitter depuis le tableau de bord Hootsuite vers votre flux d'application
  • refresh : se lance lorsque la colonne de l'appli est actualisée, soit par l'utilisateur au sein du flux, soit lors de l'actualisation du tableau de bord
  • sendtoapp : l'inscription à cet événement permettra aux utilisateurs d'accéder à l'item de menu Send to <app stream>... dans les menus de message de flux de Facebook et Twitter. Cet événement se lance lorsque l'utilisateur clique sur l'item de menu

callback : (function)

Fonction permettant de gérer les rappels, les paramètres de la fonction sont déterminés par cet événement. Consultez la section des événements pour plus de détails sur les formats attendus de rappel.

Exemple :

hsp.bind('refresh', function () { window.location.reload(); });

Comme expliqué dans la section Bonnes pratiques, il est logique de supprimer le rechargement du flux lorsque l'utilisateur interagit avec lui (exemple : publication de messages, détails étendus ou bien position de défilement loin du haut de la page). Une approche possible pourrait ressembler à ceci :

hsp.bind('refresh', function () { // collect any text the user has entered into a comment entry box $(".hs_commentEntry textarea").each(function () { comments += $(this).val(); }); // comment entry boxes are empty and user has not scrolled down more than 15px if (comments === '' && $(window).scrollTop() < 15) { window.location.reload(); } });

L'utilisation de window.location.reload() n'est manifestement pas la meilleure approche et n'a servi que pour la simplicité des exemples. L'une des solutions les plus élégantes serait de rapidement vérifier les nouveaux messages en utilisant AJAX et d'injecter uniquement les nouveaux messages dans le DOM tout en conservant intacts les messages existants.

hsp.clearStatusMessage()

Supprime tous les messages de statut actuellement visibles.

hsp.composeMessage(message, params)

Ouvre la boîte de dialogue Partager sur les réseaux sociaux dans le tableau de bord Hootsuite.

message : (string)

Les règles des messages Twitter s'appliquent ; par exemple, pour envoyer un message direct à @Hootsuite, il faut écrire : d Hootsuite <votre message ici>

params : (object, facultatif) :

  • shortenLinks : bool, facultatif
     Raccourcit tous les liens présents dans les messages avec le raccourcisseur d'URL par défaut de l'utilisateur (ow.ly / ht.ly / ou une url personnalisée). Prend la valeur false par défaut.
  • timestamp : bool OU int, facultatif
     Ouvre le planificateur et y inscrit l'horodatage (au format GMT) Si la valeur transmise est true, le planificateur s'ouvre alors sans afficher d'heure par défaut. Prend la valeur false par défaut.
  • replyToId : string, facultatif
     Rédige un nouveau tweet en réponse à un tweet existant. Si un identifiant de chaîne valide est transmis pour un tweet existant, alors l'outil de composition traitera le nouveau message dans le cadre de la conversation.

Exemple :

hsp.composeMessage( 'message text', { shortenLinks: true } );

hsp.retweet(id, screenName)

Ouvre le processus de boîte de dialogue de retweet dans le tableau de bord Hootsuite pour le tweet identifié qui doit être retweeté par screenName.

id : (string)

L'id_str tweetId de Twitter pour le tweet à retweeter

screen_name : (string, facultatif)

Le screen_name Twitter avec lequel vous voulez retweeter

Exemple :

hsp.retweet( '369937169529708544', 'Hootsuite' );

hsp.customUserInfo(data)

Ouvre une fenêtre pop-up d'information sur l'utilisateur.

données : (JSON object)

Exemple :

var data = { "fullName": "David Chan", "screenName": "@chandavid", "avatar": "https://d1cmhiswqj5a7e.cloudfront.net/http%3A%2F%2Fplacehold.it%2F30x30%2F444", "profileUrl": "https://twitter.com/chandavid", "userLocation": "Vancouver, BC", "bio": "JavaScript/web/martini developer. Working on @Hootsuite. Making by breaking.", "extra": [ {"label": "Age", "value": "Unknown"}, {"label": "Gender", "value": "Male"} ], "links": [ {"label": "Hootsuite", "url": "https://hootsuite.com"}, {"label": "Blog", "url": "https://blog.hootsuite.com"} ] };

hsp.showCustomPopup(src, title, width, height)

Affiche une fenêtre pop-up modale avec une iFrame montrant du contenu de l'URL spécifiée. Lorsqu'elle se ferme, la boîte de dialogue lance l'événement closePopUp().

src : (string)

L'URL du contenu à afficher dans le pop-up

titre : (string)

Le titre affiché dans la fenêtre pop-up

width : (int)

La largeur en pixels du pop-up. La largeur respecte les contraintes suivantes :

  • Lorsqu'elle n'est pas spécifiée, la largeur est de 640 pixels par défaut
  • La largeur minimum est de 300 pixels.
  • La largeur maximum est de 900 pixels.

height : (int)

La hauteur en pixels du pop-up. La largeur respecte les contraintes suivantes :

  • Lorsqu'elle n'est pas spécifiée, la hauteur est de 445 pixels par défaut
  • La hauteur minimum est de 225 pixels.
  • La hauteur maximum est de 500 pixels.

Exemple :

hsp.showStatusMessage('Done!', 'success') ;

Remarques importantes :

Veuillez ne pas initialiser de nouveau la fonction hsp au sein du pop-up personnalisé. Votre pop-up ne devrait pas être utilisé pour d'autres fonctions hsp que la fonction closeCustomPopup(apiKey, pid).

Si votre pop-up et votre flux/plug-in d'application sont sur le même domaine, il est recommandé que votre pop-up utilise la fonction javascript ci-dessous pour communiquer vers votre flux/plug-in et exécuter la fonction hsp : window.parent.frames[apiKey_pid].hsp.some_function()

Remarque : les fonctions hsp qui lient les événements ne sont pas disponibles depuis le pop-up personnalisé.

hsp.closeCustomPopup(apiKey, pid)

Ferme la fenêtre pop-up modale.

Remarque : Assurez-vous que la page iFrame de la fenêtre pop-up personnalisée et la page de flux d'application partagent le même domaine. Il n'est pas nécessaire (et pas souhaitable) d'appeler de nouveau la fonction hsp.init() dans la page iFrame, incluez simplement hsp.js et appelez hsp.closeCustomPopup(apiKey, pid). Vous pouvez utiliser JavaScript pour communiquer entre le pop-up et le flux comme ceci :

window.parent.frames["<%= apiKey %>_<%= pid %>"].location.reload();

apiKey : (string)

La clé API de votre appli

pid : (string)

Identifiant de placement (pid) associé à chaque installation unique de flux d'application (ou de plug-in). Vous pouvez obtenir le pid de chaque flux d'application depuis la requête URL obtenue par votre serveur. Par exemple :

https://demo.ca/stream.html?lang=en&theme=blue_steel&timezone=-25200&pid=60956&uid=136

hsp.showImagePreview(src, externalUrl)

Affiche une image dans une fenêtre pop-up, peut éventuellement être liée à une URL externe.

src : (string)

URL de l'image

externalURL : (string)

L'URL à ouvrir si l'utilisateur clique sur l'image

hsp.showStatusMessage(message, type)

Affiche une notification en haut et au centre du tableau de bord Hootsuite.

message : (string)

Doit être bref, 70 caractères maximum.

type : (string) :

Peut être l'un des suivants :

  • info : Fond bleu
  • error : Fond rouge
  • warning : Fond jaune
  • success : Fond vert

hsp.updatePlacementSubtitle(name)

Met à jour le sous-titre du flux d'application.

Remarque : nécessite que le récepteur d'applis soit configuré (voir ci-dessus).

name (str)

35 caractères max.

hsp.showUser(twitterHandle)

Ouvre un pop-up d'informations utilisateur pour le nom d'utilisateur Twitter spécifié.

twitterHandle : (string)

Nom d'utilisateur Twitter

Exemple :

hsp.showUser('hootsuite_help');

showUser.f203dc7a

hsp.showFollowDialog(twitterHandle, isFollow)

Ouvre une boîte de dialogue pour s'abonner ou se désabonner d'un compte Twitter.

twitterHandle : (string)

Nom d'utilisateur Twitter

isFollow : (bool)

true pour s'abonner, false pour se désabonner.

Exemple :

hsp.showFollowDialog('hootsuite_help', true);

showFollowDialog.ff5cb783

hsp.getTwitterAccounts(callback)

Obtient une liste (array) de tous les profils Twitter (noms d'utilisateur) que l'utilisateur connecté à ajouté à son compte Hootsuite.

callback : (function)

La fonction accepte les chaînes de tableau (array strings)

Exemple :

// this would log: ["twitteruser_123", "twitter_user_abcd"] hsp.getTwitterAccounts(console.log);

hsp.assignItem(data)

Attribue un message, ou tout contenu sous forme de texte, à un utilisateur Hootsuite (lui-même ou un coéquipier)

données : (JSON object)

Exemple :

var data = { "messageId": "1000020", //REQUIRED "message": "Hi, I'm having an issue with my account", //REQUIRED "userId": 172299, //optional, but recommended "userName": "@chandavid", //optional, but recommended "userAvatar": "https://d1cmhiswqj5a7e.cloudfront.net/http%3A%2F%2Fplacehold.it%2F30x30%2F444", //optional, but recommended "timestamp": 1345051990 //optional, but recommended };

Événements API

Cette section décrit les différents événements disponibles et les signatures des fonctions de gestion des événements attendus accessibles via la fonction hsp.bind().

refresh()

Se lance lorsque la colonne de l'appli est actualisée, soit par l'utilisateur au sein du flux, soit lors de l'actualisation du tableau de bord.

format de rappel : une fonction sans paramètres

Exemple :

function refreshHandler () { }

dropuser()

Se lance lorsqu'un utilisateur fait un glisser & déposer avec un avatar de compte Twitter depuis le tableau de bord Hootsuite vers votre flux d'application
 

format de rappel : une fonction avec deux paramètres, le pseudo Twitter de l'utilisateur et l'identifiant unique du Tweet qui a été glissé par l'utilisateur

Exemple :

function dropUserHandler ( username, tweetId ) { // ... }

sendcomposedmsgtoapp()

Ajoute un plug-in d'applis au sélecteur natif du réseau social Hootsuite. L'utilisateur peut envoyer des messages au plug-in directement depuis la zone de composition de message d'Hootsuite

REMARQUE : Vous devez contacter notre équipe de gestion du Répertoire des applis pour autoriser cet événement de liaison pour votre plug-in d'appli.

format de rappel : un objet javascript qui contient les données du message

Structure de données d'objet message :

Message: (object) text: (string)

Exemple :

function sendComposedMsgToAppHandler (message) { // ... }

closepopup()

Se lance lorsqu'un pop-up personnalisé, ouvert par votre flux d'application, est refermé

format de rappel : une fonction sans paramètres

Exemple :

function closePopupHandler () { // ... }

sendtoapp()

L'inscription à cet événement permettra aux utilisateurs d'accéder à l'item de menu Send to <app stream>… dans les menus de message de flux de Facebook et Twitter. Cet événement se lance lorsque l'utilisateur clique sur l'item de menu.

format de rappel : un objet javascript qui contient les données du message

Structure de données d'objet message :

Message: (object) version: (string) la version actuelle est la 1 post : (object) href: (string) l'url vers l'ID de publication originale : (string) horodateur de l'ID de la publication externe : (string) format horodatage iso 8601 source : (string) uniquement pour twitter, par exemple appli iPhone network: (string) user: (object) userid: (string) uniquement pour facebook et twitter username: (string) attachments: (array) items: (array) target: (string) l'url vers la page de ressource originurl: (string) l'url vers la vraie ressource thumbnailsrc : (string) l'url vers l'intitulé de la vignette : (string) type: (string) link | video | photoalbum | photo content: (object) body: (string) bodyhtml: (string) type: (string) conversations: (array) id: (int/string) uid: (int) name: (string) text: (string) datetime: (string) geo: (string) uniquement pour twitter retweetcount: (string) uniquement pour twitter source: (string) uniquement pour twitter profileurl: (string) uniquement pour facebook likes: (int) uniquement pour facebook

Exemple d'objet message :

( { version:"1", post : { href : "https://www.facebook.com/photo.php?fbid=1000000", id : "100000000000_9999999999", datetime : "2012-04-06T08:27:00", source : " ", network : "facebook", user : { userid : "100000000000000", username : "Hootsuite" }, content : { type : "text/html", body : "Preview: the amazing photos ...", bodyhtml : "Preview: the amazing photos ..." }, attachments : [ type : "photo", title: "Hootsuite App", items : [ { target : "https://www.facebook.com/photo.php?fbid=100000", originurl : "https://photos-g.ak.fbcdn.net/100000_n.jpg", thumbnailurl : "https://photos-g.ak.fbcdn.net/100000_s.jpg" }, { target : "https://www.facebook.com/photo.php?fbid=200000", originurl : "https://photos-g.ak.fbcdn.net/200000_n.jpg", thumbnailurl : "https://photos-g.ak.fbcdn.net/200000_s.jpg" } ] ], conversation : { { datetime : "2012-05-15T13:43:32", id : "13148577321_394882755588473_38475883", likes : 1, name : "John Smith", profileurl : "https://www.facebook/john.smith", text : "That's a very good picture!", uid : 2377483482 } } } } )

Exemple :

function sendToAppHandler ( message ) { // ... }

sendprofiletoapp()

L'inscription à cet événement permettra aux utilisateurs d'accéder à un item de menu dans les menus de profil de Facebook ou Twitter. L'événement se lance lorsque l'utilisateur clique sur l'item de menu.

format de rappel : un objet javascript qui contient les données du profil

Structure de données d'objet profil :

(cliquez sur le lien pour agrandir) Twitter

Profile: (object) created_at (string) description (string) followers_count (int) friends_count (int) id (int) id_str (string) lang (string) listed_count (int) location (string) name (string) network (string) profile_image_url (string) profile_image_url_https (string) screen_name (string) statuses_count (int) time_zone (string) url (string) utc_offset (int) verified (boolean)

 Facebook

Profile: (object) bio (string) first_name (string) gender (string) id (string) last_name (string) link (string) locale (string) name (string) network (string) picture (string) username (string)

sendassignmentupdates()

L'inscription à cet événement permettra à une appli d'être notifiée des mises à jour qui lui sont attribuées

format de rappel : un objet javascript qui contient les données d'information mises à jour

Exemple d'attribution au Callback :

{ action: "ASSIGN" errorMessage: "" messageId: "123456" success: 1 toMemberId: "123" toMemberName: "John Smith" }

Exemple de Callback résolu :

{ action: "RESOLVED" success: 1 errorMessage: "" messageId: "1353547240" }

Fonctions API spécifiques au protocole OAuth

Ces fonctions font partie des procédures d'authentification OAuth, telles qu'elles sont décrites sur la page « Processus d'authentification »

hsp.startAppTokenAuth()

Débute le processus de création de jetons de session.
 
Quand la fonction est appelée, Hootsuite envoie le jeton d'accès OAuth stocké vers le point de terminaison d'authentification de l'appli qui valide les jetons, puis crée et renvoie un jeton de session. Hootsuite recharge ensuite le flux d'application, en transmettant le nouveau jeton de session comme un paramètre d'URL.

hsp.editAppAuth()

Affiche le pop-up d'authentification pour l'appli.

editAppAuth.dabb2b17