← Vanity URLs

Vanity URLs Documentation

BSM Vanity URLs is a WordPress redirect, branded-link, dynamic QR code, analytics, and URL management platform. It provides centralized control over vanity URLs and QR codes while adding workspace management, custom domains, branding controls, analytics, interstitials, and an optional self-service Link Portal.

BSM Vanity URLs is designed for organizations that need short, memorable URLs and QR codes that can be managed centrally without changing printed materials or published links whenever the final destination changes.

Requirements

  • WordPress 6.5 or later
  • PHP 8.0 or later
  • WordPress pretty permalinks are recommended.
  • A BSM Vanity URLs Pro license is required for Pro features.
  • Custom domains require access to the domain's DNS configuration.
  • The WordPress hosting environment must accept the custom hostname and provide valid HTTPS before a custom domain can be used publicly.

Installation

  1. Download the BSM Vanity URLs ZIP file.
  2. In WordPress, go to Plugins > Add Plugin > Upload Plugin.
  3. Select the BSM Vanity URLs ZIP file.
  4. Click Install Now.
  5. Activate BSM Vanity URLs.

The plugin installs into the stable directory:

/wp-content/plugins/bsm-vanity-urls/

Future updates replace this same plugin directory. Version numbers are not included in the installed folder name.

Getting Started

After activation, open BSM Vanity URLs from the WordPress administration menu.

The plugin creates a Site Workspace for URLs and QR codes managed directly by the WordPress site.

Depending on your license and enabled features, BSM Vanity URLs can also provide Portal workspaces for individuals and teams.

Recommended Initial Setup

  1. Review Settings.
  2. Confirm the QR base path.
  3. Configure any custom domains you intend to use.
  4. Review Branding settings before enabling branded QR codes.
  5. Create your first vanity URL.
  6. Create and test your first dynamic QR code.
  7. Review Analytics after the URL or QR code begins receiving traffic.

Vanity URLs

A vanity URL is a short, memorable URL that redirects visitors to another destination.

For example:

https://example.org/join

can redirect to:

https://example.org/membership/current-campaign/?source=vanity

Creating a Vanity URL

  1. Open BSM Vanity URLs > Add New.
  2. Select the appropriate workspace.
  3. Enter the vanity path.
  4. Enter the destination URL.
  5. Select the redirect status.
  6. Configure any available routing or interstitial options.
  7. Save the URL.

Redirect Status Codes

BSM Vanity URLs supports:

  • 301 — Permanent Redirect
  • 302 — Temporary Redirect
  • 307 — Temporary Redirect preserving the request method
  • 308 — Permanent Redirect preserving the request method

Use 301 or 308 only when the redirect should be treated as permanent. For campaigns or destinations that may change, a temporary redirect is generally more appropriate.

URL Matching

Normal vanity paths are matched case-insensitively.

For example:

/Join
/join
/JOIN

are treated as the same vanity path.

A trailing slash is also normalized:

/join
/join/

Both resolve to the same vanity URL.

Query String Handling

Incoming query parameters are preserved by default.

For example:

https://example.org/join?utm_source=email&campaign=fall

will carry those parameters to the destination.

If the configured destination already contains a parameter with the same name, the parameter configured on the destination takes precedence.

BSM does not intentionally lowercase query parameter values.

Dynamic QR Codes

BSM Vanity URLs creates dynamic QR codes. The QR code points to a permanent BSM-managed route rather than directly embedding the final destination.

For example:

https://example.org/qr/X7ka2

can initially redirect to one destination and later be reassigned to another destination without replacing the printed QR code.

Why Dynamic QR Codes Matter

Once a QR code is printed on signage, brochures, advertisements, tickets, packaging, or other physical material, replacing the QR image can be expensive or impossible.

BSM therefore treats the QR route as a persistent asset. The destination can change while the public QR identity remains stable.

QR Code Identity

Each QR code has its own persistent record containing information such as:

  • QR ID
  • Public QR route
  • Workspace ownership
  • Destination
  • Encoded hostname
  • Encoded URL
  • Error-correction configuration
  • Print Lock status
  • Destination history
  • Transfer history
  • Analytics

Changing a QR destination does not require changing the public QR route.

QR Image Formats

QR exports are generated locally by BSM Vanity URLs. An external QR-generation service is not required.

Raster Formats

  • PNG
  • JPG

Available raster sizes include:

  • 512 × 512 pixels
  • 1024 × 1024 pixels
  • 2048 × 2048 pixels

1024 × 1024 is recommended for most general-purpose downloads.

Vector Formats

Pro supports true vector QR exports:

  • SVG
  • EPS

Vector exports are appropriate for professional printing, signage, large-format graphics, and design applications where resolution-independent artwork is required.

QR Error Correction

BSM supports multiple QR error-correction levels, including:

  • Medium (M)
  • Quartile (Q)
  • High (H)

Quartile (Q) is the default and recommended setting for standard BSM QR codes.

Higher error correction provides greater tolerance for damage or visual obstruction but increases QR complexity.

QR Export Cache

Generated QR images are not permanently stored in the WordPress Media Library.

BSM stores the QR definition in the database and generates downloadable files when needed.

Temporary exports are cached under a BSM-managed directory organized by workspace and QR asset.

Example:

/wp-content/uploads/bsm-vanity-cache/qr/
    workspace-27/
        2194/
            qr-2194-512.png
            qr-2194-1024.png
            qr-2194-2048.png
            qr-2194.svg
            qr-2194.eps

Cached QR exports expire after seven days of inactivity.

When an expired export is requested again, BSM regenerates it automatically from the persistent QR definition.

Cache cleanup never deletes the QR record, public QR route, destination, analytics, Print Lock, or configuration.

Print Lock

Print Lock protects QR codes that have been distributed in physical materials.

Once a QR code is marked as printed, BSM treats its public URL as infrastructure rather than disposable content.

Print Lock protects the QR's public identity from automatic reuse or lifecycle cleanup.

The destination behind a Print Locked QR can still be changed. That is the primary advantage of using a dynamic QR code.

Administrators should use Print Lock for QR codes placed on long-lived materials such as:

  • Permanent signage
  • Building displays
  • Printed brochures
  • Business cards
  • Packaging
  • Annual reports
  • Posters
  • Physical advertisements

Workspaces

BSM Vanity URLs uses workspaces to organize ownership, permissions, links, QR codes, analytics, branding, domains, and Portal access.

The core ownership rule is:

Assets belong to workspaces, not individual users.

The user who creates an asset is retained for auditing, but deleting or removing that user does not automatically delete workspace assets.

Site Workspace

The Site Workspace contains assets managed directly through the WordPress BSM Vanity URLs administration interface.

Portal Workspaces

BSM Vanity URLs Pro can provide individual or team workspaces through the optional Link Portal.

Each workspace maintains its own:

  • Members
  • Roles
  • Links
  • QR codes
  • Analytics
  • Branding policy
  • Custom domains
  • Plan and usage limits

Workspace Roles

Portal workspaces support role-based access.

Default workspace roles include:

  • Owner — Full workspace authority, including workspace-wide branding decisions.
  • Manager — Operational workspace management without Owner-only risk decisions.
  • Editor — Edit and manage permitted workspace assets.
  • Creator — Create and manage permitted content.
  • Analyst — Primarily analytics/reporting access.

Internally, BSM uses capabilities rather than relying solely on role names. This allows permissions to evolve without changing asset ownership.

Team Invitations and Seats

Workspace Owners and authorized members can invite users according to their workspace permissions and plan.

Invitations are associated with the invited email address.

Pending invitations consume a workspace seat so the workspace cannot exceed its plan limit by issuing more invitations than available seats.

Once an invitation is accepted, membership is associated with the selected WordPress user account rather than permanently depending on the user's email address.

Changing the account email later does not automatically remove workspace membership.

Portal Plans

Portal plans control the feature envelope and resource limits available to a workspace.

Plans can define limits and capabilities such as:

  • Maximum links
  • Maximum team members
  • QR availability
  • Campaign availability
  • Analytics retention
  • Advanced analytics
  • Vector QR exports
  • QR branding
  • Interstitial requirements
  • Custom domains
  • Workspace-root link creation
  • Member-namespace link creation

Portal plan definitions are controlled by WordPress/BSM administrators. Workspace Owners can use plans assigned or made available to them but cannot redefine plan capabilities.

Link Portal

BSM Vanity URLs Pro includes an optional public-facing Link Portal.

The Portal allows authorized WordPress users to manage links and related assets without requiring access to the normal WordPress administration interface.

The Portal is disabled by default.

Portal Authentication

The Portal uses WordPress users for authentication.

Workspace authorization is managed separately through BSM workspace memberships and capabilities.

Managed Portal

BSM can provide a managed Portal under a dedicated route such as:

/links/

WordPress Page / Shortcode

The complete Portal can also be embedded into a WordPress page using:

[bsm_vanity_portal]

This is useful when the Portal should appear inside the site's normal WordPress theme, header, and footer.

Active Workspace

Users who belong to multiple Portal workspaces can select their active workspace.

The active workspace determines which links, QR codes, analytics, permissions, branding rules, and usage limits are currently displayed.

BSM validates workspace membership server-side. Changing a workspace identifier in a browser request does not grant access to another workspace.

Custom Domains

Pro workspaces can use verified custom domains for branded links and, when explicitly enabled, branded QR codes.

Examples:

go.example.org
links.example.org
example.link

Custom domains belong to workspaces rather than individual links.

Domain Verification

BSM generates a DNS verification token for the custom domain.

The required TXT record must be added to the domain's DNS configuration.

After DNS changes propagate, use the domain verification control in BSM Vanity URLs.

A domain must be verified before BSM will use it for branded routing.

HTTPS and Hosting

DNS verification does not automatically create an SSL/TLS certificate.

The hosting platform, reverse proxy, CDN, or web server must:

  • Accept the custom hostname.
  • Route requests to the WordPress installation.
  • Provide a valid HTTPS certificate.

BSM intentionally treats domain ownership, DNS routing, server acceptance, and HTTPS availability as separate requirements.

Branding

Branding is configured independently for links and QR codes.

Brand Links

When enabled, newly created workspace vanity links can use the workspace's verified primary custom domain.

Brand QR Codes

Branded QR Codes are a separate setting and are disabled by default.

When enabled, newly created QR codes encode the workspace's selected custom domain directly into the QR image.

This creates a permanent dependency between printed QR codes and that hostname.

Branded QR Risk Acceptance

Because a custom hostname becomes part of the physical QR code, BSM requires explicit acceptance before Branded QR Codes can be enabled.

The acceptance warns that printed QR codes depend on the selected domain remaining:

  • Registered
  • Under the organization's control
  • Correctly configured in DNS
  • Available over HTTPS
  • Routed to the appropriate BSM Vanity URLs installation

If the domain expires, is transferred, or stops routing correctly, printed QR codes using that hostname may stop working.

Who Can Accept the Risk?

For a Portal workspace, only the Workspace Owner can establish or change the workspace's Branded QR policy.

For the Site Workspace, a WordPress administrator or appropriately authorized BSM plugin administrator controls the policy.

Managers, Editors, Creators, and Analysts cannot accept a workspace-wide branded QR risk on behalf of a Portal workspace.

Audit Record

BSM stores an auditable acceptance record including the accepting user, domain, timestamp, authority context, acceptance-statement version, statement content, and statement hash.

Changing the branded QR domain requires a new acceptance.

Changing Branding Settings

Disabling Branded QR Codes normally affects future QR codes only.

Existing QR codes retain the hostname that was originally encoded into them.

For example, if an existing QR contains:

https://go.example.org/qr/X7ka2

changing the workspace's primary domain does not silently change that QR to another hostname.

This protects printed materials from unexpected QR identity changes.

Emergency Branded Routing Suspension

BSM provides a separate emergency mechanism for situations where existing branded links or QR codes must stop working immediately.

This is different from simply disabling branding for future assets.

Available Emergency Controls

A Workspace Owner can independently suspend:

  • Existing branded links
  • Existing branded QR codes

Suspension is applied at the workspace/routing level. BSM does not need to modify every individual link or QR record.

Two-Stage Confirmation

Because suspension can immediately break public and printed assets, BSM requires two warnings.

The first warning presents the impact, including the number of affected assets.

The second warning requires an explicit typed confirmation before routing is suspended.

Suspension takes effect immediately after final confirmation.

Suspended Requests

Suspended branded routes return an unavailable response rather than deleting the asset.

BSM uses an HTTP 410 Gone response for the controlled unavailable state.

QR records, links, destinations, analytics, Print Locks, ownership information, and audit history remain intact.

Analytics During Suspension

Requests to suspended routes can be recorded as:

route_suspended

This allows administrators to understand how much traffic attempted to use an asset while routing was disabled.

Administrative Recovery

WordPress administrators have supervisory recovery controls for Portal workspaces.

An administrator can restore branded Link or QR routing even if:

  • The Workspace Owner is unavailable.
  • The Workspace Owner lost access.
  • The Workspace Owner account was removed.
  • The suspension was performed accidentally.

Administrative recovery is audited.

Restoring routing does not regenerate QR codes, change routes, alter destinations, or reset analytics.

Administrative Lock

Administrators can apply a supervisory lock when necessary to prevent a workspace from immediately changing a routing state that was established administratively.

Administrative actions do not silently rewrite existing QR identities.

Transferring QR Codes Between Workspaces

A QR code can be transferred from one workspace to another without changing its public QR route.

The transfer preserves:

  • QR ID
  • Public QR key
  • Encoded URL
  • Encoded hostname
  • Destination history
  • Print Lock
  • QR configuration
  • Audit history

The destination workspace becomes the current owner.

QR Export Cache During Transfer

Cached exports are not physically moved between workspace directories.

The new workspace generates its own cached export on demand.

The old workspace's cached files remain inaccessible through BSM after ownership changes and are removed automatically by the normal seven-day cache-cleanup process.

Analytics When Transferring a QR

When transferring a QR code, administrators can choose how historical analytics should be exposed to the destination workspace.

Options include:

  • Transfer analytics with QR — The destination workspace can view the QR's complete historical performance.
  • Start analytics fresh — Destination-workspace reporting begins at the transfer boundary.

Neither option deletes or rewrites historical analytics.

Historical events retain their original workspace attribution so administrators can determine which workspace owned the QR when traffic occurred.

Analytics

BSM Vanity URLs provides analytics for vanity links and QR codes.

Available reporting can include:

  • Total requests
  • QR scans
  • First and last activity
  • Daily traffic
  • Hourly traffic
  • Referrer hosts
  • Device classification
  • Operating-system information
  • Workspace attribution
  • QR-specific activity
  • Suspended-route requests

Additional analytics capabilities may depend on the installed license and workspace plan.

Interstitials

Pro can place an interstitial screen between a vanity URL request and its final destination.

Interstitials can be used for:

  • Advertisements
  • Announcements
  • Promotions
  • Disclaimers
  • Messages

Interstitials can include a countdown and a Continue Now action.

Portal plans can also require interstitial behavior for particular workspace tiers.

Workspace Expiration Lifecycle

Portal-managed workspaces use a staged expiration lifecycle designed to avoid immediately destroying public links and QR routes.

Days 0–7

Normal operation during the initial grace period.

Days 8–14

An expiration-warning interstitial can be displayed before the visitor continues to the destination.

Days 15–30

Links can display a customizable dead-link page.

Days 31–60

The asset remains in a retained dead/tombstone state.

Day 60 and Later

The workspace becomes eligible for cleanup according to configured lifecycle policies.

QR Route Reservation

QR routes remain reserved beyond the initial cleanup period to reduce the risk of an old QR code being reassigned to unrelated content.

The default safe-release eligibility point is after 180 days.

Eligibility does not guarantee automatic reuse. Print Lock and recent traffic can prevent automatic release and require administrative review.

Scheduled Maintenance

BSM Vanity URLs performs scheduled maintenance for tasks including:

  • Expired invitation cleanup
  • Workspace expiration processing
  • QR route lifecycle processing
  • Safe-release checks
  • QR export-cache cleanup
  • Removal of empty cache directories

QR export cache files are normally removed after seven days without access.

License

BSM Vanity URLs uses the shared BSM licensing architecture.

Open:

BSM Vanity URLs > License

to review license information and available Pro capabilities.

The License menu remains the final item in the BSM Vanity URLs administration menu.

Automatic Updates

BSM Vanity URLs integrates with the BSM Plugin Release Manager for WordPress updates.

When a newer eligible release is available, WordPress can display the update through the normal Plugins and Updates interfaces.

BSM uses its update service to retrieve information including:

  • Current available version
  • Plugin metadata
  • Release information
  • Package information
  • Compatibility information

Updates continue to use the stable plugin directory:

/wp-content/plugins/bsm-vanity-urls/

Update Diagnostics

If an automatic update is not appearing as expected, BSM provides update diagnostics.

Diagnostics can include:

  • Last update check
  • HTTP response status
  • Last API response
  • Last API error

This information can help determine whether the issue is related to connectivity, the update service, package availability, or the WordPress installation.

Data Retention

Deactivating BSM Vanity URLs does not delete its persistent data.

QR export cache files are temporary and can be regenerated.

Persistent information such as links, QR records, workspaces, analytics, Print Locks, ownership records, branding policies, risk acceptances, and audit history is retained independently of the QR export cache.

Security and Permissions

BSM Vanity URLs uses WordPress authentication together with workspace-specific authorization.

Important security behaviors include:

  • Server-side workspace membership validation.
  • Capability-based authorization.
  • Owner-only workspace risk decisions where appropriate.
  • WordPress administrator supervisory recovery.
  • Nonce-protected administrative actions.
  • Verified custom-domain ownership.
  • Authorized QR export delivery.
  • Auditing of sensitive branding, transfer, suspension, and recovery actions.

Recommended QR Practices

  • Use the stable site domain for long-lived printed QR codes unless branded QR codes are specifically required.
  • Use Print Lock when a QR code enters physical production.
  • Test every QR code from a physical device before printing.
  • Use vector SVG or EPS for professional print workflows when available.
  • Keep sufficient whitespace around the QR code.
  • Do not allow a custom domain used by printed QR codes to expire.
  • Do not change DNS or hosting for a QR-dependent custom domain without validating existing QR routes.
  • Use dynamic destinations instead of replacing printed QR codes whenever possible.

Recommended Vanity URL Practices

  • Use short, memorable paths.
  • Avoid creating paths that conflict with WordPress pages or application routes.
  • Use temporary redirect codes when campaign destinations are expected to change.
  • Use groups or workspaces to organize large URL inventories.
  • Review analytics before retiring high-traffic links.
  • Preserve old public routes when changing campaign structure unless there is a deliberate reason to retire them.

Troubleshooting

A Vanity URL Does Not Redirect

  • Confirm the redirect is active.
  • Confirm the destination is valid.
  • Check for a conflicting WordPress page or reserved route.
  • Confirm the workspace is active.
  • Check whether branded routing has been suspended.
  • Clear relevant WordPress, host, or CDN caches if necessary.

A QR Code Does Not Work

  • Confirm the QR record remains active.
  • Confirm the destination is valid.
  • Confirm the workspace is active.
  • Check whether QR routing has been suspended.
  • If the QR uses a custom domain, verify DNS, HTTPS, and domain routing.
  • Confirm the encoded hostname remains under your control.

A Custom Domain Does Not Work

  • Confirm DNS ownership verification succeeded.
  • Confirm the domain points to the correct hosting environment.
  • Confirm the host accepts requests for the custom hostname.
  • Confirm a valid HTTPS certificate exists.
  • Confirm the domain is active in BSM Vanity URLs.
  • Confirm branded routing has not been administratively suspended.

An Update Does Not Appear

  • Review the BSM update diagnostics.
  • Confirm the site can make outbound HTTPS requests.
  • Check the last HTTP response and API error.
  • Confirm the installed plugin version.
  • Confirm the update package is available for the release.
  • Confirm any applicable BSM license is valid for the requested update.

Support Information

When requesting support, include:

  • BSM Vanity URLs version
  • WordPress version
  • PHP version
  • Relevant workspace
  • Affected vanity URL or QR ID
  • Whether a custom domain is involved
  • Any displayed error message
  • Update diagnostics when the issue involves updates

Do not send passwords, authentication cookies, private license credentials, or other sensitive authentication information in a support request.

About BSM Vanity URLs

BSM Vanity URLs is developed by BSM Strategy.

The product is designed around a simple principle: public URLs and printed QR codes become organizational infrastructure. BSM therefore emphasizes persistent routing, controlled ownership, auditability, analytics, recoverability, and safe lifecycle management rather than treating redirects and QR codes as disposable records.

Need help? Visit Support & FAQ