URLs for Page tagging in Adopt

Last updated: June 22, 2023 21:28

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 in Adopt.

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 is 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 in Adopt 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.
`<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`

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 `NOT`in 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/fs`.
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`