Manual Configuration

Configuring the Tag Manually

When manually tagging, or using a WSP Feature, the Webtrends tag must be configured manually in the JavaScript files, vs the other methods that utilize SharePoint lists to acheive the same goal.

JavaScript Files

There are at least 3 JavaScript files that are used in manual or WSP tagging. These are:

• webtrends.load.js - The load files responsible for loading other Webtrends files, and configuring the tag.
• webtrends.sp.js - The SharePoint Plugin responsible for collecting SharePoint related data.
• webtrends.js - The Webtrends core library responsible for base functionality.

Additionally, you may commonly have additional files available depending on the needs of your environment.

• webtrends.ups.js - The User Profile Service Plugin responsible for querying SharePoint's User Profile Service to collect user data.
• webtrends.spsocial.js - The SharePoint Social Plugin responsible for tracking social media interactions within Site Newfeeds and Blog Templates.
• webtrends.xxxx.js - You may have custom plugins associated with your tagging unique to your tracking needs.

Load File Configuration

At the top of the webtrends.load.js file is a MANUAL TAG CONFIG START section, ending in MANUAL TAG CONFIG END. This section contains a function that is run by the tag when the global configuration object (window.wt_sp_globals.configs) from the App/Add-in or Extension is not detected in the DOM during page load.

The following properties in the config object are adjustable from the top down. Those not listed should be left unaltered without the help of Technical Support:

• window.wt_sp_globals.url- The location of the Webtrends files on your SharePoint server. By default this is configured programmatically for the site collection root URL plus a WebtrendsAssets sub folder, e.g. https://domain.com/sites/sitecollection/WebtrendsAssets/. It can be overwritten by setting window.wt_sp_globals.url prior to the the config section, or by editing the respective declaration.

  window.wt_sp_globals.url = window.wt_sp_globals.url ?                       window.wt_sp_globals.url :             window.wt_sp_globals.spPageContextInfo.siteAbsoluteUrl + "/WebtrendsAssets/";
  

• window.wt_sp_globals.configs.domain- The domain to send Webtrends data to. When using Webtrends On Demand, this should be set to statse.webtrendslive.com. If using an on premises installation of Webtrends Analytics, this should be set to the domain of your on premisies SDC server.

  domain: "statse.webtrendslive.com", // SDC Server
  

• window.wt_sp_globals.configs.dcsid- The DCSID or Data Collection Server Identifierto send data to.

   dcsid: "xxxxxxxxxxxxxxxxxxxxxxxxx_xxxx", // DCSID
  

• window.wt_sp_globals.configs.timezone- The time zone for the server.

  timezone: "-8", // Time zone
  

• window.wt_sp_globals.configs.downloads- A list of file extensions to look for during link tracking to count the link click as a download.

  downloadtypes: "xls,doc,ppt,one,pub,jpg,bmp,gif,png,wmv,mpg,mp4,avi,csv,zip,txt,rtf,ics,js,dotx,gzip,mpp,msg,oft,pdf,potx,sql,vsd,vsdx,xap,xml,xps,xsn,docx,docm,dotm,docb,xlt,xlm,xlsx,xlsm,xlsb,pptx,pptm,ppsx,ppsm,onepkg",
  

• window.wt_sp_globals.configs.i18n- Enables double-byte character encoding to properly encode some foreign language characters.

    i18n: false,
  

Tag Plugins

Within the plugins object you may have one or more tag plugins defined and each may contain options unique to the plugin.

SharePoint Plugin

The webtrends.sp.js plugin is the primary method of collecting SharePoint specific data.

Plugin Section
The plugin section for the SharePoint Plugin contains one customizable property called overlays, which allows for the modification of behavior for the tracking code indesired circumstances, e.g. the collection of a special attribute for the link tracking title rather than the default text.

To overwrite a method within the SharePoint Plugin, the desiredmethod name to replace should be specified as a JS property name within the overlays object, and a new function definition provided as the replacement function definition, e.g.

sp: {
    ...
    overlays: {
        getAllClickTitle: function (el, evt) {
            // CUSTOM DEFINITION
        }
    }
},

Config Section
The majority of configuration for the SharePoint Plugin is found after the plugins section, in the window.wt_sp_globals.configs.plugins.sp.xxxx area.

• extraUserInfo - Enables the collection of extra user data provided by the User Profile Service plugin or the User Info Collector WSP Feature.

  window.wt_sp_globals.configs.plugins.sp.extraUserInfo = true;
  

• username - Enables the collection of the user name from the HTML of the page (upper right of screen).
  :

  window.wt_sp_globals.configs.plugins.sp.username = true;
  

  Note:

  This is only used as a backup when the User Profile Service API call fails, or if the User Info Collector WSP Feature is not enabled.
  ::

• userlogin - Enables the collection of the user login from the page's _spPageContextInfo object, found in SP2016 and above.

  window.wt_sp_globals.configs.plugins.sp.userlogin = true;
  

• dcsaut - Enables the copying of a specific parameter into the DCS.dcsaut parameter, setting the Authenticated User Name field in the SDC log files.

  window.wt_sp_globals.configs.plugins.sp.dcsaut = true;
  

• dcsautParam - Specifies the parameter to copy into DCS.dcsaut. Normally WT.shp_login.

  window.wt_sp_globals.configs.plugins.sp.dcsautParam = "WT.shp_login";
  

• dcsvid - Enables the copying of a specific parameter into the WT.dcsvid parameter, setting the Visitor ID for VDM profiles.

  window.wt_sp_globals.configs.plugins.sp.dcsvid = false;
  

  Note:

  VDM Profiles are a Legacy product.

• dcsvidParam- Specifies the parameter to copy into WT.dcsvid. Normally WT.shp_login.

  window.wt_sp_globals.configs.plugins.sp.dcsvidParam = "WT.shp_login";
  

• siteInfo - Enables the colleciton of the Site Collection and Site Title and Root URL.

  window.wt_sp_globals.configs.plugins.sp.siteInfo = true;
  

• toContent - Copies the Site Info data into the WT.cg_n and WT.cg_s parameters used for legacy reports.

  window.wt_sp_globals.configs.plugins.sp.toContent = true;
  

• search - Enables the collection of search specific data such as the search phrase, number of results, clickthroughs to results, etc.

  window.wt_sp_globals.configs.plugins.sp.search = true;
  

• legacySearch - Disables the collection of enhanced search experience data such as number of searches, refiners, pagination, position os search result clicks, etc.

  window.wt_sp_globals.configs.plugins.sp.legacySearch = false;
  

• bread - Enables the collection of breadcrumb titles on pages.

  window.wt_sp_globals.configs.plugins.sp.bread = true;
  

  Note:

  Breadcrumb trails must appear in the HTML of the page. This is less common in later versions of SharePoint.

• webparts - Enables the collection of web part names using a REST API call or HTML, allowing clicks by web part types reporting.

  window.wt_sp_globals.configs.plugins.sp.webparts = true;
  

• webPartLimit - Specifies the character limit of web part names to include, to avoid overly long web part names in reports.

  window.wt_sp_globals.configs.plugins.sp.webPartLimit = "40";
  

• webPartIds - Enables the inclusion of the web part instance id in the web part name, to allow differentiation of two of the same web part type on the same page in modern view, which does not allow the alteration of web part titles.

  window.wt_sp_globals.configs.plugins.sp.webPartIds = false;
  

• documentMenuClick - Enables the tracking of clicks to Links, ECB Menu interactions, Hover Card interactions, and Ribbons interactions related to documents.

  window.wt_sp_globals.configs.plugins.sp.documentMenuClick = true;
  

  Note:

  The name of this property is legacy and now controls all document interaction tracking.

• documentMetadata - Enables the collection of document metadata using REST API calls on the hover to detected document links, to be send on document clicks.

  window.wt_sp_globals.configs.plugins.sp.documentMetadata = false;
  

  Note:

  Enabling this feature will increase REST API traffic for your environment.
  -Data is stored in sessionStorage to attempt to reduce overall traffic.
  -Some data is available without REST API calls.
  -Slow server response may result in untracked metadata on the click event.

• documentMetadataFields - Specificies a comma delimited list of properties (list fields) to collect for documents.

  window.wt_sp_globals.configs.plugins.sp.documentMetadataFields = "";
  

  Note:

  If a specified property is not available in existing data on the page, a REST API calls is performed to collect all properties, and the specified property is retreived from the results.
  -Property names should be the text as referred to by SharePoint for best results, e.g. Created_x0020_By
  -Contact Technical Support for assistance in determining the proper field name text.

• list - Enables the collection of list interaction data such as list name, list item, and action.

  window.wt_sp_globals.configs.plugins.sp.list = true;
  

• allClick - Enables the collection of data for link tracking on all <a> links that are not already tracked via another method, such as document or list tracking.

  window.wt_sp_globals.configs.plugins.sp.allClick = true;
  

  Note:

  This is recommended for best reporting results.

• socialMenuClick - Enables the tracking of social media interactions in site newsfeeds and blog templates.

  window.wt_sp_globals.configs.plugins.sp.socialMenuClick = true;
  

  Note:

  The webtrends.spsocial.js plugin must be enabled in order to collect the enhanced social interaction data for newsfeeds and for all tracking inblog templates.

• legacySocial - Disables the enhanced social data for newsfeeds for legacy purposes.

  window.wt_sp_globals.configs.plugins.sp.legacySocial = false;
  

• articleImpressions - Enables one additional impression hit for each detected article within modern news web parts on a page to facilitate clickthrough data.

  window.wt_sp_globals.configs.plugins.sp.articleImpressions = false;
  

• multiTrack - Disables the collection of automatic link click data on <a> links where multiTrack function calls have been implemented in the link's onclick event, to avoid duplicate data on links that have been custom coded.

  window.wt_sp_globals.configs.plugins.sp.multiTrack = false;
  

• skipUPSInApps - Disables the User Profile Service API REST call from the webtrends.ups.js plugin when the currently viewed page is detected as an App/Add-in.

  window.wt_sp_globals.configs.plugins.sp.skipUPSInApps = false;
  

  Note:

  This avoids credential pop-ups when viewing some 3rd party Add-ins that used app only authentication.

The next section of properties specify HTML element ids or class names used to detect various types of components on a page.

• breadid - Specifies the HTML Element ID to look in for breadcrumb paths.

  window.wt_sp_globals.configs.plugins.sp.ids.breadid = "DeltaPlaceHolderPageTitleInTitleArea";
  

• pritopleveluserid - Specifies the primary HTML Element ID to look in for the user name, normally in the upper right of the page.

  window.wt_sp_globals.configs.plugins.sp.ids.pritopleveluserid = "SuiteNavUserName"; // zz4_Menu for 2013
  

• sectopleveluserid - Specifies an alternative HTML Element ID to look for the user name text.

  window.wt_sp_globals.configs.plugins.sp.ids.sectopleveluserid = "zz5_Menu"; // zz5_Menu for 2013
  

• DataProvider - Specifies the HTML Element ID to look for the search result data provider to detect search result interactions.

  window.wt_sp_globals.configs.plugins.sp.ids.searchBox = "DataProvider";
  

• searchPages - Specifies a comma delimited list of page names to look for search result data.

  window.wt_sp_globals.configs.plugins.sp.ids.searchPage = "osssearchresults.aspx,results.aspx,search.aspx"; // list of search pages to check for (partial matches)
  

  Note:

  Pages with matching names that are not actuall search results pages, e.g. /NotSearch.aspx may cause the tag to not fire page view events.

  • Edit this list to use be more specific to exclude /NotSearch.aspx or avoid using pages names using "...results.aspx" or "...search.aspx".
• searchResultBodyClassName - Specifies a comma delimited list of search results element class names to look for, to detect search result clickthroughs.

  window.wt_sp_globals.configs.plugins.sp.ids.searchResultBodyClassName = "ms-srch-item,ms-srch-bestBetItem,ms-srch-people-item,ms-srch-video-results ms-srch-video-results-container";
  

  Note:

  This is only used for classic view.

• obfuscate - Enables an MD5 hash to irreversibly encrypt sensitive user data such as user logins.

  window.wt_sp_globals.configs.plugins.sp.obfuscate = false;
  

  Note:

  This is recommended if you wish to avoid sending sensitive data vs. disabling the data entirely.
  -This allows the tracking of unique user ids for proper visitor and session identification without allowing the data to appear intelligable in reports,
  -e.g. Joe Smith will appear as 69f549bb037e620b1d885f93ee9f4066 in User Name reports, but the analysis engine is able to identify the user as a unique person.

• obfuscateParams - Specifies a comma delimieted list of parameter values to apply the MD5 hash to prior to sending to Webtrends.

  window.wt_sp_globals.configs.plugins.sp.obfuscateParams = "WT.shp_login,WT.shp_uname,DCS.dcsaut,WT.dcsvid,WT.shp_mgr,WT.soc_author,WT.soc_login,WT.soc_reply_author,WT.soc_reply_login,WT.soc_follow_author,WT.soc_follow_login,WT.article_author";
  

• stripIP - Enables the truncation of the Client IP Address field in the SDC logs, removing the last octect.

  window.wt_sp_globals.configs.plugins.sp.stripIP = false;
  

  Note:

  Geo Location data is augemented prior to the modification to the log value.

• legacyOnSite - Alters the link tracking code behavior so that off site link tracking is based on the current site collection rather than domain.

  window.wt_sp_globals.configs.plugins.sp.legacyOnSite = false;
  

  Note:

  Data for off domain, site collection, and sub site is available by default and is supperior to this legacy method.

• homedom - Specifies a comma delimited list ofon-site domains to use for off-site link tracking detection.

  window.wt_sp_globals.configs.plugins.sp.homedom = window.location.hostname;
  

  Note:

  Clicks to links that point to domains specified here are seen as on-site rather than off-site, allowing you to account for subdomains or alternative domains that are considered part of your environment.

• homedomRegExp - Alters the interpretation of the homedom field to use a Regular Express rather than a comma delimited list.

window.wt_sp_globals.configs.plugins.sp.homedomRegExp = false;

User Profile Service Plugin

The webtrends.ups.js plugin is an optional plugin allowing the use of REST API calls to the SharePoint User Profile Service to collect User Data Properties for reporting.

Plugin Section
The plugin section for the User Profile Service plugin contains one configurable property called userProfile, which allows the user to specify the following:

• userProfile - Specifies a list of User Profile Properties to collect, and the Webtrends Parameter to use to send the data.

ups: {
    ...
    userProfile: {
        Department: "WT.shp_dept",
        Manager: "WT.shp_mgr",
        PreferredName: "WT.shp_uname",
        Office: "WT.shp_office",
        AccountName: "WT.shp_login",
        Title: "WT.shp_title",
        Location: "WT.shp_location",
        Function: "WT.shp_function"
    }
},

SharePoint Social Plugin

The SharePoint Social Plugin was recently introduced to provide enhanced tracking of site newsfeed interactions including data about the individual post being interacted with, or social hash tags. The plugin also provides support for blog templates with similar data, which was previously not tracked.

Plugin Section
The SharePoint Social Plugin contains one configurable property called options, which allows the user to specify the following:

• impressions - Enables one additional hit for each detected post to send on page view events, for clickthrough type reporting.
• textLenght - Specifies the character limit for the post and reply content parameter, which includes the text from the post or reply. This option allows you to reduce the amount of data included in the reports to make them more legible.

spsocial: {
    ...
    options: {
        impressions: false,
        textLength: 50
    }
}

SharePoint Language Conversion Plugin

The SharePoint Language Conversion Plugin was created to allow users to properly track some foreign language site interactions. There are some interactions that rely on the text of the link to detect the action due to the lack of reliable HTML attributes to properly identify the link. For foreign language sites, the text of the link needs to be translated into the English value in order for the tracking code to properly recognize the event.

Plugin Section
There are no user configurable portions of this section.

JS File
The plugin contains a function definition which contains a large switch statement that converts the incoming foreign language text into an English equivalent.

In order to alter the file, add a case rows with the link's foregin language text in lower case, e.g.

case "example foreign language text":
case "cancelar":
    value = "Cancel";
    break;