Client Context JavaScript API

April 17, 2024

Topics:
Context Hub,Developing,Personalization

CREATED FOR:

Developer

CQ_Analytics.ClientContextMgr

The CQ_Analytics.ClientContextMgr object is a singleton that contains a set of self-registered session stores, and provides methods for registering, persisting, and managing the session stores.

Extends CQ_Analytics.PersistedSessionStore.

Methods

getRegisteredStore(name)

Returns a session store of a specified name. See also Accessing a Session Store.

Parameters

name: String. The name of the session store.

Returns

A CQ_Analytics.SessionStore object that represents the session store of the given name. Returns null when no store exists of the given name.

register(sessionstore)

Registers a session store with Client Context. Fires the storeregister and storeupdate events upon completion.

Parameters

sessionstore: CQ_Analytics.SessionStore. The session store object to register.

Returns

No returned value.

CQ_Analytics.ClientContextUtils

Provides methods for listening for session store activation and registration. See also Checking That a Session Store is Defined and Initialized.

Methods

onStoreInitialized(storeName, callback, delay)

Registers a callback function that is called when a session store is initialized. For stores that are initialized several times, specify a callback delay so that the callback function is called only once:

When the store is initialized during the delay period of a previous initialization, the previous function call is cancelled, and the function is called again for the current initialization.
If the delay period lapses before a subsequent initialization occurs, the callback function is executed twice.

For example, a session store is based on a JSON object and retrieved via a JSON request. The following intialization scenarios are possible:

The request is completed, data retrieved and loaded into the store. In this case, initialization occurs once.
The request fails (timeout). In this case initialization does not happen and there is no data in the store.
The store is pre-populated with default values (init properties), but the request fails (timeout). There is only one initialization with default values.
The store is pre-populated.

When the delay is set to true or several milliseconds, the method waits before calling the callback method. If another initialization event is triggered before the delay is passed, it will wait until the delay time is exceeded with no initialization event. This enables waiting for a second initialization event to be triggered and calls the callback function in the most optimal case.

Parameters

storeName: String. The name of the session store to add the listener.
callback: Function. The function to call upon store initialization.
delay: Boolean or Number. The amount of time to delay the call to the callback function, in milliseconds. A boolean value of true uses the default delay of 200 ms. A boolean value of false or a negative number causes no delay to be used.

Returns

No returned value.

onStoreRegistered(storeName, callback)

Registers a callback function that is called when a session store is registered. The register event occurs when a store is registered to CQ_Analytics.ClientContextMgr.

Parameters

storeName: String. The name of the session store to add the listener.
callback: Function. The function to call upon store initialization.

Returns

No returned value.

CQ_Analytics.JSONPStore

A non-persisted session store that contains JSON data. The data is retrieved from an external JSONP service. Use the getInstance or getRegisteredInstance method to create an instance of this class.

Extends CQ_Analytics.JSONStore.

Properties

See CQ_Analytics.JSONStore and CQ_Analytics.SessonStore for inherited properties.

Methods

Also see CQ_Analytics.JSONStore and CQ_Analytics.SessonStore for inherited methods.

getInstance(storeName, serviceURL, dynamicData, deferLoading, loadingCallback)

Creates a CQ_Analytics.JSONPStore object.

Parameters

storeName: String. The name to use as the STORENAME property. The value of the STOREKEY property is set to storeName with all upper-case characters. If no storeName is provided, the method returns null.
serviceURL: String. The URL of the JSONP service
dynamicData: (Optional) Object. JSON data to append to the store’s initialization data before the callback function is called.
deferLoading: (Optional) Boolean. A value of true prevents the JSONP service from being called upon object creation. A value of false causes the JSONP service to be called.
loadingCallback: (Optional) String. The name of the function to call for processing the JSONP object that the JSONP service returns. The callback function must define a single parameter that is a CQ_Analytics.JSONPStore object.

Returns

The new CQ_Analytics.JSONPStore object, or null if storeName is null.

getServiceURL()

Retrieves the URL of the JSONP service that this object uses to retrieve JSON data.

Parameters

None.

Returns

A String that represents the service URL, or null if no service URL has been configured.

load(serviceURL, dynamicData, callback)

Calls the JSONP service. The JSONP URL is the service URL suffixed with a give callback function name.

Parameters

serviceURL: (Optional) String. The JSONP service to call. A value of null causes the already-configured service URL to be used. A non-null value sets the JSONP service to use for this object. (See setServiceURL.)
dynamicData: (Optional) Object. JSON data to append to the store’s initialization data before the callback function is called.
callback: (Optional) String. The name of the function to call for processing the JSONP object that the JSONP service returns. The callback function must define a single parameter that is a CQ_Analytics.JSONPStore object.

Returns

No returned value.

registerNewInstance(storeName, serviceURL, dynamicData, callback)

Creates a CQ_Analytics.JSONPStore object and registers the store with Client Context.

Parameters

storeName: String. The name to use as the STORENAME property. The value of the STOREKEY property is set to storeName with all upper-case characters. If no storeName is provided, the method returns null.
serviceURL: (Optional) String. The URL of the JSONP service.
dynamicData: (Optional) Object. JSON data to append to the store’s initialization data before the callback function is called.
callback: (Optional) String. The name of the function to call for processing the JSONP object that the JSONP service returns. The callback function must define a single parameter that is a CQ_Analytics.JSONPStore object.

Returns

The registered CQ_Analytics.JSONPStore object.

setServiceURL(serviceURL)

Sets the URL of the JSONP service to use for retrieving JSON data.

Parameters

serviceURL: String. The URL of the JSONP service that provides JSON data

Returns

No returned value.

CQ_Analytics.JSONStore

A container for a JSON object. Create an instance of this class to create a non-persisted session store that contains JSON data:

myjsonstore = new CQ_Analytics.JSONStore

You can define a set of data that populates the store upon initialization.

Extends CQ_Analytics.SessionStore.

Properties

STOREKEY

The key that identifies the store. Use the getInstance method to retrieve this value.

STORENAME

The name of the store. Use the getInstance method to retrieve this value.

Methods

Also see CQ_Analytics.SessionStore for inherited methods.

clear()

Removes the session store data and removes all initialization properties.

Parameters

None.

Returns

No returned value.

getInstance(storeName, jsonData)

Creates a CQ_Analytics.JSONStore object with a given name and initialized with the given JSON data (calls the initJSON method).

Parameters

storeName: String. The name to use as the STORENAME property. The value of the STOREKEY property is set to storeName with all upper-case characters.
jsonData: Object. An object that contains JSON data.

Returns

The CQ_Analytics.JSONStore object.

getJSON()

Retrieves the data of the session store in JSON format.

Parameters

None.

Returns

An object that represents the store data in JSON format.

init()

Clears the session store and initializes it with the initialization property. Sets the initialization flag to true and then fires the initialize and update events.

Parameters

None.

Returns

No returned data.

initJSON(jsonData, doNotClear)

Creates initialization properties from the data in a JSON object. You can optionally remove all existing initialization properties.

The names of the properties are derived from the hierarchy of the data in the JSON object. The following example code represents a JSON object:

{
A: "valueA",
B: {
     B1: "valueBB1"
    }
}

For this example, the following properties are created in the store:

A: "valueA"
B/B1: "valueBB1"

Parameters

jsonData: A JSON object that contains the data to store.
doNotClear: A value of true preserves the existing initialization properties and adds those derived from the JSON object. A value of false removes existing initialization properties before adding those derived from the JSON object.

Returns

No returned value.

registerNewInstance(storeName, jsonData)

Creates a CQ_Analytics.JSONStore object with a given name and initialized with the given JSON data (calls the initJSON method). The new object is automatically registered with the Clickstream Cloud Manager.

Parameters

storeName: String. The name to use as the STORENAME property. The value of the STOREKEY property is set to storeName with all upper-case characters.
jsonData: Object. An object that contains JSON data.

Returns

The CQ_Analytics.JSONStore object.

CQ_Analytics.Observable

Fires events and allows other objects to listen to these events and react. Classes that extend this class can fire events that cause listeners to be called.

Methods

addListener(event, fct, scope)

Registers a listener for an event. See also Creating a Listener to React to a Session Store Update.

Parameters

event: String. The name of the event to listen for.
fct: Function. The function that is called when the event occurs.
scope: (Optional) Object. The scope in which to execute the handler function. The handler function’s “this” context.

Returns

No returned value.

removeListener(event, fct)

Removes the given event handler for an event.

Parameters

event: String. The name of the event.
fct: Function. The event handler.

Returns

No returned value.

CQ_Analyics.PersistedJSONPStore

A persisted container of a JSON object retrieved from a remote JSONP service.

Extends CQ_Analytics.PersistedJSONStore.

Methods

Also see CQ_Analytics.PersistedJSONStore for inherited methods.

getInstance(storeName, serviceURL, dynamicData, deferLoading, loadingCallback)

Creates a CQ_Analytics.PersistedJSONPStore object.

Parameters

storeName: String. The name to use as the STORENAME property. The value of the STOREKEY property is set to storeName with all upper-case characters. If no storeName is provided, the method returns null.
serviceURL: String. The URL of the JSONP service
dynamicData: (Optional) Object. JSON data to append to the store’s initialization data before the callback function is called.
deferLoading: (Optional) Boolean. A value of true prevents the JSONP service from being called upon object creation. A value of false causes the JSONP service to be called.
loadingCallback: (Optional) String. The name of the function to call for processing the JSONP object that the JSONP service returns. The callback function must define a single parameter that is a CQ_Analytics.JSONPStore object.

Returns

The new CQ_Analytics.PersistedJSONPStore object, or null if storeName is null.

getServiceURL()

Retrieves the URL of the JSONP service that this object uses to retrieve JSON data.

Parameters

None.

Returns

A String that represents the service URL, or null if no service URL has been configured.

load(serviceURL, dynamicData, callback)

Calls the JSONP service. The JSONP URL is the service URL suffixed with a give callback function name.

Parameters

serviceURL: (Optional) String. The JSONP service to call. A value of null causes the already-configured service URL to be used. A non-null value sets the JSONP service to use for this object. (See setServiceURL.)
dynamicData: (Optional) Object. JSON data to append to the store’s initialization data before the callback function is called.
callback: (Optional) String. The name of the function to call for processing the JSONP object that the JSONP service returns. The callback function must define a single parameter that is a CQ_Analytics.JSONPStore object.

Returns

No returned value.

registerNewInstance(storeName, serviceURL, dynamicData, callback)

Creates a CQ_Analytics.PersistedJSONPStore object and registers the store with Client Context.

Parameters

storeName: String. The name to use as the STORENAME property. The value of the STOREKEY property is set to storeName with all upper-case characters. If no storeName is provided, the method returns null.
serviceURL: (Optional) String. The URL of the JSONP service.
dynamicData: (Optional) Object. JSON data to append to the store’s initialization data before the callback function is called.
callback: (Optional) String. The name of the function to call for processing the JSONP object that the JSONP service returns. The callback function must define a single parameter that is a CQ_Analytics.JSONPStore object.

Returns

The registered CQ_Analytics.PersistedJSONPStore object.

setServiceURL(serviceURL)

Sets the URL of the JSONP service to use for retrieving JSON data.

Parameters

serviceURL: String. The URL of the JSONP service that provides JSON data

Returns

No returned value.

CQ_Analytics.PersistedJSONStore

A persisted container of a JSON object.

Extends CQ_Analytics.PersistedSessionStore.

Properties

STOREKEY

The key that identifies the store. Use the getInstance method to retrieve this value.

STORENAME

The name of the store. Use the getInstance method to retrieve this value.

Methods

Also see CQ_Analytics.PersistedSessionStore for inherited methods.

getInstance(storeName, jsonData)

Creates a CQ_Analytics.PersistedJSONStore object with a given name and initialized with the given JSON data (calls the initJSON method).

Parameters

storeName: String. The name to use as the STORENAME property. The value of the STOREKEY property is set to storeName with all upper-case characters.
jsonData: Object. An object that contains JSON data.

Returns

The CQ_Analytics.PersistedJSONStore object.

getJSON()

Retrieves the data of the session store in JSON format.

Parameters

None.

Returns

An object that represents the store data in JSON format.

initJSON(jsonData, doNotClear)

Creates initialization properties from the data in a JSON object. You can optionally remove all existing initialization properties.

The names of the properties are derived from the hierarchy of the data in the JSON object. The following example code represents a JSON object:

{
A: "valueA",
B: {
     B1: "valueBB1"
    }
}

For this example, the following properties are created in the store:

A: "valueA"
B/B1: "valueBB1"

Parameters

jsonData: A JSON object that contains the data to store.
doNotClear: A value of true preserves the existing initialization properties and adds those derived from the JSON object. A value of false removes existing initialization properties before adding those derived from the JSON object.

Returns

No returned value.

registerNewInstance(storeName, jsonData)

Creates a CQ_Analytics.PersistedJSONStore object with a given name and initialized with the given JSON data (calls the initJSON method). The new object is automatically registered with the Client Context Manager.

Parameters

storeName: String. The name to use as the STORENAME property. The value of the STOREKEY property is set to storeName with all upper-case characters.
jsonData: Object. An object that contains JSON data.

Returns

The CQ_Analytics.PersistedJSONStore object.

CQ_Analytics.PersistedSessionStore

A container of properties and values. The data is persisted using CQ_Analytics.SessionPersistence. Create an instance of this class to create a persisted session store:

mypersistedstore = new CQ_Analytics.PersistedSessionStore

Extends CQ_Analytics.SessionStore.

Properties

STOREKEY

Default value is key.

Methods

See CQ_Analytics.SessionStore for inherited methods.

When the inherited methods clear, setProperty, setProperties, removeProperty are used to change the store data, the changes are automatically persisted, unless the changed properties are flagged as notPersisted.

getStoreKey()

Retrieves the STOREKEY property.

Parameters

None

Returns

The value of the STOREKEY property.

isPersisted(name)

Determines whether a data property is persisted.

Parameters

name: String. The name of the property.

Returns

A Boolean value of true if the property is persisted, and a value of false if the value is not a persisted property.

persist()

Persists the session store. The default persistence mode uses browser localStorage using ClientSidePersistence as the name ( window.localStorage.set("ClientSidePersistance", store);)

If localStorage is not available or writeable, then the store is persisted as a property of the window.

Fires the persist event upon completion.

Parameters

None

Returns

No returned value.

reset(deferEvent)

Removes all data properties from the store and persists the store. Optionally does not fire the udpate event upon completion.

Parameters

deferEvent: A value of true prevents the update event from being fired. A value of false causes the update event to fire.

Returns

No returned value.

setNonPersisted(name)

Flags a data property as not persisted.

Parameters

name: String. The name of the property that is not to be persisted.

Returns

No return value.

CQ_Analytics.SessionStore

CQ_Analytics.SessionStore represents a session store. Create an instance of this class to create a session store:

mystore = new CQ_Analytics.SessionStore

Extends CQ_Analytics.Observable.

Properties

STORENAME

The name of the session store. Use getName to retrieve the value of this property.

Methods

addInitProperty(name, value)

Adds a property and value to the session store initialization data.

Use loadInitProperties to populate the session store data with the initialization values.

Parameters

name: String. The name of the property to add.
value: String. The value of the property to add.

Returns

No returned value.

setProperties(properties)

Sets the values of multiple properties. Fires the update event upon completion. Calls the init method if the data property of the store does not exist.

Parameters

Properties: Object. An object that contains enumerable properties. Each property name and value is added to the store.

Returns

No returned value.

setProperty(name, value)

Sets the value of a property. Fires the update event upon completion. Calls the init method if the data property of the store does not exist.

Parameters

name: String. The name of the property.
value: String. Property value.

Returns

No returned value.

recommendation-more-help