O&O Implementation Guide – Salesforce Audience Studio Resources

Interchange O&O allows website operators to target advertising and content based upon segments created in Salesforce Audience Studio. Each segment is associated with a unique ID; that ID is a value attached to the Audience Studio segment key or cookie. Once delivered back to the page, the Audience Studio segment key or cookie and all attached values can be injected into your ad server or content management system (CMS) for targeting.

In this article we discuss the various steps involved in accessing the audience segment information for a given user in the browser. We also provide a description of how those audience segments can be sent to various ad servers such as DFP (DoubleClick for Publishers), AdTech, OAS, OpenX and SmartAd Server, and how you can test the implementation once complete.

On-page Interchange O&O Integration by Implementing Interchange snippet
Ad Server Integration by Modifying Ad Calls
Test Interchange Implementation by Running Test Campaign

These steps are broken out based on your version of ad server and ad tags. Please use the appropriate code based on your environment.

This article describes integration for the following ad servers:

DFP [Step 1] [Step 2]
AdTech [Step 1] [Step 2]
OAS [Step 1] [Step 2] [OAS Alternative Method: Cookie Targeting]
OpenX [Step 1] [Step 2]
Smart Ad Server [Step 1] [Step 2]

Step 1: On-Page Interchange O&O Integration - Implement Interchange Snippet

For most ad servers, the first step in the implementation process involves including code - the Interchange Snippet - that will set some JavaScript variables on the page that you may use to pass information to other systems. The JavaScript code provided below must be placed in the <head> so that it is above the first ad call.

Retrieve your Interchange snippet for the websites by visiting Manage>> Sites in Audience Studio and clicking the </> (Actions) button on the right:

This code sets two JavaScript variables that can be accessed by other JavaScript code on the page:

Krux.user: this is the Krux User ID of the current user
Krux.segments: this custom targeting key is an array of strings, where each element of the array is the unique ID of an Audience Segment that the user belongs to.

Step 1 for Google DFP

There are two methods for targeting segments in DFP:

Client-side implementation, which uses DFP’s key value targeting capability.
Sending segments to DFP Audience via a S2S connection.

Note that there are trade-offs and possible cost implications from Google based on which method you select, so you should review your business use-cases with your Salesforce Audience Studio Solutions team to determine the recommended approach.

DFP Premium Ad Server

Implement the base interchange snippet and Continue to Step 2 for DFP

Using S2S Integration into DFP Audience

If you’ve elected to utilize the S2S integration into DFP Audience, you must still implement the O&O snippet to pull the Krux User ID (kuid) into a variable to be passed into the ad call. In lieu of sending the segments via the ad call, they will be sent nightly into your Audience module via our S2S connection. To enable the S2S integration, please provide the following:

Provide Audience Studio with your Google Audience Manager ID
Contact your DFP account manager to allowlist Krux (Salesforce Audience Studio) into your Audience account. Details below:

User: adx@kruxdigital
Customer ID: 474-848-6027 
CID: 65558970

Step 1 for AdTech

In addition to the base interchange snippet, this code sets an additional javascript variable Krux.adTechKeyValues that is injected in the ad-call later on.

 <script class="kxint" type="text/javascript">
    var kvs = [];
    if(Krux.user) {
      kvs.push('u=' + Krux.user);
    }
    if(Krux.segments) {
      kvs.push('ksg=' + Krux.segments.join(':'));
    }
    Krux.adTechKeyValues = kvs.length ? kvs.join(';') + ';' : '';
  })();
</script>

Continue to Step 2 for AdTech

Step 1 for OAS

In addition to the base interchange snippet, this code sets an additional javascript variable Krux.oasKeyValues that is injected in the ad-call later on.

 <script class="kxint" type="text/javascript">
    var oas_params = [];
    if (Krux.user) {
     oas_params.push('kuid=' + Krux.user);
    }
    if (Krux.segments) {
     oas_params.push('ksg=' + Krux.segments);
    }
    Krux.oasKeyValues = oas_params.length ? oas_params.join(';') + ';' : '';
  })();
</script>

Continue to Step 2 for OAS

OAS Alternative Method: Cookie Targeting

As an alternative to using the key value method, publishers may wish to use the OAS Cookie Targeting method. Note that the OAS Cookie Targeting method may adversely affect forecasting or reporting within the OAS system, while the Audience Studio key value method will not. Therefore, Salesforce Audience Studio recommends the key value method.

Each segment is associated with a unique ID and that ID is a value attached to the 'ksg_oas' cookie. Once delivered back to the page, 'ksg_oas' and all its attached values can be injected into your ad server or content management system (CMS) for targeting.

Audience Studio sets two cookies that can be used for cookie targeting in OAS:

kuid_oas: this is the Krux User ID of the current user
ksg_oas: this is an array of strings, where each element of the array is the unique ID of an Audience Segment that the user belongs to

OAS Integration

Once the kuid_oas and ksg_oas are available via Audience Studio, you can now begin targeting campaigns to the audience segments (ksg_oas) through the OAS cookie Targeting functionality.

Adding `ksg_oas` as a Keyname

In order to easily access the audience segments build in Audience Studio, you may wish to create a Keyname for the ksg_oas cookie, which will allow you to utilize the Cookie Wizard when targeting. Otherwise, you can manually enter in the cookie name in the Cookie field. To create a Keyname:

Select the Databases tab.
From the Databases submenu, select Keynames.
Click New Keyname to display the New Keyname screen – set the Keyname to ksg_oas, enter the valid values (the segment Unique ID in Salesforce Audience Studio) then click the Add button.

Targeting to `ksg_oas`

To target a campaign to an audience segment built in Audience Studio, follow the OAS guide for targeting to Plain Text Cookies.

On the Campaign screen, select the Target tab.
Scroll down and select Cookie Targeting.
If you have entered in ksg_oas as a Keyname, you can use the Cookie Wizard. Otherwise you can always enter in the Boolean expression in the Cookie field.

Example 1: Cookie Wizard

Example 2: Cookie field

If you wish to target the campaign to multiple segments, make sure that you use the OR clause for maximum segment coverage. Always use the contains ~ operator for specifying the Keyvalue (segment Unique ID) to the Keyname.

Step 1 for OpenX

In addition to the interchange snippet, this code sets an additional javascript variable Krux.oxKeyValues that is injected in the ad-call later on.

 <script class="kxint" type="text/javascript">
   // OpenX Interchange
    var ox_params = [];
    if (Krux.user) {
     ox_params.push('c.kuid=' + Krux.user);
    }
    if (Krux.segments) {
     ox_params.push('c.ksg=' + Krux.segments);
    }
    Krux.oxKeyValues = ox_params.length ? ox_params.join(';') + ';' : '';
  })();
</script>

Continue to Step 2 for OpenX

Step 1 for Smart AdServer

In addition to the base interchange snippet, this code sets an additional javascript variable Krux.SmartKeyValues that is injected in the ad-call later on.

 <script class="kxint" type="text/javascript">
    if (Krux.user) {
      Krux.SmartKeyValues = 'kuid='+Krux.user+';';
      for (var i = 0; i < Krux.segments.length; i++ ) {
       Krux.SmartKeyValues +='ksg'+Krux.segments[i]+';'; 
      }
    }
</script>

Continue to Step 2 for SmartAd Server

Step 2: Ad Server Integration - Modify Ad Calls

This step involves modifying the ad call to push the Krux User ID and Salesforce Audience Studio Segments (when applicable) into the ad call. Once you’ve modified the ad call, you can follow these steps to check your updated ad call:

In Firefox, open the Firebug Net tab, or you can select the ad and Inspect the Element
In Chrome, open View > Developer > Developer Tools > Elements tab
If your ad server is DFP, search for 'ad.doubleclick.net'
The long URL containing that domain is the ad call; you may want to copy and paste that URL into a separate text editor to view
Within that URL, you should find the Audience Studio Segment key and user ID (eg: 'ksg', 'kuid')

Step 2 for DFP

In order to access the audience segments built in Audience Studio, you will need to add the key value 'ksg' as a custom targeting key. In addition, you will need to add 'kuid' to ensure that the Krux User ID is made available in the ad logs for processing.

For example, in DFP Premium, please complete the following steps:

Select the "Inventory" tab, then select "Key-values" from the menu options.
Create ksg: On the "Key-values" screen, select "New Key" and create a new key for "ksg" as a Dynamic value "Users will enter targeting values when creating line items or checking inventory". Then click "Add values".
Note: if using the S2S method, you do not need to add ksg as a Key-values variable.
Create kuid: On the "Key-values" screen, select "New Key" and create a new key for "kuid" as a Dynamic value "Users will enter targeting values when creating line items or checking inventory". Then click "Add values".

Next, the Audience Studio information must be integrated into the DFP ad calls.

The following code snippet provides an example (highlighted) of how Audience Studio audience segments and user ID can be integrated into an example DFP ad call.

<script type="text/javascript">
    (function() {
    var useSSL = 'https:' == document.location.protocol;
    var src = (useSSL ? 'https:' : 'http:') +   '//www.googletagservices.com/tag/js/gpt. js';
    document.write('<scr' + 'ipt src="' + src + '"></scr' + 'ipt>');
    })();
</script>

<script>
    googletag.defineSlot("/1234/travel",[728,90], "div-gpt-ad-123456789-0")
    .addService(googletag.pubads());
    googletag.defineSlot("/1234/travel",[728,90], "div-gpt-ad-123456789-1")
    .addService(googletag.pubads());

   googletag.pubads().setTargeting("ksg", Krux.segments);
   googletag.pubads().setTargeting("kuid", Krux.user);

    googletag.pubads().enableSingleRequest();
    googletag.pubads().enableSyncRendering();
    googletag.enableServices();
});
</script>

Note that segment data is set in the GPT setup tag in the <head> at the page level via googletag.pubads(). setTargeting and individual ad slots do not need to be setup with specific segment data. Also, if utilizing the S2S method, you can omit the "ksg" setTargeting, but you must set the "kuid" setTargeting.

The easiest way is to test the ad call modification is to enable the Google Publisher Console for GPT. More information on enabling the console can be found at http://support.google.com/dfp_premium/bin/answer.py?hl=en&answer=2462712.

Once enabled, the Google Publisher Console should have three tabs, one for Ad Units, one for Page Request, and another for About. Going to Page Request should highlight all the activity that GPT is undertaking. Included in there should be 2 lines for setting targeting for Audience Studio audience data, example below:

Setting targeting attribute ksg with value XYZ for service publisher_ads
Setting targeting attribute kuid with value ABC for server publisher_ads

Step 2 for AdTech

The following example shows how an example ad call (first box) should be changed to append: Krux.adTechKeyValues (second box). In addition, you will need to create a key for 'ksg' in AdTech.

    
document.write('<scr' + 'ipt type="text/javascript" language="javascript1.1" src="http://adserver.adtech.de/addyn|3.0|858|3721126|0|410|ADTECH;kvpbt=false;loc=100;target=_blank;key=jp;grp=1072;misc='
+ new Date().getTime() + '"><\/scri' + 'pt>');


<script type="text/javascript"> (function() {
var adTech = ‘<script type="text/javascript" language="javascript1.1" src="http://adserver.adtech.de/addyn|3.0|858|3721126|0|410|ADTECH;kvpbt=false;loc=100;target=_blank;key=jp;grp=1072;'
    if (window.Krux.adTechKeyValues) {
 adTech = adTech + window.Krux.adTechKeyValues; 
 }
adTech += '">' + '<\/script>'; document.write(adTech);
})();
</script>

Step 2 for OAS

The following code snippet provides an example (highlighted) of how window.Krux. oasKeyValues can be integrated into an ad call.

    
if (window.Krux.oasKeyValues) {
    oas_tag.taxonomy += window.Krux.oasKeyValues;
    oas_tag.query += window.Krux.oasKeyValues;
}

Step 2 for OpenX

You will need to include the custom parameter c.ksg for ad targeting. OpenX’s documentation on this may be found here:https://docs.openx.com/Content/publishers/targeting_custom_variables.html

Example c.ksg, c.kuid in an OpenX ad call

http://oxd.site.com/w/1.0/arj?o=1346445001&callback=OX_1346445001&ju=http%3A//www.site.com/&c.ksg_ox=xxxx,yyyy,zzzz&c.kuid_ox=xxxx

Step 2 for SmartAd Server

The following code snippet provides an example (highlighted) of how Krux.SmartKeyValues can be integrated into an ad call


<script src='http://diff.smartadserver.com/config.js?nwid=73' type="text/javascript"></script>
<script type="text/javascript">
    sas.setup({ domain: 'http://diff.smartadserver.com', async: true, renderMode: 0});
</script>

<script type="text/javascript">
sas.call("onecall", {
siteId:79441, // 
pageId:579235, // Seite : _Christests/keywords (PageID=579235)
formatId:'34156,34343,34348',
target:'kuid=pty4pyhoh;ksg=pwnz4cdu7;ksg=px5fixvlu;ksg=ng8iq52a6'// Targeting
});
</script>

<script type="text/javascript">
    sas.render('34156');  // Format : _chrisontour_mpu 300x250
</script>

Step 3: Testing the Interchange O&O

This section describes how to test the complete "round trip" of a user being assigned to a segment, the segment assignment being passed to a new page, and the segment being passed directly to your ad server.

Onsite Integration

Note: This testing is only applicable for O&O Onsite to the ad server. If you manually associate the user into a segment, the user will be pushed into that segment for on-page use until the segment reprocesses. No other interchange modalities, such as sending to partners (SSPs, DSPs), are affected and they cannot be tested using this methodology.

There are three steps in testing the full "round trip" of segment creation and use:

Associate the User to the Segment
Verify Segments to the Page
Inject Segments into the Ad Call

Step 3.1: Associate the User to the Segment

First, create a segment in Audience Studio within Segments. Once a segment is created (see the Segment Builder User Guide for more information) and has been processed, Audience Studio will assign the segment a unique ID.

Next, enable the segment for testing by clicking the Actions Gear button to the right of the segment to select Enable Test Mode. All segments enabled for testing will have a flag icon displayed next to their name in the segments list.

Your browser's Krux ID has now been associated to that segment.

Step 3.2: Verify Segments on the Page

Assuming the segment is enabled for Interchange O&O, you can now check if you were placed into the test segment and that the segment is loading correctly to the page. Visit any page that has your account's Control Tag running.

Important Note: Ensure that you are visiting the page from the same browser in which you added yourself to the segment.

Load the Control Tag Helper. See the Snippet segments in the Control Tag tab.

Or Open a browser developer console tab

In Firefox, open the Firebug > Console
In Chrome, open View > Developer > Developer Tools > Console

Type localStorage.kxsegs to view the segments your browser is in. If you are expecting to be included in one or more segments, you should segment id(s) comma separated.

Step 3.3: Target the Segment for Testing

With the test segment being returned to the page, you can now opt to launch a test campaign against the test segment. Audience Studio recommends you run a test campaign well before any paid campaigns to ensure that the integration between Audience Studio and your ad server is complete. If you’re not able to target a campaign in your ad server, you should check the Interchange steps to ensure that everything is set up properly. Here are some common troubleshooting steps:

Are the kuid and segments being returned back to the page?
Go to your web browser's console and ensure that localStorage.kxuser and localStorage.kxsegs return values. Make sure that you do not have DNT (do not track) or have opted out of Audience Studio.

Is the Interchange snippet on the page?
Review Step 1 and ensure that the Audience Studio key value variable (eg: Krux.dfppKeyValues returns values.

Is the ad call being modified?
View the ad call to ensure that the kuid and ksg (if using key values) are being passed through.

Is your ad server set up to receive key values?
Review your setup to ensure that custom targeting variables are set.

Is the segment targeted for Interchange O&O and does it have a population?
Go to Segments to ensure that the segment is targeted and that it has a population.
A target bullseye will appear within the segments list for the segment.