Edit in GitHubLog an issue

targetGlobalSettings()

You can override settings in the at.js library using targetGlobalSettings(), rather than configuring them in the Target Standard/Premium UI or by using REST APIs.

Settings#

You can override the following settings:

bodyHiddenStyle#

  • Type: String

  • Default Value: body { opacity: 0 }

  • Description: Used only when globalMboxAutocreate === true to minimize the chance of flicker.

    For more information, see How at.js Manages Flicker.

bodyHidingEnabled#

  • Type: Boolean
  • Default Value: true
  • Description: Used to control flicker when target-global-mbox is used to deliver offers created in the Visual Experience Composer, also known as visual offers.

clientCode#

  • Type: String
  • Default Value: Value set via UI.
  • Description: Represents the client code.

cookieDomain#

  • Type: String
  • Default Value: If possible set to the top level domain.
  • Description: Represents the domain used when saving cookies.

crossDomain#

  • Type: String
  • Default Value: Value set via UI.
  • Description: Indicates whether cross-domain tracking is enabled or not. The allowed values are: disabled, enabled,or x-only.

cspScriptNonce#

cspStyleNonce#

dataProviders#

decisioningMethod#

  • Type: String

  • Default Value: server-side

  • Other Values: on-device, hybrid

  • Description: See Decisioning Methods below.

    Decisioning Methods

    With on-device decisioning, Target introduces a new setting called Decisioning Method that dictates how at.js delivers your experiences. The decisioningMethod has three values: server-side only, on-device only, and hybrid. When decisioningMethod is set in targetGlobalSettings(), it acts as the default decisioning method for all Target decisions.

    Server-side only:

    Server-side only is the default decisioning method that is set out of the box when at.js 2.5+ 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.

    On-device only:

    On-device only is the decisioning method that must be set in at.js 2.5+ 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 the supported features section.

    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+ is configured to only look for the cached rules artifact to make decisions.

    Hybrid:

    Hybrid is the decisioning method that must be set in at.js 2.5+ 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.

defaultContentHiddenStyle#

  • Type: String
  • Default Value: visibility: hidden
  • Description: Used only for wrapping mboxes that use DIV with class name "mboxDefault" and are executed via mboxCreate(), mboxUpdate(), or mboxDefine() to hide default content.

defaultContentVisibleStyle#

  • Type: String
  • Default Value: visibility: visible
  • Description: Used only for wrapping mboxes that use DIV with class name "mboxDefault" and are executed via mboxCreate(), mboxUpdate(), or mboxDefine() to reveal applied offer if any or default content.

deviceIdLifetime#

  • Type: Number
  • Default Value: 63244800000 ms = 2 years
  • Description: Amount of time deviceId is persisted in cookies.

enabled#

  • Type: Boolean

  • Default Value: true

  • Description: When enabled, a Target request to retrieve experiences and DOM manipulation to render the experiences is executed automatically. Furthermore, Target calls can be executed manually via getOffer(s) / applyOffer(s).

    When disabled, Target requests are not automatically or manually executed.

globalMboxAutoCreate#

  • Type: Number
  • Default Value: Value set via UI.
  • Description: Indicates whether the global mbox request should be fired or not.

imsOrgId#

  • Type: Sting
  • Default Value: true
  • Description: Represents the IMS ORG ID.

optinEnabled#

  • Type: Boolean
  • Default Value: false
  • Description: Target provides opt-in functionality support via Adobe Experience Platform to help support your consent management strategy. Opt-in functionality lets customers control how and when the Target tag is fired. There is also an option via Adobe Experience Platform to pre-approve the Target tag. To enable the ability to use Opt-In in the Target at.js library, add the optinEnabled=true setting. In Adobe Experience Platform you must select “enable” from the GDPR Opt-In drop-down list in the extension installation view. See the Adobe Experience Platform documentation for more details. For more information about this setting as it relates to privacy and data protection regulations, including the European Union’s General Data Protection Regulation (GDPR) and the California Consumer Privacy Act (CCPA), see Privacy and data protection regulations.

optoutEnabled#

  • Type: Boolean
  • Default Value: false
  • Description: Indicates whether Target should call the Visitor API isOptedOut() function. This is part of Device Graph enablement.

overrideMboxEdgeServer#

  • Type: Boolean

  • Default Value: true (true beginning with at.js version 1.6.2)

  • Description: Indicates if we should use <clientCode>.tt.omtrdc.net domain or mboxedge<clusterNumber>.tt.omtrdc.net domain.

    If this value is true, mboxedge<clusterNumber>.tt.omtrdc.net domain will be saved to a cookie. Currently not working with CNAME when using at.js versions prior to at.js 1.8.2 and at.js 2.3.1. If this is an issue for you, consider updating at.js to a newer, supported version.

overrideMboxEdgeServerTimeout#

  • Type: Number
  • Default Value: 1860000 => 31 minutes
  • Description: Indicates the cookie lifetime that contains the mboxedge<clusterNumber>.tt.omtrdc.net value.

pageLoadEnabled#

  • Type: Boolean
  • Default Value: true
  • Description: When enabled, automatically retrieve experiences that must be returned on page load.

secureOnly#

  • Type: Boolean
  • Default Value: false
  • Description: Indicates whether at.js should use HTTPS only or be allowed to switch between HTTP and HTTPS based on the page protocol. When set to true, secureOnly also sets the Secure and SameSite attributes to the mbox cookie.

selectorsPollingTimeout#

  • Type: Number

  • Default Value: 5000 ms = 5 s

  • Description: In at.js 0.9.6, Target introduced this new setting that can be overridden via targetGlobalSettings.

    The selectorsPollingTimeout setting represents how long the client is willing to wait for all the elements identified by selectors to appear on the page.

    Activities created via the Visual Experience Composer (VEC) have offers that contain selectors.

serverDomain#

  • Type: String
  • Default Value: Value set via UI.
  • Description: Represents the Target edge server.

serverState#

telemetryEnabled#

  • Type: Boolean
  • Default Value: true
  • Description: When enabled, Adobe collects SDK feature usage and performance telemetry data. Personal data is not collected.

timeout#

  • Type: Number
  • Default Value: Value set via UI.
  • Description: Represents the Target edge request timeout.

viewsEnabled#

  • Type: Boolean
  • Default Value: true
  • Description: When enabled, automatically retrieve views that must be returned on page load. Views are supported in at.js 2.x only.

visitorApiTimeout#

  • Type: Number
  • Default Value: 2000 ms = 2 s
  • Description: Represents the Visitor API request timeout.

Usage#

This function can be defined before at.js is loaded or in Administration > Implementation > Edit at.js Settings > Code Settings > Library Header.

The Library Header field allows you to enter free-form JavaScript. The customization code should look something similar to the following example:

Copied to your clipboard
1window.targetGlobalSettings = {
2 timeout: 200, // using custom timeout
3 visitorApiTimeout: 500, // using custom API timeout
4 enabled: document.location.href.indexOf('https://www.adobe.com') >= 0 // enabled ONLY on adobe.com
5};

Data Providers#

This setting lets customers gather data from third-party data providers, such as Demandbase, BlueKai, and custom services, and pass the data to Target as mbox parameters in the global mbox request. It supports the collection of data from multiple providers via async and sync requests. Using this approach makes it easy to manage flicker of default page content, while including independent timeouts for each provider to limit the impact on page performance

The following videos contain more information:

VideoDescription
Using Data Providers in Adobe TargetData Providers is a capability that allows you to easily pass data from third parties to Target. A third party could be a weather service, a DMP, or even your own web service. You can then use this data to build audiences, target content, and enrich the visitor profile.
Implement Data Providers in Adobe TargetImplementation details and examples of how to use Adobe Target's dataProviders feature to retrieve data from third-party data providers and pass it in the Target request.

The window.targetGlobalSettings.dataProviders setting is an array of data providers.

Each data provider has the following structure:

KeyTypeDescription
nameStringName of provider.
versionStringProvider version. This key will be used for provider evolution.
timeoutNumberRepresents the provider timeout if this is a network request. This key is optional.
providerFunctionThe function that contains the provider data fetching logic.
The function has a single required parameter: callback. The callback parameter is a function that should be invoked only when the data has been successfully fetched or there is an error.
The callback expects two parameters:
  • error: Indicates if an error occurred. If everything is OK, then this parameter should be set to null.
  • params: A JSON object, representing the parameters that will be sent in a Target request.

The following example shows where the data provider is using sync execution:

Copied to your clipboard
1var syncDataProvider = {
2 name: "simpleDataProvider",
3 version: "1.0.0",
4 provider: function(callback) {
5 callback(null, {t1: 1});
6 }
7};
8
9window.targetGlobalSettings = {
10 dataProviders: [
11 syncDataProvider
12 ]
13};

After at.js processes window.targetGlobalSettings.dataProviders, the Target request will contain a new parameter: t1=1.

The following is an example if the parameters that you want to add to the Target request are fetched from a third-party service, such as Bluekai, Demandbase, and so forth:

Copied to your clipboard
1var blueKaiDataProvider = {
2 name: "blueKai",
3 version: "1.0.0",
4 provider: function(callback) {
5 // simulating network request
6 setTimeout(function() {
7 callback(null, {t1: 1, t2: 2, t3: 3});
8 }, 1000);
9 }
10}
11
12window.targetGlobalSettings = {
13 dataProviders: [
14 blueKaiDataProvider
15 ]
16};

After at.js processes window.targetGlobalSettings.dataProviders, the Target request will contain additional parameters: t1=1, t2=2 and t3=3.

The following example uses data providers to collect weather API data and send it as parameters in a Target request. The Target request will have additional params, such as country and weatherCondition.

Copied to your clipboard
1var weatherProvider = {
2 name: "weather-api",
3 version: "1.0.0",
4 timeout: 2000,
5 provider: function(callback) {
6 var API_KEY = "caa84fc6f5dc77b6372d2570458b8699";
7 var lat = 44.426767399999996;
8 var lon = 26.1025384;
9 var url = "//api.openweathermap.org/data/2.5/weather?";
10 var data = {
11 lat: lat,
12 lon: lon,
13 appId: API_KEY
14 }
15
16 $.ajax({
17 type: "GET",
18 url: url,
19 dataType: "json",
20 data: data,
21 success: function(data) {
22 console.log("Weather data", data);
23 callback(null, {
24 country: data.sys.country,
25 weatherCondition: data.weather[0].main
26 });
27 },
28 error: function(err) {
29 console.log("Error", err);
30 callback(err);
31 }
32 });
33 }
34 };
35
36 window.targetGlobalSettings = {
37 dataProviders: [weatherProvider]
38 };

Consider the following when working with the dataProviders setting:

  • If the data providers added to window.targetGlobalSettings.dataProviders are async, they will be executed in parallel. The Visitor API request will be executed in parallel with functions added to window.targetGlobalSettings.dataProviders to allow a minimum wait time.
  • at.js won't try to cache the data. If the data provider fetches data only once, the data provider should make sure that data is cached and, when the provider function is invoked, serve the cache data for the second invocation.

Content Security Policy#

at.js 2.3.0+ supports setting Content Security Policy nonces on SCRIPT and STYLE tags appended to the page DOM when applying delivered Target offers.

The SCRIPT and STYLE nonces should be set in targetGlobalSettings.cspScriptNonce and targetGlobalSettings.cspStyleNonce correspondingly, prior to at.js 2.3.0+ loading. See an example below:

Copied to your clipboard
1...
2<head>
3 <script nonce="<script_nonce_value>">
4window.targetGlobalSettings = {
5 cspScriptNonce: "<csp_script_nonce_value>",
6 cspStyleNonce: "<csp_style_nonce_value>"
7};
8 </script>
9 <script nonce="<script_nonce_value>" src="at.js"></script>
10...
11</head>
12...

After cspScriptNonce and cspStyleNonce settings are specified, at.js 2.3.0+ sets these as nonce attributes on all SCRIPT and STYLE tags that it appends to the DOM when applying Target offers.

Hybrid personalization#

serverState is a setting available in at.js v2.2+ that can be used to optimize page performance when a hybrid integration of Target is implemented. Hybrid integration means that you are using both at.js v2.2+ on the client-side and the Delivery API or a Target SDK on the server-side to deliver experiences. serverState gives at.js v2.2+ the ability to apply experiences directly from content fetched on the server side and returned to the client as part of the page being served.

Pre-requisites#

You must have a hybrid integration of Target.

Code samples#

To better understand how this works, please see the code examples below that you would have on your server. The code assumes you are using the Target Node.js SDK.

Copied to your clipboard
1// First, we fetch the offers via Target Node.js SDK API, as usual
2const targetResponse = await targetClient.getOffers(options);
3// A successfull response will contain Target Delivery API request and response objects, which we need to set as serverState
4const serverState = {
5 request: targetResponse.request,
6 response: targetResponse.response
7};
8// Finally, we should set window.targetGlobalSettings.serverState in the returned page, by replacing it in a page template, for example
9const PAGE_TEMPLATE = `
10<!doctype html>
11<html>
12<head>
13 ...
14 <script>
15 window.targetGlobalSettings = {
16 overrideMboxEdgeServer: true,
17 serverState: ${JSON.stringify(serverState, null, " ")}
18 };
19 </script>
20 <script src="at.js"></script>
21</head>
22...
23</html>
24`;
25// Return PAGE_TEMPLATE to the client ...

A sample serverState object JSON for view prefetch looks as follows:

Copied to your clipboard
1{
2 "request": {
3 "requestId": "076ace1cd3624048bae1ced1f9e0c536",
4 "id": {
5 "tntId": "08210e2d751a44779b8313e2d2692b96.21_27"
6 },
7 "context": {
8 "channel": "web",
9 "timeOffsetInMinutes": 0
10 },
11 "experienceCloud": {
12 "analytics": {
13 "logging": "server_side",
14 "supplementalDataId": "7D3AA246CC99FD7F-1B3DD2E75595498E"
15 }
16 },
17 "prefetch": {
18 "views": [
19 {
20 "address": {
21 "url": "my.testsite.com/"
22 }
23 }
24 ]
25 }
26 },
27 "response": {
28 "status": 200,
29 "requestId": "076ace1cd3624048bae1ced1f9e0c536",
30 "id": {
31 "tntId": "08210e2d751a44779b8313e2d2692b96.21_27"
32 },
33 "client": "testclient",
34 "edgeHost": "mboxedge21.tt.omtrdc.net",
35 "prefetch": {
36 "views": [
37 {
38 "name": "home",
39 "key": "home",
40 "options": [
41 {
42 "type": "actions",
43 "content": [
44 {
45 "type": "setHtml",
46 "selector": "#app > DIV.app-container:eq(0) > DIV.page-container:eq(0) > DIV:nth-of-type(2) > SECTION.section:eq(0) > DIV.container:eq(1) > DIV.heading:eq(0) > H1.title:eq(0)",
47 "cssSelector": "#app > DIV:nth-of-type(1) > DIV:nth-of-type(1) > DIV:nth-of-type(2) > SECTION:nth-of-type(1) > DIV:nth-of-type(2) > DIV:nth-of-type(1) > H1:nth-of-type(1)",
48 "content": "<span style=\"color:#FF0000;\">Latest</span> Products for 2020"
49 }
50 ],
51 "eventToken": "t0FRvoWosOqHmYL5G18QCZNWHtnQtQrJfmRrQugEa2qCnQ9Y9OaLL2gsdrWQTvE54PwSz67rmXWmSnkXpSSS2Q==",
52 "responseTokens": {
53 "profile.memberlevel": "0",
54 "geo.city": "dublin",
55 "activity.id": "302740",
56 "experience.name": "Experience B",
57 "geo.country": "ireland"
58 }
59 }
60 ],
61 "state": "J+W1Fq18hxliDDJonTPfV0S+mzxapAO3d14M43EsM9f12A6QaqL+E3XKkRFlmq9U"
62 }
63 ]
64 }
65 }
66}

After the page is loaded in the browser, at.js applies all the Target offers from serverState immediately, without firing any network calls against the Target edge. Additionally, at.js prehides only the DOM elements for which Target offers are available in the content fetched server-side, thus positively impacting page-load performance and end-user experience.

Important Notes#

Consider the following when using serverState:

  • At the moment, at.js v2.2 supports only delivering experiences via serverState for:

    • VEC-created activities that are executed on page load.

    • Pre-fetched views.

      In case of SPAs using Target Views and triggerView() in the at.js API, at.js v2.2 caches the content for all Views prefetched on the server-side and applies these as soon as each View is triggered via triggerView(), again without firing any additional content-fetching calls to Target.

    • Note: Currently, mboxes retrieved on the server-side is not supported in serverState.

  • When applying serverState offers, at.js takes into consideration pageLoadEnabled and viewsEnabled settings, e.g. Page Load offers will not be applied if the pageLoadEnabled setting is false.

    To turn these settings on, enable the toggle in Administration > Implementation > Edit > Page Load Enabled.

    Page Load Enabled settings

  • If you are using serverState and using <script> tags in the content returned, ensure that your HTML content uses <\/script> instead of </script>. If you use </script>, the browser interprets </script> as the end on an inline SCRIPT and it might break the HTML page.

Additional resources#

To learn more how serverState works, check out the following resources:

Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.