Contents

Introduction

  • Importing and merging advertiser's platforms' data
  • Requirements, installation & updates
  • Limitations
  • Changelog
  • License
  • Support

Tracking params, importing and merging

  • Google AdWords
  • Microsoft Bing Ads
  • Criteo
  • Facebook Ads
  • Taboola
  • Individual campaigns
  • Other advertising platforms and Piwik's default tracking params

API

  • getVisits
  • getEcommerceOrderWithVisits
  • getEcommerceOrdersWithVisits
  • getMarketingPerformance
  • getStatus

Extending AOM

  • Events

Quality assurance and monitoring

  • Logging
  • Monitoring

Plugin development

  • Tests

Tracking params, importing and merging

Here you'll find all the information about how to set up the tracking params that enable the plugin to assign imported platform data to individual visits.

Make sure that you have understood and followed the introduction before adding params.

Google AdWords

Tracking params

Since July 2017 the only supported way for Google AdWords is to use auto-tagging, which automatically adds a parameter named gclid to all links coming from AdWords. With the help of AdWords' click performance report we can identify campaign, ad group etc. for every single AdWords click afterwards.

When a Google AdWords ad for which you enabled auto-tagging is clicked, data like the following can be found in log_visit.aom_ad_params:

{
    "platform":"AdWords",
    "gclid":"CICO-Krt9c4CFSQz0wodCNUH8Q"
}

Importing & merging

For importing and merging you must activate AdWords and provide API credentials within this plugin's settings. This requires a web application in the Google API console with Piwik's full URI (e.g. http://local.piwik.de?module=AOM&action=platformAction&platform=AdWords&method=processOAuthRedirect) being an authorized redirect URI.

AdWords data is being (re)imported for the last 3 days (as old data might change). At first a click performance report will be fetched to identify campaign, ad group etc. for every single AdWords click (gclid). Afterwards, the usual merge process is going to happen.

Microsoft Bing Ads

Tracking params

We use URL tracking to obtain the required data. The following params are supported:

Param Mandatory Contents
{prefix}_platform true Bing
{prefix}_campaign_id true {CampaignId}
{prefix}_ad_group_id true {AdGroupId}
{prefix}_target_id true {TargetId}

A typical link at Microsoft Bing Ads (with the prefix "aom") should have the following params:

&aom_platform=Bing&aom_campaign_id={CampaignId}&aom_ad_group_id={AdGroupId}&aom_target_id={TargetId}

When a Bing ad is clicked, data like the following can be found in log_visit.aom_ad_params:

{
    "platform":"Bing",
    "campaignId":190561279,
    "adGroupId":2029114499,
    "targetId":"40414589411"
}

Importing & merging

For importing and merging you must activate Bing and provide API credentials within this plugin's settings. This requires a mobile or desktop client app at Bing. Piwik's URI (e.g. http://local.piwik.de/) must be added at Bing to the app's valid redirect URLs under "API settings".

Bing's data is being imported once a day.

Criteo

Tracking params

When using Criteo, all links must be created manually. The following params must be replaced manually with their corresponding IDs:

Param Mandatory Contents
{prefix}_platform true Criteo
{prefix}_campaign_id true 14340

A typical link at Criteo (with the prefix "aom") should have the following params:

&aom_platform=Criteo&aom_campaign_id=14340

When a Criteo ad is clicked, data like the following can be found in log_visit.aom_ad_params:

{
    "platform":"Criteo",
    "campaignId":"14340"
}

Importing & merging

Criteo's data is being imported once a day.

Merging is solely based on Criteo's campaign ID.

Facebook Ads

Attention: The implementation of Facebook Ads is deprecated and does not work at the moment.

Tracking params

When using Facebook Ads, all links must be created manually. The following params must be replaced manually with their corresponding IDs:

Param Mandatory Contents
{prefix}_platform true FacebookAds
{prefix}_campaign_id true 4160286035775
{prefix}_adset_id true 6028603577541
{prefix}_ad_id true 5760286037541

A typical link at FacebookAds (with the prefix "aom") should have the following params:

&aom_platform=FacebookAds&aom_campaign_id=4160286035775&aom_adset_id=6028603577541&aom_ad_id=5760286037541

When a Facebook Ads ad is clicked, data like the following can be found in log_visit.aom_ad_params:

{
    "platform":"FacebookAds",
    "campaignId":"4160286035775",
    "adsetId":"6028603577541",
    "adId":"5760286037541"
}

Importing & merging

For importing and merging you must activate Facebook Ads and provide API credentials within this plugin's settings. This requires a Facebook App with Marketing API access. Piwik's URI (e.g. http://local.piwik.de/) must be added to the app's valid OAuth redirect URIs.

Facebook Ads' data is being imported once a day.

Taboola

Tracking params

We use Taboola's passback macros, which are dynamic tracking parameters that can be set on campaign level. The following params are supported:

Param Mandatory Contents
{prefix}_platform true Taboola
{prefix}_campaign_id true {campaign_id}
{prefix}_site_id true {site}
{prefix}_campaign_item_id false {campaign_item_id}
{prefix}_device false {platform}

A typical link at Taboola (with the prefix "aom") should have the following params:

&aom_platform=Taboola&aom_campaign_id={campaign_id}&aom_site_id={site}&aom_campaign_item_id={campaign_item_id}&aom_device={platform}

When a Taboola ad is clicked, data like the following can be found in log_visit.aom_ad_params:

{
    "platform":"Taboola",
    "campaignId":504470,
    "siteId":"msn-germany-home"
}

Importing & merging

For importing and merging you must activate Taboola and provide API credentials within this plugin's settings.

Taboola's data is being imported every few hours.

Individual campaigns

For some campaigns, such as email marketing partnerships or CPA deals, there might not be an advertising platform with an API, where you can fetch the additional data (like campaign names and cost) from. Therefore Piwik AOM allows you to provide this data and Piwik AOM distributes the costs to the visits that resulted from the campaign (even if there were no visits the costs are still being considered). Here are some examples:

Email marketing campaign

Imagine you've created an email marketing campaign to advertise a special christmas deal which cost you $ 1000 and that you are going to send out on December 1st 2017. From previous email marketing campaigns you know that about 95% of visits occur within the first week after the email has been send out. You have added the tracking parameter pk_campaign=Email-December-2017.

Now, in Piwik AOM you would simply create an individual campaign before December 1st with the following data:

Begin of campaign End of campaign Campaign name Params Referrer Total cost in website currency
2017-12-01 2017-12-07 E-Mail special christmas deal 2017 pk_campaign=Email-December-2017 1000

Partnership with your friends-famous-website.com

Your friend offered you to place a link to your website for the whole month of December 2017 within one of his magazine articles which is hosted at friends-famous-website.com/article-4711.html. As he does not want to add any tracking params (and his visitors don't like obvious advertising), you can only identify traffic coming from him by the referrer. You agreed to pay 10 Cents per article visit. In January 2018 he informs you that there have been 5,000 visits, thus you create ex post - in January 2018 - the following individual campaign:

Begin of campaign End of campaign Campaign name Params Referrer Total cost in website currency
2017-12-01 2017-12-31 Partnership friends-famous-website.com Dec. 2017 friends-famous-website.com/article-4711.html 500

As soon as you add individual campaigns like these to Piwik AOM, Piwik AOM first distributes the cost you provided equally over all days within the campaign duration which you provided. Within these days, cost is equally distributed between visits.

You cannot distribute costs to visits that have been detected by Piwik AOM, i.e. you cannot distribute (additional) cost for example to an AdWords campaign that already got additional data from AdWords. Piwik AOM takes care of that, but you need to make sure that your specifications don't overlap, e.g. that you distribute the cost of two email marketing campaigns to the same pool of visits.

What about offline campaigns such as TV advertising, radio spots or offline magazines?

The problem with offline campaigns like TV advertising is that you can neither detect from the HTTP referrer nor from the params that the visitor came from a specific TV spot. He might have also read about your brand in an offline magazine or got a recommendation from a friend. Nonetheless, there are ways to track TV advertising and the similar - but this is a topic on our future roadmap!

Other advertising platforms and Piwik's default tracking params

You should not use any of the params listed above when the advertising platform you are using is not listed here.

Piwik's default tracking params pk_campaign and pk_kwd (or the tracking params provided by the Marketing Campaigns Reporting plugin) should be used for both supported and unsupported advertising platforms.

Found a bug, got a questions or have a fabulous idea?

Contact

We hope you find this Piwik plugin useful.
Feel free to get in touch if you have any questions or suggestions.

Got questions about Piwik AOM or suggestions how to improve?

Feel free to create an issue at github or contact me.

André Kolell
Online Marketing and Web Development Enthusiast

Want to get more out of Piwik AOM?

You miss a feature or like intense support on your individual Piwik setup?
Get in touch with me and let's work out how we can make things going.

Daniel Stonies
Passionate Web Developer and IT Project Manager