JSApi v0.6

SDK dell'App Directory

JSApi (v0.6, deprecata)

Come funziona

JSApi è il gateway di comunicazione tra la tua app e la dashboard di Hootsuite dell'SDK dell'App Directory. L'API consente agli sviluppatori di app di chiamare funzioni che inviano eventi alla dashboard di Hootsuite e di ricevere notifiche di eventi, specifici eventi della dashboard di Hootsuite all'interno di un'app.

Le interazioni tra Hootsuite e la tua app sono rese possibili da due file:

  • JS Api - la libreria in Javascript dell'SDK, hsp.js, fornisce funzioni alla base di specifiche funzionalità nella dashboard di Hootsuite. Anche hsp.js consente l'inizializzazione e la registrazione della tua app, per ricevere eventi dalla dashboard di Hootsuite attraverso un ricevitore di app ospitato dalla tua app.
  • Ricevitore di app - Il ricevitore di app permette alla tua applicazione di ricevere eventi dalla dashboard di Hootsuite. In particolare, il ricevitore è necessario perché la funzione hsp.bind() descritta di seguito funzioni.

Preparazione

 
Per utilizzare JS API, sono necessari i seguenti file:

  • JS Library - La libreria hsp.js consente la comunicazione a due vie tra la tua app e la dashboard di Hootsuite. Includi questo file nella pagina principale della tua app: https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/hsp.js
     
    Ad esempio, il riferimento a questo file nella tua pagina principale apparirebbe come segue:
    <script src="https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/hsp.js"></script>
  • Ricevitore di app - Il ricevitore di app permette alla tua applicazione di ricevere eventi dalla dashboard di Hootsuite. In particolare, il ricevitore è necessario perché hsp.bind() e hsp.updatePlacementSubtitle() funzionino. Questo file deve essere scaricato, posizionato nella root directory dell'app ospitata nella root e, in seguito, è necessario che hsp.init() faccia riferimento allo stesso file nel parametro receiverPath ( HTTPS URL).https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/my_receiver.html

Eventi & funzioni API

La comunicazione dalla tua app alla dashboard di Hootsuite avviene utilizzando le funzioni disponibili in hsp.js.
 
La comunicazione dalla dashboard di Hootsuite alla tua app è resa possibile attraverso gli eventi. Gli eventi per i quali la tua app vuole ricevere notifica sono registrati con chiamate alla funzione hsp.bind() che indica l'evento di interesse e la funzione di callback che la tua app esegue quando l'evento la innesca.

Funzioni

  • init - Inizializza JS API
  • bind - Registra un evento della dashboard di Hootsuite che deve essere gestito con l'app e l'handler dell'evento associato
  • clearStatusMessage - Rimuove tutti gli status dei messaggi attualmente visibili
  • composeMessage - Apre la finestra di dialogo Condividi con i social network
  • retweet - avvia il processo di retweet
  • customUserInfo - Apre una finestra pop-up contenente le informazioni sull'utente
  • getTwitterAccounts - Ottiene un elenco di tutti i profili Twitter degli utenti che hanno effettuato l'accesso
  • showCustomPopup - Visualizza una finestra di dialogo pop-up modale contenente un iFrame con contenuti specifici dell'app
  • closeCustomPopup - Chiude la finestra di dialogo pop-up modale
  • showFollowDialog - Apre una finestra di dialogo per seguire o smettere di seguire un utente di Twitter
  • showImagePreview - Visualizza un'immagine in una finestra pop-up
  • showStatusMessage - Visualizza una notifica
  • showUser - Apre una finestra pop-up contenente le informazioni sull'utente
  • updatePlacementSubtitle - Aggiorna il sottotitolo dello stream dell'app
  • assignItem - Assegna il contenuto di un messaggio testuale a un utente di Hootsuite

Eventi

  • closepopup - Viene lanciato quando una finestra pop-up personalizzata aperta dallo stream della tua app viene chiusa
  • dropuser - Viene lanciato quando un utente trascina & rilascia l'avatar di un utente di Twitter dalla dashboard di Hootsuite nello stream della tua app
  • refresh - Viene lanciato quando la colonna dell'app viene aggiornata per mano dell'utente all'interno dello stream o perché viene aggiornata la dashboard
  • sendtoapp - La registrazione a questo evento farà vedere agli utenti un elemento di menu nel quale sarà visualizzato Invia a <stream dell'app>... nei menu del messaggio dello stream di Twitter, Facebook e LinkedIn. Questo evento viene lanciato quando gli utenti fanno clic sull'elemento del menu
  • sendcomposedmsgtoapp - Aggiunge il plug-in dell'app al selezionatore di profilo del social network nativo di Hootsuite. L'utente può inviare messaggi al plug-in direttamente dalla casella di composizione del messaggio di Hootsuite
  • sendprofiletoapp - La registrazione a questo evento farà vedere agli utenti un elemento di menu nei menu del profilo di Twitter, Facebook, LinkedIn e Google+. L'evento viene lanciato quando gli utenti fanno clic sull'elemento del menu
  • sendassignmentupdates - La registrazione a questo evento farà ricevere a un'app notifica dei suoi aggiornamenti di assegnazione

hsp.init(params)

Inizializza JS API e carica i file CSS del tema.

params: oggetto:

  • apiKey: (stringa)
  • receiverPath: (stringa, facoltativo)
     URL assoluto del tuo file app_receiver.html. Questo deve iniziare con https://
  • sottotitolo: (stringa, facoltativo)
     Il sottotitolo della tua app, da visualizzare nel titolo dello stream.
  • callBack: (funzione, facoltativo)
     Init invia un messaggio di errore alla funzione callBack in seguito all'inizializzazione. Il contenuto del messaggio è: Nessun errore, se l'inizializzazione è stata eseguita correttamente.

Esempio:

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

hsp.bind(eventName, callback)

Registra l'handler di un evento per un evento specificato.

Nota: Per questo è necessario che il ricevitore dell'app sia impostato.

eventName: (stringa)

Nome dell'evento da gestire, può essere uno dei seguenti:

  • closepopup - Viene lanciato quando una finestra pop-up personalizzata aperta dallo stream della tua app viene chiusa
  • dropuser - Viene lanciato quando un utente trascina & rilascia l'avatar di un utente di Twitter dalla dashboard di Hootsuite nello stream della tua app
  • refresh - Viene lanciato quando la colonna dell'app viene aggiornata per mano dell'utente all'interno dello stream o perché viene aggiornata la dashboard
  • sendtoapp - La registrazione a questo evento farà vedere agli utenti un elemento di menu nel quale sarà visualizzato Invia a <stream dell'app>... nei menu del messaggio dello stream di Twitter e Facebook. Questo evento viene lanciato quando gli utenti fanno clic sull'elemento del menu

callback: (funzione)

Funzione per gestire il callback, i parametri della funzione sono determinati dall'evento. Per maggiori dettagli sui formati di callback attesi, vedere la sezione eventi.

Esempio:

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

Come detto nella sezione Procedure consigliate, è utile sopprimere il ricaricamento dello stream mentre l'utente interagisce con lo stesso (ad esempio pubblicando messaggi, ingrandendo dettagli, scorrendo verso posizioni lontane dall'inizio). Un approccio possibile potrebbe avere un aspetto simile al seguente:

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'utilizzo di window.location.reload() non è evidentemente l'approccio migliore ed è stato utilizzato per lo più per semplificare gli esempi. La soluzione più lineare sarebbe quella di eseguire il polling di ogni nuovo messaggio con AJAX e inserire solo nuovi messaggi nel DOM, lasciando i messaggi esistenti inalterati.

hsp.clearStatusMessage()

Rimuove tutti gli status dei messaggi attualmente visibili.

hsp.composeMessage(message, params)

Apre la finestra di dialogo Condividi con i social network nella dashboard di Hootsuite.

messaggio: (stringa)

Si applicano le regole per i messaggi di Twitter, ad esempio la composizione di un DM a @Hootsuite sarebbe: d Hootsuite <qui il tuo messaggio>

params: (oggetto, facoltativo):

  • shortenLinks: bool, facoltativo
     Abbrevia tutti i link trovati nel messaggio con l'abbreviazione di default dell'URL dell'utente (ow.ly / ht.ly / o vanity url). False per impostazione predefinita.
  • timestamp: bool O int, facoltativo
     Apri lo Scheduler e inserisci i timestamp (GMT). Se viene impostato su true, lo Scheduler si apre senza ora di default. False per impostazione predefinita.
  • replyToId: stringa, facoltativo
     Scrivi un nuovo tweet in risposta a un tweet esistente. Se viene inserita una stringa ID valida per un tweet esistente, il Composer tratta il nuovo messaggio come parte della conversazione.

Esempio:

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

hsp.retweet(id, screenName)

Apre il processo di dialogo del retweet nella dashboard di Hootsuite in modo che il tweet con l'ID venga retweettato da screenName.

id: (stringa)

id_str TweetId di Twitter del tweet da retweettare

screen_name: (stringa, facoltativo)

screen_name di Twitter con il quale vuoi retweettare

Esempio:

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

hsp.customUserInfo(data)

Apre una finestra pop-up contenente le informazioni sull'utente.

dati: (oggetto JSON)

Esempio:

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)

Visualizza una finestra di dialogo pop-up modale contenente un iFrame con contenuti dell'URL specificato. Su chiudi la finestra di dialogo lancia l'evento closePopUp().

src: (stringa)

L'URL del contenuto da visualizzare nella finestra pop-up

title: (stringa)

Il titolo visualizzato nella finestra pop-up

width: (int)

La larghezza della finestra pop-up in pixel. La larghezza ha i seguenti limiti:

  • Se non altrimenti specificato, la larghezza è di 640 pixel per impostazione predefinita
  • La larghezza minima è di 300 pixel.
  • La larghezza massima è di 900 pixel.

height: (int)

L'altezza della finestra pop-up in pixel. La larghezza ha i seguenti limiti:

  • Se non altrimenti specificato, l'altezza è di 445 pixel per impostazione predefinita
  • L'altezza minima è di 225 pixel.
  • L'altezza massima è di 500 pixel.

Esempio:

hsp.showStatusMessage('Fatto!', 'operazione riuscita') ;

Importante:

Non inizializzare hsp nuovamente nella finestra pop-up personalizzata. L'unica funzione hsp che la tua finestra pop-up può utilizzare è closeCustomPopup(apiKey, pid).

Se la tua finestra pop-up e lo stream o il plug-in dell'app si trovano nello stesso dominio, è preferibile che la tua finestra pop-utilizzi la seguente funzione javascript per comunicare con il tuo stream o plug-in ed eseguire la funzione hsp: window.parent.frames[apiKey_pid].hsp.some_function()

Nota: le funzioni binding di eventi hsp non sono disponibili nella finestra pop-up personalizzata.

hsp.closeCustomPopup(apiKey, pid)

Chiude la finestra pop-up modale.

Nota: Assicurati che la pagina iFrame nella finestra pop-up personalizzata e la pagine di stream dell'app condividano lo stesso dominio. Non è necessario né raccomandabile chiamare hsp.init() nuovamente nella finestra iFrame, è sufficiente includere hsp.js e chiamare hsp.closeCustomPopup(apiKey, pid). Puoi utilizzare JavaScript per far comunicare la finestra pop-up e lo stream, come dimostrato di seguito:

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

apiKey: (stringa)

La tua API Key

pid: (stringa)

Il pid è associato a ogni singola installazione di uno stream, o plug-in, di un'app. Puoi ottenere il pid di ogni stream dell'app dalla richiesta di URL che riceve il tuo server. Ad esempio:

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

hsp.showImagePreview(src, externalUrl)

Visualizza un'immagine in una finestra pop-up, che potrebbe facoltativamente essere collegata a un URL esterno.

src: (stringa)

URL immagine

externalURL: (stringa)

URL da aprire se l'utente fa clic sull'immagine

hsp.showStatusMessage(message, type)

Visualizza una notifica in alto al centro della dashboard di Hootsuite.

messaggio: (stringa)

Dovrebbe essere breve, massimo 70 caratteri.

type: (stringa):

Può essere una delle seguenti:

  • info: Background blu
  • errore: Background rosso
  • avvertenza: Background giallo
  • operazione riuscita: Background verde

hsp.updatePlacementSubtitle(name)

Aggiorna il sottotitolo dello stream dell'app.

Nota: Per questo è necessario che il ricevitore dell'app sia impostato (vedi sopra).

name (str)

Al massimo 35 caratteri

hsp.showUser(twitterHandle)

Apre una finestra pop-up con le informazioni utente relative al nome utente di Twitter specificato.

twitterHandle: (stringa)

Nome utente di Twitter

Esempio:

hsp.showUser('hootsuite_help');

showUser.f203dc7a

hsp.showFollowDialog(twitterHandle, isFollow)

Apre una finestra di dialogo per seguire o smettere di seguire un utente di Twitter.

twitterHandle: (stringa)

Nome utente di Twitter

isFollow: (bool)

true per seguire, false per smettere di seguire.

Esempio:

hsp.showFollowDialog('hootsuite_help', true);

showFollowDialog.ff5cb783

hsp.getTwitterAccounts(callback)

Ottiene un elenco (array) di tutti i profili Twitter (nomi utente) che l'utente che ha effettuato l'accesso ha aggiunto al suo account di Hootsuite.

callback: (funzione)

Funzione che accetta un array di stringhe

Esempio:

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

hsp.assignItem(data)

Assegna un messaggio, o qualunque contenuto testuale, a un utente di Hootsuite (se stesso o un membro del team)

dati: (oggetto JSON)

Esempio:

var data = {
  "messageId": "1000020", //REQUIRED
  "message": "Ciao, ho un problema con il mio 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
};

Eventi API

Questa sezione descrive il set di eventi disponibili e le signatures della funzione handler dell'evento attese utilizzando hsp.bind().

refresh()

Viene lanciato quando la colonna dell'app viene aggiornata per mano dell'utente all'interno dello stream o perché viene aggiornata la dashboard.

formato del callback: una funzione senza parametri

Esempio:

function refreshHandler () { }

dropuser()

Viene lanciato quando un utente trascina & rilascia l'avatar di un utente di Twitter dalla dashboard di Hootsuite nello stream della tua app
 

formato del callback: una funzione con due parametri, l'handle di Twitter dell'utente e l'ID univoco del tweet dal quale l'utente è stato trascinato

Esempio:

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

sendcomposedmsgtoapp()

Aggiunge il plug-in dell'app al selezionatore del social network nativo di Hootsuite. L'utente può inviare messaggi al plug-in direttamente dalla casella di composizione del messaggio di Hootsuite

NOTA: È necessario contattare il team di amministrazione della directory dell'app per abilitare questo binding di evento per il plug-in della tua app

formato del callback: un oggetto javascript che contiene i dati del messaggio

Struttura dei dati dell'oggetto del messaggio:

Message: (object)
  text: (string)

Esempio:

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

closepopup()

Viene lanciato quando una finestra pop-up personalizzata aperta dallo stream della tua app viene chiusa

formato del callback: una funzione senza parametri

Esempio:

function closePopupHandler () {
  // ...
}

sendtoapp()

La registrazione a questo evento farà vedere agli utenti un elemento di menu nel quale sarà visualizzato Invia a <stream dell'app>... nei menu del messaggio dello stream di Twitter e Facebook. Questo evento viene lanciato quando gli utenti fanno clic sull'elemento del menu.

formato del callback: un oggetto javascript che contiene i dati del messaggio

Struttura dei dati dell'oggetto del messaggio:

Message: (object)
  version: (string) current version is 1
  post: (object)
    href: (string) url to the original post
    id: (string) external post id
    datetime: (string) iso 8601 datetime format
    source: (string) twitter only e.g. iPhone App
    network: (string)

    user: (object)
      userid: (string) facebook and twitter only
      username: (string)

    attachments: (array)
      items: (array)
        target: (string) url to the resource page
        originurl: (string) url to the actual resource
        thumbnailsrc: (string) url to the thumbnail
      title: (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) twitter only
      retweetcount: (string) twitter only
      source: (string) twitter only
      profileurl: (string) facebook only
      likes: (int) facebook only

Esempio di oggetto del messaggio:

( {
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 : "Anteprima: le fantastiche foto...",
      bodyhtml : "Anteprima: le fantastiche foto..."
    },
    attachments : [
      type : "photo",
      title: "App di Hootsuite",
      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 : "Questa foto è magnifica!",
        uid : 2377483482
      }
    }
  }
} )

Esempio:

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

sendprofiletoapp()

La registrazione a questo evento farà vedere agli utenti un elemento di menu nei menu del profilo di Twitter o Facebook. L'evento viene lanciato quando gli utenti fanno clic sull'elemento del menu.

formato del callback: un oggetto javascript che contiene i dati del profilo

Struttura dei dati dell'oggetto del profilo:

(fai clic sul link per ingrandire) 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()

La registrazione a questo evento farà ricevere a un'app notifica dei suoi aggiornamenti di assegnazione

formato del callback: un oggetto javascript che contiene i dati dell'informazione aggiornata

Esempio di Callback Assign To:

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

Esempio di Callback Resolve:

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

Funzioni API specifiche per OAuth

Queste funzioni fanno parte della procedura di autenticazione di OAuth, come descritto nella pagina "Processo di autenticazione".

hsp.startAppTokenAuth()

Inizia il processo di creazione di token di sessione.
 
Quando viene chiamato, Hootsuite invia i token di accesso di OAuth all'endpoint di autenticazione dell'app, che convalida il token, crea e restituisce un token di sessione. A questo punto, Hootsuite carica nuovamente lo stream dell'app, passando il nuovo token di sessione come parametro dell'URL.

hsp.editAppAuth()

Visualizza la finestra pop-up di autenticazione dell'app.

editAppAuth.dabb2b17