Overview

Setting up Sourcepoint’s Dialogue solution is a simple process that publisher teams can get up and running quickly using our bootstrap loader to load the messaging library. This document is a quick start guide on how to get messages displaying on your site.

This document does not provide detail on setting key-value pairs for targeting or sending data to site analytics, DMPs or other platforms. These topics and more are detailed in the technical documentation “Sourcepoint Dialogue Messaging Management System”.

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.

Getting JavaScript Assets

There are two scripts used in the typical on-page Sourcepoint implementation. The first script is our bootstrap code which a script designed to asynchronously load the main Sourcepoint messaging JavaScript library. The second script is the messaging library itself.

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.

Example curl for bootstrap JavaScript

$ curl -H "Authorization: Token YOUR_AUTH_TOKEN"   "https://api.sourcepoint.com/script/bootstrap?v=1"


Example curl for messaging library

$ curl -H "Authorization: Token YOUR_AUTH_TOKEN"   "https://api.sourcepoint.com/script/msg?v=1"


The bootstrap code is placed inline just prior to the Sourcepoint Dialogue configuration parameters. The messaging library is saved to a js file that is placed in a directory structure of the web site. 

On-Page Configuration

The typical implementation for publishers is to place the Dialogue configuration code directly on the site page. As previously stated, The bootstrap code is placed inline with the Sourcepoint Dialogue parameters. The example that follows is a typical implementation and can be used for the majority of set ups.

<script type = "text/javascript"> 
( function () {
/* { PUT SP BOOTSTRAP CODE HERE INLINE }*/

/* standard configuration parameters for sourcepoint*/
window._sp_ = window._sp_ || {};
window._sp_.config = window._sp_.config || {};

window._sp_.config.account_id = YOUR_ACCOUNT_ID;
window._sp_.config.content_control_callback = function () { } ;

/* replace with your messaging domain*/
window._sp_.config.mms_domain = 'message.sp-prod.net' ;

/*messaging-specific configuration*/
window._sp_.mms = window._sp_.mms || {};
window._sp_.mms.cmd = window._sp_.mms.cmd || [];

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

window._sp_.config.mms_choice_selected_callback = function (choiceID) {
  console.log( "Choice : id=" + choiceID);
};

//CMP Flags
window._sp_.config.cmp = _sp_.config.cmp || {};
window._sp_.config.cmp.enabled = true;


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

/*tell the messaging library that all params are
set and it can proceed*/

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

/*use the sourcepoint bootstrap code
(inlined above) to load*/

/* the main messaging library this should reflect the location of the JavaScript library on your CDN*/
window._sp_.bootstrap( 'messaging-2.0.980.js' ); })();

</script>

Setting Up The Config Parameters

There are three 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 

The last configuration setting is the window._sp_.bootstrap() function. This function will load the Dialogue messaging library from the location specified in the function. For example, window._sp_.bootstrap('/js/messaging.js') will asynchronously load the messaging library from the js folder in the website directory.

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.sp-prod.net

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.

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

Leveraging Key-Value Pairs Using setTargeting(key, value)

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.

Key-Value Pair Code Example

/*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.

Key-Value Pair User Interface Setup Example

The first step is to set up a new condition for a "String Match"

Then enter the key name and the value for the ket to satisfy the condition. The last steps is to set whether the scenario should continue (yes) or not (no) from the in the last drop down.


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.


Key-Value Pair Code with Variable Example

<script>
var dmp_color = "blue";
</script>

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

});

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.

Key-Value Pair Code with Comma Separated Values

<script>
var dmp_colors = "red,blue,green";
</script>

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

Key-Value Pair User Interface Contain Setup Example

Using Data Callbacks

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 mms_cleint_data_callback Function

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 Structure for Callback 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 bicket 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
window ._sp_.config.mms_choice_selected_callback = function (choiceID) { 
  console .log( "Choice : id=" + choiceID);
} ; 

To enable to Sourcepoint Consent Management Platform, the publisher needs to make sure they are running the latest version of the Sourcepoint messaging library. They also need to add two lines of code to the existing Dialogue configuration parameters (see below).

CMP Flags

window._sp_.config.cmp = _sp_.config.cmp || {};
window._sp_.config.cmp.enabled = true;

In the example configuration below, the additional code is highlighted in yellow.

Example CMP Configuration

<script type = "text/javascript"> 
( function () {
// { PUT SP BOOTSTRAP CODE HERE INLINE }

// standard configuration parameters for sourcepoint
window._sp_ = window._sp_ || {};
window._sp_.config = window ._sp_.config || {};
window._sp_.config.account_id = YOUR_ACCOUNT_ID;
window._sp_.config.content_control_callback = function () { } ;

// replace with your messaging domain
window._sp_.config.mms_domain = 'message.sp-prod.net' ;

// messaging-specific configuration
window._sp_.mms = window._sp_.mms || {};
window._sp_.mms.cmd = window._sp_.mms.cmd || [];

//optional flags for CMP customers
window._sp_.config.cmp = _sp_.config.cmp || {};
window._sp_.config.cmp.enabled = true;

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

window._sp_.config.mms_choice_selected_callback = function (choiceID) {
  console.log( "Choice : id=" + choiceID);
} ;

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

// tell the messaging library that all params are set and it can
//proceed
window._sp_.mms.cmd.push( function () {
   window ._sp_.mms.startMsg();
});

// use the sourcepoint bootstrap code (inlined above) to load
// the main messaging library
window._sp_.bootstrap( 'messaging-2.0.980.js' ); })();
</script>

If the publisher subscribes to the Sourcepoint Consent Management Platform (CMP) and needs to capture consent for DFP, we have built that capability into the Sourcepoint CMP. At this point in time, Google DFP has enabled the ability to serve non-personalized ads through a flag set in a publisher’s GPT code.  Please read the the article entitled “Ads personalization settings in Google’s publisher ad tags” for more information.

The first step in the process is adding DoubleClick to the vendor list in the Sourcepoint UI (see screenshot below).

When a user is displayed a consent request and opts-in to DFP, the Consent Management Platform will set the following cookie value on the publisher’s first-party cookie

_sp_enable_dfp_personalized_ads=true

This cookie value can then be read back using JavaScript by the publisher on that or subsequent pageviews. The publisher takes that value and sends either a 0 or 1 to DFP based on the users choice using 

googletag.pubads().setRequestNonPersonalizedAds(1) 

or

googletag.pubads().setRequestNonPersonalizedAds(0)

If you have any questions regarding this setup, please contact your Sourcepoint account manager.

Did this answer your question?