Learning the potential of direct call rules within Adobe DTM (Dynamic Tag Management)

Share this article

Are you working within Adobe Dynamic Tag Management (DTM) and having difficulty finding a browser-based event that you can reliably use to trigger a call to your analytics platform?

Or are you encountering timing issues, where the data you’re looking to capture is not readily available on page load, and you don’t want to be making multiple server calls to capture that data when it becomes available?

Perhaps you’ve mastered page load and event-based rules, and are wondering what else you can use?

Enter direct call rules.

When I started with Adobe DTM, I understood direct call rules to be a measure of last resort, only to be used when everything else had failed. The level of documentation across them also seemed to support this theory, so I stayed away, happily working with my page load and event-based rules.

That was until I encountered a succession of DTM implementation issues where I had content loading after the page had finished loading, and my trusty ‘enters viewport’ event was being confused by the way an application process was transitioning between steps.

After an enlightening conversation with Rudi Shumpert, DTM’s product evangelist, I started to understand the potential of direct call rules, and how I could use them to resolve my implementation issues.

What are direct call rules?

As you likely know by now, Adobe DTM is a conditional rule-driven system that you can use to run your Adobe, Google and other 3rd party tools. There are three types of rules – page load, event-based and direct call.

As the name suggests, page load rules run on page load, while event-based rules look for a specific browser event, such as a click, form field interaction or a content item becoming visible, to occur. The key here is that these rules are waiting for something to occur, and it’s here that direct call rules are different.

Instead of relying on a page load or specific event occurring in the browser, direct call rules wait to be told exactly when to run – this can be done by the developer within the page code, or by tapping into a framework or API being used by the site you’re tagging up.

Creating a direct call rule.

When you create a direct call rule and open up the conditions section, you’ll notice immediately that unlike page load and event-based rules, there are no entry conditions, only a single text box;

direct call rule in adobe dtm - conditions

This is a free-text box, and what you specify within this box is the key to triggering direct call rules via the _satellite.track() method. To trigger the above example, you would run the following line of javascript, after which the rule would fire immediately – note that the string value is case sensitive, and that quotes need to be used within the brackets;

_satellite.track(‘trackInternalSearch’);

Each time you fire the above line of javascript the rule will run, making it easy to test the rule directly via your browser console.

After the conditions, direct call rules follow the same format of page load and event-based rules, allowing you to specify whether you want to trigger an s.t() or s.tl(), as well as your props, eVars and events.

So how and when do you use direct call rules?

The immediate execution of the rule and lack of additional conditions can be a double-edged sword, precise in its timing but with no backup or supporting conditions that need to be fulfilled before sending data off to Adobe. Therefore, you need to be clear when planning out your implementation about which rules you’re going to use. Every implementation is different, and you will likely need a blend of rule types to accurately capture the data that you want.

Remember that each page load containing DTM tags will automatically fire a request to Adobe. If all of your data is available on page load you can avoid sending multiple requests to Adobe by using a specific page load rule to capture particular data. If you try to run a direct call rule across every page as an s.t(), this will trigger a second call to Adobe after the page load, potentially doubling up on your metrics.

However, if you’re seeing the page load occur and the data you’re looking to capture is still being ajaxed in when the page finishes loading, or if you have a multi-step application for where the url does not change and you don’t have a reliable browser event to tell the difference between step 2 and step 3, then direct call rules suddenly become very attractive.

Once you become comfortable with direct call rules, you’ll see that you can use the 3rd party code box to ’stack’ your direct call rules, effectively firing one direct call rule from another direct call rule. This can be useful when you want to trigger multiple things/tools off the one rule, but want to separate them out without having multiple lines of code on your page. Under certain circumstances you can even use the conditions within page load and event-based rules to then fire off a direct call rule.

To give you some ideas for implementing across your own site, below are 3 examples where we have used direct call rules in an Adobe Analytics implementation.

Example 1: measuring multi-page application systems where the url does not change.

Where page load and event-based rules to measure progress through a multi-step process are not an option you can use a set of direct call rules – one for each step of the process – that run when each ’step’ has loaded. By doing this you’re moving away from looking for a specified browser event occurring to the website itself telling DTM when each step has been loaded.

Once your direct call rules are set up, implementation is as simple as your dev team running  _satellite.track(‘application-step-2’) when step 2 of your process has loaded,  _satellite.track(‘application-step-3’) when step 3 has loaded, and so on.

Note that I started at step 2, as step 1 of a multi-step process typiclly occurs as a page load. I’d trigger a page load rule to start the process, and then trigger direct call rules for all subsequent steps where the url does not change or page does not reload.

Just like page load and event based rules, you can set up relevant data elements that will be evaluated prior to your direct call rule firing.

By using a direct call rule for each step of the process where the url does not change, you allow your dev team to precisely time the measurement call to occur once the relevant process step has loaded.

Example 2: measuring in an angular environment using listener functionality.

In a recent implementation we found that when an internal search occurred, the javascript based internal search term had not yet been set on page load. This meant that instead of capturing the keyword, we were instead capturing {{keyword}}, which was not very useful. To get around this timing issue, we were able to make use of  a ‘listener’ function within the site’s underlying angular framework. This is broadly how it worked;

  1. We loaded the angular listener code on the search results page as a page load rule within the 3rd party code section, which started listening for the search keyword to change from {{keyword}}. In the Adobe Analytics section, within the same page load rule, we set s.abort=true, suppressing the automatic request to Adobe on each page load so we didn’t end up with multiple calls to Adobe.
  2. When the search term changed from {{keyword}} to an actual term, the listener code entered a loop that set the search term and search term count to local variables, shifting the variables from the underlying angular framework into something we can use within DTM.
  3. Once we had the search term and search term count variables, we double checked their values and then set them to data elements using the _satellite.setVar() method.
  4. When our data elements were set, we then triggered a direct call rule from within the page load rule, setting the data elements against the appropriate eVars & events.

By tapping into the angular listener functionality to trigger our direct call rule, we captured the actual keyword and number of results when they were ready as part of the ‘page load’ alongside the rest of the Adobe variables, and also ensured that we captured all subsequent internal searches where the page did not reload.

Below is a screenshot of our code, however I stress that this was for a specific framework and implementation, so please use it as a guide only;

Using angular code to fire a DTM direct call rule

Example 3: video milestone measurement using direct call rules.

Video milestone measurement within Adobe Analytics allow you to determine how well your audience is engaging with your videos by firing a server call with video information at set percentage complete (eg. 25%) or time based (eg. every 5 mins) markers. This typically involves some sort of integration with the player itself, which might require external assistance, and once in place may be difficult to make further changes.

However as the video measurement variables required by Adobe Analytics are all known, and most video players now have an API you can tap into that provides video title and total video time, it’s pretty straightforward to create a set of direct call rules that reflect the appropriate video start, 25%, 50%, 75% and 100% milestones;

direct call rule in adobe dtm - video milestone measurement

Each direct call rule sets the appropriate eVars, props and events, as well as anything else you’d like to pass through. In the example below I’m capturing the required variables for the 25% milestone (highlighted in yellow), as well as any additional variables available on page or from the player API (highlighted in green);

direct call rule in adobe dtm - video milestone evars

 

Once your direct call rules are set up, you can tap into the video player API to determine the total length of the video, divide that by 4 (for 25% based milestones), then watch and run _satellite.track(‘scIntVideo25Percent’) once 25% of the video time has elapsed,  _satellite.track(‘scIntVideo50Percent’) once 50% of the video time has elapsed, and so on.

By using direct call rules and separating out the video measurement from the video player, we retain complete control over what video data is captured, and when. To add in an additional 90% milestone, I would simply create a 90% rule and update my javascript to trigger this new rule at the 90% mark, all without making any changes to the player.

Give it a go yourself…

My initial understanding of direct call rules was that they were a mechanism of last resort, and in some cases the technology you’re working with forces this, however I would consider direct call rules an essential part of your implementation that may be used alongside your page load and event based rules. Ultimately every implementation is different, as are the teams you work with, and my hope with this post is that I’ve given you some ideas based on the challenges we’ve been able to resolve using direct call rules, and the confidence to give direct call rules a try yourself.


Share this article