Class s7sdk.TrackingManager

The TrackingManager component emits user-initiated events that are suitable for tracking purposes. These events are meant to help understand user behaviors and are different from normal events that facilitate component interaction. For that reason there is a special event class called UserEvent that is used primarily for tracking. This event is not handled in SDK-based viewers unless lower level control over event processing is desired. Each component has predefined logic that guides the event transmission.

When a UI component is attached to the TrackingManager component, every time a component dispatches an instance of UserEvent the TrackingManager calls the s7ComponentEvent external API if the tracking of that particular track event type is enabled, unless the TrackingManager.setCallback() function has been called with an alternative callback function. The callback function is a JavaScript function with the following syntax:

s7ComponentEvent (objectID, component class, instance name, time stamp, event data)

The objectID is the id attribute of the object tag, or the name attribute of the embed tag. The component class is set to the type of the component that dispatched the UserEvent; the instance name is the name of the component instance that dispatched the event; the time stamp is a number of seconds since the beginning of the session. The event data is the value returned by the UserData.toString() API and differs for each UserData.trackEvent type. In addition to calling the external API function, every listed event is also traced in the console output when loglevel is config or higher.

Supported events and components emitting them:

Event	Description	Components
LOAD	Emitted when the viewer starts.	ParameterManager
SWAP	Emitted when the asset is changed by the viewer.	FlyoutZoomView, NavigationView, ZoomView, MediaSet, PageScrubber, PageView, SpinView, Swatches, ThumbnailGridView, VideoPlayer, CarouselView
SWATCH	Emitted each time a swatch or thumbnail is selected.	Swatches, ThumbnailGridView
PAGE	Emitted for page turn events.	PageView
PLAY	Emitted when video begins to play.	RecutPlayer, VideoPlayer
CURRENT_TIME	Emitted each time the current video time is changed.	RecutPlayer, VideoPlayer, Video360Player
PAUSE	Emitted when pause button is clicked.	RecutPlayer, VideoPlayer
STOP	Emitted when pause button is clicked.	RecutPlayer, VideoPlayer
MILESTONE	Should be emitted when the video has played to 25%, 50%, 75% and 100%.	VideoPlayer
HREF	Emitted when an image map is clicked and its href= attribute is executed.	ImageMapEffect
ITEM	Emitted when an image map has non-empty rollover_key= attribute and `RolloverKeyEvent` event is dispatched after it was activated.	ImageMapEffect
TARG	Emitted when a zoom target it selected.	ZoomTargets
ZOOM	Emitted when the zoom level changes.	FlyoutZoomView, ZoomView, PageView, SpinView
SPIN	Emitted each time the view is changed to a different spin frame.	SpinView
PAN	Emitted each time a view is panned.	FlyoutZoomView, ZoomView, SpinView, PageView
BANNER	Emitted each time image is changed inside the CarouselView component.	CarouselView
INTERACTIVE_SWATCH	Emitted each time when the user clicks an interactive swatch.	InteractiveSwatches,CallToAction

See s7sdk.event.UserEvent for a list of events generated by each components.

Customizing Behavior Using Modifiers

For components that are attached to the TrackingManager, the following modifiers are supported:

Modifier	Syntax	Description	Default
disabletracking	event1[,event2[,...]]	Events not to track.
enabletracking	event1[,event2[,...]]	Events to track.	LOAD,SWAP,SWATCH,PAGE, PLAY,PAUSE,STOP,MILESTONE, HREF,ITEM,TARG,ZOOM,SPIN,PAN,BANNER, INTERACTIVE_SWATCH

Class Summary
Constructor Attributes	Constructor Name and Description
	s7sdk.TrackingManager(containerId, settings, compId)

Method Summary
Method Attributes	Method Name and Description
	attach(component, handler) Attach the component to the TrackingManager.
	callTrackingHandler(component, instanceName, dataString) Format the parameters and call the actual tracking function in the user code.
	detach(component) Detach the component from the TrackingManager.
	dispose() Disposes the component.
	setCallback(callbackFunction, callbackContext) TrackingManager calls the global function s7ComponentEvent() unless TrackingManager.setCallback is used to provide an alternative callback function.

Class Detail

s7sdk.TrackingManager(containerId, settings, compId)

Example Code
This example demonstrates how to use the TrackingManager component in a simple viewer. In this example a Container object,
a ZoomView object, a ZoomInButton object, a ZoomOutButton object, and a TrackingManager object are created. When a user
interacts with the ZoomView object or the zoom buttons, all tracked events are added as text to a div and appear on the
page below the viewer (for example purposes). Modify the code in the s7ComponentEvent() function as necessary to enable
event tracking on your site.

The code below does the following:

The Scene7 HTML5 SDK is linked to the page and the required s7sdk components are included in the document head.
CSS Styles are defined in the document head to control the appearance of the ZoomView and button components.
The s7sdk.Util.init() method is called to initialize the SDK.
A ParameterManager object is created to handle component modifiers for the viewer.
An initViewer() function is defined. This function initializes a couple of modifiers (hard coded for example purposes),
then creates the component objects required for this simple example. The initViewer() function also adds event listeners
that designate functions to handle relevant component events (which might be dispatched by the components as a result of
user interactions, changes in a component's state, etc.).
A required s7ComponentEvent() handler function is defined to respond to all TrackingManager events.
Additional handler functions are defined to respond to the component event listeners added in the initViewer() function.
An event listener is added to the ParameterManager object that designates the initViewer() function as the handler
to call when the Scene7 SDK is loaded and ready.
Finally, the init() method is called on the ParameterManager object to start the viewer.

<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <meta name="viewport" content="width=device-width" />

        <title>TrackingManager Component</title>

        <!-- To run this example locally you need to replace this with an absolute
        SDK path.  For more information check the HTML5 Viewers SDK User Guide or
        the examples included in the package.
        -->
        <script language="javascript" type="text/javascript"
                        src="../js/s7sdk/utils/Utils.js"></script>
        <script language="javascript" type="text/javascript">
            s7sdk.Util.lib.include('s7sdk.image.ZoomView');
            s7sdk.Util.lib.include('s7sdk.common.Container');
            s7sdk.Util.lib.include('s7sdk.common.Button');
        </script>

        <style type="text/css">
            .s7zoomview {
                top: 0px;
                left: 0px;
                height: 400px;
                width: 280px;
            }
            .s7zoominbutton{
                position: absolute;
                top: 375px;
                left: 10px;
                width: 25px;
                height: 25px;
                z-index: 5000;
            }
            .s7zoomoutbutton {
                position: absolute;
                top: 375px;
                left: 250px;
                width: 25px;
                height: 25px;
                z-index: 5000;
            }
        </style>

    </head>
    <body>

        <div style="position:absolute;top:440px;left:0px;height:200px;width:600px;">
            <code>
                <h4>Events</h4>
                <div id="trackingDiv"></div>
            </code>
        </div>

        <script language="JavaScript" type="text/javascript">
            var params, container, zoomView, zoomInButton, zoomOutButton, trackingManager;

            // Initialize the SDK
            s7sdk.Util.init();

            // Create ParameterManager instance to handles modifiers		
            params = new s7sdk.ParameterManager();
                
            // Define the function that initializes the viewer
            function initViewer(){
                // Set hardcoded modifiers (not required when values are specified on the url)
                params.push("serverurl", "http://s7d1.scene7.com/is/image");
                params.push("asset", "demo/bedroom.tif");
                params.push("disabletracking", "PAN");      // do not track PAN events

                // Create the TrackingManager object
                trackingManager = new s7sdk.TrackingManager(null, params, null);

                // Create the Container component object
                container = new s7sdk.Container(null, params, "s7container");

                // Create the ZoomView component object
                zoomView = new s7sdk.image.ZoomView( container, params, "zoomView");
                
                // Create the ZoomInButton component object
                zoomInButton = new s7sdk.common.ZoomInButton(container, params, "zoomInButton");

                // Create the ZoomOutButton component object
                zoomOutButton = new s7sdk.common.ZoomOutButton(container, params, "zoomOutButton");

                // Add event listener for zoom capability state changes
                zoomView.addEventListener(s7sdk.event.CapabilityStateEvent.NOTF_ZOOM_CAPABILITY_STATE, onZoomStateChange);

                // Add an event listener for zoom button click events
                zoomInButton.addEventListener("click", onZoomIn);
                zoomOutButton.addEventListener("click", onZoomOut);

                // Attach the ZoomView object to TrackingManager to enable tracking
                trackingManager.attach(zoomView);
            }

            // s7ComponentEvent function handles all the output from the SDK viewers.  The user can directly access
            // the tracking events if lower level control is desired - see UserEvent documentation.
            function s7ComponentEvent(objID, compClass, instName, timeStamp, eventData) {
                // To demonstrate the data available, pass event data to a div
                var element = document.getElementById("trackingDiv");
                var trackingMessages = element.innerHTML;
                element.innerHTML = eventData + "<BR>" + trackingMessages.substr(0, 1000);

                // Call the tracking support code at this point.  For instance, for SiteCatalyst tracking
                // enabled through SPS, calling s7track would transmit the data to the tracking servers.
                //s7track(eventData);
            }

            // Define an event handler function to enable/disable the zoom buttons when the ZoomView state changes
            function onZoomStateChange(event){
                if(event.s7event.state.hasCapability(s7sdk.ZoomCapabilityState.ZOOM_IN)){
                    zoomInButton.activate();
                }else{
                    zoomInButton.deactivate();
                }
                if(event.s7event.state.hasCapability(s7sdk.ZoomCapabilityState.ZOOM_OUT)){
                    zoomOutButton.activate();
                }else{
                    zoomOutButton.deactivate();
                }
            }

            // Define an event handler function to update the ZoomView when zoomIn is clicked
            function onZoomIn(event){
                zoomView.zoomIn();
            }

            // Define an event handler function to update the ZoomView when zoomOut is clicked
            function onZoomOut(event){
                zoomView.zoomOut();
            }

            // The ParameterManager will dispatch SDK_READY when all modifiers have been processed
            // and it is safe to initialize the viewer		
            params.addEventListener(s7sdk.Event.SDK_READY, initViewer, false);

            // Now it is safe to process the modifiers, the callbacks have been defined
            // this will trigger the SDK_READY event
            params.init();
        </script>

    </body>
</html>

Parameters:
{String} containerId: Not used by TrackingManager.
{s7sdk.ParameterManager} settings: A parameter manager instance that represents the desired configuration.
{String} compId: Not used by TrackingManager.

See:: s7sdk.event.UserEvent

Method Detail

attach(component, handler)

Attach the component to the TrackingManager. It is necessary to attach() a component before TrackingManager can track it.

Parameters:
component
handler

callTrackingHandler(component, instanceName, dataString)

Format the parameters and call the actual tracking function in the user code. Unless it is necessary to track events that are not emitted by the SDK framework, this function is not needed.

Parameters:
component: UIComponent, such as ZoomView or SpinView.
instanceName: Instance name passed to component constructor. Used to correlate results.
dataString: Event data in a comma-separated string format.

detach(component)

Detach the component from the TrackingManager. Turn off all event listeners.

Parameters:
component

dispose()

Disposes the component.

setCallback(callbackFunction, callbackContext)

TrackingManager calls the global function s7ComponentEvent() unless TrackingManager.setCallback is used to provide an alternative callback function. The callback takes the same parameters that s7ComponentEvent take.

Parameters:
callbackFunction: {function} Callback function to be called for each event.
callbackContext: {Object} Optional object containing callbackFunction.

Namespaces

Classes in s7sdk

Class s7sdk.TrackingManager