Working with the external reference mapping

What is the external reference mapping for?

The external reference mapping feature allows you to relate the platform to another system, such as a CRM tool. What you create an external reference, you define that whenever an ad impression or clicked is tracked for an advertiser, partner, ad space or ad media, the platform transmits a value from another system via an additional parameter in the target URL. Because this value is transmitted, it can trigger events in the other system. In most cases, this will simply imply feeding statistics, but it is possible to do much more.

Configuring the external reference mapping

Getting started

Make sure you are logged in the admin UI, click on ‘configuration’ in the administration section and proceed to click on ‘external reference mapping. On the page you see now, you will find an overview of all the external references you have created so far. This overview includes:

• An internal ID of the external reference mapping.

• The name of the external reference mapping.

• The placeholder which is used in the target URL.

• A description of the external reference mapping.

• The number of rules applied to the external reference mapping. A rule defines what value will be transmitted under what conditions.

Apart from the overview, you will also find a button ‘create new external reference mapping’ in the right top corner of the page.

Basic settings

To create a new external reference mapping, click on the ‘create new external reference mapping’ in the right top corner of the overview page. If you do so, you will see a page looking more or less like this:

Open

On this page, make sure you go through the following steps:

• Give your external reference mapping a name. It is recommended to use a name that relates to the external system you want to connect the platform to.

• A placeholder will be created automatically based on the name you gave. This placeholder will be used for the external values that will be transmitted via the additional parameter in the target URL.

• Optionally, you can write a brief description explaining the function of the external reference mapping.

When you are ready, click on ‘save’ in the right lower corner of the page.

Creating application rules

After you have created the basic settings, your external reference mapping will be displayed in the overview table. In the overview, go to the column section and click on the to create mapping rules. As was mentioned above, these rules define what value will be transmitted under what conditions. Please note that you need to create a rule for every single value you want to use.

you click on the icon, you will be taken to a page which provides you an overview of all the rules created for the external reference mapping. Proceed to click on the button ‘create new rule’ in the right lower corner of the upper panel of the page. On the page you see now, you will find a form where you can fill out values and define the conditions for their transmittance:

• ‘name’, give your rule a name. Usually, the name will point out the meaning of the value from the external system.

• Under ‘value’, you need to enter the value used for the external system.

• Under ‘touchpoint type’, define whether the value needs to be transmitted for ad impressions or for clicks. Please note you can also choose to transmit the value for both. In this case, select ‘all’.

• In the following four entries, you can choose to define that the value will be transmitted for a specific advertiser, a partner, an ad space or an ad media item. Please note that you do not necessarily need to narrow down the conditions to an ad space level. If you want a specific value to be transmitted regardless of the ad media, ad space, partner or even advertiser, just use the ‘select all’ function in all of the entries.

When you are done, click on the button ‘create’ in the right lower corner of the page. If you do so, you will be taken back to the page with the overview of the rules. Here, you can immediately proceed to create further rules.

Tracking implementation

Finally, you need to make sure the values are transmitted by adding a parameter to the target URL of your advertiser. Please note: if you have included multiple advertisers in your application rules, you will have to adjust the additional parameters for every advertiser. Make sure you go through the following steps:

• Click on ‘advertiser’ in the main menu and proceed to click on ‘manage advertisers’ in the sub-navigation menu. Find the advertiser for which you want to apply the external reference mapping and click on the icon to go to the tracking settings. Scroll down the page until you see the section ‘additional parameters’.

• Click on ‘add parameter’ in the right top corner of the panel. On the page you see now, go through the following steps:

  • Give your parameter a name. This is the actual name as it will be used in the target URL. Please note that the external system to which you want to connect the platform might have specific requirements for the parameter name.

  • Under ‘value type’, select ‘external reference mapping’.

  • Under ‘value’, select the name of the external reference mapping you have created.

  • Under ‘position’, select ‘automatically’, unless you are using an external parameter and additional value in your target URL that needs to have a specific position. For more information, please read this paragraph in the article on additional parameters.

  • Under ‘replace if exist’, select ‘on’. This will prevent a hardcoded value in a target URL of an ad media item will be used.

  • Click on ‘preview’ in the right lower corner to review the new tracking URL.

  • When you are happy with the preview, click on ‘add parameter’ in the low right corner of the page.

Testing

It is highly recommended to test the external reference mapping when you are done implementing it. To do this, make sure you go through the following steps:

• Go to ‘partner’ in the main navigation and click on ‘manage partners’. Proceed to select a partner for which the rules you created apply and login as this partner by using the icon. For more information, please read this article.

• In the partner account, go to the ad media section and select an advertiser and an ad space for which the rules you created apply. Click on ‘search’ in the right lower corner of the filter panel. As soon as the ad media of the relevant advertiser is displayed, select one ad media item and copy the click URL. If your external reference mapping is related to ad impressions as well, make sure you go to the ‘URL options’ and copy the ad impression URL as well. Please note that it only makes sense to test the ad impression URL of a banner. For more details on ad media in the partner UI, please read this article.

• To test your click URL, make sure you activate a feature that records your HTTP-headers and open a browser tab and paste the click URL in the address bar. Say, the name of the parameter related to your external reference mapping is ‘crm’ and the value related to the advertiser, partner, ad space and ad media item is ’17b13′, in case of a successful test you will find a target URL recorded looking more or less like this:

• To test your ad impression URL, make sure you activate the developer’s console of your browser, open a browser tab, and paste the ad impression URL in the address bar. If you do so, the image source URL will be loaded and you will see the image of the banner in your browser. In the console, run a network analysis and see whether you find the parameter and the value that has been related to the advertiser, partner, and ad space of the ad media item you used.