Hybrid ECID

02 Jun 2019 » MSA , Server Side

As I explained in my EMEA Summit lab, you should not use the ECID server-side if you are in a web environment. The solution I proposed was to use a hybrid approach. This means that the ECID must still be generated client-side, and then used server-side.

If you have not read my previous posts, you may wonder why you need to have the ECID code client-side. Why not run everything server-side? Let me explain it again.

The first and most important reason is the demdex cookie. As it is a 3rd party cookie, only hosts under the .demdex.net domain can read or write it; all browsers will prevent any attempt to circumvent this restriction. Since the client-side code generates calls to dpm.demdex.net from the browser, these calls will take care of this cookie:

  • If it already exists, the browser will automatically add the cookie to the HTTP calls. Remember that the demdex cookie is per browser. One benefit is that, if you have multiple websites with multiple domains, the demdex cookie will be the glue between them and the ECID service will generate the same ID on all websites, allowing you to track the same visitor across multiple domains.
  • If it does not exist, dpm.demdex.net will include a Set-Cookie HTTP header in the response with a new demdex cookie, which will be correctly stored in the browser.

There are two additional reasons why you need this client-side code:

  • It will refresh the ECID and the demdex cookie for you, with the correct frequency.
  • It will generate ID syncs, needed by AAM.

You may still think that you do not need this client-side code, because you have only one website and you are not using AAM. Think twice:

  • What if your business expands and needs more domains?
  • What if, in the future, you acquire an AAM license?

In both case, you will need to move to this hybrid approach. However, it is not possible to regenerate the demdex cookies in the browsers for the reasons explained above. Therefore, you will lose all the ECIDs you have stored server side.

Client-side code

In the client, the code has to be exactly the same you would use if the whole implementation was client-side. In other words, nothing changes here. You can use your favourite tag manager, although I recommend you use Launch. If you need to put the code directly on the page, it will look something like (maybe with more parameters):

<script type="text/javascript" src="script/VisitorAPI.js"></script>
<script type="text/javascript">
  var visitor = Visitor.getInstance("<ORG ID>");
  visitor.getMarketingCloudVisitorID();
</script>

This code does 2 things:

  • Issues calls to dpm.demdex.net.
  • Creates the AMCV cookie under your domain, with the responses of the previous call and additional information. The key parameter in this cookie is the actual ECID.

The glue between the client-side and the server-side code is the AMCV cookie. Since it is a first party cookie, all calls to your servers will include it, as long as it exists. This works perfectly in our favour: it is generated client-side, but can be consumed server-side, without any extra code.

The cookie’s exact name is AMCV_<ORG ID>,where <ORG ID> is the parameter you passed in the call to Visitor.getInstance(),ending in @AdobeOrg. The cookie value is URL-encoded. Once decoded, it looks something like:

1687686476|MCAID|2BD7CBA1853089AC-6000030400077965|MCMID|46426443971032399172061976110716804930|MCAAMLH-1554852450|7|MCAAMB-1554852450|RKhpRz8krg2tLO6pguXWp5olkAcUniQYPHaMWWgdJ3xzPWQmdj0y|MCOPTOUT-1554254850s|NONE|MCSYNCSOP|411-17770|vVersion|3.0.0

As you can see, it is a pipe-separated list of parameters. For our purposes, we are interested in the parameters after:

  • MCMID. The actual ECID.
  • MCAAML-[0-9]*. The hint location from AAM.
  • MCAAMB-[0-9]*. The AAM blob.

Server-side code

I have explained the client-side code before the server-side, as I believe it makes the explanation simpler to understand. However, the order of execution is exactly the opposite. The server-side code will run first, it will generate the HTML, send it to the browser and, only then, the client-side code will run.

Initialising the ECID object

You will need to write your own server-side code to deal with the ECID, as there are no libraries available. In the sample website I created for the summit, you can see how I initialise the ECID object:

$ecid_available = FALSE;
$cookie_name = "AMCV_" . $config->getMarketingCloudConfig(Adobe\Config::MARKETINGCLOUD_ORG);
$ecid = new Adobe\ECID($config,$data_layer['user_agent'],$data_layer['ip_client']);
if (isset($_COOKIE[$cookie_name])) {
	$ecid->loadFromAMCVCookie($_COOKIE[$cookie_name]);
	$ecid_available = TRUE;
}

In case you are not familiar with code or PHP or you want the reasoning behind this code, this is what I did:

  1. I use a variable named $ecid_available to signal whether the ECID has been read from the AMCV cookie. It gets an initial value of FALSE,until the ECID can be fully initialised. As I explain above, during the first page of the first visit, this value will not change.
  2. I use another variable with the cookie name. Check above for the details on the name.
  3. I initialise an empty ECID object.
  4. If the server receives the AMCV cookie as part of the HTTP request, which will only happen from the 2nd page of the visitor onwards:
    • I populate the ECID object with the contents of the cookie.
    • I set $ecid_available = TRUE,to signal that the ECID object is fully initialised.

Please note that this is just an academic exercise and this code has this format only for clarity. It is quite verbose and, if you are a developers, you can (and probably should) optimise it. What is important is that, whatever code you generate, it has to take into account the fact that the AMCV cookie may not be present and, as a consequence, you will not be able to initialise the ECID object. In this case, any later code using it, like Analytics or Target, must deal with this situation. In future posts I will show you how I did it.

The key method in this sample code is Adobe\ECID::loadFromAMCVCookie(),which parses the AMCV cookie. You can find its implementation details in Adobe\ECID.php. It is as simple as iterating over all tokens in the cookie and, if there is a match for any parameter we are looking for, the next token is the value we want.

Non-web environments

To finalise with, the explanation in this post is just for web environments. In other words, the hybrid approach only makes sense when you have a browser as your client. Otherwise, you can run the ECID server-side: voice skills, IoT devices, mobile apps… In fact, in some cases, your only option is to run the ECID server-side.

 

Photo by Ben Sweet on Unsplash

Related Posts