In this lesson, we will implement the Adobe Target extension with a page load request and custom parameters.
Adobe Target is the Adobe Experience Cloud solution that provides everything you need to tailor and personalize your customers’ experience, so you can maximize revenue on your web and mobile sites, apps, social media, and other digital channels.
Adobe Experience Platform Launch is being integrated into Adobe Experience Platform as a suite of data collection technologies. Several terminology changes have rolled out in the interface which you should be aware of while using this content:
At the end of this lesson, you will be able to:
To complete the lessons in this section, you must first complete the lessons in Configure tags and Add the Identity Service.
Before we get started, we need to make a slight update to the tag embed codes. When the tag embed codes are loaded asynchronously, the page may finish rendering before the Target library is fully loaded and has performed its content swap. This can lead to what is known as “flicker” where default content briefly displays before being replaced by the personalized content specified by Target. If you want to avoid this flicker, we strongly recommend hardcoding a special pre-hiding snippet immediately before tags’ asynchronous embed codes.
This has already been done on the Luma site, but let’s go ahead and do this on the sample page so you understand the implementation. Copy the following lines of code:
<script>
//prehiding snippet for Adobe Target with asynchronous tags deployment
;(function(win, doc, style, timeout) {
var STYLE_ID = 'at-body-style';
function getParent() {
return doc.getElementsByTagName('head')[0];
}
function addStyle(parent, id, def) {
if (!parent) {
return;
}
var style = doc.createElement('style');
style.id = id;
style.innerHTML = def;
parent.appendChild(style);
}
function removeStyle(parent, id) {
if (!parent) {
return;
}
var style = doc.getElementById(id);
if (!style) {
return;
}
parent.removeChild(style);
}
addStyle(getParent(), STYLE_ID, style);
setTimeout(function() {
removeStyle(getParent(), STYLE_ID);
}, timeout);
}(window, document, "body {opacity: 0 !important}", 3000));
</script>
Open the sample page and paste it just before your tag embed code as pictured below (don’t worry if the line numbers are different). In this screenshot the pre-hiding snippet has been minified:
Reload your sample page. You will notice that the page will be hidden for three seconds before it shown. This behavior is temporary and will go away after you have deployed Target. This pre-hiding behavior is controlled by two configurations at the very end of the snippet, which can be customized but are usually best left on the default settings:
body {opacity: 0 !important}
specifies the css definition to use for the pre-hiding until Target loads. By default, the entire body will be hidden. If you have a consistent DOM structure with an easily identifiable container element wrapping all of the content below your navigation, for example, and you never wanted to test or personalize your navigation, you could use this setting to limit the pre-hiding to that container element.3000
which specifies the timeout setting for the pre-hiding. By default, if Target hasn’t loaded in three seconds the page will be shown. This should be extremely rare.For more details and to obtain the un-minified pre-hiding snippet, please see the Adobe Target extension with an asynchronous deployment.
The Adobe Target extension supports client-side implementations using Target’s JavaScript SDK for the modern web, at.js. Customers still using Target’s older library, mbox.js, should upgrade to at.js 2.x in order to use tags.
The Target v2 extension consists of two main parts:
In this first exercise we will add the extension and look at the configurations. In later exercises we will use the actions.
To add the Extension
Go to Extensions > Catalog
Type target
in the filter to quickly locate the Adobe Target extensions. There are two extensions—Adobe Target and Adobe Target v2. This tutorial will use the v2 version of the extension which uses the latest version of at.js (currently 2.x) which is ideal for both traditional websites and single-page applications (SPA).
Click Install
When you add the extension, it will import many, but not all of your at.js settings from the Target interface, as pictured below. One setting that will not be imported is the Timeout, which will always be 3000ms after adding the extension. For the tutorial, leave the default settings. Note, that on the left hand side it will show the at.js version that ships with the current version of the extension.
Click Save to Library
At this point, Target isn’t really doing anything, so there is nothing to validate.
Each version of the Target extension comes with a specific version of at.js, which is listed in the extension description. You update the at.js version by updating the Target extension.
Marketers use Target to control the visitor experience on the page when testing and targeting content. Because of this important role in the display of the page, you should load Target as early as possible to minimize the impact on page visibility. In this section, we will load the Target JavaScript library—at.js—as well as fire the page load request (referred to as the “global mbox” in earlier versions of at.js).
You can use the All Pages - Library Loaded
rule you created in the lesson “Add Data Elements, Rules and Libraries” to implement Target because it is already triggered as early as possible on page loads.
To Load Target
Go to the Rules in the left navigation and then click on All Pages - Library Loaded
to open the rule editor
Under Actions, click the to add a new action
Select Extension > Adobe Target v2
Select Action Type > Load Target
Click Keep Changes
With the Load Target
action added, at.js will load on the page. However, no Target requests will fire until we add the Fire Page Load Request
action.
To Fire Page Load Request
Under Actions, click the again to add another action
Select Extension > Adobe Target v2
Select Action Type > Fire Page Load Request
There are some configurations available for the page load request related to whether or not to hide the page and CSS selector to use for pre-hiding. These settings work in conjunction with the pre-hiding snippet hardcoded on the page. Leave the default settings.
Click Keep Changes
The new action is added in sequence after the Load Target
action and the actions will execute in this order. You can drag-and-drop the actions to rearrange the order, but in this scenario, Load Target
needs to be before Fire Page Load Request
.
Click Save to Library and Build
Now that you have added the Target v2 extension and fired the Load Target
and Fire Page Load Request
actions, there should be a page load request made on all pages where your tag property is used.
To validate the Load Target and Fire Page Load Request actions
Reload your sample page. You should no longer see a delay of three seconds before the page is visible. If you are loading the sample page using the file://
protocol, you should do this step in Firefox or Safari browsers since Chrome will not fire a Target request when using the file://
protocol.
Open the Luma site
Make sure the Debugger is mapping the tag property to your Development environment, as described in the earlier lesson
Go to the Summary Tab of the Debugger
In the Launch
section, confirm that Target
appears under the Extensions
heading
In the Target
section, confirm that your at.js library version appears
Finally, go to the Target
tab, expand your client code, and confirm your page load request appears:
Congratulations! You’ve implemented Target!
Passing parameters in the Target request adds powerful capabilities to your targeting, testing, and personalization activities. The tag extension provides two actions to pass parameters:
Add Params to Page Load Request
, which adds parameters to page load requests (equivalent to the targetPageParams() method)
Add Params to All Requests
, which adds parameters in all Target requests, e.g. the page load request plus additional requests made from Custom Code actions or hardcoded on your site (equivalent to the targetPageParamsAll() method)
These actions can be used before the Load Target
action and can set different parameters on different pages based on your rule configurations. Use the rule ordering feature you used when setting Customer IDs with the Identity Service to set additional parameters on the Library Loaded
event before the rule firing the page load request.
Since most implementations use the page load request for activity delivery, it usually sufficient to just use the Add Params to Page Load Requests
action.
Parameters are used to pass custom data to Target, enriching your personalization capabilities. They are ideal for attributes that change frequently during a browsing session such as the page name, template, etc. and do not persist.
Let’s add the Page Name
data element that we created earlier in the Add Data Elements, Rules and Libraries lesson as a request parameter.
To add the request parameter
Go to the Rules in the left navigation and then click on All Pages - Library Loaded
to open the rule editor.
Under Actions, click the to add a new action
Select Extension > Adobe Target v2
Select Action Type > Add Params to Page Load Request
Enter pageName
as the Name
Click the to open the data element modal
Click the Page Name
data element
Click the Select button
Click Keep Changes
Click-and-drag on the left edge of the Add Params to Page Load Request
action to rearrange the actions it’s before the Fire Page Load Request
action (it can be before or after Load Target
)
Click Save to Library and Build
For the time-being, custom parameters passed with at.js 2.x requests are not easily visible in the Debugger, so we will utilize the browser’s developer tools.
To validate the pageName request parameter
tt.omtrdc
(or your CNAME’d domain for Target requests)Headers
> Request Payload
> execute.pageLoad.parameters
section to validate the pageName
parameter and valueSimilar to request parameters, profile parameters are also passed through the Target request. However, profile parameters get stored in Target’s visitor profile database and will persist for the duration of the visitor’s profile. You can set them on one page of your site and use them in Target activities on another page. Here is an example from an automobile website. When a visitor goes to a vehicle page, you could pass a profile parameter “profile.lastViewed=sportscar” to record their interest in that particular vehicle. When the visitor browses to other, non-vehicle pages you can target content based on their last vehicle viewed. Profile parameters are ideal for attributes that rarely change or are only available on certain pages
You won’t pass any profile parameters in this tutorial, but the workflow is almost identical to what you just did when passing the pageName
parameter. The one difference is you need to give profile parameter names a profile.
prefix. This is what a profile parameter called “userType” would look like in the Add Params to Page Load Request
action:
Entity parameters are special parameters used in Recommendations implementations for three main reasons:
entity.id
) or category (entity.categoryId
) that the visitor is currently viewing.entity.name
) and image (entity.thumbnailUrl
). Some customers populate their catalog using backend feeds, but they can also be populated using entity parameters in Target requests.You don’t need to pass any entity parameters in this tutorial, but the workflow is identical to what you did earlier when passing the pageName
request parameter—just give the parameter a name prefixed with “entity.” and map it to the relevant data element. Note that some common entities have reserved names that must be used (e.g. entity.id for the product sku). This is what it would look like to set entity parameters in the Add Params to Page Load Request
action:
The collection of customer ids with the Adobe Experience Platform Identity Service makes it easy to import CRM data into Target using the Customer Attributes feature of the Adobe Experience Cloud. It also enables cross-device visitor stitching, allowing you to maintain a consistent user experience as your customers switch between their laptops and their mobile devices.
It’s imperative to set the Customer ID in the Identity Service’s Set Customer IDs
action before firing the page load request. To that end, make sure you have the following capabilities on your site:
Set Customer IDs
action in a rule that fires at the “Library Loaded (Page Top)” eventFire Page Load Request
action in a rule that fires after the “Set Customer IDs” actionIn the previous lesson, Add the Adobe Experience Platform Identity Service, you created the All Pages - Library Loaded - Authenticated - 10
rule to fire the “Set Customer ID” action. Because this rule has an Order
setting of 10
, the customer ids are set before our our page load request fires from the All Pages - Library Loaded
rule with its Order
setting of 50
. So, you have already implemented the collection of customer ids for Target!
For the time-being, custom parameters passed with at.js 2.x requests are not easily visible in the Debugger, so we will utilize the browser’s developer tools.
To validate the Customer ID
Open the Luma site
Make sure the Debugger is mapping the tag property to your Development environment, as described in the earlier lesson
Log into the Luma site using the credentials test@adobe.com
/test
Return to the Luma homepage
Open your browser’s developer tools
Click on the Network tab
Filter the requests to tt.omtrdc
(or your CNAME’d domain for Target requests)
Expand the Headers
> Request Payload
> id.customerIds.0
section to validate the customer id settings and value:
The Adobe Experience Platform Identity Service will allow you to send multiple ids to the Service, however, only the first one will be sent to Target.
This is an optional exercise for Target Premium customers.
The property token is a reserved parameter used with the Target Premium Enterprise User Permissions feature. It is used to define different digital properties so that different members of an Experience Cloud Organization can be assigned different permissions on each property. For example, you might want one group of users to be able to set up Target activities on your web site, but not in your mobile application.
Target properties are analogous to tag properties and Analytics report suites. An enterprise with multiple brands, websites, and marketing teams might use a different Target property, tag property and Analytics report suite for each website or mobile app. Tags properties are differentiated by their embed codes, Analytics report suites are differentiated by their report suite id, and Target properties are differentiated by their property token parameter.
The property token must be implemented using a custom code action in tags with the targetPageParams()
function. If you are implementing multiple sites with different using different at_property values with a single tag property, you could manage the at_property value via a data element.
Here is an optional exercise, if you are a Target Premium customer and would like to implement a property token in your Tutorial property:
In a separate tab, open the Target user interface
Go to **Administration > Properties **
Identify the Property that you want to use and click the **</> ** (or create a new property)
Copy the code snippet within the <script></script>
to your clipboard
In your tags tab, go to the Rules in the left navigation and then click on All Pages - Library Loaded
to open the rule editor.
Under Actions, click the Core - Custom Code
action to open the Action Configuration
Open the code editor and paste the code from the Target interface containing the targetPageParams()
function
Click the the Save button
Check the Execute globally box so targetPageParams()
is declared in the global scope
Click Keep Changes
Click Save to Library and Build
If you try to add the at_property
parameter via the Add Params to Page Load Request action, the parameter will populate in the network request but Target’s Visual Experience Composer (VEC) will not be able to auto-detect it when loading the page. Always populate at_property
using the targetPageParams()
function in a Custom Code action.
For the time-being, custom parameters passed with at.js 2.x requests are not easily visible in the Debugger, so we will utilize the browser’s developer tools.
To validate the Property Token parameter
Open the Luma site
Make sure the Debugger is mapping the tag property to your Development environment, as described in the earlier lesson
Open your browser’s developer tools
Click on the Network tab
Filter the requests to tt.omtrdc
(or your CNAME’d domain for Target requests)
Expand the Headers
> Request Payload
> property.token
section to validate the value
The order confirmation request is a special type of request used to send order details to Target. The inclusion of three specific request parameters—orderId, orderTotal, and productPurchasedId—is what turns a regular Target request into an order request. In addition to reporting revenue, the order request also does the following:
The best practice is to use an order confirmation request in all order funnels, even on non-retail sites. For example, lead generation sites usually have lead funnels with a unique “lead id” generated at the end. These sites should implement an order request, using a static value (e.g. “1”) for the orderTotal.
Customers using the Analytics for Target (A4T) integration for most of their reporting may also want to implement the order request if using Automated Personalization activities, which do not support A4T. Additionally, the order request is a critical element in Recommendations implementations, powering algorithms based on purchase behavior. For the latest information about A4T support, please see the documentation.
The order confirmation request should fire from a rule that is only triggered on your order confirmation page or event. Often, it can be combined with a rule setting the Adobe Analytics purchase event. It must be configured using the Custom Code action of the Core extension, using the appropriate data elements to set the orderId, orderTotal, and productPurchasedId parameters.
Let’s add the data elements and rule we need to fire an order confirmation request on the Luma site. Since you have already created several data elements, these instructions will be abbreviated.
To create the data element for Order Id
Order Id
digitalData.cart.orderId
as the JavaScript variable name
Clean text
optionTo create the data element for the Cart Amount
Cart Amount
digitalData.cart.cartAmount
as the JavaScript variable name
Clean text
optionTo create the data element for Cart SKUs (Target)
Click Add Data Element
Name the data element Cart SKUs (Target)
Select Data Element Type > Custom Code
For Target, the skus must be a comma separated list. This custom code will reformat the data layer array into the proper format. In the custom code editor, paste the following:
var targetProdSkus="";
for (var i=0; i<digitalData.cart.cartEntries.length; i++) {
if(i>0) {
targetProdSkus = targetProdSkus + ",";
}
targetProdSkus = targetProdSkus + digitalData.cart.cartEntries[i].sku;
}
return targetProdSkus;
Check the Force lowercase value
option
Check the Clean text
option
Click Save to Library
Now we need to create a rule to fire the order confirmation request with these data elements as parameters on the order confirmation page.
To create the rule for Order Confirmation page
Order Confirmation Page - Library Loaded - 60
Order
to 60
so that it will fire after the Load Target
action (which is in our All Pages - Library Loaded
rule where Order
is set to 50
)Select Condition Type > Path Without Query String
For Path equals
enter thank-you.html
Toggle on the Regex option to change the logic from equals
to contains
(you can use the Test
feature to confirm the test will pass with the URL https://luma.enablementadobe.com/content/luma/us/en/user/checkout/order/thank-you.html
Click Keep Changes
Select Action Type > Custom Code
Click Open Editor
Paste the following code into the Edit Code
modal
adobe.target.getOffer({
"mbox": "orderConfirmPage",
"params":{
"orderId": _satellite.getVar('Order Id'),
"orderTotal": _satellite.getVar('Cart Amount'),
"productPurchasedId": _satellite.getVar('Cart SKUs (Target)')
},
"success": function(offer) {
adobe.target.applyOffer({
"mbox": "orderConfirmPage",
"offer": offer
});
},
"error": function(status, error) {
console.log('Error', status, error);
}
});
Click Save to save the custom code
Click Keep Changes to keep the action
For the time-being, custom parameters passed with at.js 2.x requests are not easily visible in the Debugger, so we will utilize the browser’s developer tools.
Open the Luma site
Make sure the Debugger is mapping the tag property to your Development environment, as described in the earlier lesson
Browse the site and add several products to your cart
Continue to checkout
During the checkout process the only required fields are First Name
and Last Name
On the Review Order page, be sure to click the Place Order
button
Open your browser’s developer tools
Click on the Network tab
Filter the requests to tt.omtrdc
(or your CNAME’d domain for Target requests)
Click on the second request
Expand the Headers
> Request Payload
> execute.mboxes.0
section to validate the request name and the order parameters:
There are rare instances when you need to make Target requests other than the page load and order confirmation request. For example, sometimes important data you would like to use for personalization is not defined on the page before the tag embed codes—it might be hardcoded on the bottom of the page or get returned from an asynchronous API request. This data can be sent to Target using an additional request, although it will not be optimal to use this request for content delivery since the page will already visible. This data can be used to enrich the visitor profile for later use (using profile parameters) or to populate the Recommendations catalog.
In these circumstances, use the Custom Code action in the Core extension to fire a request using the getOffer()/applyOffer() and trackEvent() methods. This is very similar to what you just did in the Order Confirmation request exercise, but you will just use a different request name and will not use the special order parameters. Be sure to use the Load Target action before making Target requests from custom code.
The Edit at.js screen in the Target user interface has locations in which you can paste custom JavaScript that will execute immediately before or after the at.js file. The Library Header is sometimes used to override at.js settings via the
targetGlobalSettings() function or pass data from third parties using the Data Providers feature. The Library Footer is sometimes used to add at.js custom event listeners.
To replicate this capability in tags, just use the Custom Code action in the Core extension and sequence the action before (Library Header) or after (Library Footer) the Load Target action. This can be done in the same rule as the Load Target
action (as pictured below) or in separate rules with events or order settings that will reliably fire before or after the rule containing Load Target
:
To learn more about use cases for custom headers and footers see the following resources: