Summary

The purpose of this document is to help our publishers get started sending people into Research For Good's survey offers, and be able to track in real time their conversions.

Complete Tracking

Complete Tracking

We provide three different ways for you to track your completes (conversions) in real time.

1. Page Redirect with HMAC_MD5 security

This method allows you to specify a web page URL that the respondent will be redirected to, following the completion a survey. Optionally, you may also specify URLs for non-complete attempts.

All of the parameters you included in the offer URL will be sent back to you in the complete URL.

For example, suppose you provide us a complete URL of http://my.server.com/mypage.jsp

If you redirected your respondent to

http://survey.saysoforgood.com/trop/survey/50bb8073a0c6101ab41aabcd/B?custom_id=123456

Then following a complete, we will redirect the respondent to

http://my.server.com/mypage.jsp?custom_id=123456&security=28e08e74bd1725796137cd837b0c87c2

We will append an HMAC-MD5 hash of the complete query string, secured via a pre-shared key. This prevents a respondent from attempting to forge the complete URL and obtain a reward without completing a survey.

For example, if our pre-shared key is "123498ejoasdfas234890asdlkq23490ika", then the following javascript may be used to compute the security hash:

<script src="http://crypto-js.googlecode.com/svn/tags/3.1.2/build/rollups/hmac-md5.js"></script>
<script>
var hash = CryptoJS.HmacMD5("custom_id=123456", "123498ejoasdfas234890asdlkq23490ika");
</script>

Details of the javascript library used above may be found at https://code.google.com/p/crypto-js/ , however the HMAC-MD5 is a standard algorithm available in any language and usually from multiple sources.

You must verify the hash before rewarding your respondent. Without this security, it is extremely easy for a respondent to attempt to forge the complete URL.

If you choose this method, we must pre-arrange the pre-shared key and security parameter name

2. Client Side callback ("Pixel Fire") with HMAC_MD5 security

This method allows you to specify a web callback URL that will be asynchronously called from the respondent's web browser following the completion of a survey. You may track this either via HTTP parameters, or via a cookie previously left on the user's computer. In either case, you must verify the HMAC_MD5 hash before rewarding your respondent. Without this security, it is extremely easy for a respondent to attempt to forge the complete URL.

All of the parameters you included in the offer URL will be sent back to you in the complete URL.

For example, suppose you provide us a complete URL of http://my.server.com/mypixel.jsp

If you redirected your respondent to

http://survey.saysoforgood.com/trop/survey/50bb8073a0c6101ab41aabcd/B?custom_id=123456

Then following a complete, we will fire the callback using the following URL:

http://my.server.com/mypixel.jsp?custom_id=123456&security=28e08e74bd1725796137cd837b0c87c2

We will append an HMAC-MD5 hash of the complete query string, secured via a pre-shared key. This prevents a respondent from attempting to forge the complete URL and obtain a reward without completing a survey.

For example, if our pre-shared key is "123498ejoasdfas234890asdlkq23490ika", then the following javascript may be used to compute the security hash:

<script src="http://crypto-js.googlecode.com/svn/tags/3.1.2/build/rollups/hmac-md5.js"></script>
<script>
var hash = CryptoJS.HmacMD5("custom_id=123456", "123498ejoasdfas234890asdlkq23490ika");
</script>

Details of the javascript library used above may found at https://code.google.com/p/crypto-js/ , however the HMAC-MD5 is a standard algorithm available in any language and usually from multiple sources.

3. Server Side callback with IP address filter

As an alternative to the HMAC-MD5 security of the first two methods, we can invoke your callback URL directly from our servers. The callback URL must contain an identifier to allow you to know which respondent has completed the offer (as it will not contain any cookie information).

You must check the IP address that the callback comes from, and only reward your respondent if the IP address is on the list of our servers. Without this security, it is extremely easy for a respondent to attempt to forge the complete URL.

You should verify the following static IP addresses and only accept conversions that are sent from those:

15.222.163.99
3.97.223.177
3.97.28.227
3.230.105.121
52.21.20.32
52.45.41.61

Callback Parameters

You can add any of the following placeholders to your callbacks to get more detailed information back from us: