URL Expander URL pattern validation rules

When registering URL patterns for the URL Expander intent, your patterns must follow specific validation rules to ensure they're secure and functional.

URL patterns define which URLs your app can recognize and expand. These patterns use wildcards to match multiple URLs from your platform while maintaining security and specificity.

URLs used with the URL Expander intent must follow these rules:

• Use the https:// protocol.
• Include a valid domain.
• The TLD must not contain a wildcard.
• Contain no more than 3 wildcards.
• Not include query parameters or fragments.

https://example.com/*
https://*.example.com/*
https://example.co.uk/*

http://example.com/*  (Must use HTTPS)
https://example.*  (Wildcard in TLD)
https://example/* (Invalid domain)

URLs must use the HTTPS protocol.

https://example.com/*

example.com/*
http://example.com/*

All URLs must explicitly use the https:// protocol. HTTP URLs and protocol-relative URLs aren't supported for security reasons.

The domain must be a valid domain name that follows DNS naming conventions.

https://example/*
https://example.comm/*
https://com/*
https://co.uk/*

The domain must include:

• A valid top-level domain (TLD) such as .com, .org, .co.uk.
• A valid second-level domain (the part before the TLD).
• Proper formatting with no typos or malformed parts.

You can use up to 3 wildcards (*) per URL pattern. Wildcards match any string of characters in that position.

Wildcards are allowed in:

• Subdomains: Match different subdomains (for example, https://*.example.com/*).
• Path segments: Match different paths (for example, https://example.com/*/docs/*).

Wildcards aren't allowed in:

• Top-level domains (TLD): The TLD must be explicit (for example, https://example.* is invalid).
• Registrable domain (eTLD+1): The core domain must be explicit (for example, https://*.com is invalid).

https://*.example.com/*
https://example.com/*/docs/*
https://subdomain.example.com/*/*

https://example.*/*  (Wildcard in TLD)
https://*.*.*.*.example.com/*  (Exceeds 3 wildcards)
https://*.com  (Wildcard at registrable domain level)

Each URL pattern can contain a maximum of 3 wildcards. This limit ensures that patterns remain specific enough to identify URLs from your platform.

Valid (3 wildcards):

https://*.example.com/*/*

Invalid (4 wildcards):

https://*.*.example.com/*/*

URL patterns can't include query parameters (?) or fragments (#). Patterns should match the base URL structure only.

https://example.com?param=value
https://example.com#section
https://example.com/path?query=string
https://example.com/path#fragment

https://example.com/*
https://example.com/path/*

When a user pastes a URL with query parameters or fragments, your app's expandUrl method receives the full URL including those parts. However, the pattern you register should only match the base URL structure.

Example:

• Registered pattern: https://docs.example.com/document/*
• User pastes: https://docs.example.com/document/abc123?view=edit#page2
• Pattern matches: Yes (query parameters and fragments are ignored for pattern matching)
• Your app receives: The full URL including ?view=edit#page2

You can register exact URLs without wildcards if you want to match only specific URLs:

https://example.com/specific-page

However, this is rarely useful since most apps need to match multiple URLs. Exact URLs are only recommended for testing or very specific use cases.

Use subdomain wildcards to match all subdomains of your platform:

https://*.example.com/*

This matches:

• https://docs.example.com/page
• https://app.example.com/resource
• https://cdn.example.com/asset

Use path wildcards to match different resources within your platform:

https://example.com/docs/*/view

This matches:

• https://example.com/docs/page1/view
• https://example.com/docs/page2/view
• https://example.com/docs/section/subsection/view

Note that a single wildcard matches one or more path segments.

Use patterns that are specific to your platform to avoid conflicts with other apps:

Good:

https://docs.myplatform.com/document/*
https://myplatform.com/resources/*

Avoid:

https://*.com/*  (Too broad)
https://*/*  (Too broad)

If your platform has different URL structures for different content types, register multiple patterns:

const urlPatterns = [
  "https://docs.myplatform.com/document/*",
  "https://docs.myplatform.com/presentation/*",
  "https://myplatform.com/media/*",
];

Design patterns that can accommodate future URL structures on your platform. Use wildcards strategically to allow for growth while maintaining specificity.

Before deploying, test your patterns with various URLs from your platform to ensure they match correctly:

• URLs with different path lengths.
• URLs with different subdomains (if applicable).
• URLs with query parameters and fragments.
• Edge cases specific to your platform.

const urlPatterns = [
  "https://docs.platform.com/doc/*",
  "https://docs.platform.com/sheet/*",
  "https://docs.platform.com/presentation/*",
];

const urlPatterns = [
  "https://platform.com/image/*",
  "https://platform.com/video/*",
  "https://cdn.platform.com/assets/*",
];

const urlPatterns = [
  "https://*.platform.com/content/*",  // Matches any regional subdomain
];

const urlPatterns = [
  "https://api.platform.com/*/resources/*",  // Matches any version
];

• URL Expander intent overview
• URL Expander implementation guide