Implementation best practices for Single Page Applications (SPAs)

Last update: 2023-03-27
  • Created for:
  • Intermediate
    Developer

Learn some best practices for implementing Adobe Analytics on Single Page Applications (SPAs). This includes using Experience Platform Tags, the recommended implementation method.

INITIAL NOTES:

  • The content below references the use of Experience Platform Tags to implement Adobe Analytics on your site. These considerations apply if Experience Platform Tags is not used, therefore, you must adapt them to your implementation method.
  • There are differences in SPAs, therefore, you should adjust your approach accordingly to best meet your needs.

Simple diagram of working with SPAs in Experience Platform Tags

SPA for analytics in tags

NOTE: This is a simplified diagram of how SPA pages are handled in an Adobe Analytics implementation using Experience Platform Tags. The following sections identify steps and issues to consider.

Set the data layer

When new content is loaded or when an action occurs on a SPA page, update the data layer first. This must happen before a custom event that triggers a rule executes in Experience Platform Tags. This ensures that the correct values from the data layer are pushed into Tags and then Adobe Analytics.

The following is a sample data layer. Any of these elements may change based on the initial view or subsequent change of the view given an action taken on your SPA page. For example, on a full or majority view change, it is a common requirement to pass in a unique “pageName” value to differentiate between the views in Adobe Analytics reporting.

<script>
    digitalData = {
        pageInstanceID: "Launch Demo Site",
        page:{
            pageInfo:{
                pageID: '2745374',
                pageName: 'acs demo - product listing page'
            },
            attributes:{
                project: "Experience Platform Launch Project"
            }
        },
        user : [ {
          "profile" : [ {
            "attributes" : {
              "gender" : "male",
              "age" : "35"
            }
          } ]
        }],
        libraries : {
          adobe : {
            launch : {
              state : 0, // 0 = not loaded , 1 = loaded
              domain : "assets.adobedtm.com"
            }
          }
        }

     };
    </script>

Set custom events and listen for these events in Experience Platform Tags

When new content loads or when an action occurs on the SPA page, Experience Platform Tags needs to be informed to run a rule that sends data to Analytics. There are a couple approaches for this: Direct Call rules or Custom Events.

  • Direct Call rules: Set up a direct call rule that executes when it is called directly from the page. If the page load or action is simple or unique and can execute a specific set of instructions every time (for example, set eVar4 to X and trigger event2 every time), then this approach is suitable. Refer to Experience Platform Tags documentation for more details about creating direct call rules.
  • Custom Events: If you need to dynamically attach a payload with unique values for events that occur on SPA pages, use custom JavaScript events, and listen for them in Experience Platform Tags. Use the payload to set data elements and Analytics variables in Tags. This method is considered the best practice, as this need is typically prevalent for SPAs. Our examples below use the custom events method.

Examples: In this help document, there are links to sample SPA sites that implement Analytics and other Experience Cloud solutions. In these examples, the following custom events are used:

  • Event-view-start: Execute on the view start of the view/state that loads.
  • Event-view-end: Execute when a view/state change occurs and all SPA components on the page finish loading. This is the event that typically sends data to Adobe Analytics.
  • Event-action-trigger: Execute when any event occurs on the page except view/state load. Examples of this include a click event or a smaller content change without a view change.

Refer to the pages and docs referenced above for more information about how and when these events fire. You do not need to use the same event names in your implementation. The functional use case for the method used is essential to understand as the recommended best practice for each. The following video demonstrates a sample SPA page and sample code in Experience Platform Tags that listens for the custom events.

 Transcript

Everybody, in this video we want to talk about a couple of best practices for using Adobe Analytics to track your spam pages. And this implementation that we’re going to use here is Launch by Adobe. So, we have here a demo site and we’ve got headphones, we’ve got this product page And if we were to switch over to a different product It’s likely that we would change a great deal of the view. Maybe not the navigation, but everything else. And so in that instance we want to be able to track this in our analytics program as a new page. And so, even though it’s SPA, we want to treat it like there is a new page loaded. And so we’re going to talk about how to do that And on the other hand there might be some small changes as well, You’ll see an Add To Cart button here. And if we click on that… It just changes the button and it adds it to cart. But it definitely doesn’t change the entire view. So we don’t want to treat that like a different page. So we want to be able to track those two different things. Now if we look at the source of this page, I just want to point out a couple of things here. And the best practice really for being able to track SPA pages is to create javascript custom events. In this case we have decided to call a custom event event-view-end And that will be triggered and will represent the end of a new view. So when that finishes loading it’ll trigger this event view and custom event. And that’s what we will use to send in our variables into Adobe analytics for the new page view. Now if we look down a little bit here we also have an event-action-trigger and this is the event we decided to name to use for tracking smaller interactions. So, for example clicking on the Add to Cart button. So those are two very different things. Right? The top one here is for a complete view change and it’s a I should say completed view change and the event-action-trigger is this for a smaller non-page view action on your site. So I just wanted you to remember those as we go into launch and look at how we’re going to trigger some rules to send data into analytics.

Here we have Launch by Adobe and I’ve opened up this spot demo property and clicked into the Rules here. So, we’ve created these rules. I just want to bring up a couple of them. First of all the page load: event-view-end So as this comes up, I mean this is just a name that we’ve given this Again, so that we know what is in it. And you’ll see that the event that actually then triggers this rule is right up here at the top. And when we click into that… and this is using our core extension in Launch It’s really our only choice here for this. And then the event type that we’re going to use is custom event. And there are many different kinds of triggers that we could use but we’re going to use the custom event as the trigger to let this rule happen and you’ll see here that we are then using a specific element We are using the event-view-end to trigger this rule. Again this is the end of the view change Cancel that. and we’ll talk about what we actually then do later on. But I just really in this video wanted to show you that this is how we are actually going to kick off a page view rule is by using the customer event at the end of that view change now Now, before I let you go here I’m gonna look at one more and that is this event: global link click Again, that’s a name we’ve given that but is for a smaller interaction with the page and you can see here in our events that actually kick that off. We got a couple of them but if I click into one… It’s the same kind of thing Core extension custom event and we name our customer event which in this case was event-action-trigger and that is trigger and actually on an element here and then add an element here he other one is triggering on a different element. But the point is that we are using this custom event to be able to trigger this rule that in this case will not send in a new page view but we’ll send in smaller pieces of data. I guess you could say a smaller pieces of data send in different variables in order to save some data into our analytics reports. -

Execute s.t() or s.tl() in the Experience Platform Tags

An important concept to understand for Analytics when working with a SPA is the difference between s.t() and s.tl(). Your code triggers one or the other of these methods in Experience Platform Tags to send data into Analytics.

  • s.t() - The “t” stands for “track”, and this represents a page view. If the view changes enough that you consider it a new “page”, use this call. Set a unique value to the s.pageName variable and use s.t() to send the data into Analytics.

  • s.tl() - The “tl” stands for “track link”, and this represents a link click or small content change. If the view change is minimal, use s.tl() to pass in a unique value about the interaction to Analytics. This variable passed in is not s.pageName, as this is ignored in Analytics when s.tl() calls are received.

TIP: As a general guideline, if the screen changes by more than 50%, use the s.t() page view call. Otherwise, use s.tl(). However, use your judgment when considering actions that constitute a new “page” and how that should be presented in Adobe Analytics reports.

The following video shows where and how to trigger s.t() or s.tl() in Tags.

 Transcript

In this short video I just want to connect some dots for you. Here we are in Launch by Adobe and I’ve opened up the SPA demo property and we’re in the Rules section and I want to go down here to the page load: event-view-end rule. In this rule, we have an event which is the core custom event of event-view-end So when a new view completes loading on your page, this is gonna kick off because we have coded that in there at the end of the view. So that event-view-end triggers this rule. That’s one dot to connect.

Cancel out.

Now let’s take a look at what actually happens when we kick off this rule. You’ll see done here in the actions that the first thing we’re gonna do is set some variables and then we’re gonna send a beacon. Then we’re gonna clear some variables. I wanna talk about clearing variables in another video but I want to talk about these first two. So let’s click into Set variables.

And we’ll just scroll down here… And we’ll see the only thing is really being said here is a page name. We’re using a data element a Page name data element to dynamically populate the page name and send that into analytics. I’m not going to go over data elements in this video that’s a topic for a Launch video on another day. But in any case we are going to dynamically pick up the page name from the from the data layer on the page and send it in. So that’s the first thing: the setting of the variables.

Now that we’ve got the variables set, we want to send the beacons. So I click on that and we’ll see that we really have two choices here: an s.t or s.tl And this is really the crux of the matter here. This is where the rubber hits the road or any other analogy I can think of. But you have to decide whether your rule is going to send an s.t which as you can see here sends data into analytics and treats it as a page view, a full page view. Or an s.tl which sends data into analytics and does not treat it as a page view, typically used for smaller actions or changes on our site. But in this case since it’s the end of the loading of a bunch of stuff on your page, we do want to treat it like a page view. And so we’re going to connect it to that s.t and that’s the other dot we’re connecting here. So, we are going to send that in, treat it as a page view and send in that page name.

So I cancel out of this rule.

Let’s take a look at another one.

Right here we have the event Global Link click and as I click into the custom event here. We have the custom event called event-action-trigger. And that was coded on our page for smaller events, smaller actions or smaller pieces of content that might load that we don’t want to treat like a whole page view. So we triggered this event and therefore this rule kicks off.

So what happens when this rule kicks off? Well down here again we’re going to set some variables. We’re going to send a beacon and then we’ll clear the variables. So let’s look at the variables being set and in this case we are not changing the page name because it’s not the whole page. So in this case we’re just going to take the link name dynamically and push it into eVar1. And then that’s gonna go in on the next step when we send the beacon. And you can see here that you can send any number of eVars or props or events or whatever you want to do with any of these rules. But in this case we’re just going to track the length that they clicked on and put it into eVar1 and that’s all that happens in this step.

Then, the crucial step of sending the beacon. In this case since we’re not doing a whole page load, We are gonna use s.tl. So it does not treat it as a page view. We already saw that we’re going to set eVar1 and then we’re going to send this in and we’re going to populate the custom link name as Global Link click. And that’s just going to go into the custom link report. Also the link name will go into the eVar1 report as we saw. And that’s it. And so that’s really how these things tie together. We have these custom events on our page. They’re coded in for when things happen, whether it’s a full page load or whether it’s just a smaller link click. And then we decide to hook that to a rule that uses either an s.t for the larger page loads or an s.tl for a non-page load for a smaller action on our site.

Clear Variables

Send the right data into Analytics at the right time. In a SPA environment, a value stored in an Analytics variable persists and resends into Analytics, potentially when you no longer want it. A function exists in the Analytics Tags extension to clear the variables to ensure that the next call doesn’t errantly send data into Analytics.

The diagram above shows variables cleared after you send in data. In reality, this can happen before OR after the call, however, be consistent in your Experience Platform Tags rules for a cleaner implementation. If you clear variables before you execute s.t(), set the new variables immediately after the call and then proceed to send the new data into Analytics.

NOTE: Clearing variables is not always needed when running s.tl(). This call requires the use of the linkTrackVars variable to instruct Analytics which variables to set. This happens automatically Experience Platform Tags through configuration. It prevents errant variables from setting in contrast to the behavior with s.t() calls in a SPA environment. To ensure the cleanest and most reliable implementation, it is likely easier to use the clear variables function for both calls in a SPA environment.

The following video shows where and how to clear variables in Tags.

 Transcript

In this video we’re gonna talk about clearing variables when you’re sending data from your SPA page into Adobe analytics using Launch by Adobe. Here we are in Launch and I have opened up the SPA demo property and I went into the Rules section and have opened the rule page load: event-view-end. And so this rule kicks off when a view has changed at the end of the load of the information on a view change. This rule kicks off. If we look down at what happens here when this rule executes… We can see that we set some variables and then we send in a beacon and then we clear the variables. I’m gonna click into that.

And this is very simple or very basic. And it is just simply using the Adobe Analytics extension and then choosing Clear Variables. And we do this so that we don’t have any lingering variables that get sent in on subsequent hits. So very important. I’m going to cancel out of that… And that’s really the whole thing. I just want to mention one more thing and that is that you can actually do this before you set the variables, or like we have in this one, after. If you set it after, then of course you’re gonna set the variables, send them in and clear the variables and you’re ready for the next time. However, you can imagine it would be fine if those variables are sitting around and we clear them before we reset them and send them in. So you can actually have the clearing of the variables first. But, one important thing: you’re probably going to want to be very consistent across your site as you do that. So either it’ll have the clearing of the variables always at the end or have it always at the beginning. And I do recommend that you do clear these variables again so that you don’t get any extraneous data going in on subsequent hits.

Additional considerations

Custom Code windows in Experience Platform Tags

In the Tags Analytics extension, there are two places where custom code may be inserted: The “library management” and “Configure tracker using custom code” sections.

Tags Analytics custom code windows

Either one of these locations runs the code contained therein once for the initial page load your SPA page. If the code should run on a view or action change, implement that code in the appropriate rule (for example, the “page load: event-view-end” rule), to ensure that the code executes every time the rule runs. When creating thet action in the rule, set Extension = Core and Action Type = Custom Code.

“Hybrid” SPA and traditional sites

Some sites are comprised of a combination of traditional and SPA pages. In this instance, use a strategy that works for both page types. When configuring your custom events on the site and triggering rules in Experience Platform Tags, ensure that double hits aren’t sent into Analytics based on hash changes, and so on. In this case, suppress one of the page views to prevent duplicate data passed into Adobe Analytics.

If you decide to separate the functionality into unique rules for more control, remember to document that you have done this. If you change one rule, make the same change to the other rule.

Integration with Target using A4T

When integrating with Target using A4T, confirm that the Target and Analytics requests sent in on the same view or action pass the same SDID parameter value. This ensures that your data properly synchronizes in the backend.

To view these hits, use a debugger or packet monitoring tool. Adobe provides an Experience Platform Debugger for this purpose. It’s a Chrome extension that can be downloaded here. Target should execute first on the page. This can be verified in the debugger, as well.

Additional resources

Previous page
Next page

On this page