Sourcepoint Setup & Configuration v1

Setting up Sourcepoint’s CMP solution is a simple process that publisher teams can get up and running quickly. This document is a quick start guide on how to get consent messages displaying on your site. Please be aware that this setup would likely change for delivering adblock messages.

This article provides detail on simply getting consent messages displayed on your site. For additional details on setting key-value pairs for targeting or sending data to site analytics, DMPs or other platforms, please read article Optional Targeting Features And Callbacks.

Implementation can be divided into three steps.

  1. Getting JavaScript Assets

  2. Page Configuration

  3. Setting Up The Messaging Domain

Please read through the content below regarding on each of these implementation steps and feel free to reach out to your Sourcepoint account manager with any questions you may have.

We also included additional information on how to leverage our key-value pair targeting features and our data callbacks. Key-value pairs are used to create highly targeted based on data points from external systems like DMPs and CRM platforms. Our callback are used to set cookie values based on the messages a user have seen and to send data to external systems such as website analytics platforms and DMPs.

The latest version of our consent messaging library can be accessed from the API listed below. The scripts can be pulled from our API using the following curl commands or you can request the latest version of our script from your Sourcepoint account manager. Example curl commands to pull these scripts are below. Your Sourcepoint account manager can provide you with your authorization token.

Example API curl for messaging.js library

$ curl -H "Authorization: Token INSERT API TOKEN HERE" "https://api.sourcepoint.com/script/msg_without_detection"

The typical implementation for publishers is to place the Dialogue configuration code directly on the site page. The example that follows is a typical implementation and can be used for the majority of set ups.

The code listed below is the minimum you need to get started showing messages. It does not include any callbacks or the code to set key-value pairs for additional targeting. Your Sourcepoint partner manager will supply you with your account ID. You will need to set up your own subdomain and CNAME that subdomain to our message{accountIdHere}.sp-prod.net where {accountIdHere} is replaced by your account ID. For example, for account ID 1001, you would CNAME your subdomain to message1001.sp-prod.net.

On-Page Configuration of Sourcepoint Code Example

<!--start Sourcepoint code-->
<script type = "text/javascript">
window._sp_ = window._sp_ || {};
window._sp_.config = window._sp_.config || {};
window._sp_.config.account_id = YOUR_ACCOUNT_ID;//repalce with your account ID
window._sp_.config.mms_domain = 'YOUR CNAME'D SUBDOMAIN OR 3RD PARTY DOMAIN HERE';//replace 'message{accountIdHere}.sp-prod.net' with your CNAME’d messaging subdomain
window._sp_.mms = window._sp_.mms || {};
window._sp_.mms.cmd = window._sp_.mms.cmd || [];//CMP Flags
window._sp_.config.cmp = _sp_.config.cmp || {};
window._sp_.config.cmp.enabled = true;//Have message show immediately
window._sp_.config.detection = window._sp_.config.detection || {};
window._sp_.config.detection.timeout = 1;//Code to call the server and display a message
window._sp_.mms.cmd.push( function () {
window._sp_.mms.startMsg();
});
</script>
<!--URL in line below needs to be replaced with messaging file location on your CDN-->
<script type="text/javascript" src="//scripts.yourcdn.com/js/messaging.js"></script>
<!--end Sourcepoint code-->

Setting Up The Config Parameters

There are two essential configuration parameters to set up a publisher instance of the Dialogue solution. The first is the window._sp_.config.account_id variable. This is set to the account id you receive from your Sourcepoint account manager. The id associates your data and site up to the publisher account in the Sourcepoint user interface.

The second is the window._sp_.config.mms_domain variable. This is set to the messaging subdomain that has a CNAME DNS entry to the Sourcepoint Dialogue server. You should not include http:// or https:// as part of this variable. The Sourcepoint scripts will inherit the protocol of the page automatically. This is the communication channel between the site and the consent messaging platform.

Setting up The Messaging Domain

The Dialogue JavaScript communicates with the Sourcepoint messaging server on a subdomain of the site. This allows messaging cookies to be “first party” cookies and creates a discrete messaging channel between the publisher’s messaging subdomain and the Dialogue messaging server. Once created, the subdomain is the publisher creates a DNS CNAME record to direct traffic to the Sourcepoint message message{accountIdHere}.sp-prod.net where {accountIdHere} is replaced by your account ID.

Once you have created the CNAME record alert your Sourcepoint Account manager so that they can create an SSL certificate for the subdomain. This will ensure that both secure and non-secure traffic are handled properly.

Starting The Message Decision Process Using startMsg()

The startMsg() function tells the messaging library that all targeting functions have been called and everything is ready for the call to the messaging server. At this point, the messaging library will make its call to the Dialogue server and see if the conditions are right to display a message to the site visitor. If the Dialogue server determines that a message should be displayed to the site visitor then the server returns the HTML and CSS necessary to display the message.

An example of the call to startMsg() looks like the one below, and it's proper position in the configuration can be seen in the snippet above.

window._sp_.mms.cmd.push( function () {
window._sp_.mms.startMsg();
});

Note: Once the startMsg() call has been made, any targeting parameters set after the startMsg() call will not be considered in delivering the message.

The setTargeting(key, value) function will add a Key-Value pair to the messaging call for the purposes of decisioning in the messaging scenario. Multiple key-value pairs can be added per messaging call. In order for the value to be sent, this call must come before the startMsg() function is called.

If we look at the example above for a typical Dialogue implementation we see the code below. The setTargeting(key,value) function being used here enables you to send data to Sourcepoint to be used in a scenario as targeting criteria. In this example, the profile we are sending is meant to convey the color_preference of blue for the user. This information could be data that is stored in the site DMP and passed as JavaScript string to Dialogue.

// example usage of setting a targeting parameter
window._sp_.mms.cmd.push( function () {
window._sp_.mms.setTargeting( "color_preference" , "blue" );
});

To leverage this data, there would be a corresponding step in the Dialogue user interface that would perform (or not perform) an action based on the value portion of the key-value pair being sent. In the example screenshot below, the scenario is setup to show a message only if there is value of blue being sent for the color_preference key.

The value portion of the key-value pair can be sent as a JavaScript variable. The example below shows the variable dmp_color being set outside the setTargeting function and that variable being used as the value portion of the key-value pair. The same UI setup from the previous example could apply.

<script>
var dmp_color = "blue";
</script><script>
// example usage of setting a targeting parameter
window._sp_.mms.cmd.push( function () {
window._sp_.mms.setTargeting( "color_preference" , dmp_color );
});
</script>

Sourcepoint can match either using “match” logic or “contains” logic. The previous user interface example showed using “match” logic. However, in some instances you may need to use “contains” logic. For example if the data being sent from the external DMP is a comma separated list.

In the example below, the dmp_colors variable contains a comma separated list of color values (red, blue and green). If we want to show messages to users that have blue as a color preference, but also may have other color preferences too, we can do this by sending the values to Dialogue using the dmp_colors variable and then leverage the contains logic in the UI.

<script>
var dmp_colors = "red,blue,green";
</script><script>
// example usage of setting a targeting parameter
window ._sp_.mms.cmd.push( function () {
window ._sp_.mms.setTargeting( "color_preference" , dmp_colors );
});
</script>

Sourcepoint provides callback functions at two specific events in the message process. These callbacks can be used to set custom cookie values for later key-value pair targeting, send data to website analytics platforms for deeper analysis, send data to DMPs for custom targeting, etc.

The mms_client_data_callback() Function

The first callback, mms_client_data_callback, is triggered when the Dialogue server responds and determines whether or not a message should be served to the user. The callback each time a call to startMsg() is called regardless of whether a message is shown or not. The example function below prints the callback’s JSON to the developer console window.

Example Client Data Callback

window._sp_.config.mms_client_data_callback = function (o) {
console.log("data callback json: " + o);
};

The JSON data sent to the function provides data on some key aspects of the message being displayed.

Presence of an adblocker

  • Message ID of the message shown to the web visitor this pageview (0 if no message is shown)

  • Unique Identifier of partition or A/B test group that visitor is in

  • The campaign ID currently running for this site

  • If the user has previously clicked on any choice options

Below is the structure of JSON data sent to the callback and a table of definitions for each of the value within the JSON.

Example JSON Data

{
"d":{
"abp":true ,
"abt":false
},
"o":{
"wl":false ,
"oir":false
},
"u":{
"uuid":"46ca8814-846a-48e2-98f9-96ffd8729909",
"bucket" : 667
},
"info":{
"cmpgn_id":3633,
"prtn_uuid":"2a25f387-d823-4a52-9a82-84131bb41e32",
"msg_id":3974,
"msg_desc":"All options"
}
}

JSON Data Definitions

  • d.abp - A value of true if adblocker present, false otherwise

  • d.abt - No longer used.

  • o.wl - Whether the user clicked on the button to show the whitelist instructions or not. This is NOT whether a user actually whitelisted. It only measures whether the user engaged with the whitelist instructions button or not.

  • o.oir - The user has opted-in to recovery in the past

  • u.uuid - Sourcepoint assigned UUID for the user (randomly assigned when first see user)

  • u.bucket - Sourcepoint assigned partition bucket (randomly assigned when first see user)

  • info.cmpgn_id - The campaign ID of the campaign currently running.

  • info.prtn_uuid - The id value associated with the partition the user belongs to. Partitions are determined in the Dialogue UI by assigning a group of bucket values to a partition.

  • info.msg_id - The ID value of the message shown (or 0 if no message this call)

  • info.msg_desc - The text description of message entered into the Dialogue UI.

The mms_choice_selected_callback() Function

The Choice Selected Callback is fired when a user selects a choice in a message. The callback provides information on the choice selected and also provides the opportunity for publishers to set a cookie on the user for additional targeting or leveraged as key-value pairs in an adserver.

The framework will pass an integer ID to the choice selected callback

1 = Whitelist Instructions Viewed 2 = Opt-in Recovery 3 = Alt Ad 4 = Publisher Custom Choice (iFrame) 5 = Publisher Custom Choice Redirect 6 = Continue With Adblocker 7 = Alt Pay (requires additional agreement with Sourcepoint) 8 = not used 9 = Custom JavaScript (enabled by Sourcepoint) 10 = Welect Video (requires separate agreement with Welect and Sourcepoint) 11 = Accept All (consent) 12 = Show Privacy Manager (consent) 13 = Reject All (consent)

Example Choice Callback

//JavaScript code for example callback
window ._sp_.config.mms_choice_selected_callback = function (choiceID) {
console .log( "Choice : id=" + choiceID);
} ;