JSApi v0.6

App-Verzeichnis-SDK

JSApi (v0.6, veraltet)

Funktionsweise

JSApi ist der Kommunikationskanal des App-Verzeichnis-SDKs zwischen Ihrer App und dem Hootsuite Dashboard. Mit der API können App-Entwickler Funktionen aufrufen, die Events an das Hootsuite Dashboard senden, und Event-Benachrichtigungen zu spezifischen Hootsuite Dashboard-Events in einer App empfangen.

Interaktionen zwischen Hootsuite und Ihrer App werden durch zwei Dateien ermöglicht:

  • JS-Api: Die SDK-Javascript-Bibliothek hsp.js bietet Optionen für spezifische Funktionen im Hootsuite Dashboard. hsp.js ermöglicht auch die Initialisierung und Registrierung Ihrer App, damit sie Events aus dem Hootsuite Dashboard über einen von Ihrer App gehosteten App-Receiver empfangen kann.
  • App-Receiver: Über den App-Receiver kann Ihre Anwendung Events aus dem Hootsuite Dashboard empfangen. Genauer gesagt wird der Receiver für die unten beschriebene Funktion hsp.bind() benötigt.

Einrichtung

 
Zur Verwendung der JS-API benötigen Sie die folgenden Dateien:

  • JS-Bibliothek: Die hsp.js-Bibliothek ermöglicht die wechselseitige Kommunikation zwischen Ihrer App und dem Hootsuite Dashboard. Fügen Sie diese Datei auf der Hauptseite Ihrer App ein: https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/hsp.js
     
    Die Referenz zu dieser Datei auf der Hauptseite würde beispielweise folgendermaßen angezeigt:
    <script src="https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/hsp.js"></script>
  • App-Receiver: Über den App-Receiver kann Ihre Anwendung Events aus dem Hootsuite Dashboard empfangen. Genauer gesagt wird der Receiver für hsp.bind() und hsp.updatePlacementSubtitle() benötigt. Sie müssen die Datei herunterladen, in dem vom Stamm gehosteten Stammverzeichnis der App speichern und dann durch hsp.init() im Parameter receiverPath referenzieren (HTTPS-URL).https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/my_receiver.html

API-Funktionen und Events

Die Kommunikation von Ihrer App zum Hootsuite Dashboard erfolgt über die Funktionen in hsp.js.
 
Die Kommunikation vom Hootsuite Dashboard zu Ihrer App wird durch Events ermöglicht. Die Events, über die Ihre App benachrichtigt werden soll, werden mit Aufrufen der Funktion hsp.bind() unter Angabe des betreffenden Events und der Rückfrage-Funktion registriert, die Ihre App ausführt, wenn der Event ausgelöst wird.

Funktionen

  • init: Initialisiert die JS-API.
  • bind: Registriert ein Hootsuite Dashboard-Event, das mit der App und einem zugehörigen Event-Handler behandelt werden soll.
  • clearStatusMessage: Entfernt alle derzeit sichtbaren Statusmeldungen.
  • composeMessage: Öffnet das Dialogfeld In sozialen Netzwerken veröffentlichen.
  • retweet: Startet Retweet-Dialogprozess.
  • customUserInfo: Öffnet ein Popup-Fenster mit Benutzerinformationen.
  • getTwitterAccounts: Ruft eine Liste aller Twitter-Profile für den angemeldeten Benutzer ab.
  • showCustomPopup: Zeigt einen modalen Popup-Dialog mit einem iFrame mit App-spezifischen Inhalten an.
  • closeCustomPopup: Schließt den modalen Popup-Dialog.
  • showFollowDialog: Öffnet ein Dialogfenster, um einem Twitter-Benutzer zu folgen oder das Folgen zu beenden.
  • showImagePreview: Zeigt ein Bild in einem Popup-Fenster an.
  • showStatusMessage: Zeigt eine Benachrichtigung an.
  • showUser: Öffnet ein Popup mit Benutzerinformationen.
  • updatePlacementSubtitle: Aktualisiert den Untertitel des App-Streams.
  • assignItem: Weist einem Hootsuite Benutzer Textnachrichtinhalte zu.

Events

  • closepopup: Wird ausgelöst, wenn ein von Ihrem App-Stream geöffnetes, benutzerdefiniertes Popup geschlossen wird.
  • dropuser: Wird ausgelöst, wenn ein Benutzer ein Avatar eines Twitter-Benutzers aus dem Hootsuite Dashboard in Ihren App-Stream zieht.
  • refresh: Wird ausgelöst, wenn die App-Spalte vom Benutzer im Stream oder als Teil einer Dashboard-Aktualisierung aktualisiert wird.
  • sendtoapp: Durch die Registrierung für diesen Event wird Benutzern ein Menüelement An <app stream> senden… in Twitter-, Facebook- und LinkedIn-Stream-Nachrichtenmenüs angezeigt. Dieser Event wird ausgelöst, wenn Benutzer auf das Menüelement klicken.
  • sendcomposedmsgtoapp: Fügt der nativen Hootsuite Profilauswahl für soziale Netzwerke ein App-Plug-in hinzu. Benutzer können direkt aus dem Nachrichteneingabefeld von Hootsuite Nachrichten an das Plug-in senden.
  • sendprofiletoapp: Durch die Registrierung für diesen Event wird Benutzern ein Menüelement in Profilmenüs auf Twitter-, Facebook-, LinkedIn- und Google+-Seiten angezeigt. Der Event wird ausgelöst, wenn Benutzer auf das Menüelement klicken.
  • sendassignmentupdates: Durch die Registrierung dieses Events wird eine App über Zuweisungsupdates informiert.

hsp.init(params)

Initialisiert die JS-API und lädt die CSS-Designdateien.

params: object:

  • apiKey: (String)
  • receiverPath: (String, optional)
     Absolute URL der Datei app_receiver.html. Diese muss mit https:// beginnen.
  • subtitle: (String, optional)
     Der Untertitel Ihrer App, der im Titel des Streams angezeigt wird.
  • callBack: (Funktion, optional)
     Init sendet nach der Initialisierung eine Fehlermeldung an die callBack-Funktion. Die Meldung lautet: Kein Fehler, wenn Initialisierung erfolgreich ist.

Beispiel:

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

hsp.bind(eventName, callback)

Registriert einen Event-Handler für einen angegebenen Event.

Hinweis: Dafür muss der App-Receivereingerichtet sein.

eventName: (String)

Name des zu behandelnden Events; kann einer der folgenden sein:

  • closepopup: Wird ausgelöst, wenn ein von Ihrem App-Stream geöffnetes, benutzerdefiniertes Popup geschlossen wird.
  • dropuser: Wird ausgelöst, wenn ein Benutzer ein Avatar eines Twitter-Benutzers aus dem Hootsuite Dashboard in Ihren App-Stream zieht.
  • refresh: Wird ausgelöst, wenn die App-Spalte vom Benutzer im Stream oder als Teil einer Dashboard-Aktualisierung aktualisiert wird.
  • sendtoapp: Durch die Registrierung für diesen Event wird Benutzern ein Menüelement An <app stream> senden… in Twitter- und Facebook-Stream-Nachrichtenmenüs angezeigt. Dieser Event wird ausgelöst, wenn Benutzer auf das Menüelement klicken.

callback: (Funktion)

Funktion zum Behandeln der Rückfrage. Die Parameter der Funktion werden von dem Event bestimmt. Genauere Angaben zu den erwarteten Rückfrageformaten finden Sie im Abschnitt zu Events.

Beispiel:

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

Wie im Abschnitt Best Practices angegeben, ist es sinnvoll, das erneute Laden des Streams zu vermeiden, während der Benutzer mit diesem interagiert (z. B. Posten von Nachrichten, erweiterte Details, Scrollposition möglicherweise nicht im oberen Bereich). Ein möglicher Ansatz könnte folgendermaßen aussehen:

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(); } });

Die Verwendung von window.location.reload() ist nicht der beste Ansatz und wurde weitgehend aufgrund der einfachen Beispiele verwendet. Eine der elegantesten Lösungen ist das Abfragen neuer Nachrichten über AJAX und das Einfügen nur neuer Nachrichten in die DOM, während vorhandene Nachrichten unberührt bleiben.

hsp.clearStatusMessage()

Entfernt alle derzeit sichtbaren Statusmeldungen.

hsp.composeMessage(message, params)

Öffnet das Dialogfeld In sozialen Netzwerken veröffentlichen im Hootsuite Dashboard.

message: (String)

Regeln für Twitter-Nachrichten gelten, z. B. zum Erstellen einer DM an @Hootsuite: d hootsuite <Ihre Nachricht>

params: (Objekt, optional):

  • shortenLinks: bool, optional
     Kürzt alle Links in Nachricht mit standardmäßigem URL-Verkürzungsdienst des Benutzers (ow.ly / ht.ly / oder Wunsch-URL). Lautet standardmäßig "false".
  • timestamp: bool ODER int, optional
     Öffnet den Zeitplan und fügt die Zeitangabe ein (in GMT). Wird "true" eingegeben, wird der Zeitplan ohne Standardzeit geöffnet. Lautet standardmäßig "false".
  • replyToId: String, optional
     Erstellt einen neuen Tweet als Antwort auf einen bestehenden Tweet. Wird eine gültige String-Identifikation für einen vorhandenen Tweet eingegeben, behandelt der Composer die neue Nachricht als Teil der Unterhaltung.

Beispiel:

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

hsp.retweet(id, screenName)

Öffnet den Retweet-Dialogprozess im Hootsuite Dashboard für Tweet mit Identifikation zwecks Retweet durch screenName.

id: (String)

id_str tweetId von Twitter für den Tweet zwecks Retweet.

screen_name: (String, optional)

Der screen_name von Twitter, mit dem Retweet durchgeführt werden soll.

Beispiel:

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

hsp.customUserInfo(data)

Öffnet ein Popup-Fenster mit Benutzerinformationen.

data: (JSON-Objekt)

Beispiel:

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)

Zeigt ein modales Popup-Fenster mit einem iFrame mit Inhalten aus der angegebenen URL an. Beim Schließen löst der Dialog den Event closePopUp() aus.

src: (String)

Im Popup anzuzeigende URL der Inhalte.

title: (String)

Der im Popup-Fenster angezeigte Titel.

width: (int)

Die Breite des Popup in Pixel. Für die Breite gelten folgende Einschränkungen:

  • Sofern nicht angegeben entspricht die Breite standardmäßig 640 Pixel.
  • Die Mindestbreite sind 300 Pixel.
  • Die maximale Breite sind 900 Pixel.

height: (int)

Die Höhe des Popup in Pixel. Für die Breite gelten folgende Einschränkungen:

  • Sofern nicht angegeben entspricht die Höhe standardmäßig 445 Pixel.
  • Die Mindesthöhe sind 225 Pixel.
  • Die maximale Höhe sind 500 Pixel.

Beispiel:

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

Wichtig:

Initialisieren Sie hsp nicht erneut im benutzerdefinierten Popup. Das Popup darf keine hsp-Funktionen außer closeCustomPopup(apiKey, pid) verwenden.

Wenn sich Popup und App-Stream/-Plug-in in derselben Domäne befinden, wird empfohlen, dass das Popup die folgende Javascript-Funktion nutzt, um mit dem Stream/Plug-in zu kommunizieren und die hsp-Funktion auszuführen: window.parent.frames[apiKey_pid].hsp.some_function()

Hinweis: hsp-Event-Bindungsfunktionen sind im benutzerdefinierten Popup nicht verfügbar.

hsp.closeCustomPopup(apiKey, pid)

Schließt das modale Popup-Fenster.

Hinweis: Achten Sie darauf, dass die iFrame-Seite im benutzerdefinierten Popup-Fenster und die App-Stream-Seite die gleiche Domäne verwenden. Sie dürfen hsp.init() nicht erneut auf der iFrame-Seite aufrufen. Fügen Sie einfach hsp.js ein, und rufen Sie hsp.closeCustomPopup(apiKey, pid) auf. Sie können mit JavaScript folgendermaßen zwischen dem Popup und dem Stream kommunizieren:

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

apiKey: (String)

Der API-Schlüssel Ihrer App

pid: (String)

Die PID ist mit jeder eindeutigen Installation eines App-Streams (oder -Plug-ins) verknüpft. Sie erhalten die PID jedes App-Streams über die URL-Anforderung Ihres Servers. Zum Beispiel:

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

hsp.showImagePreview(src, externalUrl)

Zeigt ein Bild in einem Popup-Fenster an, das optional mit einer externen URL verknüpft sein kann.

src: (String)

Bild-URL

externalURL: (String)

URL, die geöffnet werden soll, wenn der Benutzer auf das Bild klickt.

hsp.showStatusMessage(message, type)

Zeigt eine Benachrichtigung oben in der Mitte des Hootsuite Dashboards an.

message: (String)

Sollte kurz sein, maximal 70 Zeichen.

type: (String):

Kann folgendermaßen aussehen:

  • Info: Blauer Hintergrund
  • Fehler: Roter Hintergrund
  • Warnung: Gelber Hintergrund
  • Erfolg: Grüner Hintergrund

hsp.updatePlacementSubtitle(name)

Aktualisiert den Untertitel des App-Streams.

Hinweis: Dafür muss der App-Receiver eingerichtet sein (siehe oben).

name (str)

Max. 35 Zeichen

hsp.showUser(twitterHandle)

Öffnet ein Benutzerinfo-Popup für den angegebenen Twitter-Benutzernamen.

twitterHandle: (String)

Twitter-Benutzername

Beispiel:

hsp.showUser('hootsuite_help');

showUser.f203dc7a

hsp.showFollowDialog(twitterHandle, isFollow)

Öffnet ein Dialogfenster, um einem Twitter-Benutzer zu folgen oder das Folgen zu beenden.

twitterHandle: (String)

Twitter-Benutzername

isFollow: (bool)

"true", um zu folgen, "false", um das Folgen zu beenden.

Beispiel:

hsp.showFollowDialog('hootsuite_help', true);

showFollowDialog.ff5cb783

hsp.getTwitterAccounts(callback)

Ruft eine Liste (Array) aller Twitter-Profile (Benutzernamen) ab, die der angemeldete Benutzer dem Hootsuite Konto hinzugefügt hat.

callback: (Funktion)

Funktion, die einen Array-String akzeptiert.

Beispiel:

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

hsp.assignItem(data)

Weist einem Hootsuite Benutzer (selbst oder Teammitglied) eine Nachricht oder Textinhalte zu.

data: (JSON-Objekt)

Beispiel:

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 };

API-Events

In diesem Abschnitt werden die verfügbaren Events und erwarteten Event-Handler-Funktionssignaturen beschrieben, die durch Verwendung von hsp.bind() verfügbar sind.

refresh()

Wird ausgelöst, wenn die App-Spalte vom Benutzer im Stream oder als Teil einer Dashboard-Aktualisierung aktualisiert wird.

Rückfrageformat: Eine Funktion ohne Parameter.

Beispiel:

function refreshHandler () { }

dropuser()

Wird ausgelöst, wenn ein Benutzer ein Avatar eines Twitter-Benutzers aus dem Hootsuite Dashboard in Ihren App-Stream zieht.

Rückfrageformat: Eine Funktion mit zwei Parametern, dem Twitter-Handle des Benutzers und der eindeutigen Identifikation des Tweets, von dem der Benutzer gezogen wurde.

Beispiel:

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

sendcomposedmsgtoapp()

Fügt der nativen Hootsuite Auswahl für soziale Netzwerke ein App-Plug-in hinzu. Benutzer können direkt aus dem Nachrichteneingabefeld von Hootsuite Nachrichten an das Plug-in senden.

HINWEIS: Sie müssen sich an unser App-Verzeichnis-Verwaltungsteam wenden, um diese Event-Bindung für Ihr App-Plug-in zu aktivieren.

Rückfrageformat: Ein Javascript-Objekt mit den Nachrichtendaten.

Struktur der Nachrichtenobjektdaten:

Message: (object) text: (string)

Beispiel:

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

closepopup()

Wird ausgelöst, wenn ein von Ihrem App-Stream geöffnetes, benutzerdefiniertes Popup geschlossen wird.

Rückfrageformat: Eine Funktion ohne Parameter.

Beispiel:

function closePopupHandler () { // ... }

sendtoapp()

Durch die Registrierung für diesen Event wird Benutzern das Menüelement "An <app stream> senden..." in Twitter- und Facebook-Stream-Nachrichtenmenüs angezeigt. Dieser Event wird ausgelöst, wenn Benutzer auf das Menüelement klicken.

Rückfrageformat: Ein Javascript-Objekt mit den Nachrichtendaten.

Struktur der Nachrichtenobjektdaten:

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

Beispielnachrichtenobjekt:

( { 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 } } } } )

Beispiel:

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

sendprofiletoapp()

Durch die Registrierung für diesen Event wird Benutzern ein Menüelement in Profilmenüs in Twitter oder Facebook angezeigt. Der Event wird ausgelöst, wenn Benutzer auf das Menüelement klicken.

Rückfrageformat: Ein Javascript-Objekt mit den Profildaten.

Struktur der Profilobjektdaten:

(Zum Erweitern auf den Link klicken) 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()

Durch die Registrierung dieses Events wird eine App über Zuweisungsupdates informiert.

Rückfrageformat: Ein Javascript-Objekt mit den Update-Informationsdaten.

Beispiel: Rückfragezuweisung:

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

Beispiel: Rückfrage auflösen:

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

OAuth-spezifische API-Funktionen

Diese Funktionen sind Teil des OAuth-Authentifizierungsvorgangs, wie auf der Seite "Authentifizierungsvorgang" beschrieben.

hsp.startAppTokenAuth()

Leitet den Vorgang zur Erstellung des Sitzungstokens ein.
 
Wenn aufgerufen, sendet Hootsuite das gespeicherte OAuth-Zugriffstoken an den Authentifizierungsendpunkt der App, der das Token validiert und ein Sitzungstoken zurückgibt. Anschließend lädt Hootsuite den App-Stream erneut und übergibt das neue Sitzungstoken als URL-Parameter.

hsp.editAppAuth()

Zeigt das Authentifizierungs-Popup für die App an.

editAppAuth.dabb2b17