JSApi (versión 0.6)

SDK del directorio de aplicaciones

JSApi (versión 0.6; obsoleta)

Cómo funciona

JSApi constituye la puerta de enlace de comunicaciones del SDK del directorio de aplicaciones entre su aplicación y el panel de control de Hootsuite. La API permite a los desarrolladores de aplicaciones realizar llamadas a funciones que envían eventos al panel de control de Hootsuite y recibir notificaciones específicas de eventos del panel de control de Hootsuite en una aplicación.

Las interacciones entre Hootsuite y su aplicación se realizan gracias a dos archivos:

  • JS Api: la biblioteca JavaScript del SDK, hsp.js, proporciona funciones que permiten incorporar una funcionalidad concreta en el panel de control de Hootsuite. hsp.js también posibilita el inicio y registro de su aplicación para recibir eventos desde el panel de control de Hootsuite mediante un receptor de aplicaciones que aloja la aplicación.
  • App Receiver: el receptor de aplicaciones permite que su aplicación reciba eventos desde el panel de control de Hootsuite. Más concretamente, el receptor es un archivo necesario para que la función hsp.bind() que se describe a continuación se ejecute correctamente.

Configuración

 
Los siguientes archivos son necesarios para utilizar la API de JavaScript:

  • JS Library: la biblioteca hsp.js permite una comunicación bidireccional entre su aplicación y el panel de control de Hootsuite. Incluya este archivo en la página principal de su aplicación: https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/hsp.js
     
    Por ejemplo, la referencia a este archivo en su página principal tendría el siguiente aspecto:
    <script src="https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/hsp.js"></script>
  • App Receiver: el receptor de aplicaciones permite que su aplicación reciba eventos desde el panel de control de Hootsuite. Más concretamente, el receptor es un archivo necesario para que las funciones hsp.bind() y hsp.updatePlacementSubtitle() se ejecuten correctamente. Este archivo tiene que descargarse, colocarse en el directorio raíz de la aplicación alojada y, a continuación, hacerse referencia a él mediante hsp.init() en el parámetro de receiverPath (URL de HTTPS).https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/my_receiver.html

Eventos y funciones de la API

La comunicación desde la aplicación al panel de control de Hootsuite se realiza mediante las funciones disponibles en hsp.js.
 
La comunicación desde el panel de control de Hootsuite a su aplicación se establece mediante eventos. Los eventos que se deseen notificar con la aplicación se registran con llamadas a la función hsp.bind() indicando el evento de interés y la función de devolución de llamada que ejecutará la aplicación cuando se inicie el evento.

Funciones

  • init: inicia la API de JavaScript.
  • bind: registra un evento del panel de control de Hootsuite para administrarse con la aplicación y un administrador de eventos asociado.
  • clearStatusMessage: elimina todos los mensajes de estado visibles en este momento.
  • composeMessage: abre el cuadro de diálogo "Share to Social Networks" (Compartir en las redes sociales).
  • retweet: inicia un proceso de cuadro de diálogo para retwittear.
  • customUserInfo: abre una ventana emergente con información del usuario.
  • getTwitterAccounts: obtiene una lista de todos los perfiles de Twitter del usuario que ha iniciado sesión.
  • showCustomPopup: muestra un cuadro de diálogo de ventana emergente modal que contiene un marco flotante con contenido específico de la aplicación.
  • closeCustomPopup: cierra el cuadro de diálogo de ventana emergente modal.
  • showFollowDialog: abre una ventana de cuadro de diálogo para seguir o dejar de seguir a un usuario de Twitter.
  • showImagePreview: muestra una imagen en una ventana emergente.
  • showStatusMessage: muestra una notificación.
  • showUser: abre una ventana emergente con información del usuario.
  • updatePlacementSubtitle: actualiza el subtítulo de la columna de la aplicación.
  • assignItem: asigna contenido de mensajes textuales a un usuario de Hootsuite.

Eventos

  • closepopup: se inicia cuando se cierra una ventana emergente personalizada que ha abierto su columna de aplicaciones.
  • dropuser: se inicia cuando un usuario arrastra un avatar de usuario de Twitter desde el panel de control de Hootsuite y lo suelta en la columna de aplicaciones.
  • refresh: se inicia cuando se actualiza la columna de aplicaciones, con independencia de que esta acción la realice el usuario en la columna o que se haga como parte de una actualización del panel de control.
  • sendtoapp: al registrar este evento, los usuarios verán un elemento de menú que indica que se va a enviar un elemento a una columna de aplicaciones concreta en los menús de mensaje de las columnas de Twitter, Facebook y LinkedIn. Este evento se inicia cuando los usuarios hacen clic en el elemento de menú.
  • sendcomposedmsgtoapp: agrega el complemento de aplicaciones al selector de perfiles sociales nativo de Hootsuite. Los usuarios pueden enviar mensajes al complemento directamente desde la herramienta de redacción de Hootsuite.
  • sendprofiletoapp: al registrar este evento, los usuarios verán un elemento de menú en los menús de perfiles de páginas de Twitter, Facebook, LinkedIn y Google+. El evento se inicia cuando los usuarios hacen clic en el elemento de menú.
  • sendassignmentupdates: al registrar este evento, una aplicación recibirá una notificación acerca de las actualizaciones de sus asignaciones.

hsp.init(params)

Inicia la API de JavaScript y carga los archivos CSS de temas.

params: objeto

  • apiKey: (cadena)
  • receiverPath: (cadena; opcional)
     URL absoluta del archivo app_receiver.html. Debe empezar por https://.
  • subtitle: (cadena; opcional)
     El subtítulo de su aplicación que se mostrará en el título de la columna.
  • callBack: (función; opcional)
     El proceso Init enviará un mensaje de error a la función callBack después de iniciarse. Se recibirá el mensaje "No Error" (Sin errores) si el proceso de inicio se lleva a cabo correctamente.

Ejemplo:

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

hsp.bind(eventName, callback)

Registra un administrador de eventos para un evento determinado.

Nota: se requiere configurar el archivo App Receiver.

eventName: (cadena)

El nombre del evento para administrar; puede ser uno de los siguientes:

  • closepopup: se inicia cuando se cierra una ventana emergente personalizada que ha abierto su columna de aplicaciones.
  • dropuser: se inicia cuando un usuario arrastra un avatar de usuario de Twitter desde el panel de control de Hootsuite y lo suelta en la columna de aplicaciones.
  • refresh: se inicia cuando se actualiza la columna de aplicaciones, con independencia de que esta acción la realice el usuario en la columna o que se haga como parte de una actualización del panel de control.
  • sendtoapp: al registrar este evento, los usuarios verán un elemento de menú que indica que se va a enviar un elemento a una columna de aplicaciones concreta en los menús de mensaje de las columnas de Twitter y Facebook. Este evento se inicia cuando los usuarios hacen clic en el elemento de menú.

callback: (función)

Función que permite administrar la devolución de llamada. El evento determina los parámetros de esta función. Consulte la sección de eventos para obtener información detallada sobre los formatos de devolución de llamado esperados.

Ejemplo:

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

Tal y como se indica en las prácticas recomendadas, tiene sentido suprimir la acción que vuelve a cargar la columna mientras los usuarios interactúan con ella (por ejemplo, publicando mensajes y expandiendo los detalles en una posición que probablemente no esté cerca de la parte superior). Podría emplearse un enfoque similar a este:

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

Como es obvio, utilizar window.location.reload() no constituye el mejor enfoque; se empleó principalmente para simplificar los ejemplos. Una de las soluciones más elegantes consistiría en obtener los nuevos mensajes mediante AJAX e insertarlos en el DOM sin modificar los mensajes actuales.

hsp.clearStatusMessage()

Elimina todos los mensajes de estado visibles en este momento.

hsp.composeMessage(message, params)

Abre el cuadro de diálogo "Share to Social Networks" (Compartir en las redes sociales) en el panel de control de Hootsuite.

message: (cadena)

Se aplican las reglas de mensajes de Twitter; por ejemplo, la de enviar un MD a @Hootsuite sería: d hootsuite <su mensaje>

params: (objeto; opcional):

  • shortenLinks: booleano; opcional
     Acorta todos los vínculos encontrados en el mensaje con el acortador de direcciones URL predeterminado del usuario (ow.ly, ht.ly o una URL mnemónica). El valor predeterminado está establecido como "false" (falso).
  • timestamp: booleano O int; opcional
     Abre el programador y lo rellena con la marca de tiempo (en GMT). Si se transmite el valor "true" (verdadero), el programador se abrirá sin hora predeterminada. El valor predeterminado está establecido como "false" (falso).
  • replyToId: cadena; opcional
     Redacta un nuevo tweet como respuesta a otro. Si se transmite un ID de cadena válido para un tweet existente, la función de redacción de mensajes tratará el nuevo mensaje como parte de la conversación.

Ejemplo:

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

hsp.retweet(id, screenName)

Abre el proceso de cuadro de diálogo para retwittear en el panel de control de Hootsuite con el fin de que la cadena screenName pueda retwittear un tweet con ID.

id: (cadena)

El tweetId de id_str de Twitter para el tweet que se va a retwittear.

screen_name: (cadena; opcional)

La cadena screen_name de Twitter con la que desea retwittear.

Ejemplo:

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

hsp.customUserInfo(data)

Abre una ventana emergente con información del usuario.

data: (objeto JSON)

Ejemplo:

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)

Muestra una ventana emergente modal que contiene un marco flotante que muestra contenido de la URL especificada. Al cerrar el cuadro de diálogo, se inicia el evento closePopUp().

src: (cadena)

La URL del contenido que se mostrará en la ventana emergente.

title: (cadena)

El título mostrado en la ventana emergente.

width: (int)

La anchura de la ventana emergente en píxeles. La anchura tiene las siguientes limitaciones:

  • Si no se especifica, el valor predeterminado de la anchura es de 640 píxeles.
  • La anchura mínima es de 300 píxeles.
  • La anchura máxima es de 900 píxeles.

height: (int)

La altura de la ventana emergente en píxeles. La anchura tiene las siguientes limitaciones:

  • Si no se especifica, el valor predeterminado de la altura es de 445 píxeles.
  • La altura mínima es de 225 píxeles.
  • La altura máxima es de 500 píxeles.

Ejemplo:

hsp.showStatusMessage('Listo.', 'success') ;

Importante:

no vuelva a iniciar hsp en la ventana emergente personalizada. La ventana emergente no tiene que utilizar funciones hsp distintas a closeCustomPopup(apiKey, pid).

Si la ventana emergente y el complemento o la columna de aplicaciones se encuentran en el mismo dominio, se recomienda que la ventana emergente utilice la siguiente función JavaScript para volver a comunicarse con el complemento o la columna y ejecutar la función hsp: window.parent.frames[apiKey_pid].hsp.some_function()

Nota: Las funciones de enlace de eventos hsp no se encuentran disponibles en la ventana emergente personalizada.

hsp.closeCustomPopup(apiKey, pid)

Cierra la ventana emergente modal.

Nota: Asegúrese de que la página del marco flotante de la ventana emergente personalizada y la página de la columna de aplicaciones estén compartiendo el mismo dominio. No debe volver a llamar a hsp.init() en la página del marco flotante; incluya solamente hsp.js y realice la llamada a hsp.closeCustomPopup(apiKey, pid). Puede utilizar JavaScript para establecer una comunicación entre la ventana emergente y la columna similar a esta:

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

apiKey: (cadena)

La clave de API de su aplicación.

pid: (cadena)

El PID asociado con cada instalación única de una columna de aplicaciones (o complemento). Puede obtener el PID de cada columna desde la solicitud de URL que obtiene su servidor. Por ejemplo:

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

hsp.showImagePreview(src, externalUrl)

Muestra una imagen en una ventana emergente (si lo desea, puede estar vinculada a una URL externa).

src: (cadena)

La URL de la imagen.

externalURL: (cadena)

La URL que se abrirá si un usuario hace clic en la imagen.

hsp.showStatusMessage(message, type)

Muestra una notificación en la parte superior central del panel de control de Hootsuite.

message: (cadena)

El mensaje debe ser breve; no puede superar los 70 caracteres.

type: (cadena)

Puede ser uno de los siguientes:

  • info: fondo azul.
  • error: fondo rojo.
  • warning: fondo amarillo.
  • success: fondo verde.

hsp.updatePlacementSubtitle(name)

Actualiza el subtítulo de la columna de la aplicación.

Nota: se requiere configurar el archivo App Receiver (consúltese arriba).

name (str)

Puede emplear un máximo de 35 caracteres.

hsp.showUser(twitterHandle)

Abre una ventana emergente con información del usuario correspondiente al nombre de usuario en Twitter especificado.

twitterHandle: (cadena)

El nombre de usuario en Twitter.

Ejemplo:

hsp.showUser('hootsuite_help');

showUser.f203dc7a

hsp.showFollowDialog(twitterHandle, isFollow)

Abre una ventana de cuadro de diálogo para seguir o dejar de seguir a un usuario de Twitter.

twitterHandle: (cadena)

El nombre de usuario en Twitter.

isFollow: (booleano)

Si el valor se establece como "true" (verdadero), se seguirá al usuario, si se establece como "false" (falso), se dejará de seguir.

Ejemplo:

hsp.showFollowDialog('hootsuite_help', true);

showFollowDialog.ff5cb783

hsp.getTwitterAccounts(callback)

Obtiene una lista (matriz) de todos los perfiles de Twitter (nombres de usuario) que el usuario que ha iniciado sesión ha agregado a su cuenta de Hootsuite.

callback: (función)

Función que acepta cadenas de una matriz.

Ejemplo:

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

hsp.assignItem(data)

Asigna un mensaje (o cualquier contenido textual) a un usuario de Hootsuite (a sí mismo o a un miembro del equipo).

data: (objeto JSON)

Ejemplo:

var data = {
  "messageId": "1000020", //REQUIRED
  "message": "Hola. Tengo un problema con mi cuenta.",  //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
};

Eventos de API

En esta sección se describe el conjunto de eventos disponibles y las firmas de funciones de administrador de eventos esperadas que se encuentran disponibles al utilizar hsp.bind().

refresh()

Se inicia cuando se actualiza la columna de aplicaciones, con independencia de que esta acción la realice el usuario en la columna o que se haga como parte de una actualización del panel de control.

formato de la devolución de llamada: una función sin parámetros.

Ejemplo:

function refreshHandler () { }

dropuser()

se inicia cuando un usuario arrastra un avatar de usuario de Twitter desde el panel de control de Hootsuite y lo suelta en la columna de aplicaciones.
 

formato de la devolución de llamada: una función con dos parámetros, el administrador de Twitter del usuario y el ID único del tweet desde el que se arrastró dicho usuario.

Ejemplo:

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

sendcomposedmsgtoapp()

Agrega el complemento de aplicaciones al selector de redes sociales nativo de Hootsuite. Los usuarios pueden enviar mensajes al complemento directamente desde la herramienta de redacción de Hootsuite.

NOTA: tiene que ponerse en contacto con nuestro equipo de administración del directorio de aplicaciones con el fin de permitir que este evento realice funciones de enlace para su complemento de aplicaciones.

formato de la devolución de llamada: un objeto JavaScript que contiene los datos de mensaje.

Estructura de los datos del objeto de mensaje:

Message: (object)
  text: (string)

Ejemplo:

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

closepopup()

Se inicia cuando se cierra una ventana emergente personalizada que ha abierto su columna de aplicaciones.

formato de la devolución de llamada: una función sin parámetros.

Ejemplo:

function closePopupHandler () {
  // ...
}

sendtoapp()

Al registrar este evento, los usuarios verán un elemento de menú que indica que se va a enviar un elemento a una columna de aplicaciones concreta en los menús de mensaje de las columnas de Twitter y Facebook. Este evento se inicia cuando los usuarios hacen clic en el elemento de menú.

formato de la devolución de llamada: un objeto JavaScript que contiene los datos de mensaje.

Estructura de los datos del objeto de mensaje:

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

Objeto de mensaje de ejemplo:

( {
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 : "Vista previa: las increíbles fotos...",
      bodyhtml : "Vista previa: las increíbles fotos..."
    },
    attachments : [
      type : "photo",
      title: "Aplicación de 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 : "Muy buena foto.",
        uid : 2377483482
      }
    }
  }
} )

Ejemplo:

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

sendprofiletoapp()

Al registrar este evento, los usuarios verán un elemento de menú en los menús de perfiles de páginas de Twitter o Facebook. El evento se inicia cuando los usuarios hacen clic en el elemento de menú.

formato de la devolución de llamada: un objeto JavaScript que contiene los datos de perfiles.

Estructura de los datos del objeto de perfiles:

(haga clic en el vínculo para expandir la información) 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()

Al registrar este evento, una aplicación recibirá una notificación acerca de las actualizaciones de sus asignaciones.

formato de la devolución de llamada: un objeto JavaScript que contiene los datos de la información de actualización.

Asignación de muestra a la devolución de llamada:

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

Resolución de devolución de llamada de muestra:

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

Funciones de la API específicas de OAuth

Estas funciones forman parte del procedimiento de autenticación OAuth, tal y como se describe en la página "Proceso de autenticación".

hsp.startAppTokenAuth()

Inicia el proceso de creación del token de sesión.
 
Cuando se llama a esta función, Hootsuite envía el token de acceso de OAuth al extremo de autenticación de la aplicación, que valida el token, y crea y devuelve un token de sesión. A continuación, Hootsuite vuelve a cargar la columna de aplicaciones, con lo que transmite el nuevo token de sesión como parámetro de URL.

hsp.editAppAuth()

Muestra la ventana emergente de autenticación de la aplicación.

editAppAuth.dabb2b17