---
title: "Manual Configuration"
slug: "manual-configuration"
updated: 2023-08-24T19:15:38Z
published: 2023-08-24T19:15:38Z
---
> ## Documentation Index
> Fetch the complete documentation index at: https://onpremises.webtrends.help/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
:::(Info) (Note:)
When using WSP tagging, the above files may contain the text **2013** within the file names, e.g. `webtrends.load.2013.js`. This is inconsequential, and the same files are used for SP2013, SP2016, SP2019, and SPO
:::
### 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](https://www.webtrends.com/support/){target="_blank"}:
* `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 Identifier**to 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 desired*method 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
}
}
},
```
:::(Warning) (Note:)
The overlays object is a JS object and should be formatted correctly.
- *Do not* specificy the **WebTrendsSP_intra.prototype.** in the property name.
- *Ensure* the function argument list matches that of the original function.
- *Ensure* the new definition returns the same type of data as the original function.
:::
:::(Info) (Note:)
Please contact [Technical Support](http://htttps://www.webtrends.com/support){target="_blank"} for assistance when updating the **overlays** property to avoid *breaking* tracking.
:::
:::(Info) (Note:)
Ensure the **src** property uses the proper file name uploaded to the server, e.g. use `.min` if using minified files.
:::
**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;
```
:::(Info) (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;
```
:::(Info) (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;
```
:::(Info) (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;
```
:::(Info) (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;
```
:::(Info) (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 = "";
```
:::(Info) (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](https://www.webtrends.com/support){target="_blank"} 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 \ links that are not already tracked via another method, such as *document* or *list* tracking.
```
window.wt_sp_globals.configs.plugins.sp.allClick = true;
```
:::(Info) (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;
```
:::(Info) (Note:)
The `webtrends.spsocial.js` plugin must be enabled in order to collect the enhanced *social* interaction data for *newsfeeds* and for all tracking in*blog 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 \ 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;
```
:::(Info) (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)
```
:::(Info) (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";
```
:::(Info) (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;
```
:::(Info) (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;
```
:::(Info) (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;
```
:::(Info) (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 of*on-site domains* to use for *off-site* link tracking detection.
```
window.wt_sp_globals.configs.plugins.sp.homedom = window.location.hostname;
```
:::(Info) (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.
:::(Info) (Note:)
This plugin is optional.
:::
**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"
}
},
```
:::(Info) (Note:)
To alter this configuration, ensure that the specified property name is a proper JS object property declaration.
-If the desired *User Profile Property* contains a space for example, you will need to specify the property name *within quotes* to properly format the value, e.g. ***"Custom Property"**: "WT.custom_property"*.
-Additionally, JS objects expect a trailing comma character if additional properties follow, and no comma after the last entry.
:::
:::(Info) (Note:)
Specified *User Profile Properties* will only send data if that property is filled out in the *User Profile Service* for the given user.
- If you notice some user data being sent, and some not, it's probable that the missing data either isn't defined in your environment, is incorrectly defined in the configuration, or not filled in for users.
:::
:::(Info) (Note:)
Ensure the **src** property uses the proper file name uploaded to the server, e.g. use `.min` if using minified files.
:::
#### 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.
:::(Info) (Note:)
This plugin is optional.
:::
**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
}
}
```
:::(Info) (Note:)
Ensure the **src** property uses the proper file name uploaded to the server, e.g. use `.min` if using minified files.
:::
#### 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.
:::(Info) (Note:)
This plugin is optional.
:::
*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;
```
:::(Info) (Note:)
Only Spanish is provided by default.
:::
:::(Info) (Note:)
Please contact [Technical Support](https://www.webtrends.com/support/){target="_blank"} for assistance in editing this file.
:::
:::(Info) (Note:)
Ensure the **src** property uses the proper file name uploaded to the server, e.g. use `.min` if using minified files.
:::