Join The Slack Community for Native Advertising Experts>> Join the Community

How to use Joinative's Upload Conversions feature and boost your confidence in the data

Conversions can often be a point of contention when it comes to working with native advertising platforms. Joinative includes a feature to avoid the hassle.

It’s a well-known pitfall for many native advertisers that the conversion data coming back from the likes of Taboola and Outbrain doesn’t quite match up with what internal tools are showing, whether it be Google Analytics, a custom BI solution, or something else entirely. The issue then becomes: ‘which of these can I trust’?

Naturally, it’s easier to trust the data that our own company produces, but here at Joinative we like to take another approach. We would rather consider all the data at our disposal and use it to make decisions about our native advertising campaigns. With that in mind, we produced the Upload Conversions feature.

Here is our step by step guide to using the all new Upload Conversions and some common traps to avoid.

What do I need?

In order to make the most of the Conversion Uploader, it’s advised that you have a procedure for regularly and consistently getting conversion data from your analytics/BI team. If this data comes in CSV format, even better, because this is the exact format of file you will need to upload to Joinative. There are some required fields that must be present in the file you upload to us, without which the file will not be read properly, and the upload will fail. These are:

  • date (in YYYY-MM-DD format) - which date do these conversions correspond to
  • platform - the platform that a campaign or ad belongs to (note: this is necessary in order to match the correct ads and campaigns in Joinative)
  • campaign_id - the ID of the campaign for which the conversion happened (this must be the ID as the platform records it)
  • ad_id - as above, the ID of the ad for which the conversion happened

Additionally to these, a site_id field can also be provided, if your conversion data is also broken down at site level. These 4 or 5 fields are used to aggregate the data you provide and update the correspond report data inside of Joinative. Don’t worry about how that works, we handle it all on our end.

The remaining fields of the CSV file are up to you. They must either correspond with the conversions as reported by the platform (in which case the platform must be given in the platform field), or with the custom conversions that you have previously defined in our Conversions Center.

Below is a small example of how to structure the CSV file. We’re assuming that you have defined Conversions and Leads in the Conversions Center.

date platform campaign_id ad_id Conversions Leads
2020-01-01 taboola my_campaign_id another_ad_id 1 5
2020-01-01 taboola my_campaign_id my_ad_id 2 14
2020-01-01 taboola my_other_campaign my_other_ad 0 5

As a CSV file, this will look like:

date,platform,campaign_id,ad_id,Conversions,Leads,T-Conversions,T-Leads
2020-01-01,taboola,my_campaign_id,my_ad_id,,,1,14
2020-01-01,,,my_campaign_id,my_ad_id,2,14,,
2020-01-01,taboola,my_other_campaign,my_other_ad,0,5,0,5

Here is another, more complicated example including site_id - note that the data you upload may in this case contain several rows which contain the same combination of site_id and campaign_id and indeed the same combination of ad_id and campaign_id. This is absolutely fine, we aggregate that data separately across each combination, so no data is lost.

date platform campaign_id ad_id site_id Conversions Leads
2020-01-01 taboola my_campaign_id an_ad_id some_site_id 1 5
2020-01-01 taboola my_campaign_id an_ad_id another_site_id 1 5
2020-01-01 taboola my_campaign_id a_second_ad_id some_site_id 2 14
2020-01-01 taboola my_campaign_id a_second_ad_id another_site_id 2 14

The CSV file would look like this:

date,platform,campaign_id,ad_id,site_id,Conversions,Leads
2020-01-01,taboola,my_campaign_id,an_ad_id,some_site_id,1,5
2020-01-01,taboola,my_campaign_id,an_ad_id,another_site_id,1,5
2020-01-01,taboola,my_campaign_id,a_second_ad_id,some_site_id,2,14
2020-01-01,taboola,my_campaign_id,a_second_ad_id,another_site_id,2,14

Important to note here is that Joinative automatically aggregates separately for ads and sites. What does this mean? It means that for this file, two operations are performed - first, the data is aggregated by site. This is done using a combination of ad_id and campaign_id, so in this first operation rows 1 and 2 in our data, as well as rows 3 and 4 will be added up, since they represent the same ad respectively. In the second operation, we aggregate by site_id and campaign_id, meaning that rows 1 and 3 will be added, as will rows 2 and 4, since these represent the same site respectively, even though the ads differ.

What could possibly go wrong?

Actually, quite a few things. One common issue with file uploads is that they are not very transparent when things go wrong - it’s not always straight-forward to communicate what the error was, especially when so many things can go wrong. To make this a bit easier, we’ve tried to make our error messages as clear as possible when things don’t quite turn out how we expect them to. But, in the interest of clarity, here are a few of the most frequent issues we see.

File is missing

Error message for missing CSV file - Joinative Conversion Upload

I know, I know, at this point you’re thinking “how can anyone be silly enough to make that mistake?”. Trust us, it happens, we know so because …err, well… our friends do it all the time. It could be that you select a file to upload using our file chooser, and then decide to open up the chooser again to see which other files are in there. Maybe you’re just curious to see which other files you could upload from your computer, or maybe which ones you have already uploaded. However, when you click ‘Cancel’ to carry on with what you were doing, the browser understands that as selecting no file at all and removes your previous selection. Anyway, the solution to this issue - pretty straight-forward, right? Reselect the file and try again.

File is not a valid CSV

Error message for invalid or malformed CSV file - Joinative Conversion Upload

This one is a little more nuanced, and the solution can honestly be much harder to track down. It could be that you did everything right in preparing the file, but then just named it incorrectly. File extensions like .cvs or .cav look obvious now, but when you’re very quickly pulling things together, renaming files and uploading them, it is very easy to overlook and can lead to a lot of head-scratching and hair-pulling.

Alternatively, it could be an issue that is buried deep within the file. If you’ve opened up some quotes (' or ") and not closed them, or if a semi-colon (;) has slipped in there in place of a comma (,), these are all things that can throw an error that can be hard to track down.

In this case, it may be a good idea to ask for help. A colleague’s fresh look on the file may help you, and if not, reach out to us here to get some assistance.

Missing required headers

Error message for missing headers in CSV file - Joinative Conversion Upload

As detailed above, there are certain required fields that must be present in the headers (the first row of the CSV, in case you’re not sure). If any of those headers are missing (or misspelled, even), then we won’t be able to match the conversions with the data we have inside of Joinative. For this reason, we throw an error and kindly ask you to modify the CSV before trying again.

Invalid headers

Error message for invalid headers in CSV file - Joinative Conversion Upload

On the opposite side of the coin from the scenario above, if you include some headers in the CSV that aren’t allowed, we will let you know. As a reminder, the allowed headers are:

  • date
  • platform
  • campaign_id
  • ad_id
  • site_id

as well as any conversion events that come from the platforms themselves and any conversion events that you have defined in the Conversions Center.

Non-numeric conversion data

Error message for non-aggregatable data in CSV file - Joinative Conversion Upload

When you upload a file of conversions, we aggregate the data behind the scenes to make sure the ad/site breakdown works properly - this means that if there are some non-numeric values in the conversion fields, we won’t be able to work with it. It could be that the numbers are wrapper in quotes, like '2', or just that some text has crept into the conversion data. Whatever the case, this is the reason for this error message, and is usually quite easy to find in files that are not too long.

When things go to plan

Success message for processed CSV file - Joinative Conversion Upload

Finally! It might seem like an impossible task now, given all the potential issues outlined above, but once the CSV file is properly formed and all can be correctly parsed, you will see the success message that it has been parsed. This means that the conversion data has been successfully entered into Joinative.

OK, conversions have been uploaded, what next?

Once you have successfully uploaded your conversion data, this data will be available in your Joinative reports. Check out the Reports Center for more information.