JSApi v0.6

SDK do Diretório de Aplicativos

JSApi (v0.6, obsoleta)

Como funciona

JSApi é o canal de comunicação do SDK do Diretório de Aplicativos entre seu aplicativo e o painel da Hootsuite. A API permite que os desenvolvedores chamem funções que enviam eventos para o painel da Hootsuite e recebam notificações de evento específicas no painel da Hootsuite ou em um aplicativo.

As interações entre a Hootsuite e seu aplicativo são ativadas por dois arquivos:

  • API JS - A biblioteca Javascript do SDK, hsp.js, oferece funções que geram uma funcionalidade específica no painel da Hootsuite. hsp.js também possibilita a inicialização e o registro de seu aplicativo para receber eventos do painel da Hootsuite por meio de um receptor hospedado por seu aplicativo.
  • Receptor de aplicativo - Permite que seu aplicativo receba eventos do painel da Hootsuite. O receptor é mais especificamente necessário para que a função hsp.bind() descrita abaixo funcione.

Configuração

 
Os seguintes arquivos são necessários para usar a API JS:

  • Biblioteca JS - A biblioteca hsp.js possibilita a comunicação bidirecional entre seu aplicativo e o painel da Hootsuite. Inclua este arquivo na página principal de seu aplicativo: https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/hsp.js
     
    Por exemplo, a referência a esse arquivo na página principal apareceria da seguinte maneira:
    <script src="https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/hsp.js"></script>
  • Receptor de aplicativo - Permite que seu aplicativo receba eventos do painel da Hootsuite. O receptor é mais especificamente necessário para que hsp.bind() e hsp.updatePlacementSubtitle() funcionem. Esse arquivo precisa ser baixado, colocado no diretório raiz do aplicativo hospedado na raiz e referenciado por hsp.init() no parâmetro receiverPath (URL HTTPS).https://d2l6uygi1pgnys.cloudfront.net/jsapi/0-6/my_receiver.html

Eventos de funções & da API

A comunicação de seu aplicativo com o painel da Hootsuite ocorre com as funções disponíveis em hsp.js.
 
A comunicação do painel da Hootsuite com seu aplicativo é ativada por meio de eventos. Os eventos que devem ser notificados a seu aplicativo são registrados com chamadas da função hsp.bind(), o que indica ao evento em questão e à função callback que o aplicativo será executado quando esse evento for acionado.

Funções

  • init - Inicializa a API JS
  • bind - Registra um evento do painel da Hootsuite que será processado com o aplicativo e um manipulador de evento associado
  • clearStatusMessage - Remove todas as mensagens de status visíveis
  • composeMessage - Abre a janela de diálogo Compartilhar com Redes Sociais
  • retweet - Inicia o processo de diálogo em um retweet
  • customUserInfo - Abre uma janela pop-up de informações do usuário
  • getTwitterAccounts - Obtém uma lista de todos os perfis do usuário conectado no Twitter
  • showCustomPopup - Mostra uma janela de diálogo pop-up modal que contém um iFrame com conteúdo específico ao aplicativo
  • closeCustomPopup - Fecha a janela de diálogo pop-up modal
  • showFollowDialog - Abre uma janela de diálogo para seguir ou deixar de seguir um usuário do Twitter
  • showImagePreview - Mostra uma imagem em uma janela pop-up
  • showStatusMessage - Mostra uma notificação
  • showUser - Abre uma janela pop-up de informações do usuário
  • updatePlacementSubtitle - Atualiza o subtítulo do fluxo de aplicativo
  • assignItem - Atribui algum conteúdo de mensagem de texto a um usuário da Hootsuite

Eventos

  • closepopup - Acionado quando uma janela pop-up personalizada aberta pelo fluxo de aplicativo é fechada
  • dropuser - Acionado quando o usuário arrasta e solta o avatar de um usuário do Twitter do painel da Hootsuite em seu fluxo de aplicativo
  • refresh - Acionado quando a coluna do aplicativo é atualizada, seja pelo usuário no fluxo ou como parte de uma atualização do painel
  • sendtoapp - O registro deste evento fará com que os usuários vejam um item de menu Enviar para <fluxo de aplicativo>… nos menus de mensagem de fluxo do Twitter, Facebook e LinkedIn. Esse evento é acionado quando os usuários clicam no item de menu
  • sendcomposedmsgtoapp - Adiciona o plug-in de aplicativo ao seletor de perfil de redes sociais nativo da Hootsuite. O usuário pode enviar mensagens para o plug-in diretamente da caixa de composição de mensagem da Hootsuite
  • sendprofiletoapp - O registro deste evento fará com que os usuários vejam um item nos menus de perfil do Twitter, Facebook, LinkedIn e Google+. O evento é acionado quando os usuários clicam no item de menu
  • sendassignmentupdates - O registro deste evento permitirá que o aplicativo seja notificado de suas atualizações de atribuição

hsp.init(params)

Inicializa a API JS e carrega os arquivos CSS de tema.

params: object:

  • apiKey: (string)
  • receiverPath: (string, opcional)
     URL absoluto de seu arquivo app_receiver.html. Deve começar com https://
  • subtitle: (string, opcional)
     O subtítulo de seu aplicativo, a ser exibido no título do fluxo.
  • callBack: (função, opcional)
     Init enviará uma mensagem de erro para a função callBack após a inicialização. A mensagem é: Sem erro, se a inicialização for bem-sucedida.

Por exemplo:

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

hsp.bind(eventName, callback)

Registra um manipulador para um evento específico.

Observação: requer que o receptor de aplicativo seja configurado.

eventName: (string)

Nome do evento a ser manipulado. Pode ser um destes:

  • closepopup - Acionado quando uma janela pop-up personalizada aberta pelo fluxo de aplicativo é fechada
  • dropuser - Acionado quando o usuário arrasta e solta o avatar de um usuário do Twitter do painel da Hootsuite em seu fluxo de aplicativo
  • refresh - Acionado quando a coluna do aplicativo é atualizada, seja pelo usuário no fluxo ou como parte de uma atualização do painel
  • sendtoapp - O registro deste evento fará com que os usuários vejam um item de menu Enviar para <fluxo de aplicativo>… nos menus de mensagem de fluxo do Twitter, Facebook e LinkedIn. Esse evento é acionado quando os usuários clicam no item de menu

callback: (função)

Função para manipular o retorno. Os parâmetros da função são determinados pelo evento. Consulte a seção de eventos para obter detalhes sobre os formatos de retorno esperados.

Por exemplo:

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

Como informado na seção Melhores práticas, é recomendável suprimir a recarga do fluxo enquanto o usuário está interagindo com ele (por exemplo, publicando mensagens, detalhes expandidos, possivelmente rolar a posição até um ponto distante da parte superior). Uma possível abordagem poderia ser esta:

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

O uso de window.location.reload() não é obviamente a melhor abordagem, e foi utilizada principalmente para manter os exemplos simples. Uma das melhores soluções seria sondar a existência de alguma nova mensagem via AJAX e injetar somente as novas mensagens no DOM, mantendo as mensagens já existentes intactas.

hsp.clearStatusMessage()

Remove todas as mensagens de status visíveis.

hsp.composeMessage(message, params)

Abre a janela de diálogo Compartilhar com Redes Sociais no painel da Hootsuite.

message: (string)

Aplicam-se regras de mensagem do Twitter. Por exemplo, para compor um DM para @Hootsuite: d hootsuite <sua mensagem aqui>

params: (objeto, opcional):

  • shortenLinks: bool, opcional
     Encurte todos os links encontrados na mensagem com o encurtador de URL padrão do usuário (ow.ly / ht.ly / ou url personalizado). O padrão é falso.
  • timestamp: bool OU int, opcional
     Abra o Agendamento e preencha-o com o carimbo de data/hora (em GMT). Se for informada a opção verdadeiro, o Agendamento abrirá sem horário padrão. O padrão é falso.
  • replyToId: string, opcional
     Componha um novo tweet em resposta a um outro tweet. Se uma ID de string válida foi informada para um tweet já existente, o recurso de composição tratará a nova mensagem como parte da conversa.

Por exemplo:

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

hsp.retweet(id, screenName)

Abre o processo de diálogo do retweet no painel da Hootsuite para o tweet com a id a ser enviada como retweet por screenName.

id: (string)

id_str tweetId do Twitter para o tweet do retweet

screen_name: (string, opcional)

O screen_name do Twitter com o qual você deseja enviar o retweet

Por exemplo:

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

hsp.customUserInfo(data)

Abre uma janela pop-up de informações do usuário.

data: (objeto JSON)

Por exemplo:

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)

Mostra uma janela pop-up modal que contém um iFrame com conteúdo do URL especificado. Ao ser fechada, a janela de diálogo aciona o evento closePopUp().

src: (string)

O URL do conteúdo a ser exibido na janela pop-up

title: (string)

O título exibido na janela pop-up

width: (int)

A largura em pixels da janela pop-up. A largura tem as seguintes restrições:

  • Se não for especificada, o valor padrão da largura será de 640 pixels
  • A largura mínima é de 300 pixels.
  • A largura máxima é de 900 pixels.

height: (int)

A altura em pixels da janela pop-up. A largura tem as seguintes restrições:

  • Se não for especificada, o valor padrão da altura será de 445 pixels
  • A altura mínima é de 225 pixels.
  • A altura máxima é de 500 pixels.

Por exemplo:

hsp.showStatusMessage('Pronto!', 'sucesso') ;

Importante:

Não inicialize hsp novamente dentro da janela pop-up personalizada. Sua janela pop-up não deve usar qualquer função hsp que não seja closeCustoomPopup(apiKey, pid).

Se sua janela pop-up e fluxo/plug-in de aplicativo estão no mesmo domínio, é recomendável que sua janela pop-up utilize a seguinte função javascript para comunicar-se de volta com o fluxo/plug-in e executar a função hsp: window.parent.frames[apiKey_pid].hsp.some_function()

Observação: As funções de vinculação de evento hsp não estão disponíveis na janela pop-up personalizada.

hsp.closeCustomPopup(apiKey, pid)

Fecha a janela pop-up modal.

Observação: Certifique-se de que a página iFrame na janela pop-up personalizada e a página de fluxo de aplicativo compartilhem o mesmo domínio. Você não precisa (nem deve) chamar hsp.init() novamente na página iFrame; basta incluir hsp.js e chamar hsp.closeCustomPopup(apiKey, pid). Você pode usar o JavaScript para comunicação entre a janela pop-up e o fluxo desta maneira:

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

apiKey: (string)

API Key de seu aplicativo

pid: (string)

O pid está associado a cada instalação exclusiva de um fluxo (ou plug-in) de aplicativo. Você pode obter o pid de cada fluxo de aplicativo na solicitação de url que seu servidor recebe. Por exemplo:

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

hsp.showImagePreview(src, externalUrl)

Mostra uma imagem em uma janela pop-up, opcionalmente vinculada a um URL externo.

src: (string)

URL da imagem

externalURL: (string)

URL a ser aberto se o usuário clica na imagem

hsp.showStatusMessage(message, type)

Mostra uma notificação na área central superior do painel da Hootsuite.

message: (string)

Deve ser concisa com um máximo de 70 caracteres.

type: (string):

Pode ser uma destas:

  • info: Plano de fundo azul
  • erro: Plano de fundo vermelho
  • aviso: Plano de fundo amarelo
  • sucesso: Plano de fundo verde

hsp.updatePlacementSubtitle(name)

Atualiza o subtítulo do fluxo de aplicativo.

Observação: Requer que o receptor de aplicativo seja configurado (veja acima).

name (str)

Máximo de 35 caracteres

hsp.showUser(twitterHandle)

Abre uma janela pop-up com informações referentes ao nome de usuário especificado no Twitter.

twitterHandle: (string)

Nome de usuário no Twitter

Por exemplo:

hsp.showUser('hootsuite_help');

showUser.f203dc7a

hsp.showFollowDialog(twitterHandle, isFollow)

Abre uma janela de diálogo com a opção de seguir ou deixar de seguir um usuário do Twitter.

twitterHandle: (string)

Nome de usuário no Twitter

isFollow: (bool)

verdadeiro para seguir, falso para deixar de seguir.

Por exemplo:

hsp.showFollowDialog('hootsuite_help', true);

showFollowDialog.ff5cb783

hsp.getTwitterAccounts(callback)

Obtém uma lista (array) de todos os perfis do Twitter (nomes de usuário) que o usuário conectado adicionou à respectiva conta da Hootsuite.

callback: (função)

Função que aceita um array de strings

Por exemplo:

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

hsp.assignItem(data)

Atribua uma mensagem ou algum conteúdo de texto a um usuário da Hootsuite (indivíduo ou membro de equipe)

data: (objeto JSON)

Por exemplo:

var data = {
  "messageId": "1000020", //REQUIRED
  "message": "Olá, estou tendo um problema com minha conta",  //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

Esta seção descreve o conjunto de eventos disponíveis e as assinaturas da função do manipulador de evento esperada disponíveis com o uso de hsp.bind().

refresh()

Acionado quando a coluna do aplicativo é atualizada, seja pelo usuário no fluxo ou como parte de uma atualização do painel.

formato de retorno: uma função sem parâmetros

Por exemplo:

function refreshHandler () { }

dropuser()

Acionado quando o usuário arrasta e solta o avatar de um usuário do Twitter do painel da Hootsuite em seu fluxo de aplicativo
 

formato de retorno: uma função com dois parâmetros, o handle do usuário no Twitter e a ID exclusiva do tweet de onde o usuário foi arrastado

Por exemplo:

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

sendcomposedmsgtoapp()

Adiciona o plug-in de aplicativo ao seletor de redes sociais nativo da Hootsuite. O usuário pode enviar mensagens para o plug-in diretamente da caixa de composição de mensagem da Hootsuite

OBSERVAÇÃO: você precisa contatar a equipe administrativa do diretório de aplicativos para possibilitar essa vinculação de evento para seu plug-in de aplicativo

formato de retorno: Um objeto javascript que contém os dados da mensagem

Estrutura de dados do objeto da mensagem:

Message: (object)
  text: (string)

Por exemplo:

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

closepopup()

Acionado quando uma janela pop-up personalizada aberta pelo fluxo de aplicativo é fechada

formato de retorno: uma função sem parâmetros

Por exemplo:

function closePopupHandler () {
  // ...
}

sendtoapp()

O registro deste evento fará com que os usuários vejam um item de menu Enviar para <fluxo de aplicativo>… nos menus de mensagem de fluxo do Twitter, Facebook e LinkedIn. Esse evento é acionado quando os usuários clicam no item de menu.

formato de retorno: Um objeto javascript que contém os dados da mensagem

Estrutura de dados do objeto da mensagem:

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

Exemplo de objeto da mensagem:

( {
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 : "Pré-visualização: fotos incríveis ...",
      bodyhtml : "Pré-visualização: fotos incríveis ..."
    },
    attachments : [
      type : "photo",
      title: "Aplicativo da 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 : "Esta foto é excelente!",
        uid : 2377483482
      }
    }
  }
} )

Por exemplo:

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

sendprofiletoapp()

O registro deste evento fará com que os usuários vejam um item nos menus de perfil do Twitter ou do Facebook. O evento é acionado quando os usuários clicam no item de menu.

formato de retorno: Um objeto javascript que contém os dados do perfil

Estrutura de dados do objeto do perfil:

(clique no link para expandir) 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()

O registro deste evento permitirá que o aplicativo seja notificado de suas atualizações de atribuição

formato de retorno: Um objeto javascript que contém os dados da atualização

Exemplo de atribuição para retorno de chamada:

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

Exemplo de resolução de retorno de chamada:

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

Funções de API específicas ao OAuth

Essas funções fazem parte do procedimento de autenticação do OAuth, conforme descrito na página "Processo de autenticação".

hsp.startAppTokenAuth()

Inicia o processo de criação do token de sessão.
 
Quando chamada, a Hootsuite envia o token de acesso do OAuth armazenado para o endpoint de autenticação do aplicativo que valida o token e cria e retorna um token de sessão. A Hootsuite, em seguida, recarrega o fluxo de aplicativo, passando o novo token de sessão como um parâmetro URL.

hsp.editAppAuth()

Exibe a janela pop-up de autenticação do aplicativo.

editAppAuth.dabb2b17