Community Advisor

Web SDK Part 4: Avoiding Banana Peels (and other things that can trip you up!)

Forum|Forum|1 year ago
February 16, 2024
25 replies
12675 views

Going back to what I said in my first post of this series, I'm a big fan of Web SDK but 'the elephant in the room' is that Web SDK was not primarily designed for Adobe Analytics. This means there are a few unexpected things that can cause you to slip up. I'm here to help you avoid those banana peels!

This article is going to cover six potential issues relating to:

Automated Click Data Collection
using Adobe Target with Adobe Analytics
Market Channels on Single Page Application (SPA) Websites

Automated Click Data Collection

As an Adobe Analytics expert you are probably used to your Adobe Analytics implementation automatically tracking Exit Links and Download Links. Within the Web SDK Extension you can enable 'Click Data Collection' and on first glance this appears to be the same capability. It is true that 'Click Data Collection' provides automatic Exit Link and Download Link tracking. However, there are some big differences that you need to be aware of!

Banana Peel #1: Click Data Collection fires all the time?!

Yes, you heard me correctly; it doesn't just track Exit Links and Download Links, it actually tracks every single time any link is clicked. So, unless you want to receive a large invoice from Adobe for all those additional server calls, you are going to need to do something about this!

Solution

Fortunately, it is easy to supress these additional calls. Within the configuration of the Web SDK Extension, Adobe provides a callback function that only executes when the automated Click Data Collection fires (If you are doing this in code see onBeforeLinkClickSend).

Returning false in this callback function stops the Web SDK sending the data.

Therefore, to supress the additional calls, we can include a small snippet of code in the callback function, that detects if it is an 'other' link tracking call (rather than the other possible values 'exit' or 'download') and if so, blocks the call by returning false. For example:

if (content.xdm.web.webInteraction.type === "other") {
  return false;
}

NOTE: The callback function only executes when the automated link tracking happens. Therefore, this will not stop any custom link tracking that you're doing (which is a good thing!).

Banana Peel #2: Exit and Download tracking doesn't capture the link URL

By default, Click Data Collection actually captures the text of the link, rather than the link URL. This means if you do nothing, your Download Links and Exit Links will start collecting different values to what you are used to. You may be happy to accept this change, but if you are not, there is a simple fix to revert the value back to the URL.

Solution

Adobe's recommended approach is to remove the value of the options.xdm.web.webInteraction.name property (which is where the text of the link is captured). If this property is undefined, Adobe falls back to using the link URL. Again, we can put code within the same callback function to achieve this. For example:

if (content.xdm.web.webInteraction.type === "download"||content.xdm.web.webInteraction.type === "exit") {
  content.xdm.web.webInteraction.name = undefined;
}

Banana Peel #3: Exit Links fires when moving between subdomains of your website

If the link domain does not have the exact same top-level domain and subdomain, Exit Link tracking fires. This means by default you might be tracking a lot of navigations that you consider internal to your site (e.g. shop.mysite.com to checkout.mysite.com).

Solution

Unfortunately, there is no 'out of the box' whitelist/blacklist for exit link tracking domains. However, again it is easy to use the same callback function to supress the unwanted Exit Link tracking. For example:

if (content.xdm.web.webInteraction.type === "exit"){  
  if (content.xdm.web.webInteraction.URL.includes("mysite.com")){
    return false;
}

This approach could also be extended to cover any other domains that you want to supress Exit Link tracking for.

Adobe Target (in combination with Web SDK and Adobe Analytics)

Using Adobe Target in combination with Web SDK and Adobe Analytics has many benefits. However, if you are using both Analytics and Target there are a couple things you need to be aware of...

Banana Peel #4: Migrating Adobe Analytics but not Adobe Target

To reduce the complexity of migrating to Web SDK, you may be tempted to phase your migration by moving Adobe Analytics over first and then moving Adobe Target over at a later date. If possible, you should avoid this because it will break the A4T (Analytics for Target) integration between the two capabilities.

Solution

If you want the A4T integration to continue working, you have to migrate both Adobe Analytics and Adobe Target to Web SDK at the same time.

Banana Peel #5: 'Send Events' just for Adobe Target

With your non-Web SDK implementation, you will be used to making calls to Adobe Target separately from Adobe Analytics. With Web SDK this is no longer possible; every time you call the Send Event, the hit will be forwarded by the Edge Network to Target and Analytics whether you like it or not! Therefore, problems occur if you only populate the XDM Object with Adobe Target in mind.

If you do this, Adobe Analytics will still receive the hit and may revert to some default behaviours which may not be desirable! The main two default behaviours you need to look out for are:

if you don't tell Adobe Analytics otherwise, it treats incoming hits as Page Views
if you don't give Adobe Analytics a pageName it records the URL of the page in the page name variable

For example, you might forget to fully populate the XDM Object when using Send Event to tell Target that:

a proposition has been displayed
a button has been clicked

In both these scenarios you would get the previously mentioned default behaviours in Adobe Analytics, inflating your Page Views and causing URLs to appear in the page name variable.

Solution

The issues described are easily avoided by making sure the XDM Object is always populated in a way that is valid for Adobe Analytics. For the above example, I would suggest populating the relevant properties in the web.webInteraction part of the XDM Object so that Adobe Analytics treats the hit as link tracking (see part 2 of this series for how to do this).

Banana Peel #6: Marketing Channels breaks on SPA websites

A Single Page Application (SPA) website is designed to improve load performance by not fully refreshing the browser when a user navigates between screens.

There is a key difference between how the old Adobe Analytics JavaScript and the new Web SDK JavaScript handles these SPA page loads (i.e. where the browser does not fully refresh).

This difference potentially will break your Marketing Channel Rules and can affect any rule that use Hit Attributes derived from the following variables:

URL
Query String Parameters
Referring URL

The old Analytics code only included these variables in the payload of the first page view made after a full reload. This meant that additional page views made as a result of SPA navigations (i.e. without a full refresh) did not have these variables included in the hit. Conversely, the Web SDK transmits these variables on every page view.

This could have big implications for any Marketing Channel Rules that reference any of these variables (or attributes derived from them). We found that our Marketing Channels were being corrupted as they were being overwritten when rules were being triggered when we hadn't expected.

Solution

This is a difficult one as I'm not sure I have a 'recommended' approach. Therefore, I will share with you what we have done, but caveat it by saying you need to work out what is best for your situation.

We couldn't find a satisfactory way of changing our Marketing Channel Rules to work with the new Web SDK behaviour. This led us to go down the route of manipulating the values in the XDM Object to replicate what was happening with the old Adobe Analytics JavaScript. To achieve this, we had to detect whether or not we were on the first page view following a full browser refresh, and then alter the XDM object appropriately. As a result, we were able to leave the Marketing Channel Rules as they were and get the same outcome.

Final Thoughts

A lot of the knowledge in this article was hard won (i.e. we made mistakes and had to learn from them!). Hopefully, I have saved you some of the pain and head-scratching that we had to go through.

And in that spirit, I think it would be fantastic if you've come across your own 'banana peels' while implementing Web SDK, if you share them in the comments!

As always, thanks for reading, and if you would like updates on when these posts go live please consider following me on LinkedIn.

Read other parts of this blog series:

Analytics

Show previous replies

bjoern__koth

Community Advisor and Adobe Champion

HI @franc_g
you can send data to multiple tools at the same time with alloy/WebSDK, but don't have to.

i.e., the target call should be going out as soon as the library loads, where the page view can be sent out when the rest of the data layer is present.

This has caused a lot of confusion on my end as well, leading to lots of trial an error in the first place, not exactly knowing which fields to set.

Luckily, the WebSDK's sendEvent has now something called "guided events" where you can specify if a request should only go to Target or Analytics.

Hope that helps,

Björn

Cheers from Switzerland!

Franc_G

Level 4

@bjoern__koth thanks for the suggestion. It is quite clear that analytics and AT events need to be separated, while the AT event needs to happen as soon as possible (ideally when the dataLayer is ready). In our case, we are using Ensighten TMS (and not the Adobe Launch), so will have to ty to implement the guided event via custom code somehow. By any chance you know how the "sendEvent" syntax would look like in case of the guided event set up ?

alloy("sendEvent", {});

I am assuming that something needs to be in the payload to indicate that this is a guided event.

bjoern__koth

Community Advisor and Adobe Champion

Hi @franc_g

that is a veeery good question 😄 I tested both the Target and Analytics guided event on a blank environment and deliberately left the XDM field empty (probably for Analytics you will need to set more in the Web section).

So, this is what the requests look like (I added a line of code in the "on before event send" section of the WebSDK).

Is it just me or is the only difference really the eventType? Am I missing something?

[UPDATE] since I deliberately omitted setting the XDM, these requests would've looked differently in the "web" section. See thread further down.

The guided events seem to only remove some fields from the XDM payload (potentially also other things), to reduce the risk of human error i.e., causing unwanted page view calls in analytics through a set page (web.webPageDetails.name).

Cheers

Cheers from Switzerland!

Franc_G

Level 4

@bjoern__koth it seems like sending the "eventType": "decisioning.propositionDisplay" is the only way out of it. Have found this post - Solved: Unintended extra pageviews using WebSDK - Adobe Experience League Community - 433317. However, it appears that Adobe has not fully addressed the issue.

Merging the AT and Analytics calls is not a viable option - unless we can "hide everything" for about 3 sec on each page load :))) 🙂

I have added the the stand alone event for the AT.

The problem with this approach is that it seems like the the "xdm.web.webPageDetails.name" is not being passed on. As result of that we have a limitation - we can't launch AT tests based on this mbox parameter. Which, in turn, is essential in case of SPAs (url doesn't change in those areas most of the time).

{
    "xdm": {
      "_experience": {
        "decisioning": {
          "propositions": [
            {
              "id": "AT:eyJhY3RpdlkITI4NCEifQ==",
              "scope": "__view__",
              "scopeDetails": {
                "decisionProvider": "TGT",
                "activity": { "id": "1101284" },
                "experience": { "id": "1" },
                "strategies": [{ "step": "conversion", "trafficType": "0" }],
                "characteristics": {
                  "eventToken": "7Wp3F4m0QljihYIOGM6eVg69G8N8iH9Rluw=="
                },
                "correlationID": "1101284:1:0"
              }
            }
          ],
          "propositionEventType": { "display": 1 }
        }
      },
      "eventType": "decisioning.propositionDisplay",
      "web": {
        "webPageDetails": {
          "URL": "https://sit.fid.co.uk"
        },
        "webReferrer": { "URL": "" }
      },
      "device": {
        "screenHeight": 1080,
        "screenWidth": 1920,
        "screenOrientation": "landscape"
      },
      "environment": {
        "type": "browser",
        "browserDetails": { "viewportWidth": 942, "viewportHeight": 956 }
      },
      "placeContext": {
        "localTimezoneOffset": -60,
        "localTime": "2024-05-14T10:52:38.683+01:00"
      },
      "timestamp": "2024-05-14T09:52:38.683Z",
      "implementationDetails": {
        "name": "https://ns.adobe.com/experience/alloy",
        "version": "2.14.0",
        "environment": "browser"
      }
    }
  }

bjoern__koth

Community Advisor and Adobe Champion

Hi @franc_g

yeah I was in that thread as well 😄

I guess the xdm.web.webPageDetails.name would indicate an Analytics request. I deliberately left the XDM empty in my example which I should've probably not.

The "guided events" seem to only remove some set fields to not trigger a page view event in Analytics.

Check this documentation out.

If you set the webPageDetails.name, it will internally send an analytics page view.

Think about it for a moment: in the old world with AppMeasurement, even though you were allowed to set a pageName on link tracking / s.tl(), the pageName resp., "Page" dimension would not show in a breakdown by that dimension (until today, I have not fully understood why this value would not be processed if I could see it in the context of a page view or a link click metric, but that is another story...)

So, basically the only allowed location to set a page name is when you want to track a page view event.

In other words, if you want to only send to Target, omit the page name altogether.

In the old Target world, you would've also not had the Analytics page name at hand.

If this is necessary, I would suggest checking out whether you cannot just set this value in the free-form data and setting an __adobe.target object with the page name there instead

Or (since this seems to be reserved for really target specific data like entities, just throw it into the data object on highest level)

alloy("sendEvent",{
  "xdm":{
    "eventType": "decisioning.propositionDisplay",
    // .....
  },
  // 
  "data":{
    "page": {
        "name": "my page name"
    },
    "__adobe": {
        "target": {
            // some more target-related fields, e.g. for recommendations, such as entity.brand
        }
    }
  }
});

Hope that helps

Cheers from Switzerland!

Franc_G

Level 4

@bjoern__koth I am back to square one - sending the pageName within data obj does not work. I have set an AT test based on the very specific audience - setting the pageName as an mbox parameter. So, the test is being triggered only if the pageName value is being passed to the AT. My analytics calls do not contain the "xdm.web.webPageDetails.name" (removed it on purpose). Based on this doc, it might be worth removing the "xdm.web.webPageDetails.URL" from analytics calls as well (we will have those with the

"eventType": "decisioning.propositionDisplay" calls). And, in theory, we should have a correct pageView count as well as AT parameters.

Now, the only question is does the data going to add up ? ie we have pageName (and URL) and the rest of the custom variables (eVars, props) in two separate calls...

j_goetze_5000

Level 2

Hi @andrew_wathen_ when will the user group session be up on the youtube channel? Im sorry to say I missed it!

Andrew_Wathen_

Author

Community Advisor

@j_goetze_5000 it went live today!🙂

Elephants and Banana Peels: Navigating the Web SDK Jungle! | Adobe Analytics User Group (youtube.com)

Pradeep-Jaiswal

Level 5

Awesome thanks for sharing your wisdom @andrew_wathen_

I have few follow up question for you and Franc_G bjoern_k samhollingshead jlinhardt_blueAcorn and others

I have check box enabled on 'enable click data collection' in webSDK extension to track download/exit link. when i clicked on exit or download link, I can see 'collect' call instead of 'interact' call in the network tab. and I dont find a way to differentiate between two collect call of exit link and download link.

1) Do I need to setup any configuration to specify content.xdm.web.webInteraction.type='download'

2) where does content object comes from, is it part of 'enable click data collection' checkbox ? In the collect call, I dont see any content object.

3) status code of content call is '204-no content'

however as per this link it should populate xdm object
https://experienceleague.adobe.com/en/docs/experience-platform/web-sdk/commands/configure/clickcollectionenabled
If the link matches criteria based on values in downloadLinkQualifier, or if the link contains a download HTML attribute, xdm.web.webInteraction.type is set to "download"

Pradeep-Jaiswal

Level 5

I just realized that it was an omnibug limitation that it doesnt show full information in the UI for the collect call, however in network tab I do see entire payload with xdm object.

My followup question is why does adobe creates this as collect call instead of interact call ? does it make any difference ?

Show more replies

Automated Click Data Collection

Banana Peel #1: Click Data Collection fires all the time?!

Solution

Banana Peel #2: Exit and Download tracking doesn't capture the link URL

Solution

Banana Peel #3: Exit Links fires when moving between subdomains of your website

Solution

Adobe Target (in combination with Web SDK and Adobe Analytics)

Banana Peel #4: Migrating Adobe Analytics but not Adobe Target

Solution

Banana Peel #5: 'Send Events' just for Adobe Target

Solution

Banana Peel #6: Marketing Channels breaks on SPA websites

Solution

Final Thoughts

Read other parts of this blog series:

Sign up

Login with SSO

Login to the community

Login with SSO

Scanning file for viruses.

This file cannot be downloaded