URLs for Page tagging

This article explains how URL syntax is used for creating rules in Page tagging. It includes examples and guidance on how to edit Page tagging rules. For an overview of Page tagging, see Tagging and viewing Pages.

URL syntax

Pendo follows standard Web URL syntax rules for tagging Pages. A URL has several parts. The main parts of a URL are the communication protocol, the subdomain, the domain or hostname, and the path. For example, the following URL, https://www.example.com/category/user/profile.html, is constructed as follows:

URL syntax	Description
https://	The communication protocol or scheme that the browser must use to access a website.
www.	The subdomain. This groups different parts of a website that share a domain. This doesn't have to be www.. It could, for example, be app., as in https://app.example.com.
example.com	The domain name. This consists of two parts: the second-level domain (example) and the top-level domain (.com). These are often combined and referenced together for simplicity. Pendo defaults to hiding your domain with a wildcard (*). This is because you might have Pendo installed in multiple environments (staging, testing, and prod) and the wildcard helps you to avoid tagging everything again in each environment.
/category/user/profile.html	The path to the resource on the Web server. Everything after the domain is the path. This identifies certain content or folders in the domain. In this example: category is a subfolder, sometimes called a subdirectory, similar to a folder on your computer. profile.html is a page. This is an endpoint with content. It can have different extensions for different file types or simply end with a forward slash In most cases, the path is case-sensitive, and so we recommend that you capture case syntax for tagged Pages in Pendo.

 

URLs can be more or less complicated than this. See the examples below.

Fragment example

A fragment is an internal page reference, sometimes called a named anchor, referring to a section within a webpage. A fragment usually appears at the end of a URL and begins with a hashtag (#) followed by an identifier. For example, the following URL, https://www.example.com#someHeader, includes the following parts:

• https:// is the communication protocol.

• www. is the subdomain.

• example.com is the domain.

• #someHeader is the fragment.

Path fragment example

A path fragment is an internal page reference that's used as routing for the Web framework technology of the website. A path fragment usually appears at the end of a URL and begins with a hashtag (#) followed by an identifier. For example, the following URL, https://www.example.com#products/widgets/12345, includes the following parts:

• https:// is the communication protocol.

• www. is the subdomain.

• example.com is the domain.

• #products/widgets/12345 is the path fragment.

Query parameter example

Query parameters define specific content or actions based on the data passed at the end of the URL. Query parameters usually appear at the end of a URL and begin with a question mark (?) followed by a query parameter. For example, the following URL, https://www.example.com?products=widgets, includes the following parts:

• https:// is the communication protocol.

• www. is the subdomain.

• example.com is the domain.

• ?products=widgets is the query parameter, which is a key-value pair.

If you have more than one query parameter in the string that follows the question mark (?), key-value pairs are typically separated by an ampersand (&). For example: ?products=widgets&source=browser-search.

Path fragment query parameter example

You can have a combination of paths, fragments, and query parameters at the end of a URL. For example, the following URL, https://www.example.com/#products/widgets?item=12345 , includes the following parts:

• https:// is the communication protocol.

• www. is the subdomain.

• example.com is the domain.

• #products=widgets is a path fragment used for web framework routing.

• ?item=12345 is a path fragment query parameter, which is a key-value pair.

URL syntax examples

This section provides an overview and examples of the available statements and equivalent syntax for creating rules with the Rule Builder or using the Custom URL option when tagging Pages in the Visual Design Studio. For information about these two options, see the Tagging and viewing Pages article.

Rule Builder statements and URL syntax

The Rule Builder option for tagging Pages in the Visual Design Studio helps you to create a rule by giving you the option to apply statements to parts of the URL that you provided for tagging. This section provides an explanation of these statements.

Statement	Syntax	Description
<Ignore>	/*/	Ignores everything inside of two forward slashes.
<Ignore after>	**	Ignores everything in the URL after a double star.
<Parameter>	/*parameter*/	Ignores everything inside of two forward slashes.
<Contains>	~contains:	Includes a specific string that follows.
search_params=_value	?parameter= value	When a parameter matches the specified value.
search_params=<anything>	?parameter	When a parameter matches any value.

 

Custom URL syntax examples

The Custom URL option for tagging Pages in the Visual Design Studio allows you to create a Page rule using standard URL syntax. This section provides examples of this syntax. For more guidance, see the Supported URLs section in this article. 

Example type	Custom URL	Match	Don't match
Subdomains	//~contains:pendo.io/**	https://app.pendo.io AND https://help.pendo.io	https://www.insert.io/
Query parameters	//www.pendo.io/features?language=english	https://www.pendo.io/features?language=english	https://www.pendo.io/features?language=french
Query parameters	//www.pendo.io/features?language	https://www.pendo.io/features?language=english AND https://www.pendo.io/features?language=french

 

Overlapping tagging rules

User interactions with your application are captured as raw events and sent to Pendo through the Pendo agent. Pendo processes these events and matches them against the rules you create for tagging Pages. Only events that you've defined in your tagging rule for a Page are pulled into the analytics for that Page. When you segment or filter based on a named Page in Pendo, you're searching every raw event and only pulling in events that match the rules that you've defined for that Page. This has implications for how overlapping rules impact your analytics.

A Pendo Page can be made up of several rules, as well as rules that include wildcards to capture multiple URLs. This allows you refine the search of raw events to define what counts towards a Page view, such as variations of the same URL. It also allows you to create a Page that represents views of an entire application or area of your application, which can be helpful for segments, reports, and guide targeting. For example, you might want to capture all the individual contact profiles under a single Page in Pendo called "All contacts".

You can capture both a group of URLs in a single Page and individual URLs belonging to that group in other individual Pages. This gives you flexibility in your analytics to see the data that's most useful to you. If an event satisfies the criteria defined by the tagging rules for more than one tagged Page, it's pulled into the metrics for each of those Pages. 

For example, as well as a single Page that captures a group of URLs called "All contacts" in Pendo, you might want to capture the individual contact profiles as separate Pages in Pendo. Overlapping or duplicate tagging rules between the "All contacts" Page and the individual contact profile Pages don't compete with each other. Rather, Pages that have overlapping or duplicate tagging rules count the same event against each relevant Page with a matching tag.

Example URLs	Tagging rules	Page	Page views
https://www.example.com/contacts	//*/contacts	Contacts landing page	10
https://www.example.com/contacts/SteveRogers	//*/contacts/SteveRogers	Steve Rogers	2
https://www.example.com/contacts/TonyStark	//*/contacts/TonyStark	Tony Stark	3
https://www.example.com/contacts/JenniferWalters	//*/contacts/JenniferWalters	Jennifer Walter	1
https://www.example.com/contacts/ThorOdinson	//*/contacts/ThorOdinson	Thor Odinson	4
https://www.example.com/contacts/NatashaRomanoff	//*/contacts/NatashaRomanoff	Natasha Romanoff	2
All of the above	//*/contacts //*contacts/*	All contacts	22

 

Parameterized URLs 

Pendo provides the ability to parameterize a URL. This functions similarly to wildcard * except that it nests various wildcard results under the Pendo Page you created. This is useful to create Page rules across a countable variety of URLs with a single entry.

For example, if you have the following three URLs that carry similar content or that you would like to view together:

https://www.pendo.io/features/foo/

https://www.pendo.io/features/bar/

https://www.pendo.io/features/ipsum/

You could use the following Page rule to capture all three:

https://www.pendo.io/features/*parameter*/

These would appear inside your subscription under your Page rule like this:

You can store a single query parameter as a Page Parameter using the same syntax described above, for example: https://www.pendo.io?first=*parameterValue*.

If you're using a Page rule with a parameter, you can't include any other rules on the same page, otherwise, you don't see the Top Parameters data.

Only the top 100 parameters are displayed in the Pendo UI. To analyze all collected Page parameters, use the API described in Analyze Page parameters with the API.

URLs with UTM parameters

UTMs are tags added to the end of a URL to provide context on the source of the link. For example, a link embedded in an email might look like the following: www.example.com?utm_source=email. By adding utm_source to your URL, you can track activity from each source independently.

To view analytics for a UTM parameter value, you must tag your UTM parameters as Pages in Pendo. We recommend either of the following two approaches for tagging UTM parameter Pages in Pendo: 

• Tag each URL individually, creating one Page for every UTM parameter value.
• Create one Page that captures all possible UTM values using Pendo's parameter functionality.

Option 1. Create a Page for each UTM parameter value

If you have a limited number of UTM parameter values or are only interested in a select few, you can tag each value as an individual Page in Pendo. Since each UTM parameter value has its own page in Pendo, you can view usage analytics for each UTM source individually. You can also explore each value throughout the Pendo UI, including in Data Explorer, Funnel, and Path reports.

For example, to view activity for the three utm_source values below, you can create one Page in Pendo for each parameter value.

 

Option 2. Create a Page that captures multiple UTM parameter values

If there are many possible values for the UTM parameter, you can use Pendo’s parameter functionality to create one rule that captures all possible values in a single Page in Pendo.

For example, you can use a single rule with a parameter to create a Page that would allow you to view activity for all three utm_source values below. These values appear under your Top Parameters for that Page, aong with the number of views for each value on the Parameters table. 

 

Supported URLS

The table that follows lists supported standard URL syntax and examples.

	Description	Example
Standard URL	The full address of a Webpage.	https://www.pendo.io/features/platform/index.html
Wildcards (*)	The symbol used to match any number of characters in the URL. You can use multiple wildcards.	https://www.pendo.io/features/* https://www.pendo.io/features/platform/index.html/*/*
Ignore After (**)	Ignore everything after a double wildcard.	https://www.pendo.io/features/platform/index.html/users/**
Fragment (#)	Internal page reference.	https://domain.com/#page1. You can't use a wildcard (*) after a fragment (#) in Page rules.
Path fragment (# or #!)	Internal page routing.	https://domain.com/#documents/engineering/widgets. You can use a wildcard (*) in a path fragment.
Contains (~contains:)	Include a specific string.	https://www.pendo.io/features/platform/index.html/users/~contains:dashboard
Query parameter existence (?)	Query whether a parameter exists.	https://pendo.io?mobile
Query parameter value (?and =)	Query the value of a parameter.	https://pendo.io?language=english
Multiple query parameters (?, &, and =)	Query the existence and value of multiple parameters.	https://pendo.io?mobile&language=english

 

Pendo understands the difference between https://domain.com/#page1 and https://domain.com/#page2. The Page rule, https://*, will match with both URLs. If your URLs are structured this way and you would like to have a Page rule that only corresponds with https://domain.com, review the Location API documentation.

Unsupported URLs

The table that follows lists URL syntax that isn't supported, and includes examples.

Page Parameters (sections after an ; but before a ? or #)	Pendo skips dynamically set page parameters in the URL.
Any form of NOT within page rules.	Pendo doesn't support NOTin the URL syntax.
Contains (~contains:) after a query (?)	Pendo doesn't support ~contains:? in the URL syntax.
* only acts as a wildcard when matching the entirety of a string between two slashes	For example, https://www.pendo.io/features will be matched by https://*/* but not by //*.pendo.io/features or //www.pendo.io/f*s.
Neither * nor ~contains: works after a ?	Wildcards and "Contains" are treated literally.
The order of query parameters is ignored after a ?	For example, https://www.pendo.io?first=one&second=two and https://www.pendo.io?second=two&first=one will both be matched by the page rule //www.pendo.io?first=one&second=two.

 

URL normalization

We use normalization to convert URLs into a format that makes rule matching more consistent and reliable. Specifically, we implement some special rules for %20 and + for spaces. This is so that you don't need to create several rules for every way in which a space is communicated in the URL. We also normalize # into #!for path fragments. This is for differentiating between fragments and path fragments.

The table below presents some examples of how original URLs are normalized, and what rules would match with these.

Original URL	Normalized URL	Matching rules
https://www.example.com/foo%20bar	http://www.example.com/foo+bar	//*/foo%20bar
https://www.example.com/foo+bar	http://www.example.com/foo%2Bbar	//*/foo+bar //*/foo%20bar
https://www.example.com/?query=foo%20bar	http://www.example.com/foo+bar	//*?query=foo+bar //*?query=foo%20bar
https://www.example.com/#path/to/page/	http://www.example.com/#!path/to/page/	//*#!/page/to/page
https://domain.com/#documents/123/widgets	http://domain.com/#!documents/123/widgets	//*/#!/documents/*/widgets