Upgrading from at.js 1.x to at.js 2.x

The newest version of at.js in Adobe Target provides rich feature sets that equip your business to execute personalization on next-generation, client-side technologies. This new version is focused on upgrading at.js to have harmonious interactions with single page applications (SPAs).

Here are some benefits of using at.js 2.x that are not available in previous versions:

• The ability to cache all offers on page-load to reduce multiple server calls to a single server call.
• Tremendously improve your end-users' experiences on your site because offers are shown immediately via the cache without any lag time that traditional server calls introduce.
• Simple one-line of code and one-time developer setup to enable your marketers to create and run A/B and XT activities via the VEC on your SPAs.

at.js 2.x system diagrams#

The following diagrams help you understand the workflow of at.js 2.x with Views and how this enhances the SPA integration. To get a better introduction of the concepts used in at.js 2.x, see Single Page Application implementation.

Now, wherever triggerView() is implemented on your SPA, the Views and actions are retrieved from cache and shown to the user without a server call. triggerView() also makes a notifications request to the Target backend in order to increment and record impression counts.

Deploy at.js 2.x#

Deploy at.js 2.x via tags in Adobe Experience Platform extension.

Or

Manually download at.js 2.x using the Target UI and deploy it using the method of your choice.

Deprecated at.js functions#

There are several functions that have been deprecated in at.js 2.x.

You can find the deprecated functions and their counterpart below. For a complete list of functions, see at.js functions.

mboxCreate(mbox,params)#

Description:

Executes a request and applies the offer to the closest DIV with the mboxDefault class name.

Example:

<div class="mboxDefault">
  default content to replace by offer
</div>
<script>
  mboxCreate('mboxName','param1=value1','param2=value2');
</script>
CopyCopied to your clipboard
1<div class="mboxDefault">
2  default content to replace by offer
3</div>
4<script>
5  mboxCreate('mboxName','param1=value1','param2=value2');
6</script>

at.js 2.x equivalent

An alternative to mboxCreate(mbox, params) is getOffer() and applyOffer().

Example:

<div class="mboxDefault"> 
  default content to replace by offer 
</div> 
<script> 
  var el = document.currentScript.previousElementSibling;
  adobe.target.getOffer({
    mbox: "mboxName",
    params: {
      param1: "value1",
      param2: "value2"
    },
    success: function(offer) {
      adobe.target.applyOffer({
        mbox: "mboxName",
        selector: el,
        offer: offer
      });
    },
    error: function(error) {
      console.error(error);
      el.style.visibility = "visible";
    }
  });
</script> 
CopyCopied to your clipboard
1<div class="mboxDefault"> 
2  default content to replace by offer 
3</div> 
4<script> 
5  var el = document.currentScript.previousElementSibling;
6  adobe.target.getOffer({
7    mbox: "mboxName",
8    params: {
9      param1: "value1",
10      param2: "value2"
11    },
12    success: function(offer) {
13      adobe.target.applyOffer({
14        mbox: "mboxName",
15        selector: el,
16        offer: offer
17      });
18    },
19    error: function(error) {
20      console.error(error);
21      el.style.visibility = "visible";
22    }
23  });
24</script> 

mboxDefine() and mboxUpdate()#

Description:

Creates an internal mapping between an element and an mbox name, but does not execute the request. Used in conjunction with mboxUpdate(), which executes the request and applies the offer to the element identified by the nodeId in mboxDefine(). Can also be used to update an mbox initiated by mboxCreate.

Example:

<div id="someId" class="mboxDefault"></div>
<script>
 mboxDefine('someId','mboxName','param1=value1','param2=value2');
 mboxUpdate('mboxName','param3=value3','param4=value4');
</script>
CopyCopied to your clipboard
1<div id="someId" class="mboxDefault"></div>
2<script>
3 mboxDefine('someId','mboxName','param1=value1','param2=value2');
4 mboxUpdate('mboxName','param3=value3','param4=value4');
5</script>

at.js 2.x equivalent:

An alternative to mboxDefine() and mboxUpdate is getOffer() and applyOffer(), with the selector option used in applyOffer(). This approach lets you map the offer to an element using any CSS selector, not just one with an ID.

Example:

<div id="someId" class="mboxDefault"> 
  default content to replace by offer 
</div> 
<script> 
  adobe.target.getOffer({
    mbox: "mboxName",
    params: {
      param1: "value1",
      param2: "value2",
      param3: "value3",
      param4: "value4" 
    },
    success: function(offer) {
      adobe.target.applyOffer({
        mbox: "mboxName",
        selector: "#someId",
        offer: offer
      });
    },
    error: function(error) {
      console.error(error);
      var el = document.getElementById("someId");
      el.style.visibility = "visible";
    }
  });
</script>
CopyCopied to your clipboard
1<div id="someId" class="mboxDefault"> 
2  default content to replace by offer 
3</div> 
4<script> 
5  adobe.target.getOffer({
6    mbox: "mboxName",
7    params: {
8      param1: "value1",
9      param2: "value2",
10      param3: "value3",
11      param4: "value4" 
12    },
13    success: function(offer) {
14      adobe.target.applyOffer({
15        mbox: "mboxName",
16        selector: "#someId",
17        offer: offer
18      });
19    },
20    error: function(error) {
21      console.error(error);
22      var el = document.getElementById("someId");
23      el.style.visibility = "visible";
24    }
25  });
26</script>

adobe.target.registerExtension()#

Description:

Provides a standard way to register a specific extension.

This is no longer supported and should not be used.

Summary of deprecated, new, and supported at.js functions in 2.x#

Limitations and callouts#

Be aware of the following limitations and callouts:

Conversion tracking#

Customers using mboxCreate() for conversion tracking must use trackEvent() or getOffer().

Offer delivery#

Customers who do not replace mboxCreate() with getOffer() or applyOffer() risk not having offers delivered.

Can at.js 2.x be used on some pages while at.js 1.x is on other pages?#

Yes, the visitor profile is preserved across pages using different versions and libraries. The cookie format is the same.

New API use in at.js 2.x#

at.js 2.x uses a new API, which we call the Delivery API. In order to debug whether at.js is calling the Target edge server correctly, you can filter the Network tab of your browser’s Developer Tools to “delivery”, “tt.omtrdc.net,” or your client code. You will also notice that Target sends a JSON payload instead of key-value pairs.

Target Global Mbox is no longer used#

In at.js 2.x, you no longer see “target-global-mbox” visibly in the network calls. Instead, we have replaced the “target-global-mbox” syntax to “execute > pageLoad” in the JSON payload sent to the Target servers, as seen below:

{
  "id": {
    // ...
  },
  "context": {
    "channel": "web",
    // ...
  },
  "execute": {
    "pageLoad": {}
  }
}
CopyCopied to your clipboard
1{
2  "id": {
3    // ...
4  },
5  "context": {
6    "channel": "web",
7    // ...
8  },
9  "execute": {
10    "pageLoad": {}
11  }
12}

Essentially the global mbox concept was introduced to let Target know whether to retrieve offers and content on page-load. Thus, we have made this more explicit in our newest version.

Does the global mbox name in at.js matter anymore?#

Customers are able to specify a global mbox name via Target > Administration > Implementation > Edit at.js Settings. This setting is used by the Target edge severs to translate execute > pageLoad to the global mbox name that appears in the Target UI. This allows customers to continue to use server-side APIs, the form-based composer, profile scripts, and create audiences using the global mbox name. We strongly recommend that you also make sure the same global mbox name is configured on the Administration > Visual Experience Composer page, as well, in case you still have pages using at.js 1.x, as shown in the following illustrations.

and

Does the auto-create global mbox setting need to be turned on for at.js 2.x?#

In most cases, yes. This setting tells at.js 2.x to fire a request to the Target edge servers upon page load. Because global mbox is translated to execute > pageLoad, and if you want to fire a request on page load, then this setting should be on.

Will existing VEC activities continue to work, even though the target global mbox name is not specified from at.js 2.x?#

Yes, because execute > pageLoad is treated on the Target backend like target-global-mbox.

If my form-based activities are targeted to the target-global-mbox, will those activities continue to work?#

Yes, because execute > pageLoad is treated on the Target edge servers like target-global-mbox.

Supported and non-supported at.js 2.x Settings#

Cross-domain tracking support in at.js 2.x#

Cross-domain tracking makes it possible to stitch visitors across different domains. Because a new cookie must be created for each domain, it is difficult to track visitors when they navigate from domain to domain. To accomplish cross-domain tracking, Target uses a third-party cookie to track visitors across domains. This allows you to create a Target activity that spans siteA.com and siteB.com and visitors remain in the same experience when they navigate across unique domains. This functionality ties into Target’s third-party and first-party cookie behavior.

In Target, the third-party cookie is stored in <CLIENTCODE>.tt.omtrdc.net. The first-party cookie is stored in clientdomain.com. The first request returns HTTP response headers that attempt to set third-party cookies named mboxSession and mboxPC, whereas a redirect request is sent back with an extra parameter (mboxXDomainCheck=true). If the browser accepts third-party cookies, the redirect request includes those cookies, and the experience is returned. This workflow is possible because we use the HTTP GET method.

However, in at.js 2.x, HTTP GET is no longer used and instead we use HTTP POST. HTTP POST is now used via at.js 2.x to send JSON payloads to Target Edge servers. This means that the redirect request to check whether a browser supports third-party cookies now breaks. This is because HTTP GET requests are idempotent transactions, while HTTP POST is non-idempotent and must not be arbitrarily repeated. Therefore, cross-domain tracking in at.js 2.x is no longer supported out of the box. Only at.js 1.x has out-of-the-box support for cross-domain tracking.

If you want to use cross-domain tracking, you must install the ECID library v4.3.0+ in conjunction with at.js 2.x. The ECID library exists to manage persistent IDs that are used to identify a visitor even across domains.

Auto Create Global Mbox is supported#

This setting tells at.js 2.x to fire a request to the Target edge servers on page-load. Because the global mbox is translated to execute > pageLoad, and this is interpreted by the Target edge servers, customers should turn this on if they want to fire a request on page-load.

Global Mbox Name is supported#

Customers are able to specify a global mbox name via Target > Administration > Implementation > Edit. This setting is used by the Target edge severs to translate execute > pageLoad to the inputted global mbox name. This allows for customers to continue to use server-side APIs, the form-based composer, profile scripts, and create audiences that target the global mbox.

Are the below at.js custom events applicable to triggerView() or is it only for applyOffer() or applyOffers()?#

• adobe.target.event.CONTENT_RENDERING_FAILED
• adobe.target.event.CONTENT_RENDERING_SUCCEEDED
• adobe.target.event.CONTENT_RENDERING_NO_OFFERS
• adobe.target.event.CONTENT_RENDERING_REDIRECT

Yes the at.js custom events are applicable to triggerView() as well.

It says when I call triggerView() with {“page” : “true”}, it will send a notification to the Target backend and increase the impression. Does it also cause the profile scripts to execute?#

When a prefetch call is made to the Target backend, the profile scripts are executed. Thereafter, the impacted profile data will then be encrypted and passed back to the client side. After triggerView() with {"page": "true"} is invoked, a notification is sent along with the encrypted profile data. This is when the Target backend will then decrypt the profile data and store into the databases.

Do we need to add pre-hiding code before calling triggerView() in order to manage flicker?#

No, you do not need to add pre-hiding code before calling triggerView(). at.js 2.x manages the pre-hiding and flicker logic before the view is displayed and applied.

Which at.js 1.x parameters for creating audiences are not supported in at.js 2.x?#

The following at.js 1.x parameters are NOT currently supported for audience creation when using at.js 2.x:

• browserHeight
• browserWidth
• browserTimeOffset
• screenHeight
• screenWidth
• screenOrientation
• colorDepth
• devicePixelRatio
• vst.* parameters (see below)

at.js 2.x does not support creating audiences using vst.* parameters#

Customers on at.js 1.x were able to use vst. mbox parameters to create audiences. This was an unintended side-effect of how at.js 1.x sent mbox parameters to the Target back-end. After migrating to at.js 2.x, you can no longer create audiences using these parameters because at.js 2.x* sends mbox parameters differently.

at.js compatibility#

The following tables explain at.js. 2.x compatibility with different activity types, integrations, features, and at.js functions.

Activity types#

Integrations#

Features#

Query string parameters#

Response tokens#

at.js 2.x, just like at.js 1.x, uses the custom event at-request-succeeded to surface response tokens. For code examples using the at-request-succeeded custom event, see Response tokens.

at.js 1.x parameters to at.js 2.x payload mapping#

This section outlines the mappings between at.js 1.x and at.js 2.x.

Before delving into parameters mapping, the endpoints that these library versions are using have changed:

• at.js 1.x - http://<client code>.tt.omtrdc.net/m2/<client code>/mbox/json
• at.js 2.x - http://<client code>.tt.omtrdc.net/rest/v1/delivery

Another significant difference is that:

• at.js 1.x - Client code is part of the path
• at.js 2.x - Client code is sent as a query string parameter, such as: http://<client code>.tt.omtrdc.net/rest/v1/delivery?client=democlient

The following sections list each at.js 1.x parameter, its description, and the corresponding 2.x JSON payload (if applicable):

at_property#

(at.js 1.x parameter)

Used for Enterprise User Permissions.

{
  ....
  "property": {
    "token": "1213213123122313121"
  }
  ....
}
CopyCopied to your clipboard
1{
2  ....
3  "property": {
4    "token": "1213213123122313121"
5  }
6  ....
7}

mboxHost#

(at.js 1.x parameter)

The domain of the page where the Target library runs.

at.js 2.x JSON payload:

{
  "context": {
    "browser": {
       "host": "test.com"
    }
  }
}
CopyCopied to your clipboard
1{
2  "context": {
3    "browser": {
4       "host": "test.com"
5    }
6  }
7}

webGLRenderer#

(at.js 1.x parameter)

The WEB GL renderer capabilities of the browser. This is used by our device detection mechanism to determine whether the visitor's device is a desktop, iPhone, Android device, etc.

at.js 2.x JSON payload:

{
  "context": {
    "browser": {
       "webGLRenderer": "AMD Radeon Pro 560X OpenGL Engine"
    }
  }
}
CopyCopied to your clipboard
1{
2  "context": {
3    "browser": {
4       "webGLRenderer": "AMD Radeon Pro 560X OpenGL Engine"
5    }
6  }
7}

mboxURL#

(at.js 1.x parameter)

The page URL.

at.js 2.x JSON payload:

{
  "context": {
    "address": {
       "url": "http://test.com"
    }
  }
}

CopyCopied to your clipboard
1{
2  "context": {
3    "address": {
4       "url": "http://test.com"
5    }
6  }
7}
8

mboxReferrer#

(at.js 1.x parameter)

The page referrer.

at.js 2.x JSON payload:

{
  "context": {
    "address": {
       "referringUrl": "http://google.com"
    }
  }
}
CopyCopied to your clipboard
1{
2  "context": {
3    "address": {
4       "referringUrl": "http://google.com"
5    }
6  }
7}

mbox (the name) equals to global mbox#

(at.js 1.x parameter)

Delivery API no longer has a global mbox concept. In the JSON payload you must use execute > pageLoad.

at.js 2.x JSON payload:

{
  "execute": {
    "pageLoad": {
       "parameters": ....
       "profileParameters": ...
       .....
    }
  }
}
CopyCopied to your clipboard
1{
2  "execute": {
3    "pageLoad": {
4       "parameters": ....
5       "profileParameters": ...
6       .....
7    }
8  }
9}

mbox (the name) is not equal to global mbox#

(at.js 1.x parameter)

To use an mbox name, pass it to execute > mboxes. An mbox requires an index and name.

at.js 2.x JSON payload:

{
  "execute": {
    "mboxes": [{
       "index": 0,
       "name": "some-mbox",
       "parameters": ....
       "profileParameters": ...
       .....
    }]
  }
}
CopyCopied to your clipboard
1{
2  "execute": {
3    "mboxes": [{
4       "index": 0,
5       "name": "some-mbox",
6       "parameters": ....
7       "profileParameters": ...
8       .....
9    }]
10  }
11}

mboxId#

(at.js 1.x parameter)

No longer used.

mboxCount#

(at.js 1.x parameter)

No longer used.

mboxRid#

(at.js 1.x parameter)

Request ID used by downstream systems to help with debugging.

at.js 2.x JSON payload:

{
  "requestId": "2412234442342"
  ....
}
CopyCopied to your clipboard
1{
2  "requestId": "2412234442342"
3  ....
4}

mboxTime#

(at.js 1.x parameter)

No longer used.

mboxSession#

(at.js 1.x parameter)

Session ID is sent as a query string parameter (sessionId) to the Delivery API endpoint.

mboxPC#

(at.js 1.x parameter)

The TNT ID is passed into id > tntId.

at.js 2.x JSON payload:

{
  "id": {
    "tntId": "ca5ddd7e33504c58b70d45d0368bcc70.21_3"
  }
  ....
}
CopyCopied to your clipboard
1{
2  "id": {
3    "tntId": "ca5ddd7e33504c58b70d45d0368bcc70.21_3"
4  }
5  ....
6}

mboxMCGVID#

(at.js 1.x parameter)

Marketing Cloud Visitor ID is passed into id > marketingCloudVisitorId.

at.js 2.x JSON payload:

{
  "id": {
    "marketingCloudVisitorId": "797110122341429343505"
  }
  ....
}
CopyCopied to your clipboard
1{
2  "id": {
3    "marketingCloudVisitorId": "797110122341429343505"
4  }
5  ....
6}

vst.aaaa.id and vst.aaaa.authState#

(at.js 1.x parameters)

Customer IDs should be passed into id > customerIds.

at.js 2.x JSON payload:

{
  "id": {
    "customerIds": [{
       "id": "1232131",
       "integrationCode": "aaaa",
       "authenticatedState": "....."
     }]
  }
  ....
}
CopyCopied to your clipboard
1{
2  "id": {
3    "customerIds": [{
4       "id": "1232131",
5       "integrationCode": "aaaa",
6       "authenticatedState": "....."
7     }]
8  }
9  ....
10}

mbox3rdPartyId#

(at.js 1.x parameter)

Customer third-party ID used to link different Target IDs.

at.js 2.x JSON payload:

{
  "id": {
    "thirdPartyId": "1232312323123"
  }
  ....
}
CopyCopied to your clipboard
1{
2  "id": {
3    "thirdPartyId": "1232312323123"
4  }
5  ....
6}

mboxMCSDID#

(at.js 1.x parameter)

SDID, also known as Supplemental Data ID. Should be passed into experienceCloud > analytics > supplementalDataId.

at.js 2.x JSON payload:

{
  "experienceCloud": {
    "analytics": {
      "supplementalDataId": "1212321132123131"
    }
  }
  ....
}
CopyCopied to your clipboard
1{
2  "experienceCloud": {
3    "analytics": {
4      "supplementalDataId": "1212321132123131"
5    }
6  }
7  ....
8}

vst.trk#

(at.js 1.x parameter)

Analytics tracking server. Should be passed into experienceCloud > analytics > trackingServer.

at.js 2.x JSON payload:

{
  "experienceCloud": {
    "analytics": {
      "trackingServer": "analytics.test.com"
    }
  }
  ....
}
CopyCopied to your clipboard
1{
2  "experienceCloud": {
3    "analytics": {
4      "trackingServer": "analytics.test.com"
5    }
6  }
7  ....
8}

vst.trks#

(at.js 1.x parameter)

Analytics tracking server secure. Should be passed into experienceCloud > analytics > trackingServerSecure.

at.js 2.x JSON payload:

{
  "experienceCloud": {
    "analytics": {
      "trackingServerSecure": "secure-analytics.test.com"
    }
  }
  ....
}
CopyCopied to your clipboard
1{
2  "experienceCloud": {
3    "analytics": {
4      "trackingServerSecure": "secure-analytics.test.com"
5    }
6  }
7  ....
8}

mboxMCGLH#

(at.js 1.x parameter)

Audience Manager location hint. Should be passed into experienceCloud > audienceManager > locationHint.

at.js 2.x JSON payload:

{
  "experienceCloud": {
    "audienceManager": {
      "locationHint": 9
    }
  }
  ....
}
CopyCopied to your clipboard
1{
2  "experienceCloud": {
3    "audienceManager": {
4      "locationHint": 9
5    }
6  }
7  ....
8}

mboxAAMB#

(at.js 1.x parameter)

Audience Manager blob. Should be passed into experienceCloud > audienceManager > blob.

at.js 2.x JSON payload:

{
  "experienceCloud": {
    "audienceManager": {
      "blob": "2142342343242342"
    }
  }
  ....
}
CopyCopied to your clipboard
1{
2  "experienceCloud": {
3    "audienceManager": {
4      "blob": "2142342343242342"
5    }
6  }
7  ....
8}

mboxVersion#

(at.js 1.x parameter)

Version is sent as a query string parameter via the version parameter.

Training video: at.js 2.x architectural diagram #

at.js 2.x enhances Adobe Target's support for SPAs and integrates with other Experience Cloud solutions. This video explains how everything comes together.

See Understanding how at.js 2.x works for more information.