Add option to specify a URL in the manual extension

[EmilePerron]

Changes

This PR gives users the possibility of specifying a custom tracking location for their pages via a new u option in the manual script extension.

The main advantage of this addition is that it allows users to aggregate and/or redact URLs to improve the privacy and usefulness of their analytics. This helps to resolve the issues mentioned in #136.

Custom URLs can be specified either as a string, or a function which returns a string. Absolute URLs (complete with protocol and anchor) are the expected value, in order to maintain the same functionality as with the

Tests

• This PR does not require tests

Changelog

• Entry has been added to changelog

Documentation

• Docs have been updated

Other notes and information

• This PR is a followup to [WIP] Adds 'custom-location' script extension (in response to #136) #1398 and Filter Page URLs #136. Check these out to see the discussion that lead to this implementation.
• I tried to keep the weight as low as possible: this new feature only adds 6 characters to the manual extension script (4 bytes when gzipped).

Usage examples:

<script defer data-domain="yourdomain.com" src="https://plausible.io/js/plausible.manual.js"></script>
<script>
// define the `plausible` function to manually trigger events
window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) }

// Trigger pageview with a custom location
plausible('pageview'. {u: 'https://website.com/my/custom/location'})

// Alternatively, use a function
plausible('pageview'. {u: getMyLocation()})
</script>

[EmilePerron]

Hey folks!

I went ahead and closed the previous PR for this feature since we moved to a completely different implementation.

For the documentation, should I simply mention this new feature in the section about the manual script extension, or should I create a new documentation page as I had started to do in plausible/docs#136 to explain why this might be useful and how to achieve it in more details?

I'll wait for your feedback before working on that part.

Cheers!

[ukutaht]

Optional chaining isn't supported in relatively recent (2019-2020) browsers: https://caniuse.com/?search=optional%20chaining

I think it's fine to just always use the standard if-else flow

[EmilePerron]

Good call!

I went ahead and replaced it with the following ternary, which saves a few bytes over a regular if-else:
payload.u = options && options.u ? options.u : location.href

I also reverted the dependency update for uglify-js, as the old one better reflected your browser support stance.

[ukutaht]

Looks good! I would like to remove the optional chaining but otherwise this is good to go

[metmarkosaric]

For the documentation, should I simply mention this new feature in the section about the manual script extension, or should I create a new documentation page as I had started to do in plausible/docs#136 to explain why this might be useful and how to achieve it in more details?

thanks for your contribution @EmilePerron! in terms of docs, we can mention it on the script extensions page and then link from there to its own docs page. this is not the smallest feature to describe so best it has its own page

[EmilePerron]

thanks for your contribution @EmilePerron! in terms of docs, we can mention it on the script extensions page and then link from there to its own docs page. this is not the smallest feature to describe so best it has its own page

Great! I'll go ahead and do just that then 👍

[ukutaht]

Thanks @EmilePerron. I'll let you know when this is live

[ukutaht]

@EmilePerron it's live

[ukutaht]

Could you test it and let me know how it works?

[EmilePerron]

@ukutaht

Just tested it really briefly, looks like it works as intended.

Here's the snippet I used for all my pages :

<script defer data-domain="koalati.com" src="https://plausible.io/js/plausible.manual.js"></script>
<script>window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) }</script>
<script>plausible("pageview");</script>

And to test it I ran the following in my browser's console:

plausible("pageview", { u: "https://koalati.webflow.io/test" })

The command in my console:

The results on Plausible:

[EmilePerron]

I'll try and update my documentation MR tonight or tomorrow 👨🏻‍💻

[ukutaht]

@EmilePerron Thanks! Did it count double or did you manually trigger the second pageview?

[EmilePerron]

@ukutaht I manually triggered the second pageview, which is why it shows up twice. So it feels to me like it works as intended - there's no duplicate count or anything :)

[ukutaht]

Wonderful