SNAM API v2.1

O SNAM é uma plataforma que realiza a coleta de dados nas Redes Sociais, aplicando sobre estes dados análise cognitiva e inteligência, fornecendo para empresas e desenvolvedores a capacidade de conhecer o perfil, sentimento, emoções e até o comportamento dos seus cliente e usuários.

Esta documentação irá descrever como você pode automatizar a integração entre o seu sistema e o SNAM.io. Com esta API você pode gerenciar seus usuários, solicitando assim a atualização e manutenção dos dados coletados e definido quais Agentes e Inteligência serão aplicados para cada usuário em cada coleta de dados.

Como Funciona

Para entender como o SNAM.io funciona é necessário primeiramente compreender os seus principais componentes e como eles se integram.

O Core do SNAM utiliza-se de 3 componentes que se integram entre si, para que desta forma possa obter os dados das Redes Sociais e entregar um valor sobre estes dados, estes componentes são: Connections , Collector e Agentes, segue abaixo uma imagem para ilustrar o fluxo de dados entre estes componentes.


1 - Connections

Uma connection é uma fonte que fornece dados ao SNAM.io, ou seja, cada Rede Social, blog ou sistema na qual o SNAM se conecta para obter dados.

ATENÇÂO: Pelo fato do SNAM.io utilizar-se das APIs das Redes Sociais, por padrão você precisa ter um APP aprovado na Rede Social com a qual irá realizar a connection, com as devidas permissões necessárias para as coletas e Agentes de Inteligência a serem utilizados.

Caso a aplicação não tenha um APP aprovado na rede social, avaliamos em conjunto alternativas para a integração, entre em contato pelo e-mail snam@beonpop.com.

   Connections Suportadas
  • Facebook
  • Instagram
  • Twitter
  • SoundCloud em breve
  • Youtube em breve
  • Linkedin em breve

ATENÇÂO: Caso necessite de uma conexão que ainda não está integrada com o SNAM.io, entre em contato pelo e-mail snam@beonpop.com para uma avaliação.


AuthID:


Pelo fato do SNAM.io suportar multiplas Redes Sociais para uma mesma pessoa, empresa ou perfil, criamos um identificador único chamado de AuthID .
Antes de realizar uma requisição com coleta de dados, você deve cadastrar o AuthID no SNAM.io informando seus dados de Acesso a Rede Social (Obtido através de SocialLogin), para que desta forma os Collectors possam coletar os dados.


2 - Collectors

Os Collectors são métodos de cada Connection que obtem cada dado específico em cada Rede Social, blog ou sistema, os collectors usam os dados de acesso do seu APP e do AuthID informados na configuração do SNAM.io, desta forma o collector saberá em qual Rede Social de qual aplicação de Qual usuário os dados devem ser obtidos.
Cabe aos collectors enviar os dados aos Agentes, para que os mesmos apliquem a sua devida Inteligência sobre estes dados.


3 - Agentes de Inteligência

Os Agentes de Inteligência são processos que tratam, compilam, consolidam ou transformam os dados.
Pelo fato do SNAM.io obter diversos dados em diversas conexões, os Agentes de Inteligência trabalham de duas formas de execução, assíncrono e sincrono:

Síncrono (Sync) Esta forma de execução trabalha como Request/Response, ou seja, você fará a solicitação de execução do agente e o mesmo irá prontamente retornar o resultado esperado.

Assíncrono (Async) Esta forma de execução trabalha de forma assíncrona, pois a mesma necessita coletar os diversos dados em diversas connections, com isso esta solicitação irá retornar um requisition_id, que é o identificador unico da requisição e um handle, com estas duas informações você saberá quando a execução estará concluída, através do método de status ou da configuração de WebHook.


Modos de Execução:


As Redes Sociais funcionam em modelo de Grafo conectando entre si 3 componentes básicos: Nós ou Atores, Vincúlos e Fluxos de Informação. Para representar este modelo no SNAM.io de uma forma que você possa executar os Agentes de Inteligência nos elementos vitais para o funcionamento de uma Rede Social, criamos 3 Modos de Execução que representam estes principais componentes:

main    Agente de Inteligência realizará a análise da Página/Perfil para o AuthID (Usuário) gerando resultado geral.
object  Agente de Inteligência realizará a análise de um Objeto que pode ser um (POST, Photo, Vídeo, Tweet)
people Agente de Inteligência realizará a análise das pessoas através das interações ocorridas

Autenticação

Para autenticar na API é necessário que você possua as credenciais de acesso. Os mesmos são fornecidos pelo BeOnPop, caso ainda não possua entre em contato no e-mail snam@beonpop.com.

  • APP-ID : Identificador da sua aplicação.
  • APP-TOKEN : Access Token da sua aplicação.

Alguns pedidos que exigem autenticação irão retornar 404 Not Found, em vez de 403 Forbidden. Isso é para evitar detecção da existência de dados privados por usuários não autorizados.

Há duas maneiras de autenticar através da API:

HTTP Basic

curl -u "<APP-ID>:<APP-TOKEN>" https://<aplicativo>.snam.io/v2.1/version

X-Auth (envio no header)

curl -H "x-Auth-APPID: <APP-ID>" -H "x-Auth-TOKEN: <APP-TOKEN>" https://<aplicativo>.snam.io/v2.1/version

Parâmetros

A API possui suporte a dois métodos para o envio de parâmetros

QueryString

  
  curl -i -X POST https://<aplicativo>.snam.io/v2.1/auth \ 
  -u "<APP-ID>:<APP-TOKEN>" \ 
  -d "email=teste@beonpop.com&name=beonpop"
  

JSON

Para enviar um JSON, é necessário informar no header o content-type: application/json

  
  curl -i -X POST https://<aplicativo>.snam.io/v2.1/auth \
  -u "<APP-ID>:<APP-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"email" : "teste@beonpop.com", "name" : "beonpop"}'
  

Response

Cada resposta retorna um código HTTP apropriado conforme especificação https://tools.ietf.org/html/rfc7231#section-6.

Todas as respostas retornam no formato JSON válido.

É disponibilizado por padrão timestamps created_at e updated_at. Os dados que representam datas são retornados no formato ISO8601.


{
  // ...
  "created_at": "2012-01-01T12:00:00Z",
  "updated_at": "2012-01-01T13:00:00Z",
  // ...
}
      

Exemplos códigos HTTP

Alguns exemplos de códigos HTTP de retorno
Códigos HTTP Descrição
200 OK Requisição com êxito para um pedido GET, DELETE ou PATCH, PUT que se completou de forma síncrona
201 Created Requisição com êxito para um pedido POST, PUT
202 Accepted Requisição aceita para um pedido POST, PUT, DELETE, ou PATCH que será processada de forma assíncrona
400 Bad Request A solicitação enviada é inválida
401 Unauthorized Requisição falhou porque a aplicação () não está autenticada
403 Forbidden Requisição falhou porque a aplicação () não tem autorização para acessar o recurso específico
404 Not Found Recurso não existe.
404 Method not allowed O verbo enviado não é válido para o recurso solicitado
422 Unprocessable Entity Sua requisição foi entendida, mas contém parâmetros inválidos
429 Too Many Requests Você superou o limite de consumo, tente novamente mais tarde
498 Invalid Token O Token de acesso a Rede Social está expirado ou é inválido
500 Internal Server Error Algo deu errado com o Servidor, confira o site do estado e/ou notifique o problema

Response Errors

Na situação de envio de dados inválidos no Request (422 Unprocessable Entity) será incluído ao corpo da resposta JSON um parâmetro errors, que lista quais foram os erros informados na requisição.


HTTP/1.0 422 Unprocessable Entity
{
  "id": "unprocessable_entity",
  "message": "The given data failed to pass validation.",
  "errors": {
    "email": ["The email field is required."],
    "name": ["The name field is required."]
  }
}

Paginação

Algumas requisições realizadas na API irão retornar uma lista de informações, estas informações não serão retornadas em uma única resposta, isso ocorre pois algumas respostas podem ter milhares de informações, por isso estas requisições são paginadas.
Segue abaixo um exemplo de uma resposta JSON paginada:

curl -i https://<aplicativo>.snam.io/v2.1/d5d13c2bf767c9c0bb4fdea845942379b045fc82/main?limit=5 -u "<APP-ID>:<APP-TOKEN>" 

HTTP/1.0 200 OK
{
  "data": [{
    ...
  }, {
    ...
  }, {
    ...
  }],
  "paging": {
    "previous": {
      "url": "https://<aplicativo>.snam.io/v2.1/d5d13c2bf767c9c0bb4fdea845942379b045fc82?offset=0&limit=5",
      "offset": 0
    },
    "next": {
      "url": "https://<aplicativo>.snam.io/v2.1/d5d13c2bf767c9c0bb4fdea845942379b045fc82?offset=10&limit=5",
      "offset": 10
    },
    "limit": "5"
  }
}

Descrição dos parâmetros retornados no paging

Códigos HTTP Descrição
offset Indicador do Início de cada página
limit Número de objetos individuais que são devolvidos em cada página. Um limite de 0 não irá retornar nenhum resultado.
next Url que informa qual a próxima página a ser requisitada. Se não for exibida, esta será a última página
previous Url que informa a página de dados anterior. Se não for incluída, esta é a primeira página

WebHook

Receba eventos das coletas de dados e Agentes de Inteligência em tempo real com o WebHook. Ao configurar o WebHook no SNAM App uma URL pre-determinada receberá uma requisição HTTP POST.

Entendendo as configurações de WebHook no SNAM App.


Campo Descrição
Status A qualquer momento você pode ativar e desativar o webhook. Quando o webhook está inativo e um evento ocorre no sistema, a notificação não é criada. Se o evento é ativado posteriormente, essa notificação será perdida, mas todas as próximas serão criadas no momento que os eventos forem ocorrendo.
URL Endereço que receberá a requisição HTTP POST de notificação do evento. É recomendável que seja um endereço que use SSL, ou seja, que inicie com https://.
content-type Você pode escolher por receber a requisição no formato application/json ou application/x-www-form-urlencoded. Essa configuração será usada no cabeçalho Content-Type da requisição
verify_token Corresponde a um valor fornecido por você, essa é uma verificação de segurança para que seu servidor saiba que a solicitação está sendo feita pelo SNAM.io

Recebendo um webhook


A seguir um exemplo dos dados enviados pelo SNAM.io para sua URL de recebimento.
Campo Descrição
action Ação do evento.

Valores permitidos: {initiated, completed}

verify_token Valor configurado por você no SNAM App para verificação de segurança.
requisition_sid SNAM ID da coleta de dados
authid Identificador da Autenticação no SNAM

Exemplo WebHook Coleta Iniciada


{
    "action": "initiated",
    "verify_token": "cn*Y?P)m$&#vG6-`h3VZX/@cnrQ4aTH`'}wP7+]>r-6xDJw'&@",
    "requisition_sid": "7e2955c0163ad6ae91c6fc9a4c00c702e637dcbb",
    "authid": "70ccdd2a79b80bb6"
}

Exemplo WebHook Coleta Finalizada


{
    "action": "completed",
    "verify_token": "cn*Y?P)m$&#vG6-`h3VZX/@cnrQ4aTH`'}wP7+]>r-6xDJw'&@",
    "requisition_sid": "7e2955c0163ad6ae91c6fc9a4c00c702e637dcbb",
    "authid": "70ccdd2a79b80bb6",
    "agent": "pop-rank"
}

Agentes de Inteligência

POP Score

Este Agente de Inteligência mensura a popularidade de perfis nas Redes Sociais, através da medida de referência chamada POP “Points of Performance”, através da coleta de dados eficiente e rápida promovida pelo core do SNAM.io, este agente aplica um algoritmo único nos dados coletados, levando em consideração interações e indicadores para cada conta analisada, com estas interações e indicadores o Agente gera as seguintes métricas:


Como o algoritmo do POP Score funciona?


O POP Score é uma métrica de desempenho global, baseado no algoritmo criado pelo BeOnPop, o índice analisa e acompanha o desempenho de marcas e indivíduos em redes sociais e atribui uma pontuação. POP significa “Points of Performance” ou seja, seu desempenho em pontos; quanto maior a pontuação, melhor será o seu desempenho. Não há limite numérico para sua pontuação.
Entre outros fatores, o POP Score considera o tipo de interação, seu impacto e peso. Alguns exemplos:
Interação Connection (Rede Social) Impacto
Reações Facebook Baixo
Curtir Instagram, Twitter Baixo
Comentários Facebook, Instagram Alto
Compartilhamentos Facebook Alto
Retweets Twitter Alto
Amigos / Seguidores Facebook, Twitter, Instagram Muito Baixo

Interação: As principais interações de cada Rede Social.

Impacto: Cada interação cria um diferente nível de impacto. Por exemplo: curtir uma publicação é uma interação de “baixo” impacto. A pessoa mais impactada por curtidas é quem fez a publicação, enquanto compartilhar uma publicação é uma interação alta por aumentar o alcance, uma vez que todos os amigos da pessoa que compartilhou a publicação agora tem acesso a ela.


Modos de Execução Suportados:


Main POP Score Geral somando todas as interações de todas as conexões cadastradas ou informadas.
Object POP Score por Objeto da Rede Social, (Posts,Videos,Fotos, Mídia) aplicando o POP Score sobre as interações do objeto, possibilitando e exibição da timeline do perfil das redes sociais conectadas.


Dados Retornados:


pops “Points of Performance” Popularidade gerada pelas interações
shares Total de compartilhamentos
friends/fans/followers Total de amigos, seguidores, fãs
objects Total de objetos (fotos, vídeos, mídias, tweets)
comments Total de comentários
reactions Total de reações/curtidas
period Périodo da coleta de dados, os dados usados pelo Agente foram dados criados dentro deste período.
created_at Data de criação da requisição, essa é a data da primeira requisição efetuada.
updated_at Data da atualização da requisição, essa é a data da última requisição efetuada.


Exemplo de Resposta:



  {
    "pops": "1.804",
    "period": {
        "since": "2017-08-28T00:00:00+0000",
        "until": "2017-09-28T16:14:38+0000"
    },
    "shares": 3,
    "friends": 688,
    "objects": 21,
    "comments": 13,
    "reactions": 347,
    "created_at": "2017-09-28T15:07:25+0000",
    "updated_at": "2017-09-28T16:14:38+0000"
  }

POP Rank

Este Agente de Inteligência obtem todas as pessoas que você influênciou, criando assim sua influência direta, identificando quem são as pessoas que mais interagem com com as publicações.

Tipos de Reações (Facebook): Este Agente tem a capacidade de obter métricas por tipo de reações do Facebook, identificando Raiva, Alegria, Surpresa, entre outros disponíveis.


Modos de Execução Suportados:


Main Além das métricas somandas para o usuário, retorna a influência Real e os detalhes de reações do Facebook.
People POP Rank das pessoas que interagiram com o usuário nas Redes Sociais aplicando o POP Score sobre as interações que as pessoas realizaram com o usuário na Rede Social.


Dados Retornados:


influence Total de pessoas que interagiram com suas publicações.
shares Total de compartilhamentos
friends/fans/followers Total de amigos, seguidores, fãs
objects Total de objetos (fotos, vídeos, mídias, tweets)
comments Total de comentários
reactions Total de reações/curtidas
reactions_type Total de reações do Facebook por tipo (wow,haha,like,lovesad,angry,thankfull)
period Périodo da coleta de dados, os dados usados pelo Agente foram dados criados dentro deste período.
created_at Data de criação da requisição, essa é a data da primeira requisição efetuada.
updated_at Data da atualização da requisição, essa é a data da última requisição efetuada.


Exemplo de Resposta:



  {
    "period": {
        "since": "2017-08-28T00:00:00+0000",
        "until": "2017-09-28T16:14:38+0000"
    },
    "shares": 3,
    "objects": 21,
    "comments": 13,
    "reactions": 347,
    "reactions_type": {
        "wow": 1,
        "haha": 3,
        "like": 292,
        "love": 51
    },
    "created_at": "2017-09-28T15:23:49+0000",
    "updated_at": "2017-09-28T16:14:38+0000",
    "influence": "408"
  }

Começando

Para começar a usar a API, você precisa de duas coisas:

   1. Criar ou já possuir APPs cadastrados nas Redes Sociais que deseja conectar o SNAM.io
   2. Ter um APP-ID e APP-TOKEN para autenticação no SNAM.io

Para mais informações ou para solicitar credenciais de acesso entre em contato no e-mail snam@beonpop.com.

Como Integrar sua aplicação

A integração entre seu APP e o SNAM.io é feita em 3 partes: Registro de Usuário, Requisição e Consulta


Registro de Usuário (AuthId)


Primeiramente sua aplicação deve registrar o seu usuário no SNAM.io, informando quais as Connections o SNAM.io deve obter os dados, conforme os passos abaixo

  • 1. Obtenha o AccessToken da Rede Social

    A sua aplicação deve efetuar a autenticação do usuário nas Redes Sociais (OAuth). Após a autorização do usuário final, aplicação recebe o UserId e o AccessToken da Rede Social.

  • 2. Cadastro do Usuário e Conexão no SNAM.io

    A sua aplicação envia ao SNAM.io o UserID e AccessToken da Rede Social, com isso o SNAM.io gera o AuthID que é um identificador único do usuário da sua aplicação e o identificador de cada conexão (Rede Social) o ConnectionID .

    
    curl -i -X POST https://<aplicativo>.snam.io/v2.1/auth \
    -u "<x-Auth-APPID>:<x-Auth-TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
       "name": "Cleber Rodrigues",
       "external_id": 6,
       "email": "cleber@cleberar.com",
       "connections": [{
           "connection": "facebook",
           "userid": 100002492169441,
           "token": "CAAH3ZAA .... nVi5aFqToAZDZD"
       }, {
           "connection": "twitter",
           "userid": 62806399,
           "token": {
               "oauth_token": "628 .... PIrYmt",
               "oauth_token_secret": "18U2 .... WJ12ab"
           }
       }]
    }'
    
    HTTP/1.0 201 Created
    {
        "authid": "70ccdd2a79b80bb6",
        "name": "Cleber Rodrigues",
        "external_id": 6,
        "email": "cleber@cleberar.com",
        "connections": [{
            "name": "facebook",
            "uuid": "c9bd8174-9643-4d42-8701-2859566cee93",
            "userid": 100002492169441
        }, {
            "name": "twitter",
            "uuid": "82872b01-312a-4ea7-8c3d-e54e4ef25e46",
            "userid": "62806399"
        }]
    }
                

    Para mais detalhes sobre cadastro de AuthID veja 1.Cadastro de AuthID


Requisição


Após ter seu usuário registrado no SNAM.io com as suas devidas conexões, você pode a qualquer momento coletar dados do mesmo, aplicando um Agente de Inteligência específico.

  • 3. Requisição

    A sua aplicação envia ao SNAM.io o AuthID do usuário na qual deseja coletar os dados das Redes Sociais conectadas (ConnectionID), informando quais Agentes de Inteligência você deseja executar nos dados coletados.
    A coleta de dados é assíncrona, desta forma será retornado um Hash, na qual a aplicação irá consultar sobre o término da mesma.

    curl -i -X POST https://<aplicativo>.snam.io/v2.1/requisition \
    -u "<x-Auth-APPID>:<x-Auth-TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
       "authid" : "70ccdd2a79b80bb6",
       "modes": ["main"],
       "agents": ["pop-score"]
    }'
    
    HTTP/1.0 200 OK
    {
        "requisition_sid": "d5d13c2bf767c9c0bb4fdea845942379b045fc82",
        "handle": "25xYnT096bjCHUkzBC+GjwSxWjh\/gO30h6C7v9hTQeTttMR3nW5kyLNjLZHRUkr62YAZp2Jt8KjuBHbSABY7YWIhwqXc5kgLYPOF9Pk+prI="
    }
    

    Para mais detalhes sobre cadastro de AuthID veja 1.Executar Requisição


Consulta de Dados


  • 4. Consulta

    Após a conclusão da coleta de dados, o SNAM.io está apto a fornecer para a sua aplicação, informações das Redes Sociais conectadas e o resultado de cada Agente de Inteligência informado na coleta.

    curl -i https://<aplicativo>.snam.io/v2.1/requisition/d5d13c2bf767c9c0bb4fdea845942379b045fc82 \
    -u "<x-Auth-APPID>:<x-Auth-TOKEN>"
    
    HTTP/1.0 200 OK
    {
        "authid": "7f22e664c87a8901",
        "name": "Cleber Rodrigues",
        "external": {
           "id": "dbffe0fb57dbbe7c6fb75070c9fbae33"
        },
        "agents": {
          ...
        }
      }
    

    Para mais detalhes sobre cadastro de AuthID veja - Consulta

Endpoints


Bibliotecas SNAM

Bibliotecas, SDKs e Kits para facilitarem sua integração com o SNAM.io


  • SNAM SDK PHP beta

    Simples SDK OpenSource feito em PHP para agilizar sua integração com o SNAM.io.
    Suporte a OAuth : Abstração para efetuar Social Login e efetuar cadastro de AuthId no SNAM.io