Set up Adobe Target with Platform Web SDK

Learn how to implement Adobe Target using Platform Web SDK. Learn how to deliver experiences and how to pass additional parameters to Target.

Adobe Target is the Adobe Experience Cloud application that provides everything you need to tailor and personalize your customers’ experience, so you can maximize revenue on your web and mobile sites, apps, and other digital channels.

Learning objectives

At the end of this lesson, you will be able to:

• Understand how to add the Platform Web SDK pre-hiding snippet to prevent flicker when using Target with asynchronous tag embed codes
• Configure a datastream to enable Target functionality
• Render visual personalization decisions when the page loads (formerly called the “global mbox”)
• Pass XDM data to Target and understand the mapping to Target parameters
• Pass custom data to Target such as profile and entity parameters
• Validate a Target implementation with Platform Web SDK

Prerequisites

To complete the lessons in this section, you must first:

• Complete all lessons for initial configuration of the Platform Web SDK, including setting up data elements and rules.
• Ensure you have an Editor or Approver role.
• Install the Visual Experience Composer helper extension if you are using the Google Chrome browser.
• Know how to set up activities in Target. If you need a refresher, the following tutorials and guides are helpful for this lesson:
  • Use the Visual Experience Composer (VEC) Helper Extension
  • Use the Visual Experience Composer
  • Use the Form-Based Experience Composer
  • Create Experience Targeting Activities

Add flicker mitigation

Before starting, determine if an extra flicker handling solution is required depending on how the tag library is loaded.

Asynchronous implementation

When a tag library loads asynchronously, the page may finish rendering before Target has performed a content swap. This behavior 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, Adobe recommends adding a special pre-hiding snippet immediately before the asynchronous tag embed code.

This snippet is already present on the Luma site, but let’s take a closer look to understand what this code does:

<script>
  !function(e,a,n,t){var i=e.head;if(i){
  if (a) return;
  var o=e.createElement("style");
  o.id="alloy-prehiding",o.innerText=n,i.appendChild(o),setTimeout(function(){o.parentNode&&o.parentNode.removeChild(o)},t)}}
  (document, document.location.href.indexOf("mboxEdit") !== -1, ".body { opacity: 0 !important }", 3000);
</script>

The pre-hiding snippet creates a style tag in the head of the page with the CSS definition of your choosing. This style tag is removed when a response from Target is received, or the timeout is reached.

The pre-hiding behavior is controlled by two configurations at the very end of the snippet.

• body { opacity: 0 !important } specifies the CSS definition to use for the pre-hiding until Target loads. By default, the whole page is hidden. You can update this definition to the selectors you want to pre-hide along with how you want to hide them. You may include multiple definitions since this value is simply what is inserted into the pre-hiding style tag. If you have an easily identifiable container element wrapping the content below your navigation, you could use this setting to limit the pre-hiding to that container element.
• 3000 specifies the timeout in milliseconds for the pre-hiding. If a response from Target is not received before the timeout, the pre-hiding style tag is removed. Reaching this timeout should be rare.

The pre-hiding snippet is also available within tags:

1. Go to the Extensions section of tags

2. Select Configure for the Adobe Experience Platform Web SDK extension

3. Select the Copy pre-hiding snippet to clipboard button

   

   NOTE

   The default pre-hiding snippet copied from the Platform Web SDK extension may include a CSS definition that does not exist on your site, such as .personalization-container { opacity: 0 !important }. Be sure to check and modify the pre-hiding snippet appropriately for your site.

Synchronous implementation

Adobe recommends implementing tags asynchronously as demonstrated on the Luma site. However, if the tag library is loaded synchronously, then the pre-hiding snippet is not required. Instead, the pre-hiding style is specified in the Platform Web SDK extension settings.

The pre-hiding style for synchronous implementations can be configured as follows:

1. Go to the Extensions section of tags

2. Select the Configure button for the Platform Web SDK extension

3. Select the Edit pre-hiding style button

   

4. Modify the CSS to include the selectors and hiding methods you would like to use, for example: body { opacity: 0 !important } if you would like to pre-hide the entire body of the page.

5. Save your changes and build to a library

To learn more about how the Platform Web SDK can manage flicker, you can refer to the guide section: managing flicker for personalized experiences.

Configure the datastream

Target must be enabled in the datastream configuration before any Target activities can be delivered by Platform Web SDK.

To configure Target in the datastream:

1. Go to Data Collection interface

2. On the left navigation, select Datastreams

3. Select the previously created Luma Web SDK datastream

   

4. Select Add Service
   

5. Select Adobe Target as the Service

6. Enter the optional details about your Target implementation, if desired, following the guidance below.

7. Select Save

   

Property token

Target Premium customers have the option to manage user permissions with properties. Target properties allow you to establish boundaries around where users can run Target activities. Refer to the Enterprise Permissions section of the Target documentation for details.

To setup or find property tokens, navigate to Adobe Target > Administration > Properties. The </> icon displays the implementation code. The at_property value is the property token you would use in your datastream.

Target environment ID

Environments in Target help you manage your implementation through all stages of development. This optional setting specifies which Target environment you are going to use with each datastream.

Adobe recommends setting the Target Environment ID differently for each of your development, staging, and production datastreams to keep things simple.

To setup or find Environment IDs, navigate to Adobe Target > Administration > Environments.

Target third-party ID namespace

This optional setting allows you to specify which Identity Symbol to use for the Target Third Party ID. Target only supports profile syncing on a single identity symbol or namespace. For more information, you can refer to the Real-Time profile syncing for mbox3rdPartyId section of the Target guide.

The Identity Symbols are found in the identities list under Data Collection > Customer > Identities.

For the purposes of this tutorial using the Luma site, use the Identity Symbol lumaCrmId set up during the lesson about Identities.

Render visual personalization decisions

First, you should understand the terminology used in the Target and tags interfaces.

• Activity: A set of experiences targeted to one or more audiences. For example, a simple A/B test could be an activity with two experiences.
• Experience: A set of actions targeted to one or more locations, or decision scopes.
• Decision scope: A location where a Target experience is delivered. Decision scopes are equivalent to “mboxes” if you are familiar with using older versions of Target.
• Personalization decision: An action the server determines should be applied. These decisions may be based on audience criteria and Target activity prioritization.
• Proposition: The result of decisions made by the server which are delivered in the Platform Web SDK response. For example, swapping a banner image would be a proposition.

Update the page load rule

Visual personalization decisions from Target are delivered by the Platform Web SDK, if Target is enabled in the datastream. However, they are not rendered automatically. You must modify the global page load rule to enable automatic rendering.

1. In the Data Collection interface, open the tag property you are using for this tutorial

2. Open the all pages - library load - AA & AT rule

3. Select the Adobe Experience Platform Web SDK - Send event action

4. Enable Render visual personalization decisions with the checkbox

   

5. Save your changes then build to your library

The render visual personalization decisions setting makes the Platform Web SDK automatically apply any modifications that were specified using the Target Visual Experience Composer or “global mbox”.

If you prefer to render or action on these decisions yourself using custom code, you can leave the Render visual personalization decisions setting disabled. The Platform Web SDK is flexible and provides this capability to give you complete control. You can refer to the guide for more information about manually rendering personalized content.

Set up a Target activity with the Visual Experience Composer

Now that the basic implementation portion is complete, create an Experience Targeting (XT) activity in Target to validate that everything is working correctly. You may refer to the Target tutorial for creating Experience Targeting activities if you need assistance.

1. Navigate to Target

2. Create an Experience Targeting (XT) activity using the Luma homepage for the activity URL

   

3. Modify the page, for example change the text on the homepage banner

   

4. Choose Adobe Analytics as the reporting source with the appropriate report suite and the Orders metric as the goal

   NOTE

   If you do not use Adobe Analytics then select Target as the reporting source and choose a different metric like Engagement > Page Views instead. A goal metric is required to save and preview the activity.

5. Save the activity

6. If you are comfortable with your changes, then you can activate your activity. Otherwise, if you would like to preview the experience without activating you can copy the QA Preview URL.

7. Load the Luma homepage and you should see your changes applied

8. After a few hours, you should be able to see Target activity data and conversions in Adobe Analytics. Refer to the Target Guide for detailed information about Analytics for Target (A4T) reporting.

Validate with the Debugger

If you set up an activity, you should see your content render on the page. However even if no activities are live, you can also look at the Send Event network call to confirm that Target is configured properly.

1. Open the Adobe Experience Platform debugger browser extension

2. Go to the Luma demo site and use the debugger to switch the tag property on the site to your own development property

3. Reload the page

4. Select the Network tool in the debugger

5. Filter by Adobe Experience Platform Web SDK

6. Select the value in events row for the first call

   

7. Notice that there are keys under query > personalization and decisionScopes has a value of __view__. This scope is the equivalent to Target’s “global mbox”. This Platform Web SDK call requested decisions from Target.

   

8. Close the overlay and select the event details for the second network call. This call is only present if Target returned an activity.

9. Notice that there are details about the activity and experience returned from Target. This Platform Web SDK call sends a notification that a Target activity was rendered to the user and increments an impression.

   

Set up and render a custom decision scope

Custom decision scopes (formerly known as “mboxes”) can be used to deliver HTML or JSON content in a structured fashion using the Target Form-based Experience Composer. Content delivered to one of these custom scopes is not rendered automatically by the Platform Web SDK.

Add a scope to the page load rule

Modify your page load rule to add a custom decision scope:

1. Open the all pages - library load - AA & AT rule

2. Select the Adobe Experience Platform Web SDK - Send Event action

3. Add one or more scopes you would like to use. For this example, use homepage-hero.

   

4. Save your changes and build to your library

Process the response from Target

Now that you have configured the Platform Web SDK to request content for the homepage-hero scope, you must do something with the response. The Platform Web SDK tag extension provides a Send Event Complete event which can be used to immediately trigger a new rule when a response from a Send Event action is received.

1. Create a rule called homepage - send event complete - render homepage-hero.

2. Add an event to the rule. Use the Adobe Experience Platform Web SDK extension and the Send event complete event type.

3. Add a condition to restrict the rule to the Luma homepage (path without query string equals /content/luma/us/en.html).

4. Add an action to the rule. Use the Core extension and Custom Code action type.

   

   TIP

   Give your rule events, conditions, and actions descriptive names instead of using the default names. Robust rule component names make the search results much more useful.

5. Enter custom code to read and action on the propositions returned from the Platform Web SDK response. The custom code in this example uses the approach outlined in the guide for manually rendering personalized content. The code was adapted for the homepage-hero example scope using a tag rule action.

   var propositions = event.propositions;
   
   var heroProposition;
   if (propositions) {
      // Find the hero proposition, if it exists.
      for (var i = 0; i < propositions.length; i++) {
         var proposition = propositions[i];
         if (proposition.scope === "homepage-hero") {
            heroProposition = proposition;
            break;
         }
      }
   }
   
   var heroHtml;
   if (heroProposition) {
      // Find the item from proposition that should be rendered.
      // Rather than assuming there a single item that has HTML
      // content, find the first item whose schema indicates
      // it contains HTML content.
      for (var j = 0; j < heroProposition.items.length; j++) {
         var heroPropositionItem = heroProposition.items[j];
         if (heroPropositionItem.schema === "https://ns.adobe.com/personalization/html-content-item") {
            heroHtml = heroPropositionItem.data.content;
            break;
         }
      }
   }
   
   if (heroHtml) {
      // Hero HTML exists. Time to render it.
      var heroElement = document.querySelector(".heroimage");
      heroElement.innerHTML = heroHtml;
      // For this example, we assume there is only a signle place to update in the HTML.
   }
   
   // Send a "display" event
   alloy("sendEvent", {
      xdm: {
         eventType: "propositionDisplay",
         _experience: {
            decisioning: {
               propositions: [
                  {
                     id: heroProposition.id,
                     scope: heroProposition.scope,
                     scopeDetails: heroProposition.scopeDetails
                  }
               ]
            }
         }
      }
   });
   

6. Save your changes and build to your library

7. Load the Luma homepage a few times, which should be enough to make the new homepage-hero decision scope register in the Target interface.

Set up a Target activity with the Form-based Experience Composer

Now that you have a rule to manually render a custom decision scope, you can create another Experience Targeting (XT) activity in Target. This time use the Form-Based Experience Composer.

1. Open Adobe Target

2. Deactivate the activity used for the previous lesson

3. Create an Experience Targeting (XT) activity using the Form-based Experience Composer option

   

4. Select the homepage-hero location from the location dropdown and Create HTML Offer from the content dropdown. If the location is not available, you can type it in. Target periodically populates new location names after receiving requests for that location or scope.

   

5. Paste the following code in the content box. This code is a basic hero banner with a different background image:

   <div class="we-HeroImage jumbotron" style="background-image: url('/content/luma/us/en/women/_jcr_content/root/hero_image.coreimg.jpeg');">
      <div class="container cq-dd-image">
         <div class="we-HeroImage-wrapper">
            <p class="h3">New Luma Yoga Collection</p>
            <strong class="we-HeroImage-title h1">Be active with style&nbsp;</strong>
            <p>
               <a class="btn btn-primary btn-action" href="/content/luma/us/en/products.html" role="button">Shop Now</a>
            </p>
         </div>
      </div>
   </div>
   

6. On the Goals & Settings step, choose Adobe Target as the reporting source and Engagement > Page Views as the goal

7. Save the activity

8. If you are comfortable with your changes, then you can activate your activity. Otherwise, if you would like to preview the experience without activating you can copy the QA Preview URL.

9. Load the Luma homepage and you should see your changes applied

Validate with the Debugger

If you activated your activity, you should see your content render on the page. However even if no activities are live, you can also look at the Send Event network call to confirm that Target is requesting content for your custom scopes.

1. Open the Adobe Experience Platform debugger browser extension

2. Go to the Luma demo site and use the debugger to switch the tag property on the site to your own development property

3. Reload the page

4. Select the Network tool in the debugger

5. Filter by Adobe Experience Platform Web SDK

6. Select the value in events row for the first call

   

7. Notice that there are keys under query > personalization and decisionScopes has a value of __view__ like before, but now there is also a homepage-hero scope included. This Platform Web SDK call requested decisions from Target for changes made using the VEC and the specific homepage-hero location.

   

8. Close the overlay and select the event details for the second network call. This call is only present if Target returned an activity.

9. Notice that there are details about the activity and experience returned from Target. This Platform Web SDK call sends a notification that a Target activity was rendered to the user and increments an impression.

   

Pass additional data to Target

In this section, you will pass Target-specific data and take a closer look at how XDM data is mapped to Target parameters.

There are some data points that may be useful to Target that are not mapped from the XDM object. These special Target parameters include:

• Profile attributes
• Recommendations entity attributes
• Recommendations reserved parameters
• Category values for category affinity

Create data elements for Target parameters

First you will set up a few extra data elements for a profile attribute, entity attribute, category value and then construct the data object which is used to pass non-XDM data:

• target.entity.id mapped to digitalData.product.0.productInfo.sku

• target.entity.name mapped to digitalData.product.0.productInfo.title

• target.user.categoryId using the following custom code to parse the site URL for the top-level category:

  var cat = location.pathname.split(/[/.]+/);
  if (cat[5] == 'products') {
     return (cat[6]);
  } else if (cat[5] != 'html') {
     return (cat[5]);
  }
  

• data.content using the following custom code:

  var data = {
     __adobe: {
        target: {
           "entity.id": _satellite.getVar("target.entity.id"),
           "entity.name": _satellite.getVar("target.entity.name"),
           "profile.loggedIn": _satellite.getVar("user.profile.attributes.loggedIn"),
           "user.categoryId": _satellite.getVar("target.user.categoryId")
        }
     }
  }
  return data;
  

Update the page load rule

Passing additional data for Target outside of the XDM object requires updating any applicable rules. For this example, the only modification you must make is to include the new data.content data element to the generic page load rule and product page view rule.

1. Open the all pages - library load - AA & AT rule

2. Select the Adobe Experience Platform Web SDK - Send event action

3. Add the data.content data element to the Data field

   

4. Save your changes and build to your library

5. Repeat steps 1 through 4 for the product view - library load - AA rule

Validate with the debugger

Now that the rules are updated, you can validate if the data is being passed correctly using the Adobe Debugger.

1. Navigate to the Luma demo site and login with the email test@adobe.com and password test

2. Navigate to a product details page

3. Open the Adobe Experience Platform debugger browser extension and switch the tag property to your own development property

4. Reload the page

5. Select the Network tool in the Debugger and filter by Adobe Experience Platform Web SDK

6. Select the value in events row for the first call

7. Notice that there are keys under data > __adobe > target and they are populated with information about the product, category, and login state.

   

Validate in the Target interface

Next, look in the Target interface to confirm that data was received and is available to use in audiences and activities. XDM data is automatically mapped to custom Target parameters. You can validate that XDM data was received by Target and is available by creating an audience.

1. Open Adobe Target
2. Navigate to the Audiences section
3. Create an audience and choose the Custom attribute type
4. Search the Parameter field for web. The dropdown menu should populate with all the XDM fields related to the web page details.

Next, validate that the login state profile attribute was successfully passed.

1. Choose the Visitor Profile attribute type
2. Search for loggedIn. If the attribute is available in the dropdown menu then the attribute was passed correctly to Target. New attributes may take several minutes to become available in the Target UI.

If you have Target Premium, you can also validate that the entity data was passed correctly and the product data was written to the Recommendations product catalog.

1. Navigate to the Recommendations section
2. Select Catalog Search in the left side navigation
3. Search for the product SKU or product name you visited earlier on the Luma site. The product should show up in the product catalog. New products may take several minutes to become searchable in the Recommendations product catalog.

Now that you have completed this lesson you should have a working implementation of Adobe Target using the Platform Web SDK.

Next: Implement Consent for Experience Platform Web SDK

Business.Adobe.com resources