1. Implementation Guide Version 6.0 December 2013 1

2. Index Index................................................................................................................2 1 About this document.........................................................................................3 2 About the moderation process............................................................................3 3 Integration Mechanisms ...................................................................................4 4 Contents expiration.........................................................................................20 5 Remoderation and Moderation Mistakes.............................................................20 6 Following steps...............................................................................................20 7 Tips & Troubleshooting....................................................................................21 8 Contact.........................................................................................................22 9 Appendix.......................................................................................................23

3. 1 About this document This document provides the necessary information to use the moderation services provided by Keepcon. It is orientated to those people with technical skills in charge of the development and/or administration of a website. This document is grouped in sections, covering the moderation process and specific technical documentation on how to achieve a successful integration with your site. 2 About the moderation process Keepcon offers different types of moderation services, which are out of scope in this present document, but beyond which particular service has been hired, all of them include at least two operations: submitting contents to moderate and receiving an answer for the moderated contents. It is up to the clients to incorporate to their internal process the submittal of information to moderate, the retrieval of its results and the consequent actions on the basis of those results according to their own business rules. Version 6.0 April 2013 3

4. 3 Integration Mechanisms 3.1 Integration via REST 3.1.1 Asynchronic integration method Asynchronic integration consists of performing operations of submitting content to moderate and the inquiry of moderated contents in different moments, without strict correlativity between them. In such a way, the client will have to implement two independent processes, one for each mentioned operation. Below, each operation is being described in detail, examples and steps to follow are provided to achieve a successful integration. 3.1.1.1 Submitting / retrieving contents to moderate Those contents to moderate should be submitted to Keepcon periodically and in sets (with its size to be defined according to volume and concrete needs) by the client. For example, if the average volume of content to moderate is around 1000 per hour, it would be necessary to submit sets of 50 elements every 3 minutes. Keepcon provides a REST service to which the client will submit the content set in XML format. The service URL is the following: http://service.keepcon.com/input/contentSet How to use the service: 1. Create the XML with the content in the format as detailed in section 3.1.1.1.1. 2. Invoke the service with a PUT HTTP by submitting the XML in the Request body. Basic-Authentication authentication method must be used with the user and password provided by Keepcon. 3. Read the service answer within the Response body, and verify if the submittal was carried out satisfactorily. Otherwise, retry submitting it. See section 3.1.1.1.2. Version 6.0 April 2013 4

5. 3.1.1.1.1 XML submitting format The submitted set of contents to moderate must follow the following XML format: [account-name]Jeff1989http://blog.keepcon.com/? p=1431262304000000Hello my friends!!!Gandalfhttp://blog.keepcon.com/? p=1421262304000000Hello everyonehttp://mysite.com/unafoto.jpg http://mysite.com/unvideo.flv Each XML element is detailed in section 9.1. Version 6.0 April 2013 5

6. 3.1.1.1.2 Reception confirmation As a response to the submittal, Keepcon will send an answer confirming that the contents set was successfully received, together with the set identifier generated for that submittal. The response format will be the following. Positive reception response format. 35OK Negative reception response format. ERRORSome parsing error message Keepcon generates a setId value for every set of content received successfully. . The client could use this number to do any type of tracking in its system. Important: It is very important to implement a retry mechanism. There is a possibility that due to an unexpected error or planned maintenance , the content reception service could fail. In those cases, the invoke process will have to detect the error code or lack of response, and should have to proceed to retry with some frequency until it is able to inject the contents into Keepcon platform. Version 6.0 April 2013 6

7. 3.1.1.2 Retrieving moderation results Once the contents are processed, results will be available for the client. The client will periodically check the REST service to obtain the results for the moderated contents. The URL is the following: http://service.keepcon.com/output/contentSet?contextName=[accountname]&clientACK=true where [account-name] is the name of your companys account. How to use the service: 1. Invoke the service with a PUT HTTP, submitting the account name opportunely provided by Keepcon as a parameter. Basic-Authentication method must be used with the user and password provided by Keepcon. 2. Read the service answer included in the Response body. The answer format is detailed in the following section. In case the answer is empty, it means there are no moderation results available to be checked. 3. Impact the moderation results according to your own business rules. 4. Send ACK to Keepcon: This ACK is used by Keepcon to finalize the Moderation cycle of each content. If client dont send the ACK in the next 5 minutes, Keepcon will resend the same result set in the upcoming request. To send ACK you must call this REST service: http://service.keepcon.com/ack/[setId] where [setId] is the code of the result set which is inside the XML (see below) 3.1.1.2.1 Moderation result XML format Moderation results that are submitted to the client will have the following XML format: moderator11272973151662REJECTED Version 6.0 April 2013 7

8. Inapropiatedmoderator11272973151662APPROVED Each XML element is detailed in section 7.2. Version 6.0 April 2013 8

9. 3.1.2 Synchronic integration method In this scenario, the client will submit to Keepcon contents to moderate one by one, obtaining the moderation result synchronically for each submittal. For this purpose, Keepcon provides a REST service to submit the information. The URL is the following: http://sync.keepcon.com/synchronic/moderate/ How to use the service: 1. Create the XML with one content in the format detailed below. 2. Invoke the service with a PUT HTTP by including the XML in the Request body. Basic-Authentication method must be used with the user and password provided by Keepcon. 3. Read the service answer attached to the Response body, and verify if the operation was carried out successfully. See the XML response format detailed below. 4. Impact the moderation results according to your own business rules. Content to moderate should have the following XML format. [account-name]Jhon1989http://blog.keepcon.com/? p=1431262304000000Hello World!!! Note: in case the service receives more than one content to moderate in the same submittal, moderation will be cancelled and it will answer with ERROR status. Version 6.0 April 2013 9

10. As a response, the service will answer the moderation results in the following XML format: OKREJECTEDnaked_bodiescontact_information Each XML element is detailed in section 7.3. Important: It is very important to implement a retry mechanism. There is a possibility that due to an unexpected error or planned maintenance, the content reception service could fail. In those cases, the invoke process will have to detect the error code or lack of response, and should have to proceed to retry with some frequency until it is able to inject the contents into Keepcon platform. 3.2 Integration via API It is possible to submit content to Keepcons server by using APIs available for PHP and Java languages, instead of using REST services. APIs are the integration method recommended by Keepcon because they are easier to use and they tend to minimize errors. Through APIs it is possible to use both synchronic and asynchronic moderation mechanisms. Each API has an initialization file that is necessary to set up before starting the process. Version 6.0 April 2013 10

11. Before starting to use the API in the productive environment, it is important to coordinate with Keepcons technical staff those fields that will be included in the moderation process. 3.2.1 PHP API 3.2.1.1 API set-up To set-up PHP API, files included in keepcon-api-php.zip must be copied in a file accessible for the PHP code of your system. ZIP directory structure must be respected. If necessary, configuration variables of the file keepcon-client-api.ini could be modified (see 3.2.1.6) 3.2.1.2 API initialization The first step for the use of API is the initialization. This step has to be carried out for both asynchronic and synchronic calls. Initialization always has the following syntax: Version 6.0 April 2013 12

13. 3.2.1.4 Example of asynchronic reception This example shows how to retrieve moderation results. When retrieving these results, the API will bring sets of 50 results at the most. If there are fewer results available, then the API will bring a smaller set. In case there are no results left, the API will bring zero results. Once the API is initialized, the results method should be invoked and you should iterate for the moderationResults collection to obtain the result of each performed moderation. From each ModerationResult the element ID and the moderation result can be obtained to take action in your company system. Besides, additional information can be obtained as well, like the moderators name, moderation data and elements Tags. Elements Tags are used to relate the moderation policies of your company, for example: bad words, nudity, contact information, etc. Finally, you must send and ACK to Keepcon. This ACK is used by Keepcon to finalize the Moderation cycle of each content. If client dont send the ACK in the next 5 minutes, Keepcon will resend the same result set in the upcoming request. 3.2.1.5 Example of synchronic moderation This example shows how to invoke the synchronic moderation service. After initializing the API, one content with its correspondent fields has to be created and submit it invoking the send_sync method. This method submits the content and brings the moderation result back. The moderation result is inside a ModerationResult object, from which the ID element and the moderation decision can be obtained to take action in the your sytem. Besides, additional information can be obtained as well, like the moderators name, moderation data and elements TAGs. 3.2.1.6 Configuration file keepcon-client-api.ini configuration file is configured with default values that in most cases are not necessary to modify. In chapter 5.4 all the variables that compose this file are detailed. 3.2.2 API Java The first step to start using API Java is to ask Keepcons technical staff for the JAR file that has the API java classes, use examples and documentation in Javadoc format. 3.2.2.1 API use and examples examples-api-java.zip file has available examples to perform synchronic and asynchronic moderations. These examples were developed taking into account real implementations from many of our clients. Therefore, this code can be used as template to start integration from scratch. It is only necessary to implement those actions in each moderation result: what to do in case of approving or rejecting an element in your system. 3.2.2.2 Configuration file keepcon-client-api.ini configuration file is configured with default values that in most cases are not necessary to modify. In chapter 5.4 all the variables that compose this configuration file are detailed. Version 6.0 April 2013 15

16. 3.3 Integration via Plugins 3.3.1 Wordpress Plugin For those clients using Wordpress, the easiest way of integrating with Keepcon s platform is through the installation and configuration of a plugin developed for that purpose. 3.3.1.1 Wordpress plugin setup To setup the plugin unzip keepcon-wordpress-plugin.zip into the folder wpcontent/plugins of your Wordpress installation. Once unzipped, the plugin folder will have another folder inside called keepcon. After that, enter Wordpress plugins administration console, and a plugin called Keepcon Moderation Plugin should appear listed. To activate it, press the Activate link. 3.3.1.2 Wordpress plugin configuration After activating the plugin, it has to be configured. For that, enter the configuration screen by clicking Keepcon Configuration link that appears in Settings section. Version 6.0 April 2013 16

17. When you click on Keepcon Configuration, the following plugin configuration screen will appear. Version 6.0 April 2013 17

18. In this configuration screen, the only values which are necessary to modify are Content Type and Password. To request these values, send an e-mail to Keepcons technical staff (support@keepcon.com). You can also configure the plugin to operate in synchronic or asynchronic moderation modes. Version 6.0 April 2013 18

19. . When using synchronic moderation, every user generated post will be immediately processed by Keepcon, while the asynchronic way will be executed every certain period of time. The HTTPS protocol can also be used for the information to travel through a safe channel. Finally, the use of a Proxy can be configured if needed. The remaining options must stay with the default values unless Keepcons technical staff requests some particular change. 3.3.1.3 Plugin test Before testing, get in touch with Keepcons technical staff to register the account with its correspondent moderation rules. Once the plugin is configured, the following steps can be tested: 1. Create an inappropriate message in the correspondent blog. 2. Verify that the message appears as published and that it also appears in Wordpress Comments screen. 3. After around 30 seconds, the comment should be eliminated from the blog and should appear in the Trash folder in Comments screen. That means the comment was automatically moderated and eliminated by Keepcon. 3.3.2 Facebook plugin Keepcons platform can import, moderate and eliminate comments and posts generated in Facebook Wall pages. To perform this integration, the only necessary thing is that the client grants Keepcon certain permissions inside Facebook account. The rest of the import process and messages deletion is performed automatically. It is not necessary to codify anything additional. To grant the requested permissions, ask Keepcons technical staff for the document Keepcon Instructions for Facebook permission grant. 3.3.3 Disqus plugin Keepcons platform can import, moderate and eliminate comments and posts generated using Disqus commenting tool. To perform this integration, the only necessary thing is that the client grants Keepcon its credentials for Disqus account. The rest of the import process and messages deletion is performed automatically. It is not necessary to codify anything additional. Version 6.0 April 2013 19

20. 3.3.4 YouTube plugin Keepcons platform can import, moderate and eliminate comments and posts generated for YouTube videos. To perform this integration, the only necessary thing is that the client grants Keepcon certain permissions inside YouTube account. The rest of the import process and messages deletion is performed automatically. It is not necessary to codify anything additional. 3.4 HTTPS protocol In order to achieve a better security for the contents transfer, Keepcon services can be used through HTTPS Protocol. All of the available integration methods (REST, PHP, Java, Wordpress and Facebook) can use this protocol. 4 Contents expiration For those clients using our Manual Moderation Platform it is important to mention that all contents that Keepcons platform receives have a default expiration of 15 days. That is to say, if content is submitted and, during 15 days, this content is not manually moderated, it will be marked as expired and will be discarded from our system. The only way of moderating it will be by resending it. In case a longer expiration is needed, it has to be requested to Keepcons technical staff. It is possible to require a default moderation result for expired content. For example we can approve all content that not moderated for 15 days. 5 Remoderation and Moderation Mistakes In some situations it is possible a single content to be moderated twice so your system may receive two different results for the same content in different moments. For example, you may receive a REJECTED result for content_id =133 and the next day you receive an APPROVED result for the same content_id. This situation is used to happen when a manual or automatic moderation mistake occurs and a revision action is done. So our recommendation is that your system should be prepared to handle this situation and it would be able to impact a new result for the same content_id. But this is only a suggestion and it is up to your business rules. 6 Following steps Version 6.0 April 2013 20

21. Once the integration between the clients system and Keepcons platform is finished, we recommend following these steps: Verify the correct export of results: Once the contents are visible in the platform, they have to be manually moderated by choosing different moderation criteria, for example, rejecting and approving contents by choosing different tags. After that, execute the code that gets the results and verify that the received values are the correct ones. Try the platforms Contents Administrator to know how to search for historical elements. 7 Verify the correct import of contents: Ask for a user and a password to enter the platform (http://platform.keepcon.com) and visually verify that the contents appear as pending for moderation. It is important to submit contents that are not automatically moderated during this first step. Try our Reports & BI Tool in http://tools.keepcon.com/sites/reports. This tool helps to visualize statistical graphics with useful information for people responsible of your site. This information is updated approximately every 3 hours. Tips & Troubleshooting Timeouts: All API Requests should return in less than 1 second, but we recommend setting both connection and socket timeout between 10 and 30 seconds. HTTP Header: If you are using REST integration, then you should add the following http header to all requests: User-Agent= Keepcon Client API REST v1.0 - Context Name: [contextName] where contextName is the name of the context you are using. Service Status: To check the service health, you should go to http://status.keepcon.com. Alarms: Some customers need to be aware of critical situations. So we can configure alarms to send emails when: we receive too low or too much traffic, we detect certain level of automatic or manual decisions, we detect certain level of rejected or approved content. If you need any of these alarms you should ask them to our technical team. Latency: In case you need a very low latency (less than 1 second) then you should contact our technical team in order to setup a particular configuration. For example, we can give you direct access to our Dallas, Washington DC or Amsterdam servers. XML Format: It is important to use CDATA sections inside XML fields. CDATA should not has other CDATA inside nor ]]> strings. Version 6.0 April 2013 21

22. 8 Contact If you have any request or inquiry, you can contact Keepcons staff, that will guide you during the integration process: E-mail: support@keepcon.com Version 6.0 April 2013 22

23. 9 Appendix 9.1 Input XML for Rest service descriptive table Each of the elements of this XML is described in the following table. Schema is also available for performing validation before submitting content to Keepcon. If needed, ask for the schema (XSD file) to Keepcons technical staff. Some elements of the XML can be customized to satisfy clients needs. Element / attribute Type of piece of information Description Required setId Attribute. String Import lot identifier, generated by the client. No. contenttype Element. String This element has the context name assigned to the client. Yes. This value is immutable and will be provided by Keepcon. contents Element. This element has multiple content type child elements, with the contents to be moderated. Yes. content Element. Content to moderate. Yes. id Attribute. Entire long positive. Only content identifier provided by the client. Yes. author Element. Chain. Name of the contents author. This piece of information is not obligatory if the client is not interested in performing a followup per user. It is suggested to provide it anyway since the moderation process is more efficient taking this type of information into account. No, but suggested. Version 6.0 April 2013 23

24. Element / attribute Type of piece of information Description Required url_context Element. String. URL where the content is. The purpose of this is to visualize the content in its context to disambiguate it in case of doubt. No, but suggested. datetime Element. Format UTC in milliseconds. Content creation date and time in order to use the chronological order in the moderation queue prioritization whether it is a premoderation or a post-moderation model. No, but suggested. type Attribute. String. Internal for the platform. Type of field information. Yes. text Element. String. Content to moderate. Yes. Note: always write the content between , to avoid strange characters preventing from the correct use of the content. img Element. String. URL aiming to the image to moderate. No. Formats: GIF, JPG, PNG and BMP. video Element. String. URL aiming to the video to moderate. No. Note: Keepcon can practically manage any type of standard video format, but to convert it to FLV, it internally processes it, so if it is originally submitted as FLV, the moderation process efficiency notably improves, positively impacting on the response times. Version 6.0 April 2013 24

25. 9.2 Output XML descriptive table Each of the elements of this XML is described in the following table. Element / attribute Type of piece of information Description setId Attribute. Entire long positive. In order to carry out a proper follow-up of the moderation results submittal, Keepcon will generate a unique identifier for each group of submitted results. contents Element. This element has multiple content type child elements. content Element. A specific content. id Attribute. Entire long positive. Unique identifier of the UGC. moderationDecision Attribute. String. Shows the content moderation decision. Possible values are: REJECTED APPROVED UNKNOWN tagging Element. List of rejection reasons resulting from the content moderation process. In case the content has an approved status, the list of rejection reasons will be empty. tag Element. String. Content categorization resulting from the moderation process. Values will be defined for each client according to their moderation rules. Version 6.0 April 2013 25

26. 9.3 Synchronic moderation output XML descriptive table Each of the elements of this XML is described in the following table. Element / attribute Type of piece of information Description status Element. String. It indicates if the request was processed or not. Possible values are: OK ERROR content Element. A particular content. id Attribute. Entire long positive. Unique identifier of the client generated content. moderationDecision Element. String. Shows the content moderation decision. Possible values are: REJECTED APPROVED UNKNOWN tagging Element. List of reject reasons as a consequence of the content moderation process. In case the content has an approved status, the list of reject reasons will be empty. tag Element. String. Content categorization as a consequence of the moderation process. Values will be defined according to each clients moderation rules. 9.4 Descriptive table of the configuration file The API configuration file has the following variables. Most of the variables do not need to modify the default values. But it is important to understand the functioning of each of them. Version 6.0 April 2013 26

27. Section Name Default Description keepcon_settings keepcon_async_url http://service.keepcon.com/inp ut/contentSet URL of the Keepcon service to submit contents to moderate in an asynchronic way using protocol HTTP. This value should not be modified unless requested by Keepcon technicians. To use HTTPS the url with https:// must be used. keepcon_settings keepcon_async_results_ url http://service.keepcon.com/out put/contentSet?contextName= URL of the Keepcon service to obtain the results from asynchronic moderations by using protocol HTTP. This value should not be modified unless requested by Keepcon technicians. To use HTTPS the url with https:// must be used. keepcon_settings keepcon_async_ack_url http://service.keepcon.com /ack/ URL of the keepcon service to submit ACK. Do not change this value. keepcon_settings keepcon_sync_url http://sync.keepcon.com/synch ronic/moderate/ URL of the Keepcon service to moderate contents in a synchronic way. This value should not be modified unless requested by Keepcon technicians. keepcon_settings author_element_name author For Keepcons internal use. connection_settings client_timeout 60 Timeout in seconds to carry out the information transfers. Possibly, it will be necessary to adjust this value depending on the lengths of the texts to moderate and the conditions of the clients network. connection_settings send_retries 3 Number of retries when facing a connection problem or packages lost. This value should not be modified unless requested by Keepcon technicians. connection_settings http_adapter 'HTTP_Request2_Adapter_Sock et' Implementation of the adapter used by the client to connect to Keepcons server. Values it may take are: 'HTTP_Request2_Adapter_Socket' o 'HTTP_Request2_Adapter_Curl'. Just for PHP. connection_settings proxy_host If it is necessary to use a proxy, these values should be filled. connection_settings proxy_port If it is necessary to use a proxy, these values should be filled. connection_settings proxy_user If it is necessary to use a proxy, Version 6.0 April 2013 27

28. these values should be filled. connection_settings proxy_password If it is necessary to use a proxy, these values should be filled. connection_settings proxy_auth_scheme If it is necessary to use a proxy, these values should be filled: "basic" o "digest". logging log_file /tmp/keepcon.log Directory where the API will generate the log file. The file will only be generated if the log is activated. Just for PHP. logging debug False Indicates the API to generate Debug information in a log file. It is useful just in special circumstances where errors want to be detected. logging trace False Indicates the API to generate Debug information in a more detailed way. It is useful just in special circumstances where errors want to be detected. development development False If it is switched to True, requests are not send to Keepcons server but a false response is generated. internal_options ssl_verify_peer False It indicates if Keepcons SSL certificate is verified. Only modify this value if requested by Keepcon s support staff. Just for PHP. internal_options ssl_verify_host False It indicates if the identity of Keepcons SSL certifcate host is verified. Only modify this value if requested by Keepcons support staff. Just for PHP. internal_options follow_redirects False It indicates the http connector if it should follow the redirects sent by the server. If http_adapter is used = 'HTTP_Request2_Adapter_Curl' set this variable in True. Version 6.0 April 2013 28