At Buyapowa it’s essential that we make the integration of our tools easy, so that anyone can get the benefits of referral marketing.

In this article I will cover the steps required to start tracking referral conversion, how to test it, and how to debug when things go wrong. I will also describe the most common challenges encountered by our clients and how to tackle them.

What is the Buyapowa tracking script?

To track referral conversions, our clients apply our tracking script on the page where the conversion occurs. A typical e-commerce client would apply this tracking script on the page presented to the customer once their purchase is completed, as this is a good place to acquire new customers and drive more sales.

The exact stage where our clients apply this script will depend on what they are trying to achieve with their refer-a-friend programme, and depending on the type of business they run. The tracking event can be triggered whenever a customer performs a specific action, such as:

  • placing an order
  • subscribing to a service
  • creating an account
  • activating a SIM card
  • requesting quotes
  • and so on…

Integrating Buyapowa in two easy steps…

Tracking a referral on the order confirmation page of your site with the Buyapowa library is simple and can be done in 2 easy steps:

Step 1: Add the Buyapowa client library to the order confirmation page of your site:

<script src="//"></script>

We recommend that you add this <script> tag in the <head> section of your HTML markup to make sure it is available and ready to use before the page tries to render. Once loaded, our library gives you access to the Buyapowa tracking function.

Step 2: Call the tracking function. Here is an example of how the tracking function can be called to track a customer order:

{% raw %}
<script type="text/javascript">
  var buyapowa = new Buyapowa("https://{{market_domain}}");
    "customer_name": "{{first_name}}, {{last_name}}",
    "customer_email": "{{email_address}}",
    "order_value": "{{order_value}}",
    "voucher_code": "{{voucher_code}}",
    "order_number": "{{unique_identifier}}",
    "marketing_opt_in": "{{true_or_false}}"
{% endraw %}

Be mindful that you should replace {% raw %}{{market_domain}}{% endraw %} by the value you were provided with, the values of each properties by your own variables in the correct format we’ve specified and to remove the double curly braces surrounding the placeholder values from our template script above. We wouldn’t want to fill our systems with customers name {% raw %}{{first_name}}{% endraw %}.

How does this work?

Calling the tracking function notifies the Buyapowa platform of the conversion. To identify whether a conversion originated from the refer-a-friend programme, we rely on two pieces of information:

1. Cookies
and / or
2. Voucher codes redeemed

If the purchase is driven by the refer-a-friend programme then we will then ensure that it is a genuine referral. We’ve built a set of rules to reward only authentic referrals and discard fraudulent referrals to ensure our clients make the most of the refer-a-friend programme.

What happens next?

If the purchase was a genuine referral we can instantly reward your existing customer for having referred a friend. After having made their first purchase, the new customer can receive an invitation to start referring a friend, etc… and the process has come full circle.

How to test this integration

We recommend using developer tools to test it, and here’s how I would test: Note: If you are not familiar with developer tools, I’d recommend starting of with Google Chrome DevTools as it is very well documented.

Test this integration:

1. Open the Developer Tools.

2. Go to the Network tab and replicate the user journey until you land on the page where you’ve applied the Buyapowa tracking tag.

3. A number of requests should now be listed under the Network tab, look for a request to and its status code.

Tip: if you struggle to find it due to a significant number of requests being listed then I would recommend the “Filter” input at the top of the network tab and filter for “track”, this should filter the requests and make it easier for you to spot the requests..

4. If you see the status code 200 or 201 and if the values present under the query string parameters section match your test conversion data then the conversion was successfully tracked. Anything else points to a problem.

What could have possibly gone wrong?

Unfortunately, sometimes things go wrong.

As much as we work at making the integration simpler every day, our clients can sometimes face some issues with the integration and here is how I would tackle this:

I can’t see the tracking request in the Network tab

The best place to start is to go to the Console tab of the Developer Tools and look for errors. The most common error you could come across is “Buyapowa is not defined”. If you get this error, it means that the Buyapowa Library wasn’t loaded before you’ve called the tracking function. If there is no relevant error message then you might not even be calling the tracking function at all.

You can check if the Buyapowa object has been defined after you’ve called the function or if indeed it’s never been defined. If you type “Buyapowa” in the console and you get the same error message “Buyapowa is not defined” then you are never loading the Buyapowa Library but if Buyapowa is now defined, then it means that the Buyapowa Library is loaded but not ready to use when you call the tracking function.

The tracking request is here but the status code is wrong

It’s a pretty good start if you can see the request but it is as important to check if you’ve received a successful response. If you see a 404 status code then it’s likely that you’ve entered the wrong {{market_domain}} variable in the script. To make sure, please double check this with the value initially given to you and don’t forget to remove the curly braces.

The query string parameters’ values don’t match my test data

Click on the request and having a look at the query string parameters section which will show you what values are being passed in the request. Make sure you’ve replaced the values of each properties by your own variables and that these values are in the format expected.

If you see that one of the values is empty when it shouldn’t be, or doesn’t reflect the details of the order you’ve placed, you might want to have a look at the variables you’ve added in the tracking function.

As a good rule of thumb, if you do anything differently than our recommendations, then keep in mind that HTML loads from top to bottom and renders the content in that order.

This means that you need to make sure the variables and the functions you will call in your page have been defined beforehand by ensuring that the Buyapowa client library is ready to be used by the time your page loads the script which triggers the tracking function. The same applies to your own variables that you pass in the script they would need to be defined before calling the tracking function.

Common challenges

Depending on the size of the company and/or business decisions, our clients sometimes have some restrictions that prevent them integrating the recommended way.

Here are the most common challenges they encounter:

I can’t edit the head section of this page on my site.

We recommend that you add the first script which loads the Buyapowa client library in the <head>.
If for any reason this is not possible, then it’s ok for you to add both scripts in the <body> of the page as long as you make sure that the Buyapowa client library is loaded before you start using the tracking function in your HTML markup, it’s only a matter of making sure the script loading the Buyapowa Library appears before the script calling the function, as long as you don’t use the async parameter to load the Buyapowa Library.

I’m using a tag manager.

If you are using a tag manager, I would pay particular attention to the way they are loading the Buyapowa client library as it’s likely that if the tag manager uses an external file to load the Buyapowa client library, this file will be loaded asynchronously on the page and this will impact the tracking.
Sometimes it will look like the script tag is in <head> section, but it didn’t load before calling the function. I would look at how this script tag was added to the DOM, and if it’s been added dynamically from another script, it’s likely that the script was added to the HTML markup after you’ve called the tracking function.

I’m loading the javascript asynchronously

This is not what we recommend, but if you have to load the Library asynchronously then you could make sure that you call the tracking function only once the previous script is loaded, e.g.

{% raw %}
<script id="bp_lib" src="//" async></script>
<script type="text/javascript">
  document.getElementById("bp_lib").addEventListener("load", function(event) {
  var buyapowa = new Buyapowa("https://{{market_domain}}/");
    "customer_name": "{{first_name}}, {{last_name}}",
    "customer_email": "{{email_address}}",
    "order_value": "{{order_value}}",
    "voucher_code": "{{voucher_code}}",
    "order_number": "{{unique_identifier}}",
    "marketing_opt_in": "{{true_or_false}}"
{% endraw %}

Where should I place the Javascript which calls the tracking function in my HTML markup to avoid any impact on the user experience?

It is up to you.
We’d recommend you add the script tag which calls the tracking function just before the </body> end tag as to avoid slowing down the rendering of the content of your page. Although the tracking script should not have a major impact on delaying the rendering, it is known as best practice to put script tags unrelated to the content of your website as the last elements of your HTML.

And now you’ve got a working integration

Hopefully this has helped you overcome any challenges you faced while integrating Buyapowa and you’ve learn some tips that you can apply while debugging other projects.

We are always here to assist you debugging if you face further challenges while integrating Buyapowa.