Replace the at.js library with Platform Web SDK
Learn how to replace your on-page Adobe Target implementation to migrate from at.js to Platform Web SDK. A basic replacement consists of the following steps:
- Review your Target administration settings and make note of your IMS Organization ID
- Replace the at.js library with the Platform Web SDK
- Update the prehiding snippet for synchronous library implementations
- Configure the Platform Web SDK
Review Target administration settings
The first step to migrate Target to Platform Web SDK is to review your settings in the Target interface’s Administration section.
Implementation
Account details
- IMS Organization Id - Make note of this value since it is required to configure the Platform Web SDK.
- On-Device Decisioning - This feature is not supported by the Platform Web SDK. This setting can be disabled after you migrate and if no longer use at.js on any of your websites or have any server-side use cases for On-Device Decisioning.
Implementation methods
All editable settings in the Implementation methods section apply to at.js only. These settings are used to generate a customized at.js library for your implementation. Review these settings to check if you have any custom code or are setting 1st and 3rd party cookies for cross-domain use cases.
The Profile Lifetime setting can only be changed by Adobe Customer Care. The Target visitor profile lifetime is not impacted by your implementation approach. Both at.js and Platform Web SDK use the same visitor profile lifetime.
Privacy
- Obfuscate Visitor IP addresses - This setting impacts geotargeting capabilities. Both at.js and Platform Web SDK use the same backend IP obfuscation settings for the purposes of geotargeting.
Environments
The Platform Web SDK uses a datastream configuration which allows you to explicitly define an Environment ID for separate development, staging, and production datastreams. The main use case for this configuration is for mobile app implementations where URLs don’t exist to easily distinguish environments. The setting is optional, but can be used to ensure that all requests are properly associated with the specified environment. This differs from an at.js implementation where you must assign Target environments based on domains and host group rules.
For more information, refer to the datastream configuration guide and Target Hosts documentation.
Deploy the Platform Web SDK
Target functionality is provided by both at.js and Platform Web SDK. If both libraries are used at the same time, you may experience rendering and tracking issues. To successfully migrate to Platform Web SDK, the first step is to remove at.js and replace it with Platform Web SDK (alloy.js).
Assume a simple Target implementation with at.js:
- A data layer near the top of the page provides information for Target and other applications
- One or more third-party helper libraries whose capabilities may be used in Target activities (for example, jQuery)
- A prehiding snippet to mitigate flicker
- The Target at.js library loads asynchronously with default settings to automatically request and render activities:
code language-html |
---|
|
To upgrade Target to use Platform Web SDK, first remove at.js:
<!--Target at.js library loaded asynchonously-->
<script src="/libraries/at.js" async></script>
And replace with either alloy JavsScript library or your tags embed code and the Adobe Experience Platform Web SDK extension:
code language-html |
---|
|
code language-html |
---|
|
In the tag property, add the Adobe Experience Platform Web SDK extension:
img-md |
---|
modal-image |
The prebuilt standalone version requires a “base code” added directly to the page which creates a global function named alloy. Use this function to interact with the SDK. If you would like to name the global function something else, change the alloy
name.
Refer to the Installing the Platform Web SDK documentation for additional details and deployment options.
Update content-prehiding approach
The Platform Web SDK implementation may require a prehiding snippet depending on whether the library is loaded asynchronously or synchronously.
Asynchronous implementation
Just like with at.js, if the Platform Web SDK library loads asynchronously, the page may finish rendering before Target has performed a content swap. This behavior can lead to what is known as “flicker” where default content briefly displays before being replaced by the personalized content specified by Target. If you want to avoid this flicker, Adobe recommends adding a special prehiding snippet immediately before the asynchronous Platform Web SDK script reference or tags embed code.
If your implementation is asynchronous like the examples above, replace the at.js prehiding snippet with the version below compatible with the Platform Web SDK:
<!--Prehiding snippet for Target with asynchronous Web SDK deployment-->
<script>
!function(e,a,n,t){var i=e.head;if(i){
if (a) return;
var o=e.createElement("style");
o.id="alloy-prehiding",o.innerText=n,i.appendChild(o),setTimeout(function(){o.parentNode&&o.parentNode.removeChild(o)},t)}}
(document, document.location.href.indexOf("mboxEdit") !== -1, ".body { opacity: 0 !important }", 3000);
</script>
The prehiding snippet creates a style tag in the head of the page with the CSS definition of your choosing. This style tag is removed when a response from Target is received, or the timeout is reached.
The prehiding behavior is controlled by two configurations at the very end of the snippet.
-
body { opacity: 0 !important }
specifies the CSS definition to use for the prehiding until Target loads. By default, the whole page is hidden. You can update this definition to the selectors you want to prehide along with how you want to hide them. You may include multiple definitions since this value is simply what is inserted into the prehiding style tag. If you have an easily identifiable container element wrapping the content below your navigation, you could use this setting to limit the prehiding to that container element. -
3000
specifies the timeout in milliseconds for the prehiding. If a response from Target is not received before the timeout, the prehiding style tag is removed. Reaching this timeout should be rare.
alloy-prehiding
. If the prehiding snippet for at.js is used, it may not work properly.Synchronous implementation
Adobe recommends implementing the Platform Web SDK asynchronously for the best overall page performance. However, if the alloy.js library or tags embed code is loaded synchronously, then the prehiding snippet is not required. Instead, the prehiding style is specified in the Platform Web SDK configuration.
The prehiding style for synchronous implementations can be configured using the prehidingStyle
option. Platform Web SDK configuration is covered in the next section.
To learn more about how the Platform Web SDK can manage flicker, you can refer to the guide section: managing flicker for personalized experiences
Configure the Platform Web SDK
The Platform Web SDK must be configured on every page load. The following example assumes that the entire site is being upgraded to Platform Web SDK in a single deployment:
The configure
command must always be the first SDK command called. The edgeConfigId
is the Datastream ID
code language-javascript |
---|
|
In tags implementations, many fields are auto-populated or can be selected from dropdown menus. Note that different Platform sandboxes and datastreams can be selected for each environment. The datastream will change based on the state of the tag library in the publishing process.
img-md |
---|
modal-image |
If you plan to migrate from at.js to Platform Web SDK on a page-by-page basis, then the following configuration options are required:
code language-javascript |
---|
|
img-md |
---|
modal-image |
The noteworthy configuration options related to Target are outlined below:
edgeConfigId
ebebf826-a01f-4458-8cec-ef61de241c93
orgId
ADB3LETTERSANDNUMBERS@AdobeOrg
targetMigrationEnabled
true
idMigrationEnabled
true
thirdPartyCookiesEnabled
true
prehidingStyle
body { opacity: 0 !important }
For a complete list of options, refer to the configuring Platform Web SDK guide.
Implementation example
Once the Platform Web SDK is properly in place, the example page would look like this.
code language-html |
---|
|
Page code:
code language-html |
---|
|
In tags, add the Adobe Experience Platform Web SDK extension:
img-md |
---|
modal-image |
And add the desired configurations:\
img-md |
---|
modal-image |
It’s important to note that simply including and configuring the Platform Web SDK library as shown above does not execute any network calls to the Adobe Edge Network.
Next, learn how to request and apply VEC-based activities to the page.