On-device decisioning for at.js
- Topics:
- at.js
CREATED FOR:
- Developer
Starting with version 2.5.0, at.js offers on-device decisioning. On-device decisioning lets you cache your A/B Test and Experience Targeting (XT) activities on the browser to perform in-memory decisioning without a blocking network request to the Adobe Target Edge Network.
NOTETarget also offers the flexibility of delivering the most relevant and up-to-date experience from your experimentation and Machine Learning-driven (ML-driven) personalization activities via a live server call. In other words, when performance is most important, you can choose to use on-device decisioning. However, when the most relevant, up-to-date, and ML-driven experience is needed, a server call can be made instead.
What are the benefits of on-device decisioning?
The benefits of on-device decisioning include:
- Deliver blazing fast decisions and experiences. Bucketing and decisioning are performed in-memory and on the browser to avoid blocking network requests.
- Enhance application performance. Run experiments and deliver personalization to your customers and users without compromising end-user experiences.
- Improve Google Site Quality Score. With decisioning happening in-memory, improve the Google Site Quality score of your online business to make it more discoverable by consumers.
- Learn from real-time analytics. Gain insights from your activity performance in real time via Analytics for Target (A4T) reporting. A4T allows you to pivot your strategy at critical moments.
Supported features
The Adobe Target JS SDK gives customers the flexibility to choose between performance and freshness of data for decisions. In other words, if delivering the most relevant and engaging personalized content via machine learning is most important to you, a live server call should be made. But when performance is more critical, an on-device and in-memory decision should be made. For on-device decisioning to work, refer to the list of features that are supported:
- Activity types
- Audience targeting
- Allocation method
For more information, see Supported features for on-device decisioning.
How does on-device decisioning work?
When you deploy and initialize at.js with on-device decisioning enabled, a rule artifact that includes your on-device decisioning for A/B and XT activities, audiences, and assets, is downloaded from the closest Akamai CDN to your visitor and cached locally on your visitor’s browser. When a request is made from at.js to retrieve an experience, the decision regarding which experience to return is made in-memory, based on the metadata encoded in the cached rule artifact.
Decisioning method
With on-device decisioning, Target introduces a new setting called Decisioning Method. The Decisioning Method setting dictates how at.js delivers your experiences. Decisioning Method has three values:
- Server-side only
- On-device only
- Hybrid
Server-side only
Server-side only is the default decisioning method that is set out of the box when at.js 2.5.0+ is implemented and deployed on your web properties.
Using server-side only as the default configuration means that all decisions are made on the Target edge network, which involves a blocking server call. This approach can introduce incremental latency, but it also provides significant benefits, such as giving you the ability to apply Target’s machine-learning capabilities that include Recommendations, Automated Personalization (AP), and Auto-Target activities.
Furthermore, enhancing your personalized experiences by using Target’s user profile, which is persisted across sessions and channels, can provide powerful outcomes for your business.
Lastly, server-side only lets you use the Adobe Experience Cloud and fine-tune audiences that can be targeted against through Audience Manager and Adobe Analytics segments.
The following diagram illustrates the interaction between your visitor, the browser, at.js 2.5.0+, and the Adobe Target Edge network. This flow diagram captures new visitors and returning visitors.
(Click image to expand to full width.)
The following list corresponds to the numbers in the diagram:
The at.js library can also be loaded asynchronously with an optional pre-hiding snippet implemented on the page.
The Profile Store requests qualified audiences from the Audience Library (for example, audiences shared from Adobe Analytics, Adobe Audience Manager, and so forth.).
Customer attributes are sent to the Profile Store in a batch process.
On-device only
On-device only is the decisioning method that must be set in at.js 2.5.0+ when on-device decisioning should be used only throughout your web pages.
On-device decisioning can deliver your experiences and personalization activities at blazing fast speed because the decisions are made from a cached rules artifact that contains all of your activities that qualify for on-device decisioning.
To learn more about which activities qualify for on-device decisioning, see Supported features in on-device decisioning.
This decisioning method should be used only if performance is highly critical across all the pages that require decisions from Target. Furthermore, keep in mind that when this decisioning method is selected, your Target activities that do not qualify for on-device decisioning will not be delivered or executed. The at.js library 2.5.0+ is configured to only look for the cached rules artifact to make decisions.
The following diagram illustrates the interaction between your visitor, the browser, at.js 2.5.0+, and the Akamai CDN. The Akamai CDN caches the rules artifact for the visitor’s first visit. For the first page visit for a new visitor, the JSON rules artifact must be downloaded from the Akamai CDN to be cached locally on the visitor’s browser. After the JSON rules artifact is downloaded, the decision is made immediately without a blocking network call. The following flow diagram captures new visitors.
(Click image to expand to full width.)
The following list corresponds to the numbers in the diagram:
NOTEThe at.js library can also be loaded asynchronously with an optional pre-hiding snippet implemented on the page.
The following diagram illustrates the interaction between your visitor, the browser, at.js 2.5.0+, and the cached JSON rule artifact for the visitor’s subsequent page hit or returning visit. Because the JSON rules artifact is already cached and available on the browser, the decision is made immediately without a blocking network call. This flow diagram captures subsequent page navigation or returning visitors.
(Click image to expand to full width.)
The following list corresponds to the numbers in the diagram:
NOTEThe at.js library can also be loaded asynchronously with an optional pre-hiding snippet implemented on the page.
Hybrid
Hybrid is the decisioning method that must be set in at.js 2.5.0+ when both on-device decisioning and activities that require a network call to the Adobe Target Edge network must be executed.
When you are managing both on-device decisioning activities and server-side activities, it can be a bit complicated and tedious when thinking about how to deploy and provision Target on your pages. With hybrid as the decisioning method, Target knows when it must make a server call to the Adobe Target Edge network for activities that require server-side execution, and also when to only execute on-device decisions.
The JSON rules artifact includes metadata to inform at.js whether an mbox has a server-side activity running or an on-device decisioning activity. This decisioning method ensures that activities you intend to be delivered quickly are done through on-device decisioning and for activities that require more powerful ML-driven personalization, those activities are done via the Adobe Target Edge network.
The following diagram illustrates the interaction between your visitor, the browser, at.js 2.5.0+, the Akamai CDN, and the Adobe Target Edge Network for a new visitor visiting your page for the first time. The takeaway from this diagram is that the JSON rules artifact is downloaded asynchronously while the decisions are made through the Adobe Target Edge network.
This approach ensures that the size of the artifact, which can include many activities, doesn’t negatively influence the latency of the decision. Downloading the JSON rules artifact synchronously and making the decision thereafter can also have adverse effects to latency and can be inconsistent. Therefore, the hybrid decisioning method is a best practice recommendation to always make a server-side call for the decision for a new visitor, and as the JSON rules artifact is cached in parallel. For any subsequent page visits and return visits, the decisions are made from the cache and in-memory through the JSON rules artifact.
(Click image to expand to full width.)
The following list corresponds to the numbers in the diagram:
NOTEThe at.js library can also be loaded asynchronously with an optional pre-hiding snippet implemented on the page.
The following diagram illustrates the interaction between your visitor, the browser, at.js 2.5.0+, and the cached JSON rules artifact for a subsequent page navigation or a return visit. In this diagram, focus only on the use case that an on-device decision is made for the subsequent page navigation or return visit. Keep in mind that depending on which activities are live for certain pages, a server-side call can be made to execute server-side decisions.
(Click image to expand to full width.)
The following list corresponds to the numbers in the diagram:
NOTEThe at.js library can also be loaded asynchronously with an optional pre-hiding snippet implemented on the page.
How do I enable on-device decisioning?
On-device decisioning is available for all Target customers who use At.js 2.5.0+.
To enable on-device decisioning:
NOTE-
Click Administration > Implementation > Account details.
-
Under Account details, slide the On-Device Decisioning toggle to the “on” position.
The “Include all existing on-device decisioning qualified activities in the artifact” option displays if you enable on-device decisioning.
-
(Conditional) Slide the toggle to the “on” position if you want all your live Target activities that qualify for on-device decisioning to be automatically included in the artifact.
Leaving this toggle off means you must re-create and activate any on-device decisioning activities for them to be included in the generated rules artifact. In other words, any activity in live state before turning on the On-Device Decisioning toggle are not included in the rules artifact.
After enabling the On-Device Decisioning toggle, Target begins generating and propagating rule artifacts for your client.
WARNINGHow do I configure at.js 2.5.0+ to use on-device decisioning?
-
Click Administration > Implementation > Account details.
-
Under Implementation Methods > Main Implementation Method, click Edit next to your at.js version (must be at.js 2.5.0 or later).
WARNINGBefore changing these default settings, consult with Client Care to avoid affecting your current implementation. -
Select the desired decisioning method:
- Server-side only
- On-device only
- Hybrid
Global settings
You can configure a default Decisioning Method for all of Target decisions. The various decisioning methods are Server-side only, On-device only, and Hybrid. The decisioning method that is selected in the Target UI is configured in window.targetGlobalSettings under the decisioningMethod field. Learn more about the decisioningMethod in targetGlobalSettings().
<head>
<script type="text/javascript">
window.targetGlobalSettings = {
clientCode: "yourClientCodeHere",
imsOrgId: "imsOrgId@AdobeOrg",
decisioningMethod: "on-device"
};
</script>
<script type="text/javascript" src="at.js"></script>
</head>
Customized setting
If you set the decisioningMethod in window.targetGlobalSettings, but would like to override the decisioningMethod for each Adobe Target decision according to your use case, you can do this procedure by specifying decisioningMethod in At.js2.5.0+'s getOffers() call.
adobe.target.getOffers({
decisioningMethod:"on-device",
request: {
execute: {
mboxes: [
{
index: 0,
name: "homepage"
}
]
}
}
});
decisioningMethod as “on-device” or “hybrid.” The at.js library 2.5.0+ must know whether to download and cache the JSON rules artifact immediately after loading on the page. If the decisioning method for the global setting is set to “server-side”, and “on-device” or “hybrid” decisioning method is passed into the getOffers() call, at.js 2.5.0+ would not have the JSON rule artifact cached to execute your on-device decisions.Artifact Cache TTL
Target represents your activities that qualify for on-device decisioning as an artifact that consists of metadata, rules, and conditions. This artifact is cached on the Akamai CDN. During the first-time visit of your user, the user’s browser downloads and caches the artifact that represents your on-device decisioning activities.
On subsequent visits to your site, the browser automatically checks whether it must download a newer version of the artifact. This check adds latency. The Artifact Cache TTL defines the number of minutes you don’t want the browser to check for an updated artifact since the last successful download. The longer the time frame, the better the performance. The shorter the time frame, the better the data freshness, but at the cost of added latency.
How do I know that an activity is on-device decisioning eligible?
After you create an activity that is on-device decisioning eligible, a label that reads On-Device Decisioning Eligible, is visible in the activity’s Overview page.
This label does not mean that the activity will always be delivered via on-device decisioning. Only when at.js 2.5.0+ is configured to use on-device decisioning will this activity be executed on-device. If at.js 2.5.0+ is not configured to use on-device, then this activity will still be delivered via a server call that is made from at.js.
You can filter for all activities that are on-device decisioning eligible on the Activities page via the On-Device Decisioning Eligible filter.
NOTESummary of steps to ensure my on-device decisioning activities are delivered via At.js 2.5.0+?
-
Access the Adobe Target UI and navigate to Administration > Implementation > Account Details to enable the On-Device Decisioning toggle.
-
Enable the “Include all existing on-device decisioning qualified activities in the artifact” toggle.
The first JSON rules artifact generation can take up to 10 minutes.
-
Create and activate an activity type that is supported by on-device decisioning, and verify that it is on-device decisioning eligible.
-
Set the Decisioning Method to either “Hybrid” or “On-device only” through the at.js settings UI.
-
Download and deploy At.js 2.5.0+ to your pages.