User data API

User data API

If you have chosen the DELIGHT plan and you have the full control over the website you are advertising, you have an opportunity to customize the experience of your website for every visitor. For example, you can greet the visitor by his name, customize website design for particular ages, countries or genders, or mention his earning for viewing your website as an advertising trick - possibilities are endless! All data, that you have selected to receive is being passed as a URL string (GET method) to your website when a visitor opens it.

You can select any or all of the following data:

  • Username: This is the username of the member which he uses to log in. Variable name is “username”.
  • Account type: There are 3 possible account types – Default, Premium and Ultimate. Variable name is “type”.
  • HeedYou signup date: A date, when the member has signed up on HeedYou. Will be passed in “YYYY-MM-DD” format, for example, “2012-09-21”. Variable name is “signup”.
  • Gender: Gender of a visitor. It has only 2 possible values – male or female. Variable name is “gender”.
  • Age: Age of the visitor. Will be passed as an integer, for example, “25”. Variable name is “age”.
  • First name: Name of the visitor. Variable name is “name”.
  • Country: Visitor’s country of residence. Will be passed as a full country name, for example, “Latvia”. Variable name is “country”.
  • Member earnings on this ad: This parameter will contain an amount of reward member gets for viewing your advertisement nominated in USD. For example, “0.01”. Variable name is “earned”.

Simply click on those to select API data values that you would like to receive.

When a visitor clicks on your advertisement, he will be warned about the data being passed to a third party. He will be presented with the full list of information that is being sent to your website and given an opportunity to close the advertisement and not give away his data. That’s why you should only ask data that you need, if you ask too much you might scare away many potential customers.

The most important part is implementing it on your end. There can be no one-solution-fits-all scripts for this; you should be aware of all of the other code and content of your website. However, we will provide you with a few examples and give you a few advices on how to make the best use of this feature.

The API is not compatible with links which already have some GET parameters included. Your link must end with either “/” or a file extension – “.html”, ”.php”, etc. There are many different ways you can make the API work; we will simply provide some basic examples, which can give you an idea on what you should do.

PHP

If your website is based on PHP, this is the best solution for you. Let’s assume that you have selected visitor name.

First, you need to make sure, that parameters are there. You don’t want your website to show error messages or display broken content when you have some visitor that did not come from us or someone has simply opened your website in a new window.

if (isset($_GET['name']))
	{
		…
	}

Then, you need to create a customizable message for every visitor. Add the “$_GET['name']” variable in any sentence you want, it is going to be replaced with the visitor’s first name. Let’s create “$greeting” variable and define it as follows:

if (isset($_GET['name']))
	{
		$greeting='Hello '.$_GET['name'].'!';
	}

Notice that the message is located inside the quotes and the name variable is inserted with „’.” in the beginning and „.’” in the end. Next, we need to create an alternative, in case there is no variable passed through API.

if (isset($_GET['name']))
	{
		$greeting='Hello '.$_GET['name'].'!';
	}
	else
	{
		$greeting='Welcome to my website!';
	}

Now, we need to replace a line of text in HTML part of the code with a PHP “echo” snippet with “$greeting” variable.

Done! Now any visitor, which comes from us to visit your PHP page, will be greeted by the name. If the parameter is missing or a visitor has come from somewhere else, simple “Welcome to my website!” message will appear instead.

You can find the full code of this example by looking inside “examplephp.php” file from the library of examples you can download here. It includes 2 more variables – country and gender; it also contains examples of the more advanced use of the data. Here’s the simple demo of this example. Change the variables in the link to see how it will react to different names, countries and genders. You can also remove GET part of the link (after .php) to see how the example reacts to missing parameters.

JavaScript

If your website is based on plain HTML, you can use the JavaScript to make our API work. We have created a JavaScript function, which can parse our API and get the variables you need from the GET parameters. Simply insert it in the head section of your HTML code.

<script type="text/javascript">
function HeedYou_API_JS_Parse(val) {
    var result = false,
        tmp = [];
    var items = location.search.substr(1).split("&");
    for (var index = 0; index < items.length; index++) {
        tmp = items[index].split("=");
        if (tmp[0] === val) result = decodeURIComponent(tmp[1]);
    }
    return result;
}
</script>

Next, you need to insert code snippets that will alter the initial content of the page. Insert a snippet right after a content that it needs to change to achieve the best performance. You also need to assign the unique IDs to all HTML elements that are going to be manipulated. Here’s how this snippet should be constructed:

By default, the HTML element should contain the default, not customizable message, but should be assigned an unique ID so that it can be manipulated with.

<h3 id="greeting">Welcome to my website!</h3>

First, you need to make sure, that parameters are there. You don’t want your website to show error messages or display broken content when you have some visitor that did not come from us or someone has simply opened your website in a new window.

<h3 id="greeting">Welcome to my website!</h3>
<script type="text/javascript">
	var issetname = HeedYou_API_JS_Parse('name');
	if(issetname!==false)
	{
		…	
	}
</script>

Now we need to change the inner content of the element to our new message.

<h3 id="greeting">Welcome to my website!</h3>
<script type="text/javascript">
	var issetname = HeedYou_API_JS_Parse('name');
	if(issetname!==false)
	{
		document.getElementById('greeting').innerHTML='Hello '+issetname+'!';
	}
</script>

Done! Now any visitor, which comes from us to visit your website, will be greeted by the name. If the parameter is missing or a visitor has come from somewhere else, “Welcome to my website!” message will stay.

You can find the full code of this example by looking inside “examplephp.php” file from the library of examples you can download here. It includes 2 more variables – country and gender; it also contains examples of the more advanced use of the data. Here’s the simple demo of this example. Change the variables in the link to see how it will react to different names, countries and genders. You can also remove GET part of the link (after .php) to see how the example reacts to missing parameters.