Versão 6.0

Outubro 2012 1

Guia de Implementação

Índice

Índice ....................................................................................................................... 0

1 Sobre este documento ........................................................................................... 1

2 Sobre o processo de moderação.............................................................................. 1

3 Método de integração assincrônico .......................................................................... 2

3.1 Enviando / obtendo conteúdos a serem moderados.............................................. 2

3.1.1 Formato de XML de envio ............................................................................ 3

3.1.2 Confirmação de recebimento ....................................................................... 4

3.2 Enviando resultados de moderação .................................................................... 5

3.2.1 Formato XML de resultado de moderação ...................................................... 5

Método de integração sincrônica ................................................................................... 7

4 Contato ............................................................................................................... 8

5 Apêndice .............................................................................................................. 9

5.1 Tabela descritiva de XML de input ...................................................................... 9

5.2 Tabela descritiva de XML de output .................................................................. 11

5.3 Tabela descritiva de XML de output de moderação sincrônica ............................. 12

Versão 6.0

Outubro 2012 1

1 Sobre este documento

Este documento fornece informação necessária para utilizar os serviços de moderação providos por Keepcon.

Está orientado às pessoas com conhecimentos técnicos, encarregadas do desenvolvimento e/ou administração de um site web.

Ele está agrupado em seções, cobrindo o processo de moderação e documentação técnica específica de como levar a cabo uma integração exitosa do processo de moderação em seu site.

2 Sobre o processo de moderação

Keepcon oferece diferentes tipos de serviços de moderação, e está fora do alcance deste documento detalhá-los, independente do serviço particular que se contrate, todos eles incluem ao menos duas operações: enviar os conteúdos a serem moderados e receber uma resposta para os conteúdos moderados.

Fica como tarefa do cliente incorporar ao seu processo interno o envio de dados para moderação, a busca de resultados dos mesmos e a ação consequente em base a ditos resultados, segundo suas próprias regras de negócio.

Versão 6.0

Outubro 2012 2

3 Método de integração assincrônico

A integração assincrônica consiste em realizar as operações de envio de conteúdo a ser moderado e a consulta de conteúdos moderados de maneira separada, sem correlação entre elas. De tal forma , o cliente deverá programar dois processos independentes, um para cada operação mencionada.

À continuação, descrevemos , em detalhes, cada uma das operações, com exemplos e passos a seguir para uma integração exitosa.

3.1 Enviando / obtendo conteúdos a serem moderados

O cliente enviará a Keepcon os conteúdos a serem moderados de maneira periódica e em lotes (definir a base do volume e necessidades concretas).

Por exemplo, se a média de volume de conteúdo a ser moderado gira em torno dos 1000 por hora, seria necessário enviar lotes de 50 elementos a cada 3 minutos.

Keepcon fornece um serviço web REST pelo qual o cliente enviará o conteúdo em formato XML.

O endereço do serviço é o seguinte:

http://async.keepcon.com:63081/input/contentSet

Modo do uso do serviço:

1. Construir o XML com o conteúdo no formato que se detalha na seção 3.1.1.

2. Adquirir o serviço com um PUT HTTP enviando o XML no body do Request.

3. Ler a resposta do serviço adjunto no body do Response, e verificar se o envio se realizou satisfatoriamente. Em caso contrario, tentar novamente o envio. Ver seção 3.1.2.

Versão 6.0

Outubro 2012 3

3.1.1 Formato de XML de envio

O conteúdo enviado e a ser moderado deverá seguir o seguinte formato XML:

<?xml version="1.0" encoding="UTF-8" ?>

<import>

<contenttype>[account-name]</contenttype>

<contents>

<content id="1">

<author type="author">Pepe1989</author>

<url_context><![CDATA[http://blog.keepcon.com/?p=143]]></url_context>

<datetime>1262304000000</datetime>

<text><![CDATA[Olá amigo de toda comunidade!!!]]></text>

<img><![CDATA[http://misitio.com/una-foto.jpg]]></img>

<video><![CDATA[http://misitio.com/un-video.flv]]></video>

</content>

<content id="2">

<author type="author">Gandalf</author>

<url_context><![CDATA[http://blog.keepcon.com/?p=142]]></url_context>

<datetime>1262304000000</datetime>

<text><![CDATA[Olá, bem vindo!]]></text>

<img><![CDATA[http://misitio.com/una-foto.jpg]]></img>

<video><![CDATA[http://misitio.com/un-video.flv]]></video>

</content>

</contents>

</import>

Na seção, 5.1 detalha-se cada elemento do XML.

Versão 6.0

Outubro 2012 4

3.1.2 Confirmação de recebimento

Como resposta ao envio, Keepcon enviará uma confirmação dizendo que foi recebido com êxito um lote de conteúdos, junto com o identificador de lote referente ao tal envio. O formato da resposta será o seguinte.

Formato da resposta:recepção positiva.

<?xml version="1.0" encoding="UTF-8" ?> <response> <setId>35</setId> <status>OK</status> </response> Formato da resposta: recepção negativa.

<?xml version="1.0" encoding="UTF-8" ?> <response> <status>ERROR</status> <errorMessage>Formato xml incorreto</errorMessage> </response>

Por cada conjunto de conteúdos que Keepcon recebe, é fornecido um número de “lote” que se indica pelo atributo setId. Este poderá ser utilizado pelo cliente para seguir um conjunto de conteúdos dado: em que estado do processo de moderação se encontra, se já foi enviado o resultado, etc.

Importante:

É obrigatório implementar um mecanismo de tentativas. Existe a possibilidade que, por algum erro, imprevisto ou por tarefas de manutenção planificadas, e oportunamente comunicadas, o serviço de recebimento de conteúdos esteja fora do ar. Nesses casos o processo de invocação deverá detectar o código de erro ou a falta de resposta, e deverá proceder outras tentativas, com certa frequencia,até poder injetar os conteúdos na plataforma de Keepcon.

Versão 6.0

Outubro 2012 5

3.2 Enviando resultados de moderação

Uma vez processados os conteúdos, os resultados estarão disponíveis para o cliente.

O cliente consultará periodicamente o serviço web para obter os resultados dos conteúdos moderados.

Para isto, Keepcon fornece um serviço de web REST onde é possível verificar os resultados.

O endereço é o seguinte:

http://async.keepcon.com:63081/output/contentSet?contextName=[account-name]

onde [account-name] é o nome da conta de sua empresa.

Modo de uso do serviço:

1. Requisitar o serviço com um PUT HTTP, enviando como parâmetro o nome da conta oportunamente provida por Keepcon.

2. Ler a resposta do serviço adjunta no body do Response. O formato de resposta detalhamos na seguinte seção. No caso de não haver resposta, significa que não há resultados de moderação pendentes a serem consultados.

3. Aplicar os resultados de moderação segundo suas próprias regras de negócio.

3.2.1 Formato XML de resultado de moderação

Os resultados da moderação que se enviam ao cliente terão o seguinte formato XML:

<?xml version="1.0" encoding="UTF-8"?>

<export setId="3674">

<contents>

<content id="1" >

<moderatorName>moderador1</moderatorName>

<moderationDate>1272973151662</moderationDate>

<moderationDecision>REJECTED</moderationDecision>

<tagging>

<tag>Inapropriado</tag>

</tagging>

</content>

<content id="2" >

Versão 6.0

Outubro 2012 6

<moderatorName>moderador1</moderatorName>

<moderationDate>1272973151662</moderationDate>

<moderationDecision>APPROVED</moderationDecision>

<tagging/>

</content>

</contents>

</export>

Na seção, 5.2 detalhamoscada elemento do XML.

Versão 6.0

Outubro 2012 7

Método de integração sincrônica

Neste cenário, o cliente enviará a Keepcon os conteúdos a serem moderados um a um, obtendo o resultado de moderação de maneira sincrônica para cada envio.

Para isto, Keepcon fornece um serviço web REST por onde enviar a informação.

O endereço é o seguinte:

http://sync.keepcon.com:63081/synchronic/moderate/

Modo de uso do serviço:

1. Construir o XML com o conteúdo no formato que se detalha a continuação.

2. Adquirir o serviço com um PUT HTTP, enviando o XML no body do Request.

3. Ler a resposta do serviço, anexar no body do Response e verificar se a operação foi realizada satisfatoriamente. Ver formato de XML de resposta que se detalha à continuação.

4. Aplicar os resultados de moderação segundo suas próprias regras de negócio.

O conteúdo enviado a ser moderado deverá seguir o seguinte formato XML:

<?xml version="1.0" encoding="UTF-8" ?>

<import>

<contenttype>[account-name]</contenttype>

<contents>

<content id="1">

<author type="author">Pepe1989</author>

<url_context><![CDATA[http://blog.keepcon.com/?p=143]]></url_context>

<datetime>1262304000000</datetime>

<text><![CDATA[Olá amigos de toda a comunidade!!!]]></text>

</content>

</contents>

</root>

Nota: no caso de que o serviço receba mais de um conteúdo a ser moderado em um mesmo envio, será cancelada a moderação e haverá uma resposta com status de ERRO.

Versão 6.0

Outubro 2012 8

Como resposta, o serviço devolverá os resultados da moderação no seguinte formato XML:

<?xml version="1.0" encoding="UTF-8"?>

<response>

<status>OK</status>

<content id="1" >

<moderationDecision>REJECTED</moderationDecision>

<tagging>

<tag>nú</tag>

<tag>contato</tag>

</tagging>

</content>

</response>

Na seção 5.3 detalhamos cada elemento do XML.

Importante:

É obrigatório implementar um mecanismo de tentativas. Existe a possibilidade que por algum erro, imprevisto ou por tarefas de manutenção planificadas, e oportunamente comunicadas, o serviço de recebimento de conteúdos esteja fora do ar. Nesses casos, o processo de invocação deverá detectar o código de erro ou a falta de resposta, e deverão proceder outras tentativas, com certa frequencia, até poder injetar os conteúdos na plataforma de Keepcon.

4 Contato

Ante qualquer dúvida ou consulta, pode contatar-se com um profissional de Keepcon, que poderá auxiliá-lo no processo de integração, nos seguintes formatos:

• Correio eletrônico: support@keepcon.com

Versão 6.0

Outubro 2012 9

5 Apêndice

5.1 Tabela descritiva de XML de input

Na tabela abaixo, descrevemos cada um dos elementos deste XML.

Elemento / atributo

Tipo de dado Descrição Obrigatório

setId Elemento. Cadeia de caracteres.

Identificador de lote de importação, gerado pelo cliente.

Não.

contenttype Elemento. Cadeia. Este elemento tem a descrição da conta através da qual se identifica o tipo de conteúdo do cliente.

Este valor é imutável e será provido por Keepcon.

Sim.

contents Elemento. Este elemento contém múltiplos elementos filhos do tipo content, com os conteúdos a serem moderados.

Sim.

content Elemento. Conteúdo a ser moderado. Sim.

id Título. Inteiro extenso positivo.

Identificador único de conteúdo provido pelo cliente.

Sim.

author Elemento. Cadeia. Nome do autor do conteúdo. Este dado não é obrigatório se o cliente não está interessado em realizar seguimento por usuário. Sugere-se fornecê-lo, de todos os modos, dado que o processo de moderação é mais eficiente tendo este dado presente.

Não, mas sugerido.

Versão 6.0

Outubro 2012 10

url_context Atributo. Cadeia. URL onde se encontra o conteúdo. O propósito é poder visualizar o conteúdo em seu contexto para desambiguar no caso de dúvida.

Não, mas sugerido.

datetime Atributo. Formato UTC.

Data e hora de criação do conteúdo para poder empregar a ordem cronológico na priorização da fila de moderação, segundo seja o modelo: pré-moderação ou pós-moderação.

Não, massugerido.

type Atributo. Cadeia. Interno da plataforma. Tipo de dado do campo.

Sim.

text Elemento. Cadeia. Conteúdo a ser moderado.

Nota: sempre encerrar o conteúdo entre <![CDATA[]]>, para evitar que caracteres estranhos impeçam o correto uso do conteúdo.

Sim.

img Elemento. Cadeia. URL apontando a imagem que se deseja moderar.

Os formatos suportados são: GIF, JPG, PNG y BMP.

Não.

video Elemento. Cadeia. URL apontando ao vídeo que se deseja moderar.

Nota: Keepcon suporta praticamente qualquer formato padrão de vídeo, mas internamente para processá-lo o converte a FLV assim, se o envio é feito, originalmente, como FLV, melhora-se, de forma notória, a eficiência do processo de moderação, impactando positivamente nos tempos de resposta.

Não.

Versão 6.0

Outubro 2012 11

5.2 Tabela descritiva de XML de output

Na tabela abaixo, descrevemos cada um dos elementos deste XML.

Elemento / atributo

Tipo de dado Descrição

setId Atributo. Inteiro Longo positivo.

Para poder realizar um seguimento apropriado do envio dos resultados de moderação, Keepcon gera um identificador único para cada conjunto de resultados enviados.

contents Elemento. Este elemento contém múltiplos elementos filhos de tipo content.

content Elemento. Um conteúdo particular.

id Atributo. Inteiro longo positivo.

Identificador único de conteúdo gerado pelo cliente.

Moderação Decisão Atributo. Cadeia. Mostra a decisão de moderação do conteúdo. Os possíveis valores são:

• REJECTED

• APPROVED

• UNKNOWN

tagging Elemento Lista de motivos de recusa, resultante do processo de moderação do conteúdo. Em caso de que o conteúdo tenha um status de aprovado, a lista de motivos de recusas estará vazia.

Versão 6.0

Outubro 2012 12

tag Atributo. Cadeia. Categorização do conteúdo resultante do processo de moderação. Os valores serão definidos por cada cliente, segundo suas regras de moderação.

5.3 Tabela descritiva de XML de output de moderação sincrônica

Na tabela abaixo, descrevemos cada um dos elementos deste XML.

Elemento / atributo

Tipo de dato Descrição

status Atributo. Cadeia. Indica se a solicitação pode ser atendida ou não. Os possíveis valores são:

• OK

• ERROR

content Elemento. Um conteúdo particular.

id Atributo. Inteiro longo positivo.

Identificador único de conteúdo gerado pelo cliente.

Moderação Decisão Atributo. Cadeia. Mostra a decisão de moderação do conteúdo. Os possíveis valores são:

• REJECTED

• APPROVED

• UNKNOWN

tagging Elemento Lista de motivos de recusa, resultante do processo de moderação do conteúdo. No caso doconteúdo ter um status de aprovado, a lista de motivos de recusas estará vazia.

Versão 6.0

Outubro 2012 13

tag Atributo. Cadeia. Categorização do conteúdo, resultante do processo de moderação. Os valores serão definidos por cada cliente segundo suas regras de moderação.