Client Context Javascript API

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 a number of 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.

clear()

Removes all data properties from the store.

Parameters

None.

Returns

No return value.

getData(excluded)

Returns the store data. Optionally, excludes name properties from the data. Calls the init method if the data property of the store does not exist.

Parameters

excluded: (Optional) An array of property names to exclude from the returned data.

Returns

An object of properties and their values.

getInitProperty(name)

Retrieves the value of a data property.

Parameters

• name: String. The name of the data property to retrieve.

Returns

The value of the data property. Returnes null if the session store contains no property of the given name.

getName()

Returns the name of the session store.

Parameters

None.

Returns

A String value that represents the store name.

getProperty(name, raw)

Returns the value of a property. The value is returned as the raw property or the XSS-filtered value. Calls the init method if the data property of the store does not exist.

Parameters

• name: String. The name of the data property to retrieve.
• raw: Boolean. A value of true causes the raw property value to be returned. A value of false causes the returned value to be XSS-filtered.

Returns

The value of the data property.

getPropertyNames(excluded)

Returns the names of the properties that the session store contains. Calls the init method if the data property of the store does not exist.

Parameters

excluded: (Optional) An array of property names to omit from the results.

Returns

An array of String values that represent the session property names.

getSessionStore()

Returns the session store attached to the current object.

Parameters

None.

Returns

this

init()

Marks the store as initialized and fires the initialize event.

Parameters

None.

Returns

No returned value.

isInitialized()

Indicates whether the sessions store is initialized.

Parameters

None.

Returns

A value of true if the store is initialized, and a value of false if the store is not initialized.

loadInitProperties(obj, setValues)

Adds the properties of a given object to the intialization data of the session store. Optionally, the object data is also added to the store data.

Parameters

• obj: An object that contains enumerable propertes.
• setValues: When true, the obj properties are added to the session store data if the store data does not already include a property of the same name. When false, no data is added to the session store data.

Returns

No returned value.

removeProperty(name)

Removes a property from the session store. 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 to remove.

Returns

No returned value.

reset()

Restores the initial values of the data store. The default implementation simply removes all data. Fires the update event upon completion.

Parameters

None.

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.